# search_knowledge

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

- Canonical: https://docs.xmemo.dev/ko/docs/tools/search-knowledge
- Locale: ko-KR
- Content-Locale: ko-KR
- Canonical-Content-Digest: 0310677a87145c1efaa396cd0aa2c2893ad43e7f2bff4548b876ab6d5b61ac0e
- Edition-Digest: 2fb4e40dbddc2e7e95568b01d4250bb7f964a5aaca384e20507b1f2936439881
- Source-Revision: sha256:f9db1cd4b6ed36f17d373c2a7c050c7e3ba83004cace01216f0ec51ea5b5b265

## Tool Reference: `search_knowledge`

### Purpose

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

### Parameters

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

### Returns

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을 반환하지 않습니다.

### Errors

- 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 값이 잘못되었습니다.

### Examples

#### current published knowledge 검색



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

#### pin한 revision을 chunk로 읽기



```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): Knowledge Base content가 아니라 일반 XMemo memory에서 bounded context pack을 구성합니다.
- [search_memory](/docs/tools/search): 일반 memory surface에서 strict targeted retrieval을 사용합니다.
- [remember](/docs/tools/remember): Knowledge revision이 아니라 명시적으로 요청된 durable memory fact를 저장합니다.

## 호출 전에 read shape 선택하기

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