Searching & Querying

Search result format

Writing effective queries

Letta uses OpenAI’s text-embedding-3-small model, which handles natural language questions well. Agents can use various query styles:

Natural language questions work best:

1
# What the agent does (agent tool call)
2
archival_memory_search(query="How does the test work?")
3
# Returns: "The Voight-Kampff test measures involuntary emotional responses..."

Keywords also work:

1
# What the agent does (agent tool call)
2
archival_memory_search(query="replicant lifespan")
3
# Returns memories containing both keywords and semantically related concepts

Concept-based queries leverage semantic understanding:

1
# What the agent does (agent tool call)
2
archival_memory_search(query="artificial memories")
3
# Returns: "...experimental replicant with implanted memories..."
4
# (semantic match despite different terminology)

Filtering by time

Agents can search by date ranges:

1
# What the agent does (agent tool call)
2
3
# Recent memories
4
archival_memory_search(
5
    query="test results",
6
    start_datetime="2025-09-29T00:00:00"
7
)
8
9
# Specific time window
10
archival_memory_search(
11
    query="replicant cases",
12
    start_datetime="2025-09-29T00:00:00",
13
    end_datetime="2025-09-30T23:59:59"
14
)

Tags and organization

Tags help agents organize and filter archival memories. Agents always know what tags exist in their archive since tag lists are compiled into the context window.

Common tag patterns:

• user_info, professional, personal_history
• documentation, technical, reference
• conversation, milestone, event
• company_policy, procedure, guideline

Tag search modes:

• Match any tag
• Match all tags
• Filter by date ranges

Example of organized tagging:

1
# What the agent does (agent tool call)
2
3
# Atomic memory with precise tags
4
archival_memory_insert(
5
    content="Nexus-6 replicants have a four-year lifespan",
6
    tags=["technical", "replicant", "nexus-6"]
7
)
8
9
# Later, easy retrieval
10
archival_memory_search(
11
    query="how long do replicants live",
12
    tags=["technical"]
13
)

Performance and scale

Embedding models and search quality

Archival search quality depends on the agent’s embedding model:

Letta Cloud: All agents use text-embedding-3-small, which is optimized for most use cases. This model cannot be changed.

Self-hosted: Embedding model is pinned to the agent at creation. The default text-embedding-3-small is sufficient for nearly all use cases.

Changing embedding models (self-hosted only)

To change an agent’s embedding model, you must:

1. List and export all archival memories
2. Delete all archival memories
3. Update the agent’s embedding model
4. Re-insert all memories (they’ll be re-embedded)

Programmatic access (SDK)

Developers can manage archival memory programmatically via the SDK:

1
// Insert a memory
2
await client.agents.passages.insert(agent.id, {
3
    content: "The Voight-Kampff test requires a minimum of 20 cross-referenced questions",
4
    tags: ["technical", "testing", "protocol"]
5
});
6
7
// Search memories
8
const results = await client.agents.passages.search(agent.id, {
9
    query: "testing procedures",
10
    tags: ["protocol"],
11
    page: 0
12
});
13
14
// List all memories
15
const passages = await client.agents.passages.list(agent.id, {
16
    limit: 100
17
});
18
19
// Get a specific memory
20
const passage = await client.agents.passages.get(agent.id, passageId);

Next steps