The Knowledge Graph Gives You the What. The Why Was Never in the Folder.

The compiled-knowledge idea has won. In the span of a few months, “have your AI agent compile the codebase into a persistent, queryable structure instead of re-reading raw files every session” went from a clever framing to a default expectation, with tools like Graphify turning it into a one-command experience. The pattern is sound, the token economics are real, and if you work with coding agents on any non-trivial repository, you should be using something like it.

This piece is about the caveat at the bottom of that story, because the caveat is bigger than the story.

The caveat

The best writeups on compiled knowledge are honest about the boundary. A knowledge graph tells you what connects to what. It does not tell you why the architect made a particular trade-off, what constraints shaped the design, or what failed attempts led to the current approach. That context, as one recent piece put it, “still lives in your team’s heads, in pull request discussions, and in commit messages.”

Read that sentence as an engineer and it sounds like a limitation. Read it as someone who has watched teams operate for years and it sounds like a diagnosis. Because the knowledge that lives in heads and threads has a half-life, and it is short.

What compilation cannot reach

A compilation step, by definition, transforms what you give it. Point a graph builder at a folder and it will faithfully structure everything in the folder: the code, the docs, the diagrams, even the whiteboard photos. Modern tools do this impressively well.

But consider the questions that actually cost engineering teams money:

Why is the retry threshold 3 and not 5? The answer is an incident in March and a fix that was tuned under pressure. It is in a Slack thread.

Why does this service not use the obvious caching approach? Because the team tried it, it corrupted data under a specific failover sequence, and they ripped it out. The removal commit says “revert caching.” The reason is in a PR discussion from two quarters ago.

Why can this table never be partitioned by customer? A compliance constraint from a contract nobody in the current team has read.

None of these answers are in the folder. No parser, however good, can extract knowledge from artifacts that do not contain it. The graph will beautifully map the code that resulted from these decisions while being structurally incapable of explaining any of them.

This matters more now than it did two years ago, for a simple reason: the number of actors touching your codebase without the context has exploded. It used to be new hires. Now it is every AI agent, on every task, every day. An agent that cannot see a failed attempt will re-propose it with total confidence. You pay for the same lesson twice, and the second time it is wearing a plausible-looking diff.

The why needs capture, not compilation

The structural map can be compiled on demand because its source material (the code) is always present and always current. The why cannot, because its source material is ephemeral. The decision exists for a moment, in a conversation, and then it decays. By the time anyone thinks to document it, the details are gone and the writeup never happens.

So the missing layer is not a better compiler. It is a System of Record for engineering decisions: something that captures the why at the moment it happens, in the places it happens (Slack, pull requests, issue trackers, coding sessions), structures it into units a machine can serve (decisions, constraints, rationale, failed attempts, ownership), and delivers it with citations to both humans and AI agents, scoped to the project asking.

Getting this right involves problems that compilation never has to face. Decisions supersede each other, so the record needs lineage, not just storage. A decision that is active in one project may be rejected in another, so status has to be per-project. Context goes stale, so freshness has to be tracked and displayed rather than silently assumed. And an agent should be told how a piece of context connects to the file it is editing, with a real citation, not offered a pile of vaguely similar paragraphs.

This is the layer we have been building at Decispher, and I will keep the pitch to one paragraph: it captures decision context automatically from the tools your team already uses, maintains it as a living record with lineage and per-project status, and serves it to coding agents and humans with citations. The what-layer tools map your code. Decispher records why it looks that way. They are complements, and we think most serious teams will run both.

Measure the savings, don’t benchmark them

One more thing the compiled-knowledge movement gets right: the economics are the point. Paying an extraction cost once so that every future query is cheap is a genuinely different cost profile for agentic work.

We would push it one step further: if cheaper queries are the promise, meter them. A one-time benchmark on a sample corpus tells you what a tool can do. A running measurement on every serve tells you what it is doing for your team, this week, in tokens you can audit. That is how we report savings, and we would encourage the whole category to adopt the same discipline. Compiled knowledge is a claim about compounding value, and compounding claims deserve meters, not screenshots.

Both layers, or half the answer

The shift from “AI reads your code” to “AI understands your codebase” is real, and the structural half of it is being solved quickly and well. But understanding a codebase the way a senior engineer does was never only structural. The senior engineer knows the map, and also knows the scars: what was tried, what failed, what is load-bearing, and why.

The what is in your folder, and tools can now compile it. The why was never in your folder. It needs a system of record, and the teams that build one will compound in a way that a re-parse of the repo never can.