Skip to main content

​
Memory

Use client.memory for persistent per-user memory. Memory is tenant-scoped automatically by the client credentials. For normal agent runs, core memory is included in prompt context by default. Archival memory is not injected by default; agents can recall it through tools, or callers can opt into automatic archival recall with RunOptions.memory_policy.

​
List And Read

blocks = await client.memory.list()
all_blocks = await client.memory.list(scope="all")

core = await client.memory.get("core")
agent_core = await client.memory.get("core", agent_id="agent_emails")
Passing agent_id selects agent-scoped memory automatically.

​
Update With Conflict Protection

core = await client.memory.get("core")

updated = await client.memory.update(
    "core",
    "- Prefers concise answers\n- Works in America/New_York",
    expected_updated_at=core.updated_at.isoformat(),
)
Pass expected_updated_at=None only when creating a missing block. Existing blocks require the last-read timestamp; concurrent edits return 409 Conflict.

​
Recall Archival Memory

matches = await client.memory.recall("Acme renewal", agent_id="agent_records")

for match in matches:
    print(match.scope, match.score, match.content)

​
Per-Run Memory Policy

from agentflow import MemoryPolicy, RunOptions

result = await client.agents.run(
    agent_id="agent_records",
    message="What do we know about the Acme renewal?",
    options=RunOptions(
        memory_policy=MemoryPolicy(
            archival_mode="auto",
            archival_limit=5,
            archival_min_score=0.25,
        )
    ),
)
Use archival_mode="auto" when the current turn is likely to need past specifics. AgentFlow injects bounded matches as hidden current-turn system_reminders context and persists that hidden model input with the turn for replay. The default, tool_only, keeps archival memory out of every prompt and lets the agent recall it when needed. include_user_core and include_agent_core can disable core-memory prompt context for specialized runs.

​
Delete

await client.memory.delete("archival")
await client.memory.delete("core", agent_id="agent_emails")

​
Models

ModelFields
MemoryBlockid, block_type, content, scope, agent_id, created_at, updated_at
MemoryRecallResultcontent, score, block_type, scope, agent_id, line_number, updated_at