Archival Memory

What is archival memory?

Archival memory is a semantically searchable database where agents store facts, knowledge, and information for long-term retrieval. Unlike memory blocks that are always visible, archival memory is queried on-demand when relevant.

Key characteristics:

• Agent-immutable - Agents cannot easily modify or delete archival memories (though developers can via SDK)
• Unlimited storage - No practical size limits
• Semantic search - Find information by meaning, not exact keywords
• Tagged organization - Agents can categorize memories with tags

Best for: Event descriptions, reports, articles, historical records, and reference material that doesn’t change frequently.

When to use archival memory

Use archival memory for:

• Document repositories (API docs, technical guides, research papers)
• Conversation logs beyond the context window
• Customer interaction history and support tickets
• Reports, articles, and written content
• Code examples and technical references
• Training materials and educational content
• User research data and feedback
• Historical records and event logs

Don’t use archival memory for:

• Information that should always be visible → Use memory blocks
• Frequently changing state → Use memory blocks
• Current working memory → Use scratchpad blocks
• Information that needs frequent modification → Use memory blocks

How agents interact with archival memory

Agents have two primary tools for archival memory: archival_memory_insert and archival_memory_search.

Inserting information

Agents can insert memories during conversations using the archival_memory_insert tool:

1
# What the agent does (agent tool call)
2
archival_memory_insert(
3
    content="Deckard retired six replicants in the off-world colonies before returning to Los Angeles",
4
    tags=["replicant", "history", "retirement"]
5
)

Developers can also insert programmatically via the SDK:

1
await client.agents.passages.insert(agent.id, {
2
    content: "The Tyrell Corporation's motto: 'More human than human'",
3
    tags: ["company", "motto", "tyrell"]
4
});

Searching for information

Agents can search semantically using the archival_memory_search tool:

1
# What the agent does (agent tool call)
2
results = archival_memory_search(
3
    query="replicant lifespan",
4
    tags=["technical"],  # Optional: filter by tags
5
    page=0
6
)

Developers can also search programmatically via the SDK:

1
const results = await client.agents.passages.search(agent.id, {
2
    query: "replicant lifespan",
3
    tags: ["technical"],
4
    page: 0
5
});

Results return semantically relevant information - meaning the search understands concepts and meaning, not just exact keywords. For example, searching for “artificial memories” will find “implanted memories” even though the exact words don’t match.

Learn more about search and querying →

Real-world examples

Example 1: Personal knowledge manager

An agent with 30k+ archival memories tracking:

• Personal preferences and history
• Technical learnings and insights
• Article summaries and research notes
• Conversation highlights

Example 2: Social media agent

An agent with 32k+ memories tracking interactions:

• User preferences and conversation history
• Common topics and interests
• Interaction patterns and communication styles
• Tags by user, topic, and interaction type

Example 3: Customer support agent

• Stores ticket resolutions and common issues
• Tags by product, issue type, priority
• Searches archival for similar past issues
• Learns from successful resolutions over time

Example 4: Research assistant

• Stores paper summaries with key findings
• Tags by topic, methodology, author
• Cross-references related research
• Builds a semantic knowledge graph

Archival memory vs conversation search

Next steps