Reference

recall_context

Restore the recent project and agent context needed to continue work across sessions.

Check the budget that was actually spent

The response reports used_items and used_tokens, which separates a genuinely small answer from a truncated one.

recall_context({ query: "recent decisions", max_items: 6, max_tokens: 1200 })

Public MCP tool

recall_context

Purpose

Read a bounded multi-memory context pack with structured items and token-budgeted context text; it changes nothing.

When to use

Restore the project, task, and agent context needed to continue work across sessions.
Assemble several related memories for prompt construction within an explicit item and token budget.
Use at session/task start when a single quick result is not enough.

When NOT to use

Do not use it for one quick forgiving lookup; use recall.
Do not use it when only a strict, targeted match should be accepted; use search_memory.
Do not request an unbounded history dump; max_items and max_tokens are safety and context-quality limits.
The REST API accepts a wider field set than the public MCP tool; see https://xmemo.dev/docs/api/memory for scope, bucket, team and provenance filters.

Required scope

memory:read is required; scope, bucket, team, and agent boundaries are still enforced by the server.

Parameters

Name	Type	Description
`query`	string · required	Natural-language query the context pack is assembled for.
`max_items`	integer · default: 8	Maximum number of memories in the pack (1-50).
`max_tokens`	integer · default: 1500	Maximum rendered context length in tokens (1-12000).

Return schema

The public MCP profile returns text, not a structured object. It opens with a '### XMemo Context' heading and an 'Items: <n>' line, adds a 'Budget: ...' line when results were dropped or shortened, then one line per item in the literal form 'Reference: <id> | Type: <type> | Location: <path>', and finally a 'Context:' label followed by the bounded context body. When nothing matched it says 'No matching XMemo memory was found.' Treat the reference as an opaque identifier. Non-public profiles can return the structured pack (version, retrieval_plan, budget, items, context_text).

Examples

Restore context before a task

recall_context({
  query: "recent decisions on the memory-os project",
  max_items: 6,
  max_tokens: 1200
})

Errors

401/403: the request lacks memory:read or the temporary-memory read capability when applicable.
422: max_items, max_tokens, or an explicit limit is outside the supported budget/candidate bounds.
Validation failure: query or one of the optional filters is malformed.

recall — Choose the lightweight best-effort path for one quick answer.
search_memory — Choose strict matching when weak results are unsafe.
remember — Persist new durable context after capture policy approves it.

Source: SDK workflow helpers