"My CLAUDE.md is 1,000 lines and nobody knows which rules still matter"
The file is 1,000 lines now. Line 412 says never use the ORM's lazy loading. Nobody remembers who added it or which bug it was dodging, and the ORM has shipped two major versions since. Is it stale? Probably. Will anyone delete it? No. Deleting a rule you can't attribute is a gamble with no upside, so it stays. They all stay. The agent reads the whole file every session and the rules that matter drown in the ones that might not.
Rules files only grow because a rule, as written, carries no metadata. No date, no author, no reason. You can't ask a bare imperative whether it's still true. A rule you can't attribute is a rule you can't retire.
The standard advice, keep it short and prune regularly, is correct and doesn't survive contact with reality. Pruning requires exactly the context the file doesn't store.
What worked for us is a complement, not a replacement, and the scope matters. We build kgai, and it does not manage your CLAUDE.md. Rules files stay the right place for standing instructions to the agent. What kgai records is the layer underneath, your team's engineering decisions, each one an immutable event in an append-only log carrying who, when, and why. When a rule exists because of a decision, the decision is where the context lives. And when the constraint dies, you don't squint at a line. You record a superseding decision, supersession is an explicit link with a reason, the old decision stays queryable, and trimming the corresponding rule turns mechanical instead of scary. Recall returns only decisions in force, so an agent asking about an area gets the current picture without the archaeology.
There's a quiet payoff for the file itself. A rule backed by a recorded decision needs less prose in CLAUDE.md, because the why doesn't have to be inlined next to the instruction. The rule can be one line again.
The pattern is bigger than CLAUDE.md. Repeal needs a record makes the full argument, and git blame tells you what, not why is the same disease on the code side.
kgai is a Claude Code plugin plus a standalone kg CLI, local-first, no server, capture automatic through a skill and hooks, MIT.
If your rules file is past the point of honest reading, two commands add the decision layer underneath it. And if you're weighing tools, the comparison page is honest about ours too.
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.