Your CLAUDE.md got too long because nothing ever leaves it
Friday afternoon, a pull request touches CLAUDE.md. Plus fourteen lines, minus zero. Nobody remarks on the ratio, because every change to that file this year has had the same shape. Someone gets burned by the agent, writes a rule so it never happens again, the rule lands. One week it's a line about the migrations folder. Next month it's a paragraph on the retry helper. The diff is always green. By now you scroll past rules you wrote yourself without recognizing them, and the agent, which reads the whole file every session, is obeying instructions for a codebase that stopped existing.
The file isn't long because people wrote too much. It's long because it has an entry procedure and no exit procedure, and anything with that property grows without bound. Nobody has to be careless. Adding a line costs one bad afternoon and thirty seconds. Removing one costs proof that the reason behind it is gone, and the file stores imperatives, not reasons. I covered that half in the thousand-line CLAUDE.md and won't repeat it. This page is about the other half. What should the exit procedure be?
Ours is simple to state. A rule leaves the file when the decision behind it has been superseded. Not when it feels stale. When a record exists saying the old constraint was replaced, by what, and why. Cleanup turns from a judgment call into a diff you can defend in one sentence.
That needs the decisions kept somewhere that knows which ones still hold. Disclosure: that is the tool we build. kgai keeps an append-only, immutable decision log and projects it deterministically into a graph, so every machine replaying the log gets the same graph. Changing your mind is a new decision with an explicit supersession link to the old one, and the link carries a reason. The old decision stays queryable, as do the dead ends the team tried and rejected. Recall returns only decisions in force, though, so the loop is short. Ask what's decided about an area, spot a CLAUDE.md rule whose backing decision has been superseded, and that line is the one to cut. Repeal needs a record is the longer argument for why the reversal has to be written down at all.
The record gets written at the write boundary, not afterwards. A skill and hooks in the Claude Code plugin capture structural decisions while the session is still making them, before anyone thinks to document anything. Recall is lexical matching plus graph traversal, with no embeddings in the read path, no daemon and no server. Team sync is opt-in through an S3 bucket you own, and each writer appends to a shard of their own, so parallel sessions never produce a textual conflict. The whole thing is MIT and ships as a Claude Code plugin with a standalone kg CLI beside it.
Your CLAUDE.md can stay short if something else remembers why each line exists and tells you when that reason expires.
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.