Query Kb

Query the knowledge base

Use the cheapest precise view first, then broaden. Markdown files remain the authority; search scores, metadata rows, and graph results are derived views.

Locate the vault

• Resolve <vault> to the directory containing its managed or authored index.md, then set the shell-local KB_ROOT to that path (KB_ROOT=kb from a typical repository root, or KB_ROOT=. from inside the vault).
• Resolve <repository> to the repository root when the question concerns a repository path (KB_REPO=. from that root).
• Read the vault's applicable agent instructions and note conventions.
• Pass the resolved path to every --root; do not scan a repository root merely because that is where the agent session started.

Choose the retrieval lane

• Repository file or directory: run kb context first. Read its inherited guides root to nearest, then inspect its maintained knowledge, active plans, dated research, reports, and separate historical-plan group. Open only useful context hubs or records.
• Known frontmatter field or tag such as type, status, or area: use kb list.
• Known note title, path, or alias: use kb links or kb backlinks, which resolve note identities before returning authored relationships.
• A whole-vault structural question or relationship audit: use kb graph --json, then inspect the smallest relevant portion of its canonical output.
• A phrase, identity, or concept expressed with different vocabulary: use kb search, whose default hybrid result preserves exact and QMD evidence separately.
• Direct provenance for one note or repository path: use kb history or kb history search without changing authored metadata or links.
• Recent captures awaiting maintained disposition: use the advisory kb inbox view.
• Broad orientation: read index.md, then follow the smallest useful link trail. Use kb catalog when an exhaustive disposable inventory is actually needed.

kb context src/parser.ts --root "$KB_ROOT" --repo "$KB_REPO"
kb list --root "$KB_ROOT" --scope src/parser --where type=plan --json
kb list --root "$KB_ROOT" --where type=plan --where status=in-progress --sort area --json
kb list --root "$KB_ROOT" --tag retrieval --sort title --json
kb backlinks "Plan title or path" --root "$KB_ROOT" --json
kb links "Plan title or path" --root "$KB_ROOT" --direction both --depth 1 --limit 25 --json
kb relation list "Plan title or path" --root "$KB_ROOT" --json
kb graph --root "$KB_ROOT" --json
kb search "why browser capture uses the current tab" --root "$KB_ROOT" --json
kb search "accepted ingestion plans" --root "$KB_ROOT" --where type=plan --where status=accepted --tag ingestion --json
kb search "notes/write-path" --root "$KB_ROOT" --mode exact --no-history --json
kb history "notes/write-path" --root "$KB_ROOT" --repo "$KB_REPO" --json
kb history search src/parser.ts --root "$KB_ROOT" --repo "$KB_REPO" --json
kb inbox --root "$KB_ROOT" --limit 25 --json

kb context prints hub and record summaries, not their bodies. Each record states the exact repository_scopes declaration that matched, the match depth, and whether that declaration currently names a file, directory, or absent future or retired path. Current memory and terminal plans stay in separate groups. Guides remain the normative, always-loaded home for ownership, required commands, prohibitions, invariants, and edit gates. Scope hubs are optional pull-based rationale, history, examples, evidence, and links; they cannot override a guide or become the only home of a load-bearing rule. Use --kind file or --kind directory when auto cannot classify a missing target reliably.

Repeated filters use AND semantics. Metadata paths may be dotted. String and tag comparisons are case-insensitive; array metadata matches by membership. Missing sort values come last, with path as the deterministic tie-breaker. --where addresses authored frontmatter only; it does not filter derived H1 titles or file paths. Unquoted true, false, null, and numeric filter values are typed. Keep quotes inside the argument to match a string with the same spelling, for example --where 'external_id="9007199254740993"'. --scope is an exact, case-sensitive repository-scope filter rather than a substring or area match. Use it when the desired authored path declaration is known.

Use hybrid search as discovery

kb search first scans current Markdown for identity, phrase, metadata, tag, and prose matches. By default it runs that exact lane alongside QMD's local full-text and vector rankings, then combines the ranked lists while retaining each lane's evidence. Exact title and alias identities stay ahead of broader matches. The QMD path avoids query expansion and reranking models by default.

The first hybrid or semantic query downloads QMD's compact local embedding model; later queries reuse the local cache. Prewarm explicitly when useful:

kb index --root "$KB_ROOT"

Use --mode exact for live model-free search, --mode keyword for QMD full-text retrieval, or --mode semantic for its vector lane. Repeated --where, --has, and --tag constraints are checked against the live Markdown snapshot. QMD has no path-allowlist search in the pinned release, so a selective semantic query over-fetches a bounded global window and reports a degraded partial lane when that window cannot prove completeness. Treat every retrieval rank as a lead, not a fact. Open the returned Markdown, read enough surrounding context, and confirm claims against linked sources or capture manifests.

Default search also returns bounded explicit graph context around the strongest results. Supply --related <note> to seed a known neighborhood or --no-graph when structure does not help. Search does no Git work unless provenance is requested. Use --history --repo <repository> for optional recent per-note provenance or --require-history --repo <repository> when the task cannot proceed with a partial Git lane. --no-history remains an explicit compatibility form. Graph neighbors and Git history remain separate from primary text rank. They explain and expand candidates without becoming authored facts, links, or recency boosts.

kb history <note> returns the bounded commit history already associated with one resolved note. kb history search <query-or-path> searches the bounded Git projection directly and retains hashes, subjects, matched paths, co-change paths, and incomplete-detail diagnostics. Git co-change is historical evidence, not permission to write a scope or relationship.

Reuse one snapshot in code mode

For several related queries, prefer one SDK session to repeated CLI process startup:

import { openKnowledgeBase, packSearchContext } from "@hraness/kb/sdk";

const kb = await openKnowledgeBase({ root: "kb", repository: "." });
try {
  const result = await kb.search({
    query: "why browser capture uses the current tab",
    graph: { depth: 1 },
    history: "auto",
  });
  console.log(packSearchContext(result).content);
} finally {
  await kb.close();
}

grep, list, read, links, backlinks, search, history, and searchHistory share one confined read-only scan. QMD and Git initialize lazily. The session does not watch Markdown or repository changes. Close it before a write and open a new session after the final refresh and check.

When independent queries can run concurrently, compose them with defineWorkflow and runWorkflow or import a packaged workflow. The runner validates a finite acyclic graph, caps global concurrency, serializes QMD nodes, and keeps Git concurrency bounded. Do not bypass those resource groups with unbounded Promise.all calls. Custom workflows use the staged defineWorkflow<Input>("id").node(...).output(...) builder so dependency results and the final output remain typed.

Use focused structural views

kb graph --json returns the current resolved wikilinks, typed relationships, diagnostics, and note-level connection counts without creating a second graph store. Use it when a question spans the vault. Prefer kb relation list, kb backlinks, or kb links when a known note gives you a narrower starting point.

kb links is cycle-safe and requires an explicit traversal depth and result limit. kb relation list separates authored outbound assertions from derived inbound relationships while retaining canonical note IDs and source provenance. Open the returned Markdown before treating an edge as correct: a typed relationship records an authored assertion, not proof.

If a structural question is not covered by a named command, inspect the bounded JSON graph in the agent or a short task-local script. Do not create or commit a parallel graph database merely to answer one query. A recurring query is evidence for a focused, tested command with an explicit output contract.

Combine meaning with structure

1. For a repository-path question, use kb context before broader retrieval.
2. Use default hybrid search to discover candidate identities when exact structure does not answer the question. Read its lane evidence and partial diagnostics before relying on the order.
3. Use kb list to narrow by authored metadata such as type, status, area, or tags.
4. Use kb links at depth 1 to inspect immediate explicit relationships and kb backlinks for a focused inbound view. Increase depth only when the first neighborhood is insufficient. Traversal defaults to 50 notes and reports truncation; lower --limit for tighter agent context or raise it deliberately when a high-degree hub is genuinely relevant.
5. Use kb graph --json only when the question genuinely spans multiple neighborhoods; keep one-off processing task-local.
6. Read the authoritative notes and cited captures before synthesizing.

A title match may identify a prerequisite, prior version, or supporting note rather than the artifact that owns the current outcome. Confirm status and ownership in the candidate Markdown before answering or editing it.

Do not infer an edge from semantic similarity, or a conclusion from a tag. Do not write generated backlink sections into notes. If the query exposes stale metadata or a broken link, repair the authored Markdown and finish with kb refresh --root "$KB_ROOT" and kb check --root "$KB_ROOT". Close any open SDK session before that repair and reopen it after validation.

An authored index.md may declare kb_catalog: authored; refresh and check then leave it untouched. kb catalog --root "$KB_ROOT" renders the exhaustive inventory on demand. A managed vault keeps the original generated-catalog behavior. Neither mode changes scanning, graph analysis, semantic indexing, or attachment validation.