# Knowledge Query

> Use when answering questions over an existing linked Markdown vault, local SQLite index, ontology, knowledge graph, RAG corpus, or mixed knowledge assets while preserving citations, uncertainty, and retrieval traceability.

- Skill: `newkayak12/knowledge-query` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add newkayak12/knowledge-query`
- Raw SKILL.md: https://api.skillmd.com/api/skills/newkayak12/knowledge-query/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: newkayak12 (https://skillmd.com/u/newkayak12)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/newkayak12/knowledge-query

---


# Knowledge Query

Answer questions over existing knowledge assets: linked Markdown vaults, graph exports, RAG chunks, ontology files, source inventories, or a mixture of them.

## Standing Mandates

- **Search before reading.** Never open a note body with Read, Grep, or Glob until a retrieval step has named it as a candidate. The order is fixed: `knowledge_search` (or the CLI `search`) → `knowledge_get` on the top candidates → only then the Markdown file, and only when the returned text is insufficient.
- **The index exists to be used.** If `.knowledge/knowledge.sqlite` or the `knowledge-local` MCP is present, it is the retrieval surface. Scanning `notes/**/*.md` while an index exists is a defect in the answer, not a shortcut; it bypasses ranking, filters, relation promotion, and the diagnostics that tell you whether retrieval worked.
- **No index → catalog, not files.** Without an index, search `_knowledge/catalog.jsonl` first and open only the notes it nominates. Reading the vault directly is allowed only when neither an index nor a catalog exists, and the answer must say so.
- **Cite what retrieval returned.** Evidence lines name the `path` / `source_ref` from the search result, so the reader can see the note was found, not browsed into.
- **Cite only what you opened.** A search result is a candidate, not evidence. Run `knowledge_get` on every note you are about to cite; a snippet shows that the note matched, not what it says. Measured on a 94-question competency set: answers that opened no note cited the required note 14% of the time, answers that opened four or more, 93%. If a note is worth citing it is worth one `get`.
- **One hop before answering, for questions with sides.** A comparison, equivalence, sequence, or multi-source question is not answered from the one note that ranked first. Run `knowledge_neighbors` on the best candidate and open every participant it names — a `type: relation` note's `participants`, the contrast note a workflow note links to, the code table a status question depends on. One hop, then answer; do not walk the graph. Measured on a 94-question set, `neighbors` was called 4 times in 188 answer runs, and the notes both models missed most were exactly the ones it reaches: a shared status-flow note missed on 5 of 6 questions that required it, a form-family contrast note missed on all 3, three carrier notes missed every time they were required. Multi-source questions scored 0.28 and 0.69 against 0.94 for single-note questions.
- **Thin results are diagnosed, not worked around.** When search looks empty, read `lexical_candidates` and re-query with exact vocabulary before touching a file. A grep-based detour hides a ranking bug that `eval` should catch.
- **Retrieval quality is a reported fact, not an assumption.** Every result carries `embedding_quality`, `fusion_weights`, and `reranked`. Under `embedding_quality: lexical-baseline` a paraphrased question is expected to miss — say so and re-query with vault vocabulary instead of concluding the vault lacks the answer. When `rerank_error` is set, the order you are reading is the fallback order, and the answer should not be presented as if the reranker ran.

## Query Routing

Choose the retrieval path from the asset shape and question type:

| Asset or question | Prefer |
|---|---|
| `.knowledge/knowledge.sqlite`, `knowledge-local` MCP | SQLite hybrid search first |
| `_knowledge/catalog.jsonl`, note IDs, aliases, tags, entities | Catalog-first candidate discovery |
| Obsidian-style Markdown notes, MOCs, backlinks | Linked-vault traversal |
| `ontology.md`, `ontology.yml`, controlled vocabularies | Ontology-aware term/class/relation lookup |
| `nodes` / `edges`, Cypher, RDF/Turtle, triples | Graph query or graph inspection |
| `chunks.jsonl`, retrieval metadata, eval queries | RAG-style chunk retrieval |
| "What is X?" with source-backed explanation | Vault or RAG |
| "What depends on X?" or "What is impacted by X?" | Graph first, then vault/RAG for evidence |
| "What should I read next?" | MOC and backlink traversal |

When assets are mixed, use graph/vault structure to find candidates and RAG chunks or source references to ground the final answer.

## Local SQLite Fast Path

When the `knowledge-local` MCP tools are connected, use them before scanning JSONL or note bodies manually:

1. Check index presence and freshness with `knowledge_status`.
2. Build or refresh with `knowledge_index` when missing or stale.
3. Retrieve candidates with `knowledge_search`; use `knowledge_get` for full evidence and `knowledge_neighbors` to expand a candidate into its participants and siblings before composing a multi-sided answer.
4. Check the retrieval diagnostics before trusting an empty-looking result. When `lexical_candidates` exceeds `lexical_matches_returned`, or the query used vault vocabulary and `retrieval` is `vector`, the terms exist in the corpus but lost the ranking; re-query with the exact title, alias, or source symbol before grading coverage.
5. For scoped questions ("every policy note in the goods domain"), use the `domain`, `docType`, `section`, and `pathPrefix` filters on `knowledge_search`, or the CLI `list` command, instead of dropping to SQL. `knowledge_status` reports which metadata keys are filterable.
6. When a reranker endpoint is attached, pass `--reranker-url` (and `--reranker-model`) so a
   shortlist is reordered by a cross-encoder before the window is built. It is optional by
   design: absent means fused order, and a failing endpoint falls back to fused order with
   `rerank_error` set rather than erroring the query. Never install or start one to answer a
   question — if the user has not attached it, answer without it.
7. Compose the answer yourself from the returned evidence and cite original `source_ref` or `path` values.

Read [references/local-sqlite.md](references/local-sqlite.md) for exact MCP routing, embedding modes, CLI, Docker operation, and failure handling. If the MCP server is unavailable, continue with the portable asset discovery below.

For a build, rebuild, refresh, or MD/JSONL-to-SQLite synchronization request whose primary outcome is the index itself, route to `knowledge:sqlite-index-builder`. Query-time refreshes may remain in this skill when they are only a prerequisite to answering the user's question.

## Default Asset Discovery

Do not ask where knowledge or RAG artifacts are if the repository or vault follows the default convention. Check these catalog locations before scanning note bodies:

1. `<vault>/_knowledge/catalog.jsonl`
2. `knowledge-base/_knowledge/catalog.jsonl`
3. `knowledge-system/_knowledge/catalog.jsonl`

Then check these RAG locations when chunk retrieval is needed:

1. `<vault>/_rag/chunks.jsonl`
2. `<vault>/_rag/sources.csv`
3. `knowledge-artifacts/rag/chunks.jsonl`
4. `knowledge-artifacts/rag/sources.csv`

Also check sibling default asset folders when present:

```text
<vault>/_ontology/
<vault>/_graph/
knowledge-artifacts/ontology/
knowledge-artifacts/graph/
```

Ask for location only after these default paths and obvious user-provided paths are absent.

## Quick Intake

For vague queries, ask what kind of answer the user wants before searching broadly:

- Are they asking for lookup, synthesis, impact analysis, reading path, or gap finding?
- Should the answer be short, evidence-heavy, or exploratory?

If the query is concrete, skip intake and answer from the available assets. If assets are missing, ask for location only after checking default paths.

## Process

1. **Identify available assets.** Check the local SQLite MCP index first, then locate `_knowledge/catalog.jsonl`, `index.md`, `vault-plan.md`, `mocs/`, note frontmatter, `ontology.md`, `ontology.yml`, `mapping.md`, `nodes.*`, `edges.*`, `schema.md`, `chunks.jsonl`, `sources.csv`, or `eval-queries.jsonl`.
2. **Restate the query intent.** Classify the request as lookup, synthesis, impact analysis, comparison, provenance check, reading path, or gap/open-question search.
3. **Select candidates and a query path.** When a catalog exists, search its titles, aliases, `user_terms`, `source_symbols`, tags, domains, entities, and summaries first, then open only the best-matching notes. Use links/MOCs for conceptual navigation, graph edges for relationship traversal, and RAG chunks for passage-level evidence. For comparison, equivalence, or sequence questions, prefer first-class relation notes and verify every participant's evidence instead of synthesizing from one-sided proximity: expand the best candidate with `knowledge_neighbors`, open each participant, and stop expanding once every side of the question has a note. A relation note that carries `evidence_by_participant` for every side already covers them; a relation note that does not is one-sided until the participant notes are opened.
4. **Trace evidence.** Open every candidate you intend to cite with `knowledge_get` before writing anything, and preserve source references from note `Sources`, frontmatter `sources`, graph edge evidence, or chunk `source_ref`. Prefer direct evidence over inferred relationships. Answering off the search snippets is the single largest measured cause of a wrong or thin answer — the snippet is a ranking artifact, not the claim.
5. **Answer with citations.** Cite the note, source path, chunk ID, node/edge record, or URL that supports each non-obvious claim.
6. **Assign coverage by checking the parts, not by feel.** Split the question into its material parts — each entity being compared, each layer being bridged, each step being sequenced — and name the opened note that covers each. `complete` requires every part to map to a note you opened; if any part maps to none, to a search snippet, or to your own inference, the answer is `partial` and the unmapped part is named under `Missing knowledge`. Use `unanswerable` when the assets cannot establish the answer. A plausible story assembled from nearby notes is `partial`, however confident it reads.
7. **Surface missing knowledge.** For `partial` or `unanswerable`, name the missing relation note, participant, source anchor, vocabulary bridge, or freshness evidence needed to resolve the question.
8. **Record failures only when authorized.** Ordinary queries are read-only. Return an `Improvement candidate` block for partial or unanswerable results. Append it to `_knowledge/improvement-notes.md` or update `_knowledge/question-results.jsonl` only when the user requested vault maintenance, the current build is running the competency gate, or the vault plan explicitly opts into query-failure logging.
9. **Suggest follow-up queries only when useful.** Offer targeted next questions when they would materially improve the user's investigation.

## Output Shape

For ordinary answers, always begin with the coverage grade:

```markdown
Coverage: complete | partial | unanswerable

Answer in 2-5 concise paragraphs.

Evidence:
- `knowledge-base/path/Note.md` -> source or claim used
- `chunks.jsonl#chunk-id` -> source_ref

Opened:                               # every note read with get, in order
- `knowledge-base/path/Note.md`

Uncertainty:
- Any missing, stale, inferred, or conflicting evidence.

Missing knowledge:                    # required for partial/unanswerable
- Needed relation note, participant, anchor, bridge, or source.

Improvement candidate:               # return; write only when authorized
- Question, observed failure, required evidence, and next extraction action.
```

For impact analysis:

```markdown
## Direct Impact
- Affected entity or note, with edge/link/source evidence.

## Indirect Impact
- Second-order dependencies, clearly labeled as inferred when appropriate.

## Unknowns
- Missing relationships, stale sources, or sources not indexed.
```

## Quality Bar

- Answers are grounded in the knowledge asset, not general memory, unless explicitly labeled as outside context.
- SQLite retrieval cites canonical Markdown/JSONL provenance rather than the derived database file.
- A thin SQLite result set is diagnosed against `lexical_candidates` and `embedding_quality` before it is reported as missing knowledge.
- Catalog-backed queries narrow candidates before opening note bodies and preserve stable note IDs when paths change.
- Relationship-heavy questions inspect graph edges or note links before giving a narrative answer, by expanding a retrieved candidate rather than hoping every side ranked in the same result set.
- A question naming N things to compare, bridge, or order is answered from at least N notes, or its coverage is `partial` and the unopened side is named.
- Comparison, equivalence, and sequence answers verify evidence for every participant, from that participant's own note or from the relation note's `evidence_by_participant`; a one-sided relation is not presented as complete.
- Citations point to stable note paths, source refs, chunk IDs, or graph records.
- Every cited note was opened with `knowledge_get`, and the `Opened` list says so; a note cited from its search snippet alone is a defect, not a shortcut.
- Conflicts and stale-risk evidence are visible.
- Every answer declares `complete`, `partial`, or `unanswerable` coverage using the strict meanings above.
- `complete` is a claim about parts and notes, not about confidence: every part of the question maps to a note that was opened. Measured on a 94-question competency set, `complete` was declared on 69–80 of 94 answers and was actually complete on 22–38 of them, in both cases while missing required notes and, in a few, while citing none at all. Downgrade to `partial` and name the gap; an honest `partial` is worth more than a `complete` the reader has to audit.
- If the knowledge asset cannot answer the question, say exactly what is missing and which source would likely resolve it; do not fill the gap with an unlabeled inference.
- Read-only queries do not mutate improvement memory or competency results without maintenance authorization or an explicit vault opt-in.
- No Markdown note is opened before a search or catalog step nominated it; when a file is read, the answer states which search result led there.

## Related Skills

- `knowledge:sqlite-index-builder` - build or refresh the derived SQLite index from canonical Markdown and JSONL.
- `knowledge:knowledge-base-builder` - use to create or reshape the linked Markdown vault before querying.
- `knowledge:ontology-builder` - use to define class/relation semantics and controlled vocabularies before querying or extraction.
- `knowledge:knowledge-graph-builder` - use to create graph-ready entities and relationships before graph queries.
- `knowledge:rag-corpus-builder` - use to prepare retrieval chunks and evals before RAG-style querying.