// Blog / comparison
Repository context layer vs RAG for coding agents
RAG can retrieve code fragments. A repository context layer tells the agent which files, summaries, and checks deserve closer inspection.
// direct answer
Short answer
Use RAG to search large text or code collections. Use a repository context and verification layer to guide agents toward the right files, show when information may be outdated, and keep onboarding repeatable. The two approaches are complementary, but RAG alone does not show whether retrieved context is current.
Decide whether a coding team needs a repository context layer, RAG, or both.
// the problem
Relevant retrieval can still return outdated context
A retrieval system can surface the right-looking file and still miss whether the summary is outdated, secondary, or contradicted by current tests.
Coding agents do not only need chunks. They need a route into the repository, a confidence label, and a rule that current code takes priority over prose.
Without that layer, retrieved context can feel precise even when the agent lacks clear repository-owned verification rules.
// repository context
Where a repository context layer fits
.knowledge keeps repository context in local files: Routing Bundle, module summaries, evidence, confidence report, freshness, search index, and items to re-check.
A RAG system can still index those files, while the repository context layer explains how the agent should use them.
The practical pattern is route first, retrieve second, verify with current source and tests before behavior-changing edits.
// concrete example
A task that needs more than retrieval
A user asks an agent to change authentication behavior. RAG may retrieve an old architecture note and a current middleware file.
Conflict card: Retrieved note says auth is handled in old middleware. Current source/test says auth moved to a route guard. Decision: source/tests win.
The repository context layer shows whether the authentication summary is verified, outdated, or needs review. If confidence is weak, the retrieved note is only a pointer to current source.
The agent should then inspect the current middleware, tests, and evidence before planning the change.
// files you can inspect
Files that make repository context inspectable
Some repository-specific files appear only after setup or a health check. Run the documented setup workflow to create routing, confidence, freshness, search, metrics, and PR summary outputs.
.knowledge/maintenance/trust_report.json
RAG can retrieve a summary, while the confidence report says how much weight that summary deserves.
- Checking outdated or unverified modules
- Deciding when source re-read is mandatory
- Replacing tests
- Approving retrieved prose as current behavior
.knowledge/search/index.json
Search stays repo-owned and can index .knowledge files without turning them into hidden hosted memory.
- Scoped local retrieval
- Finding relevant wiki, module, and evidence records
- Cross-session user tracking
- Silent ranking without trust labels
.knowledge/evidence/*.json
Evidence records connect a claim to commands, files, or observed checks so retrieved content has inspectable backing.
- Validating claims
- Finding commands that produced reports
- Assuming old evidence still passes today
.knowledge/maintenance/routing_bundle.json
The routing bundle reduces broad retrieval to a targeted module and source path.
- Choosing what to retrieve
- Finding source files to re-read
- Skipping source review
.knowledge/tools/external-memory-status.js
The optional bridge exposes whether external memory is configured without making it source of truth.
- Checking optional bridge status
- Auditing source-of-truth boundaries
- Uploading repo content
- Overriding source/tests
.knowledge/external_memory/
The policy records that external memory is an optional cold-archive bridge, not authority.
- Bridge configuration review
- Policy transparency
- Runtime behavior claims
// commands to try
Commands and expected checks
node .knowledge/tools/search-knowledge.js "auth trust" - what it does
- Local knowledge search returns matching files with paths the agent can inspect.
- where to look
- .knowledge/search/index.json and matched source files
node .knowledge/tools/build-search-index.js - what it does
- The local search index is rebuilt from repo-local .knowledge files.
- where to look
- .knowledge/search/index.json
node .knowledge/tools/doctor.js - what it does
- The agent sees whether the knowledge layer is healthy enough for routing.
- where to look
- .knowledge/maintenance/quality_report.json and trust_report.json
Use the right layer for the job
// practical reference
Repository context layer vs RAG
| Question | RAG | Repository context layer |
|---|---|---|
| What does it optimize? | Finding relevant chunks. | Routing and trust before source review. |
| Where does it live? | Often hosted or index-backed. | Inside the repository as files. |
| What is the main risk? | Relevant but stale or untrusted context. | Generated summaries used beyond their trust state. |
| External memory | Can act as a cold archive bridge. | Never becomes source of truth. |
| What proves behavior? | Nothing by itself. | Still current source and tests. |
// quick FAQ
FAQ
Does .knowledge replace vector search?
No. It gives coding agents a repo-local trust and routing layer. Vector or text search can still be useful for retrieval.
Why not just index the whole repository?
Indexing helps find files. It does not tell the agent which summaries are stale, which modules are suspect, or which source files must be re-read before edits.
// next step
Choose the right context approach
Start with repo-local routing and trust, then add retrieval where search breadth matters. Keep current code and tests as the final authority.