// Blog / maintenance
How to keep agent repo context fresh after commits and merges
Agent context goes stale the same way docs go stale: code changes first, and the summaries only catch up if maintenance is explicit.
// direct answer
Short answer
Keep context fresh by syncing tracked files, rebuilding routing and search indexes, running doctor, updating stale module cards or repair queue items, and treating changed source as stronger than generated summaries until freshness is restored.
Keep repo-local agent context current after commits, merges, and module changes.
// real failure mode
The failure mode
A merge changes source files, tests, or module boundaries, but the agent context still describes the pre-merge world.
The next agent reads a plausible summary and plans against old behavior.
Freshness needs to be tracked as a maintenance signal, not remembered as a vibe.
// maintenance model
The repo-local fix
After meaningful commits or merges, run sync and rebuild the compact artifacts agents read first.
If source changed under a module summary, mark or repair the knowledge rather than pretending it is still current.
Use doctor output as the readiness signal for the knowledge layer, not for product correctness.
// concrete example
A merge that touches policy files
A merge modifies policy enforcement and tests. The old module card still says the policy path is advisory.
Freshness sync detects the changed files, routing is rebuilt, and the repair queue gets a recheck item.
Until the card is repaired, agents can use it for routing only and must re-read current source.
// repo proof
Repo proof to inspect
Fresh public archives intentionally do not ship all runtime artifacts. Run import/release to generate routing, trust, freshness, search, metrics, and PR summary outputs.
.knowledge/freshness.json
Freshness records whether tracked context may be stale after source changes.
- Post-commit checks
- Detecting stale knowledge
- Proving runtime behavior
.knowledge/maintenance/trust_report.json
Trust buckets should change when knowledge cannot be safely used for planning.
- Agent caution level
- Repair prioritization
- Approving source changes
.knowledge/maintenance/routing_bundle.json
The routing bundle is the first thing new sessions read, so it must reflect current module routes.
- Session start
- Module routing
- Skipping source and tests
.knowledge/search/index.json
Search should not point agents toward removed or stale artifacts.
- Local knowledge search
- Finding updated artifacts
- Trusting ranking as correctness
.knowledge/tools/install-git-hooks.js
Git hooks can refresh knowledge after commit, merge, or checkout when a team wants that workflow.
- Optional local automation
- Post-change hygiene
- Mandatory CI enforcement
.knowledge/github-action-templates/
knowledge-health.yml, knowledge-pr-summary.yml, and knowledge-evaluation.yml turn freshness checks into repeatable CI workflows.
- CI health checks
- PR summaries
- Evaluation gates
- Replacing human repair decisions
// command transcript
Commands and expected checks
node .knowledge/tools/sync-tracked.js - expected
- Tracked files are compared and freshness/trust state is updated.
- inspect next
- .knowledge/freshness.json and trust_report.json
node .knowledge/tools/install-git-hooks.js - expected
- Optional git hooks are installed to refresh knowledge around commit, merge, or checkout workflows.
- inspect next
- .git/hooks/ and .knowledge/maintenance/events/
node .knowledge/tools/build-routing-bundle.js - expected
- The route-first artifact is rebuilt after changes.
- inspect next
- .knowledge/maintenance/routing_bundle.json
node .knowledge/tools/build-search-index.js - expected
- Local knowledge search is rebuilt.
- inspect next
- .knowledge/search/index.json
node .knowledge/tools/doctor.js - expected
- The knowledge layer readiness is checked.
- inspect next
- .knowledge/maintenance/quality_report.json
How context becomes current again
// field guide
Post-change maintenance
| Change type | Minimum action | Extra action |
|---|---|---|
| Docs-only copy edit | Build search if knowledge docs changed. | No module repair unless behavior claims changed. |
| Small copy edit | Do not run full maintenance by default. | Rebuild search only if knowledge docs changed. |
| Source file changed | Run sync and rebuild routing. | Recheck module card if summary mentions that path. |
| Tests changed | Run sync and note changed evidence. | Update evidence if test expectations changed. |
| CI setup | Copy knowledge-health.yml, knowledge-pr-summary.yml, or knowledge-evaluation.yml. | Keep human repair review for stale context. |
| Merge across modules | Run full doctor and routing rebuild. | Review repair queue and Inspector. |
// guardrails
What the agent should not trust blindly
- Freshness is not correctness. It only tells the agent whether context may be stale.
- When source changed, generated summaries become weaker until rechecked.
- Keep maintenance commands boring and repeatable so agents can run them safely.
// common mistakes
Common mistakes
- Updating docs but not rebuilding search.
- Letting a stale module card stay trusted after source changes.
- Treating doctor score as proof that code works.
// quick FAQ
FAQ
Should freshness maintenance run in CI?
It can. The useful pattern is to run health and PR summaries in CI while still letting humans decide how to repair stale context.
What if a module remains low-confidence?
That is acceptable if agents treat it as route-only context and re-read source before behavior claims.
What if freshness.json is missing in a fresh archive?
Run flow import first. Freshness is generated inside the consumer repository so it can reflect that repo's actual tracked files.
// page-specific next step
Use this page after merges or module changes
Run sync, rebuild routing and search, run doctor, and make unresolved context debt visible before the next agent session.