Frontmatter5 fields
type- Command Documentation
title- openknowledge search
description- Build source-preserving context from local or connected knowledge bases.
tagstimestamp
openknowledge search
Search one knowledge base or all connected knowledge bases. The command returns source-based Markdown context. Search is local, lexical, and deterministic. It does not call an LLM.
Usage
okn search <key-or-path> <query>
okn search <key-or-path> <query> --budget 1200
okn search <key-or-path> <query> --matches
okn search <key-or-path> <query> --format json
okn search --all <query>| Option | Default | Description |
|---|---|---|
--all | off | Search the current local registry instead of one target. |
--budget <tokens> | 2400 | Approximate context budget. Incompatible with --matches. |
--limit <count> | 12 | Maximum selected sources or displayed matches. |
--no-expand | off | Exclude document, linked, and backlink context expansion. |
--matches | off | Show ranked snippets instead of a context packet. |
--format <format> | markdown | markdown or json. |
--spec <version> | latest | OKF version used to read the bundle. |
Output modes
The default context packet contains the query, root, content revision, token estimate, validation issues, and selected Markdown sections. Each source contains its file, heading, line range, score, relationship, and content hash. It also contains an okf+sha256:// locator.
# Open Knowledge Context
Query: validation workflow
Root: `/work/project-memory`
Context: 412 / 2400 estimated tokens
Sources: 2
## 1. Validation Workflow
Source: `guides/validation.md:7-10`
Relation: `direct`Use --matches to inspect ranked snippets and matched fields. JSON output uses schemaVersion: "1". The search-context.schema.json and search-results.schema.json files define the contracts.
How selection works
- Search divides Markdown into content sections at H1 through H3 headings. Lower headings stay in their parent section.
- BM25-style ranking combines section evidence with a document signal. Filenames, titles, headings, paths, frontmatter, metadata, and bodies affect the score. The section with the most query terms receives the document boost.
- Context mode keeps the five strongest lexical sections. It adds up to two sections from the strongest document. It then adds related parent or child sections. It also adds evidence for missing query terms. A selected nonlexical section uses the
document-contextrelation. - Search adds one level of authored links and backlinks. Use
--no-expandto prevent this expansion. A fragment selects the section that contains its heading. A lower heading resolves to its H1 through H3 parent section. A heading-only target resolves to its first content section. A link without a fragment selects the first content section. Search does not expand a missing fragment. It does not follow external, missing, or transitive links. - An outgoing target receives 55 percent of the seed score. A backlink receives 45 percent. A lexical target keeps the higher lexical or graph score. It stays one direct result with its lexical snippet and highlights. Multiple links do not add their scores.
- The command packs direct evidence first. Document and link context follow. It tries the five strongest lexical seeds before it truncates a large seed. It truncates a prioritized document context section before it selects a lower-ranked short section. Only the final selected section can be incomplete.
--allsearches the current registry snapshot. It does not refresh remotes. Reciprocal-rank fusion combines ranks under one global limit and budget. Partial failures stay visible. The command exits with status1only when all entries in a non-empty registry fail.
The token budget is an estimate. It is not a model-specific tokenizer guarantee. Use okn get when you already know the exact file to read.