# recall

当 agent 需要聚焦答案时，检索相关的持久 context。recall 默认搜索你的全部 memory；在完整的 MCP 工具面上，传入 bucket 即可只搜索该 bucket。

- Canonical: https://docs.xmemo.dev/zh/docs/tools/recall
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: a5f520ad1f7164b71407d71502e21638cd59fcf0e2c2b3e0226ca364286b5bb5
- Edition-Digest: 10780c4fd55f21dafd714517762469134a5cf0c6033abe305a6020ecb98e9a12
- Source-Revision: sha256:27b29297ea0ca25f76efcb7223face20624379ddfff4699feaaedd6ba1f0fe42

## Tool Reference: `recall`

### Purpose

执行轻量、宽容的 best-effort lookup，在回答前返回少量最相关的已保存 memory。

### Parameters

- `query` (string, required): 要 recall 的自然语言问题或主题。
- `limit` (integer, optional, default: 5): 保持有界、用于快速 lookup 的少量结果数。

### Returns

包含每条 memory 的 reference、location、content 和可用 attribution boundary 的排序文本响应。空结果是有效的 no-match 响应，不是 authorization signal。

### Errors

- 401/403：请求没有有效 bearer token 或缺少 memory:read。
- Validation failure：query、limit 或 filter syntax 无效。
- Scope or team mismatch：请求的 boundary 对经过认证的 owner 不可见。

### Examples

#### 快速 best-effort recall



```typescript
recall({
  query: "current MCP authentication decision",
  limit: 3
})
```

### Related Tools

- [search_memory](/docs/tools/search): 使用 project/team filter 执行严格的 targeted matching。
- [recall_context](/docs/tools/recall-context): 使用有界的 multi-memory context pack。
- [remember](/docs/tools/remember): 保存明确需要持久化的 fact 或 decision。

## 区分空结果与失败

空结果是有效的 no-match 答案。凭据缺失或权限不足时，则会返回 401 或 403。

```ts
recall({ query: "a topic that was never saved", limit: 3 })
// -> empty result set, HTTP 200
```