search_knowledge

호출 전에 read shape 선택하기

query는 ranked search에, knowledge_item_id는 addressed read에 사용합니다. 정확한 immutable revision이 요청에 포함될 때만 knowledge_revision_id를 추가합니다.

공개 MCP 도구

search_knowledge

목적

게시된 current Knowledge revision을 query로 순위 검색하거나 제한된 content pagination으로 승인된 하나의 item 및 revision을 정확히 읽습니다.

사용 시점

현재 published content를 lexical, semantic, hybrid 또는 RRF evidence로 순위화해야 할 때 승인된 Knowledge Base에서 topic을 검색합니다.
하나의 정확한 Knowledge item과 current revision 또는 지정된 immutable revision을 읽습니다.
revision이 caller의 context budget보다 클 때 offset과 limit_chars로 bounded content window를 사용합니다.

사용하지 않을 시점

일반 XMemo memory recall에는 사용하지 않습니다. memory surface에는 recall, search_memory 또는 recall_context를 사용합니다.
Knowledge Base나 item을 create, publish, update 또는 archive하는 데 사용하지 않습니다. 별도의 REST/service operation입니다.
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가 필요합니다. 이 도구는 read-only이며 Knowledge audit event를 생성하지 않습니다.
TOOL_CATALOG는 search_knowledge를 min_tier=free 및 hidden_but_callable=true인 advanced surface로 분류합니다. minimal public marketplace-app tool 목록에는 포함되지 않습니다.
server가 인증된 owner 또는 team-bound context를 확인하며 caller가 owner나 scope filter를 제공할 수 없습니다.

매개변수

이름	타입	설명
`query`	string · 기본값: empty	순위 검색을 위한 자연어 query이며 query mode에 필요하고 addressed identifier와 상호 배타적입니다.
`knowledge_base_id`	string · 기본값: empty	query search를 좁히거나 addressed item을 확인하는 선택적 정확한 Knowledge Base ID입니다.
`knowledge_item_id`	string · 기본값: empty	addressed read에 사용하는 정확한 authorized item ID입니다.
`knowledge_revision_id`	string · 기본값: empty	addressed item의 선택적 immutable revision ID이며 knowledge_item_id가 있어야 합니다.
`offset`	integer · 기본값: 0	addressed content의 zero-based character offset입니다.
`limit_chars`	integer · 기본값: 4000	1부터 10000자까지 가능한 addressed-read content window입니다.
`max_results`	integer · 기본값: 10	1부터 50까지 가능한 query result 최대 개수입니다.
`mode`	string · 기본값: hybrid	query scoring mode인 hybrid, lexical, semantic 또는 rrf입니다. 인식할 수 없는 text는 MCP handler가 hybrid로 normalize합니다.
`alpha`	number · 기본값: 0.5	0.0부터 1.0까지 clamp되는 hybrid lexical weight이며 semantic weight는 1-alpha입니다.

반환 스키마

Query는 {"type":"knowledge_search","results":[...]} 형식의 JSON text를 반환하며 각 result에는 current knowledge item/revision IDs, title, bounded excerpt, source/citation, reference 및 scores가 포함됩니다. Addressed read는 type='knowledge', owner/team/scope, base/item/revision IDs, title, bounded content, locator, source, reference, content_offset, content_limit, content_total_chars 및 content_truncated를 반환합니다. tool은 audit envelope을 반환하지 않습니다.

예제

current published knowledge 검색

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

pin한 revision을 chunk로 읽기

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

오류

knowledge_runtime_disabled: runtime switch가 꺼져 있어 tool이 knowledge_unavailable envelope을 반환합니다. 이는 operational state이며 unrestricted memory로의 fallback이 아닙니다.
knowledge_invalid_request: query를 addressed ID와 섞었거나 offset/limit_chars/max_results 범위를 초과했거나 request shape가 유효하지 않습니다.
knowledge_query_required or knowledge_item_required: query도 addressed item도 없거나 knowledge_item_id 없이 knowledge_revision_id를 제공했습니다.
knowledge_resource_unavailable: addressed base, item 또는 revision이 없거나 unauthorized, inactive 또는 published item이 아닙니다.
Authorization or validation failure: caller에 knowledge:read가 없거나 query가 input limit을 초과했거나 boundary 값이 잘못되었습니다.

recall_context — Knowledge Base content가 아니라 일반 XMemo memory에서 bounded context pack을 구성합니다.
search_memory — 일반 memory surface에서 strict targeted retrieval을 사용합니다.
remember — Knowledge revision이 아니라 명시적으로 요청된 durable memory fact를 저장합니다.

출처: Knowledge Bases