Six months ago, we started building a knowledge graph for our codebase to preserve the reasoning behind architectural and implementation decisions. When people leave or change teams, the code remains but the context about why it was built that way often disappears.
We fed the system git history, pull request descriptions, code review discussions, and older team-chat threads. Surprisingly, review conversations became one of the best sources because that is where people usually debate the real tradeoffs.
The graph has been genuinely helpful for onboarding. New engineers can ask why a service exists or where an unusual pattern came from and get a useful answer without tracking down the longest-tenured person. We also provide the graph as context to coding assistants during refactoring, and they make noticeably better decisions with it.
The problem is freshness. Code changes faster than the graph can be updated, so after a few weeks it starts describing an outdated system. We repeatedly re-sync it, but drift returns. We originally assumed this would be a build-once project, and that was clearly wrong.
What approaches have worked for keeping this kind of knowledge current? Should updates happen when a change is merged, through CI, continuously in the background, or via periodic re-indexing?
6 Answers
Treat each merged pull request as an update event rather than waiting for a periodic full rebuild. Capture the changed files, summarize the decision, add or revise the relevant relationships, and explicitly handle renames, reversions, and superseded decisions. A nightly job can repair missed updates, but it should be a recovery mechanism rather than the primary source of truth.
Keep an eye on scale too. A general-purpose graph may work well for a medium-sized codebase, but relationship density can make traversal queries slow as the node count grows. Eventually you may need pruning, partitioning, or focused subgraphs. That adds another maintenance problem, so design the graph around the questions people actually ask rather than trying to preserve every possible connection.
Update the parts that are actually being used instead of trying to rebuild the entire graph every time. Track which nodes and relationships were included in assistant context, then prioritize refreshing those when related changes merge. This can reduce cost and maintenance substantially.
The graph is only useful if engineers encounter it in their normal workflow. We had better results when people could ask questions from the team chat or coding tools instead of opening a separate dashboard. Automatic ingestion after each merge helped, but putting the answers where developers already work made the system much more likely to stay useful.
Freshness and stability are separate concerns. The underlying graph can ingest changes continuously, but the developer-facing view could use stable snapshots based on completed pull requests or releases. That prevents the explanation someone is reading from shifting halfway through their investigation. It improves currency, though it does not guarantee that the extracted reasoning is accurate.
Make freshness part of the delivery pipeline. A CI action or merge hook can update the affected portion of the index automatically, and a lightweight instruction can require agents to update project maps when they make changes. The latter is easier for a solo developer, while automated hooks are safer once several people are contributing.
An event-driven update at merge time seems better than waiting for a nightly batch, especially if the graph is used immediately during follow-up work.