// Blog / definition
What is repo-local knowledge routing for coding agents?
Repo-local knowledge routing is the maintained first-read path an agent uses before it spends context crawling a repository from scratch.
// direct answer
Short answer
Repo-local knowledge routing gives a coding agent one versioned, repository-owned map into current modules, evidence, trust status, stale areas, and maintenance commands. It is a routing layer, not a substitute for reading source code and tests.
Understand whether a local routing layer can reduce cold-start context work without replacing source review.
// real failure mode
The failure mode
A new coding-agent session starts by sampling README files, package manifests, source folders, tests, and old notes.
The agent may find useful context, but it has no stable signal for which summary is current, which module is risky, or which files must be checked before behavior changes.
The result is repeated orientation work and a higher chance of trusting prose that should have been rechecked against code.
// repo-local model
The repo-local fix
Repo-local knowledge routing gives the agent one maintained first-read path inside the repository.
The routing bundle points to modules, trust buckets, changed or stale files, wiki/search artifacts, and maintenance commands.
It does not replace source review. It directs the agent toward the source, tests, evidence, and repair queue that matter for the current task.
// concrete example
Concrete example
A task mentions runtime execution. Instead of crawling every top-level directory, the agent reads the routing bundle, sees which module owns runtime execution, checks whether that module is trusted, and then re-reads the current implementation and tests before editing.
If the module is marked low-confidence or stale, the agent treats the knowledge file as a route hint only. It should not quote the summary as truth until source and tests confirm it.
// repo proof
Repo proof to inspect
.knowledge/maintenance/routing_bundle.json
This is the compact route into modules, trust state, stale items, and the next files to inspect.
- Choosing the first source files to read
- Finding the relevant module boundary
- Claiming runtime behavior
- Skipping source and tests
.knowledge/modules/*.json
Module cards summarize ownership, confidence, and important paths, but their trust state controls how much weight they deserve.
- Planning a targeted read
- Spotting low-confidence areas
- Treating old summaries as current
- Making security or billing claims without code
.knowledge/evidence/*.json
Evidence ties claims back to commands, files, or observed checks so the agent can avoid free-floating prose.
- Finding supporting checks
- Reviewing source-of-truth references
- Assuming passing evidence is permanent
- Ignoring stale timestamps
.knowledge/maintenance/repair_queue.json
Knowledge debt becomes visible work instead of hidden uncertainty inside the prompt.
- Prioritizing rechecks
- Surfacing stale or suspect areas
- Blocking every edit
- Replacing engineering judgment
// command transcript
Commands and expected checks
node .knowledge/tools/install-agent-integrations.js - expected
- Agent entrypoints are installed or refreshed for Codex, Claude Code, OpenCode, and local commands.
- inspect next
- .agents/skills/*/SKILL.md and .knowledge/agent-integrations/
node .knowledge/tools/flow.js import - expected
- The repository is ingested without overwriting curated knowledge.
- inspect next
- .knowledge/project_index.json and .knowledge/modules/*.json
- caution
- Use this when bootstrapping or refreshing an existing repository.
node .knowledge/tools/flow.js release --no-color - expected
- Routing, trust, freshness, search, metrics, and Inspector outputs are rebuilt.
- inspect next
- .knowledge/maintenance/trust_report.json and .knowledge/maintenance/routing_bundle.json
From cold start to targeted source review
// field guide
Routing is / routing is not
| Routing is | Routing is not |
|---|---|
| A first-read map into current code, tests, evidence, and trust state. | A hosted memory product that the agent must blindly trust. |
| A way to mark stale, suspect, low-confidence, or advisory knowledge before use. | A shortcut around reading source for critical behavior. |
| A repo-owned artifact that can be reviewed with the codebase. | A private chat-history habit that only one agent can see. |
// guardrails
What the agent should not trust blindly
- Use trusted and near_trusted knowledge for routing and limited planning.
- Use routing_trusted knowledge only to choose files and boundaries.
- For auth, billing, runtime execution, queues, storage, signing, secrets, migrations, security, concurrency, or anything stale/suspect/low-confidence, re-read current source and tests.
// common mistakes
Common mistakes
- Treating the routing bundle as proof of product behavior.
- Using a wiki page as source of truth when the module is marked stale or low-confidence.
- Letting every agent invent a new onboarding path instead of sharing one repo-local first read.
// quick FAQ
FAQ
Is repo-local routing the same as RAG?
No. RAG retrieves chunks. Repo-local routing is a maintained first-read map that tells an agent what to inspect and how much to trust each knowledge artifact.
Can an agent edit code based only on routing_bundle.json?
No. The routing bundle should point the agent to source, tests, evidence, and stale areas. Current code and tests still decide behavior.
// page-specific next step
Use this page when you define the first-read contract
Start with the routing bundle as the agent's map, then require source and test reads before behavior-changing edits. That keeps the workflow concrete without pretending the knowledge layer is magic.