# search_knowledge

搜索已发布的 current Knowledge revisions，或通过有界 pagination 读取一个准确的已授权 item 和 immutable revision。

- Canonical: https://docs.xmemo.dev/zh/docs/tools/search-knowledge
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 0310677a87145c1efaa396cd0aa2c2893ad43e7f2bff4548b876ab6d5b61ac0e
- Edition-Digest: 9b08368a609c3c3dca2687c7c30003f328f4b946c18ffa2527b616c21a68a704
- Source-Revision: sha256:f9db1cd4b6ed36f17d373c2a7c050c7e3ba83004cace01216f0ec51ea5b5b265

## Tool Reference: `search_knowledge`

### Purpose

读取已授权的 Knowledge Base 内容：可以对 published current revisions 执行排序 query，也可以通过有界 content pagination 读取一个准确的 item/revision。

### Parameters

- `query` (string, optional, default: empty): 用于排序搜索的自然语言 query；使用 query mode 时必填，并且不能与 addressed identifiers 同时使用。
- `knowledge_base_id` (string, optional, default: empty): 可选的准确 Knowledge Base ID，用于收窄 query search 或校验 addressed item。
- `knowledge_item_id` (string, optional, default: empty): 用于 addressed read 的准确、已授权 item ID。
- `knowledge_revision_id` (string, optional, default: empty): addressed item 的可选准确 immutable revision ID；它需要同时提供 knowledge_item_id。
- `offset` (integer, optional, default: 0): addressed content 的从零开始的字符 offset。
- `limit_chars` (integer, optional, default: 4000): addressed-read content window，在 MCP boundary 为 1 到 10000 个字符。
- `max_results` (integer, optional, default: 10): query result 的最大数量，范围为 1 到 50。
- `mode` (string, optional, default: hybrid): Query scoring mode：hybrid、lexical、semantic 或 rrf。无法识别的文本会由 MCP handler 规范化为 hybrid。
- `alpha` (number, optional, default: 0.5): Hybrid lexical weight，限制在 0.0 到 1.0；semantic weight 为 1-alpha。

### Returns

Query 返回 JSON text，格式为 {"type":"knowledge_search","results":[...]}，每个 result 包含 current knowledge item/revision IDs、title、bounded excerpt、source/citation、reference 和 scores。Addressed read 返回 JSON text，type='knowledge'，并包含 owner/team/scope、base/item/revision IDs、title、bounded content、locator、source、reference、content_offset、content_limit、content_total_chars 和 content_truncated。该工具不返回 audit envelope。

### Errors

- knowledge_runtime_disabled：runtime switch 已关闭，工具返回 knowledge_unavailable envelope；这是 operational state，不是回退到 unrestricted memory。
- knowledge_invalid_request：query 与 addressed IDs 混用，offset/limit_chars/max_results 超出边界，或 request shape 无效。
- knowledge_query_required 或 knowledge_item_required：没有提供 query 或 addressed item，或提供 knowledge_revision_id 时缺少 knowledge_item_id。
- knowledge_resource_unavailable：addressed base、item 或 revision 不存在、未授权、非 active 或不是 published item。
- Authorization or validation failure：caller 缺少 knowledge:read，query 超出 input limit，或 boundary value 格式错误。

### Examples

#### 搜索当前 published knowledge



```typescript
search_knowledge({
  query: "deployment runbook",
  knowledge_base_id: "<knowledge-base-id>",
  mode: "hybrid",
  alpha: 0.5,
  max_results: 10
})
```

#### 分块读取一个 pinned revision



```typescript
search_knowledge({
  knowledge_item_id: "<knowledge-item-id>",
  knowledge_revision_id: "<immutable-revision-id>",
  offset: 0,
  limit_chars: 4000
})
```

### Related Tools

- [recall_context](/docs/tools/recall-context): 从普通 XMemo memory 而非 Knowledge Base content 构建有界 context pack。
- [search_memory](/docs/tools/search): 在普通 memory surface 上执行严格的 targeted retrieval。
- [remember](/docs/tools/remember): 持久化明确请求的 durable memory fact，而不是 Knowledge revision。

## 调用前选择 read shape

使用 query 执行 ranked search，或使用 knowledge_item_id 执行 addressed read。只有请求包含准确的 immutable revision 时，才添加 knowledge_revision_id。