# search

当事先不知道相关措辞或记录时，搜索已授权的 memory。

- Canonical: https://docs.xmemo.dev/zh/docs/tools/search
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: e4c087a8f0e12c7c67bbf556d6d2f73b0e61a736a9b8686e77e1b181a14238a7
- Edition-Digest: e4c582bf600b9c395bad51a33dc31a985ae978b9f344b0a1c51f2cdcb9b7ab98
- Source-Revision: sha256:0f9b76db3972abc862d49a83f61e83eed6529dc4507a3c290949f892dcaa48f9

## Tool Reference: `search_memory`

### Purpose

以严格的 targeted-match 语义搜索已授权的 XMemo memory，避免将弱匹配静默地当作答案。

### Parameters

- `query` (string, required): 要匹配的准确 topic 或 wording。
- `limit` (integer, optional, default: 5): 结果数量。
- `path_filter` (string, optional, default: %): 仅适用于 Claude plugin profile：logical-path ILIKE filter。Generic public profile 不接受此参数。
- `memory_type` (string, optional, default: %): 仅适用于 Claude plugin profile：memory type filter。Generic public profile 不接受此参数。
- `prefer_working` (boolean, optional, default: false): 仅适用于 Claude plugin profile：将 active working state 排在 vector results 之前。

### Returns

返回包含 opaque references、locations、content 以及可选 explanation/agent-boundary metadata 的排序文本响应。结果仍仅限于已授权的 memory。

### Errors

- 401/403：请求没有 memory:read，或无法访问选择的 scope/team。
- Validation failure：query、limit、path pattern 或 memory type 无效。
- No-match response：没有强结果同时满足目标和已授权 filter；调用者不得静默改用 recall 语义。

### Examples

#### 严格的 project 范围 lookup



```typescript
search_memory({
  query: "token identity fallback",
  limit: 5
})
```

### Related Tools

- [recall](/docs/tools/recall): 当不需要严格匹配时使用宽容的 best-effort retrieval。
- [recall_context](/docs/tools/recall-context): 使用有界的 multi-memory retrieval 生成 prompt context。
- [forget](/docs/tools/forget): 先审查返回的 reference，再删除准确的 record。

## 收窄返回过多结果的搜索

提高 limit 之前先添加 scope 和 path filter；对未指定 scope 的 query 只扩大 limit 会带来更多 noise，而不是更多 signal。

```ts
search_memory({
  query: "token identity fallback",
  limit: 5
})
```