# recall_context

恢复跨 session 继续工作所需的近期 project 和 agent context。

- Canonical: https://docs.xmemo.dev/zh/docs/tools/recall-context
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 0767dc0a1fcb4e59857a76cce464ac0c81e3dccf483200c4310a35325dccee22
- Edition-Digest: 00c47d0a193586611e1f3a92e5a03fd3ef52ec7cee45103bd40d61274831c2d6
- Source-Revision: sha256:0000db16929d847dd06d0f100593276843962eb54fb925e1a5f66997e039974c

## Tool Reference: `recall_context`

### Purpose

读取包含结构化 items 和按 token budget 限制的 context text 的有界 multi-memory context pack；它不会修改任何内容。

### Parameters

- `query` (string, required): 用于组装 context pack 的自然语言 query。
- `max_items` (integer, optional, default: 8): pack 中最多包含的 memory 数量（1-50）。
- `max_tokens` (integer, optional, default: 1500): rendered context 的最大 token 长度（1-12000）。

### Returns

Public MCP profile 返回的是 text，而不是 structured object。它以 '### XMemo Context' heading 和 'Items: <n>' line 开头；如果结果被丢弃或缩短，则添加 'Budget: ...' line；接着每条 item 各占一行，使用 literal form 'Reference: <id> | Type: <type> | Location: <path>'；最后以 'Context:' label 引出有界的 context body。没有匹配结果时显示 'No matching XMemo memory was found.'。将 reference 视为 opaque identifier。Non-public profile 可以返回 structured pack（version、retrieval_plan、budget、items、context_text）。

### Errors

- 401/403：请求没有 memory:read，或在适用时没有 temporary-memory read capability。
- 422：max_items、max_tokens 或显式 limit 超出支持的 budget/candidate 范围。
- Validation failure：query 或某个 optional filter 格式错误。

### Examples

#### 在 task 前恢复 context



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

### Related Tools

- [recall](/docs/tools/recall): 对一个快速答案选择轻量的 best-effort 路径。
- [search_memory](/docs/tools/search): 当 weak result 不安全时选择严格匹配。
- [remember](/docs/tools/remember): 在 capture policy 批准后持久化新的 context。

## 检查实际消耗的 budget

响应会报告 used_items 和 used_tokens，从而区分真正较小的答案与被截断的答案。

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