minirag-pgvector-mcp: Skill for Claude Code

Retrieve and apply the right context for a task. The evolution of manual folder-based lookup: instead of picking a folder, it embeds the query and pulls the closest chunks, optionally filtered by doctype.

When to invoke

• An LLM/agent working inside a task needs grounding context from the store.
• You want to inspect what retrieval returns for a query (debugging relevance).

Inputs

• query — the natural-language need.
• doctype (optional) — narrow to one context type (e.g. only spec).
• k (optional, default 5) — how many chunks to return.

Procedure

1. Embed the query with the same embedder used at ingest (never mix models).
2. ANN search: cosine distance <=>, WHERE doctype = $doctype when provided, LIMIT k.
3. If reranking is enabled: retrieve N (~20), rerank, take top-k.
4. Return each chunk with content, source, heading_path, score.
5. When feeding an LLM: include heading_path + source with each chunk so the model (and you) know provenance.

Guardrails

• Query embedder MUST equal ingest embedder. If embedder_id on chunks differs from the active embedder, stop and report — distances would be meaningless.
• Don't over-retrieve. Large k adds noise; prefer reranking over a huge k.
• Return provenance, always. Ungrounded context is how hallucinations sneak in.
• Do not paraphrase retrieved chunks before handing them to the model — pass them faithfully; let the model synthesize.

Verification

For a known query you have ground truth for, confirm the expected source appears in the top-k. If it doesn't, that's an eval signal — add the case to the golden set (see the eval skill) rather than tweaking blindly.

Self-check

• Are results relevant, or just lexically similar? If off, revisit chunking (see the ingest skill), not just k.
• Did I filter by the right doctype? Wrong filter silently starves retrieval.
• Am I trusting the top result without checking score/provenance? Verify before applying.