kb-query

KB Query

Answer vault-based questions by narrowing the search path before reading full documents. Cite sources with [[wikilinks]]. Do not answer from memory alone when the user asks about vault content.

Core Contract

1. Parse the question: subject, scope, time range, desired output.
2. If query telemetry is configured, start one explicit kb-query operation before the first vault lookup and retain the returned operation_id.
3. Pick the cheapest route or route combination.
4. Start from indexes, project hubs, tags, backlinks, or short search snippets.
5. Read full documents only when needed for the answer.
6. Synthesize with source [[wikilinks]].
7. Immediately before the final answer, complete that same operation with one semantic QuerySummary; the runtime Stop hook then finalizes elapsed time and token deltas including answer generation.

Keep source reading under a small budget by default. Expand only when evidence is insufficient.

Routes

Route	Use when	First move
A. Direct folder	Target project/category is clear	Read the category index or project hub if present, then selected files
B. Tag/topic collection	Topic spans folders	Use tag inventory/search, then inspect matched candidates
C. Backlink/reference	User asks what cites or depends on something	Use Obsidian backlinks or targeted wikilink search
D. Index/log browse	User asks overview, recent activity, trend, or change history	Read relevant index and only the needed log window
E. Full-text search	User gives a term, phrase, error, or concept	Use short search/context results before opening files

Complex questions can combine routes. Example: project status may use Route A for the project hub, Route D for recent _log.md, and Route E for a specific term.

Search Rules

• Do not always start from 0. Common/index.md; choose the route that best matches the question.
• For project-like names, first try the project hub if the vault uses project hubs (1. Projects/<slug>/_index.md) or inspect 1. Projects/_index.md to resolve the slug. Do not run broad full-text search on the project name before checking indexes.
• For topic-wide questions, prefer tags, backlinks, and short context snippets over reading every match.
• Use search:context for specific terms, errors, phrases, or concepts. Avoid high-frequency broad queries such as category names, project names, or large OR patterns unless the output is capped.
• If a first hit-list command returns many files, narrow to candidate paths before requesting context lines. Do not run vault-wide context grep over all matches.
• For recent activity, project _log.md files are usually newest-first when the vault uses them. Read from the top.
• For 0. Common/log.md, parse by [YYYY-MM-DD] records and inspect only the requested date range.
• Avoid logs unless the question needs time, change history, trends, or root-cause evidence.
• If the answer is already supported by index/search snippets, do not open more documents just to be exhaustive.
• If a candidate document has no frontmatter summary field, read its first paragraph as a lightweight substitute before deciding whether the full document is needed.
• Skip full-body reads for documents with frontmatter type: data (large data-style listings — raw exports, link dumps, telemetry-adjacent tables). Read only their frontmatter and summary (or first-paragraph fallback) to judge relevance; open the full body only if the user explicitly asks for its contents.