HyperKB searches locally using ripgrep and SQLite FTS5/BM25. Entry search does not require an embedding model or an external API.
Pick a search mode
hkb_search(query="connection pool", domain="infra")
hkb_search(query="postgres", mode="bm25")
hkb_search(query="pool", mode="rg")
| Mode | Behavior |
|---|---|
hybrid |
Combines ripgrep and BM25 candidates, deduplicates entries, then applies ranking signals |
rg |
Uses ripgrep text matching; a multiword query matches any of its words |
bm25 |
Uses indexed keyword matching and stemming |
recent |
Returns a recent timeline rather than a keyword search |
check |
Suggests topic files for new content |
The public MCP interface does not expose a regex switch. Do not assume that mode="rg" interprets a phrase or a regular expression as a strict pattern.
Filter before choosing a result
hkb_search(query="connection pool", domain="infra", type="decision",
status="active", author="editor-a", after="2w", top=10)
Status, type, author, and hostname filters apply across search sources. Domain scopes a dotted namespace. include_archived=True includes archive companions. Supported time inputs include epoch timestamps, durations such as 30m, 4h, 2d, and 1w, and ISO dates such as 2026-09-11.
Use offset and top for search pagination. The default result count is 10; the MCP interface bounds the requested page size. Results contain entry content, a snippet, file, epoch, provenance, and scoring metadata.
Understand ranking
Text relevance is the starting point. Recency, entry type, status, importance, and session anchors influence ordering. A high score indicates relevance under those signals; it does not verify a fact or replace reading the original rationale.
High-weight entries and decisions are exempt from the staleness penalty. Resolved or superseded entries can still be useful historical context, so they are dampened rather than automatically removed unless you filter them out.
Pack complete context
hkb_context(topic="postgres connection limits", max_tokens=3000)
The default packed mode retrieves candidate entries, ranks them for the topic, and includes complete entries that fit. Matching-line snippets are not substituted for full content. depth="shallow" requests the first 200 characters instead.
tokens_used is an estimate based on the complete JSON response, including metadata, file summaries, and truncation notices. It is not a count from a specific model tokenizer. The estimator is kept within tokens_budget; actual model token counts can differ, especially for code and non-English text. Very small budgets may not fit even the mandatory response metadata.
Check truncated and the returned entries before assuming all relevant knowledge was included. Truncation notices themselves are bounded by the budget.
Suggest files or follow a story
hkb_context(mode="suggest", topic="refactor authentication", top=5)
hkb_context(mode="narrative", topic="database migration", depth="1")
Suggestions identify files to inspect. Narrative mode follows entry links for up to two hops and can order the results chronologically. A link's presence is not evidence that the linked claim is current.
Keep the index current
Writes through HyperKB update the index. If you edit Markdown using another program, run hkb reindex. The index is rebuilt from a coordinated snapshot, and readers do not share its partial rebuild transaction. See maintenance & recovery.