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 /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
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.
Related tools
- 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