Comments explain the line. Nothing explains the system.
The comment above the cache lookup reads "// must check the flag first, see incident". Fine. You check the flag first. Then you notice the same flag is consulted in the billing worker, the export job, and a two-year-old migration, and no comment anywhere says why the flag exists at all, who introduced it, or what it replaced. Each line is explained. The thing the lines add up to is not.
That is the honest limit of a code comment. It is anchored to a location. It can tell you why this branch, this magic number, this odd ordering. It cannot tell you why the module boundary sits where it does, because that decision has no single line to sit above. Structural decisions are spread across a dozen files, and explaining one would mean pasting the same paragraph twelve times and keeping every copy in sync. Nobody does that, so the reasoning goes nowhere.
The gap gets expensive on an AI dev team. An agent reads comments faithfully. Local intent it respects. Structural intent it has to guess at from the code's current shape, which looks like an accident once the reasons are missing. So it tidies. It merges the two services that were split on purpose, or restores the direct database call that was routed through a queue after a real outage. The comments were all still true. They were just about the wrong scale.
We build kgai for exactly this layer, so read the rest knowing that. Instead of prose pinned to lines, it keeps an append-only, immutable decision log about elements of the system, features, services, business objects. Each decision records what changed, why, and what lost. From that log it projects a graph deterministically, so every machine that replays the same log gets the same graph. When the team changes its mind, the old decision is superseded through an explicit link that carries a reason, and recall returns only the decisions still in force. The dead ends stay queryable, they just stop being the answer. Reading is lexical matching plus graph traversal, with no embeddings in the read path, and there is no daemon and no server.
Capture happens where the change happens. The Claude Code plugin records through a skill and hooks at the write boundary, and a standalone kg CLI reads the same store from any terminal. Team sync is opt-in through an S3 bucket you own, with per-writer shards so parallel writes never produce a textual conflict. A million decisions across thirty writers' shards still answer a decision lookup in about 100 ms, though recall and free-text search are slower than that. MIT.
None of this replaces comments. Keep writing them for the line. What they were never going to hold is the argument for the architecture, the same argument git blame cannot reconstruct and that quietly erodes into decision drift when no record exists. Put the system's why somewhere an agent will read it before it starts tidying.
Try it on your repo. Two commands, MIT, nothing leaves your machine until you configure a bucket.
See how kgai compares to other tools on the comparison page, or browse the other notes.