Skip to main content

​
Memory

Memory is durable personalization that carries across conversations. It is scoped to the authenticated user inside the current tenant, with optional agent-specific blocks for facts that should only apply when a particular agent is active. Conversation-local chat-history compaction is documented separately in Conversation & Chat History.

​
Memory Blocks

AgentFlow stores memory as full-replacement blocks:
BlockVisibilityLimitUse
coreInjected into every agent request4,000 chars / 20 entriesStable, high-signal facts and preferences
archivalSearched on demand by query8,000 charsSpecific facts useful to recall only when relevant
Both blocks can exist in two scopes:
ScopeSubjectWhen to use
userCurrent user across all agentsGeneral preferences, responsibilities, relationships
agentCurrent user plus one agent idAgent-specific operating preferences or facts

​
How Memory Reaches The Agent

  1. The user_memory context block loads core user memory and active agent core memory by default.
  2. Archival memory is tool-only by default and is recalled by query when a request or tool needs specific past facts. If memory_policy.archival_mode="auto", bounded matches are injected as hidden current-turn system_reminders.
  3. Sleep-time memory runs after a conversation settles and updates memory from the completed conversation.
  4. Explicit update_memory tool calls write memory immediately and use compare-and-set protection.
The chat and prompt-preview APIs also accept memory_policy for per-run control: 
{
  "memory_policy": {
    "archival_mode": "tool_only",
    "archival_limit": 10,
    "archival_min_score": null,
    "include_user_core": true,
    "include_agent_core": true
  }
}
archival_mode is intentionally conservative:
ModeBehavior
tool_onlyDefault. Core memory is prompt context; archival memory is available through recall tools/API calls.
autoAdds the top archival matches for the current user message as hidden system_reminders, bounded by archival_limit and archival_min_score.
offNo automatic archival injection. Explicit memory APIs and tools are unaffected; core memory inclusion is still controlled by include_user_core and include_agent_core.

​
Reading Blocks

blocks = await client.memory.list()
core = await client.memory.get("core")
agent_core = await client.memory.get("core", scope="agent", agent_id="agent_emails")

GET /api/v1/memory/blocks
GET /api/v1/memory/blocks?scope=all
GET /api/v1/memory/blocks/core
GET /api/v1/memory/blocks/core?scope=agent&agent_id=agent_emails

​
Updating Blocks Safely

Memory edits are compare-and-set. To update an existing block, send the updated_at value you last read as expected_updated_at. If another writer changed the block first, the API returns 409 Conflict. 
core = await client.memory.get("core")

updated = await client.memory.update(
    "core",
    "- Prefers concise account summaries\n- Works in America/New_York",
    expected_updated_at=core.updated_at.isoformat(),
)

PUT /api/v1/memory/blocks/core
{
  "content": "- Prefers concise account summaries",
  "expected_updated_at": "2026-04-30T16:20:00"
}
To create a missing block, send "expected_updated_at": null. If the block already exists, the create-style write conflicts instead of overwriting silently.

​
Recalling Archival Memory

Archival recall returns ranked matching lines with scope metadata: 
matches = await client.memory.recall("Acme renewal", agent_id="agent_records")
for match in matches:
    print(match.scope, match.score, match.content)

POST /api/v1/memory/recall
{
  "query": "Acme renewal",
  "agent_id": "agent_records",
  "limit": 10
}

​
Good Memory Hygiene

Core memory should stay small, durable, and broadly useful. Archival memory can hold more specifics, but each line should still be something the agent may need later. Good core entries: 
- Prefers concise answers with explicit next actions.
- Works primarily with enterprise renewals in North America.
Good archival entries: 
- Acme renewal: CFO wants pricing options before the May 12 exec review.
- Globex implementation: legal approved the DPA on 2026-04-18.