// Blog / comparison

Local-first agent memory vs RAG for coding agents

RAG can retrieve code fragments. A local-first memory layer tells the agent which fragments, summaries, and evidence are trustworthy enough to inspect.

technical blog Architecture comparison and evaluation Published May 25, 2026 Updated May 25, 2026

Open GitHub Read .knowledge hub

// direct answer

Short answer

Use RAG for retrieval and search across large text or code collections. Use a repo-local memory layer for routing, trust, freshness, repair state, source-of-truth order, and repeatable agent onboarding. In a coding workflow they are complementary, but RAG alone does not solve stale or low-trust context.

Decide whether a coding team needs a repo-local memory layer, RAG, or both.

// real failure mode

The failure mode

A retrieval system can surface the right-looking file and still miss whether the summary is stale, advisory, or contradicted by current tests.

Coding agents do not only need chunks. They need a route into the repository, a trust label, and a rule for when prose must lose to code.

Without that layer, retrieved context can feel precise while the agent is still operating without a source-of-truth contract.

// repo-local model

Where local-first memory fits

.knowledge keeps the operating context in repository files: routing bundle, module cards, evidence, trust report, freshness, search index, and repair queue.

A RAG system can still index those artifacts, but the repo-local layer gives the agent the rules for how to 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 should not trust raw retrieval

A user asks an agent to change authentication behavior. RAG may retrieve an old architecture note and a current middleware file.

A local-first layer tells the agent whether the auth module is trusted, stale, suspect, or low-confidence. If the trust state is weak, the retrieved note becomes a hint, not a source of truth.

The agent should then inspect the current middleware, tests, and evidence before planning the change.

// repo proof

Repo proof to inspect

Trust labels

`.knowledge/maintenance/trust_report.json`

RAG can retrieve a summary, but the trust report says how much weight that summary deserves.

Use it for

Checking stale or suspect modules
Deciding when source re-read is mandatory

Do not use it for

Replacing tests
Approving retrieved prose as current behavior

Local search index

`.knowledge/search/index.json`

Search stays repo-owned and can index knowledge artifacts without turning them into hidden hosted memory.

Use it for

Scoped local retrieval
Finding relevant wiki, module, and evidence records

Do not use it for

Cross-session user tracking
Silent ranking without trust labels

Evidence layer

`.knowledge/evidence/*.json`

Evidence records connect a claim to commands, files, or observed checks so retrieved content has inspectable backing.

Use it for

Validating claims
Finding commands that produced reports

Do not use it for

Assuming old evidence still passes today

Route before retrieval

`.knowledge/maintenance/routing_bundle.json`

The routing bundle reduces broad retrieval to a targeted module and source path.

Use it for

Choosing what to retrieve
Finding source files to re-read

Do not use it for

Skipping source review

// command transcript

Commands and expected checks

node .knowledge/tools/search-knowledge.js "auth trust"

expected: Local knowledge search returns matching artifacts with file paths the agent can inspect.
inspect next: .knowledge/search/index.json and matched source files

node .knowledge/tools/build-search-index.js

expected: The local search index is rebuilt from repo-local knowledge artifacts.
inspect next: .knowledge/search/index.json

node .knowledge/tools/doctor.js

expected: The agent sees whether the knowledge layer is healthy enough for routing.
inspect next: .knowledge/maintenance/quality_report.json and trust_report.json

Decision matrix repo-local proof

Use the right layer for the job

01 RAG: find candidate chunks across a large corpus.

02 Local-first memory: define trust, freshness, routing, and repair state.

03 Source and tests: decide behavior before edits.

04 Inspector: make trust and freshness visible to humans.

// field guide

Local-first memory vs RAG

The useful distinction is operational, not ideological.
Question	RAG	Repo-local memory
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.
What proves behavior?	Nothing by itself.	Still current source and tests.

// guardrails

What the agent should not trust blindly

Do not treat retrieval relevance as trust.
Do not use repo-local summaries as behavior proof when the trust report marks the module weak.
Use RAG and local search to find context, then use source and tests to confirm behavior.

// common mistakes

Common mistakes

Asking retrieval to solve freshness and governance.
Putting all agent memory in a hosted index that reviewers cannot inspect.
Comparing RAG and .knowledge as mutually exclusive when they solve different layers.

// 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.

// page-specific next step

Use this page when choosing the context architecture

Start with repo-local routing and trust, then add retrieval where search breadth matters. Keep current code and tests as the final authority.

Read routing article Open GitHub See Inspector