# recall_context

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

- Canonical: https://docs.xmemo.dev/docs/tools/recall-context
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 0767dc0a1fcb4e59857a76cce464ac0c81e3dccf483200c4310a35325dccee22
- Edition-Digest: a42acf1df15b55e9169006218fa8e5e2e5dde27a63aa9e184c1b8af2c84ed1b0
- Source-Revision: sha256:0000db16929d847dd06d0f100593276843962eb54fb925e1a5f66997e039974c

## Tool Reference: `recall_context`

### Purpose

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

### Parameters

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

### Returns

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).

### 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.

### Examples

#### Restore context before a task



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

### Related Tools

- [recall](/docs/tools/recall): Choose the lightweight best-effort path for one quick answer.
- [search_memory](/docs/tools/search): Choose strict matching when weak results are unsafe.
- [remember](/docs/tools/remember): Persist new durable context after capture policy approves it.

## 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.

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