Updated
What is canonical context for coding agents?
Canonical context is the single current, authoritative document that answers a coding agent's question, served with a freshness marker instead of a pile of candidate files the agent has to sift. Canonical means the one doc that is the source of truth for a topic, as opposed to stale or duplicate copies.
What makes context "canonical" rather than just relevant?
Relevance is similarity; canonical is authority plus freshness. A similarity search can return five files that all mention "deploy rollback" — including an old postmortem and a duplicate wiki page. Canonical context picks the one that is current and authoritative and labels the rest stale or duplicate, so the agent reads the right doc, not the most textually similar one.
Why does it matter for an agent?
Two reasons: cost and correctness. Serving one current section instead of the top few candidates is about 60% fewer tokens per lookup. And an agent that reads the canonical doc isn't quietly reasoning over an outdated copy — fewer confidently-wrong answers from stale instructions.
How is canonical context delivered?
By indexing your docs and routing each query to the source of truth, with a freshness signal attached. trovex is an open-source, local-first MCP server that does this: it returns the canonical doc as a path:line pointer with a canonical / stale / duplicate marker, serves the section that answers, and lets agents write canonical records back so the whole fleet shares one source of truth. It runs on your machine — SQLite + ONNX, no cloud or keys.
Canonical context vs the alternatives
It's easy to confuse canonical context with three things it isn't:
- vs RAG. A plain RAG stack returns the top-k most similar chunks and leaves the agent to sift them. Canonical context returns the one current, authoritative doc and marks the rest stale or duplicate. Same retrieval machinery, a source-of-truth answer instead of a similarity pile.
- vs a bigger context window. A bigger window only lets the agent hold more; it doesn't tell it which doc is current, so it still rereads candidates. See what context costs your agents for the measured difference.
- vs a CLAUDE.md / AGENTS.md. A single static file is loaded whole every session and ages the day it ships. Canonical context routes each query to the current doc instead. A 2026 ETH Zurich study found big context files cut task success and raised cost over 20%; why context files stop scaling covers it.
FAQ
How is canonical context different from RAG?
RAG returns the top-k most similar chunks; canonical context returns the one current, authoritative doc and marks the rest stale or duplicate. It is retrieval tuned for a source of truth, not a similarity pile the agent still has to sift.
Is canonical context the same as a bigger context window or a CLAUDE.md file?
No. A bigger window only holds more; a CLAUDE.md is one static file loaded whole. Canonical context routes each query to the current doc, so the agent reads the right slice for the task, not everything and not a fixed blob.
How do I give my agents canonical context?
Index your docs and serve the one current doc per query with a freshness marker. trovex does this locally; it returns a path:line pointer marked canonical, stale, or duplicate, down to the section.
Serve your agents canonical context.
One current answer per query, with a freshness marker — in about a minute.
uv tool install trovex
Open source. No cloud, no API keys. Your docs never leave your machine.