# search_knowledge

Search published current Knowledge revisions or read one exact authorized item and immutable revision with bounded pagination.

- Canonical: https://docs.xmemo.dev/docs/tools/search-knowledge
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 0310677a87145c1efaa396cd0aa2c2893ad43e7f2bff4548b876ab6d5b61ac0e
- Edition-Digest: c1a5f5d2f9144b2c67e89efbf61f0caa336cfaf79d8217e90e3ea135a8bd9d21
- Source-Revision: sha256:f9db1cd4b6ed36f17d373c2a7c050c7e3ba83004cace01216f0ec51ea5b5b265

## Tool Reference: `search_knowledge`

### Purpose

Read authorized Knowledge Base content either by ranked query over published current revisions or by one exact item/revision with bounded content pagination.

### Parameters

- `query` (string, optional, default: empty): Natural-language query for ranked search; required when using query mode and mutually exclusive with addressed identifiers.
- `knowledge_base_id` (string, optional, default: empty): Optional exact Knowledge Base ID to narrow query search or validate an addressed item.
- `knowledge_item_id` (string, optional, default: empty): Exact authorized item ID for addressed read.
- `knowledge_revision_id` (string, optional, default: empty): Optional exact immutable revision ID for the addressed item; it requires knowledge_item_id.
- `offset` (integer, optional, default: 0): Zero-based character offset for addressed content.
- `limit_chars` (integer, optional, default: 4000): Addressed-read content window from 1 to 10000 characters at the MCP boundary.
- `max_results` (integer, optional, default: 10): Maximum query results from 1 to 50.
- `mode` (string, optional, default: hybrid): Query scoring mode: hybrid, lexical, semantic, or rrf. Unrecognized text is normalized to hybrid by the MCP handler.
- `alpha` (number, optional, default: 0.5): Hybrid lexical weight, clamped to 0.0 through 1.0; the semantic weight is 1-alpha.

### Returns

Query returns JSON text with {"type":"knowledge_search","results":[...]} where each result includes the current knowledge item/revision IDs, title, bounded excerpt, source/citation, reference, and scores. Addressed read returns JSON text with type='knowledge', owner/team/scope, base/item/revision IDs, title, bounded content, locator, source, reference, content_offset, content_limit, content_total_chars, and content_truncated. The tool returns no audit envelope.

### Errors

- knowledge_runtime_disabled: the runtime switch is off and the tool returns a knowledge_unavailable envelope; this is an operational state, not a fallback to unrestricted memory.
- knowledge_invalid_request: query was mixed with addressed IDs, offset/limit_chars/max_results exceeded bounds, or the request shape is otherwise invalid.
- knowledge_query_required or knowledge_item_required: neither a query nor an addressed item was supplied, or knowledge_revision_id was supplied without knowledge_item_id.
- knowledge_resource_unavailable: the addressed base, item, or revision is absent, unauthorized, inactive, or not a published item.
- Authorization or validation failure: the caller lacks knowledge:read, the query exceeds its input limit, or a boundary value is malformed.

### Examples

#### Search current published knowledge



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

#### Read one pinned revision in chunks



```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): Build a bounded context pack from ordinary XMemo memories rather than Knowledge Base content.
- [search_memory](/docs/tools/search): Use strict targeted retrieval on the ordinary memory surface.
- [remember](/docs/tools/remember): Persist an explicitly requested durable memory fact, not a Knowledge revision.

## Pick the read shape before calling

Use query for ranked search or knowledge_item_id for an addressed read. Add knowledge_revision_id only when the exact immutable revision is part of the request.