search_knowledge

调用前选择 read shape

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

公开 MCP 工具

search_knowledge

用途

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

适用场景

当 published content 需要依据 lexical、semantic、hybrid 或 RRF evidence 排序时，在已授权的 Knowledge Base 中搜索主题。
读取一个准确的 Knowledge item，以及它的 current revision 或指定的 immutable revision。
当 revision 大于 caller 的 context budget 时，使用带 offset 和 limit_chars 的有界 content window。

不适用场景

不要用于普通 XMemo memory recall；memory surface 请使用 recall、search_memory 或 recall_context。
不要用它创建、publish、更新或 archive Knowledge Base 或 item；这些是独立的 REST/service operations。
不要将 query 与 knowledge_item_id 或 knowledge_revision_id 混用；每次调用选择 query search 或 addressed read。
不要把 addressed historical revision 当成 current query-search result；query search 会有意跟随每个 published item 的 current_revision_id。

所需权限范围

需要 knowledge:read；该工具严格只读，不产生 Knowledge audit event。
TOOL_CATALOG 将 search_knowledge 归类为 min_tier=free 且 hidden_but_callable=true 的 advanced surface；它不属于最小 public marketplace-app tool list。
server 会解析认证的 owner 或 team-bound context，不接受 caller 提供的 owner 或 scope filters。

参数列表

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

返回模式

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。

使用示例

搜索当前 published knowledge

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

分块读取一个 pinned revision

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

错误信息

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 格式错误。

recall_context — 从普通 XMemo memory 而非 Knowledge Base content 构建有界 context pack。
search_memory — 在普通 memory surface 上执行严格的 targeted retrieval。
remember — 持久化明确请求的 durable memory fact，而不是 Knowledge revision。

来源: Knowledge Bases