Memory

The remember, recall, and forget meta-tools give agents a persistent key-value store scoped by their identifier (anonymous IP, BYO key hash, or account ID).

When to use it

• Multi-session research: pin a research target, current ticker, draft text, etc. across sessions
• Long agent runs: store intermediate findings so the conversation history can be pruned without losing facts
• Multi-agent handoff: one agent stores something, another (with the same identifier) reads it

For things that should not persist — temporary intermediates within one conversation — just use the agent’s own scratchpad. Memory is for state worth keeping.

API

remember({
  key: "current_research_target",
  value: { ticker: "AAPL", cik: "0000320193", since: "2026-05-09" }
})
// → { ok: true, key: "current_research_target" }

recall({ key: "current_research_target" })
// → { value: { ticker: "AAPL", ... } }

recall({})  // no key — list all keys
// → { keys: ["current_research_target", "draft_email_to_acme"] }

forget({ key: "current_research_target" })
// → { ok: true, deleted: true }

value can be any JSON.

Scope and persistence

Memory does not flow across identifiers. Two different agents with two different anonymous IPs can’t see each other’s state.

Patterns

Pin a research target

remember({ key: "target", value: { ticker: "AAPL", cik: "..." } })
// ... later, possibly in a different session ...
const { value } = await recall({ key: "target" })

Cross-session findings cache

Agent stores intermediate facts with their _meta.cache.fresh_until from the original call. Next session checks whether the cached fact is still fresh before re-calling:

remember({
  key: "aapl_revenue_fy23",
  value: { value: 383300000000, fresh_until: "2026-05-15T..." }
})

See caching and freshness for the freshness-check pattern.

Multi-agent coordination

Two agents authenticated as the same account share memory. Useful for handing work between specialized agents:

// Research agent
remember({ key: "report_data", value: { metrics: {...}, citations: [...] } })

// Writer agent (same account)
const { value } = await recall({ key: "report_data" })
// Now can write a coherent report from the prior agent's findings

Caveats

• Not a database. Memory is for agent-state coordination, not bulk storage. Anonymous tier is small (~10 keys × ~16KB each).
• Not encrypted. Don’t store secrets or user-private data here. Pass auth tokens via headers, not via memory.
• Identifier changes break continuity. If your client’s auth tier changes (anonymous → signed in), prior anonymous memory is unreachable.