recall_context

公开 MCP 工具

recall_context

用途

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

适用场景

• 恢复跨 session 继续工作所需的 project、task 和 agent context。
• 在明确的 item 和 token budget 内，为构建 prompt 汇集多条相关 memory。
• 在单个快速结果不足以完成任务的 session/task 开始时使用。

不适用场景

• 不要用于一次快速的宽容 lookup；请使用 recall。
• 当只应接受严格的 targeted match 时不要使用；请使用 search_memory。
• 不要请求无界的 history dump；max_items 和 max_tokens 是安全与 context 质量限制。
• REST API 接受的 field set 比 public MCP tool 更宽；scope、bucket、team 和 provenance filter 见 /docs/api/memory。

所需权限范围

• 需要 memory:read；scope、bucket、team 和 agent boundary 仍由 server 强制执行。

参数列表

返回模式

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）。

使用示例

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

错误信息

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

关联工具

• recall — 对一个快速答案选择轻量的 best-effort 路径。
• search_memory — 当 weak result 不安全时选择严格匹配。
• remember — 在 capture policy 批准后持久化新的 context。