The Silent Weight of AI Memory: Why Your CLAUDE.md Is Eating Your Repository
When Documentation Becomes a Hoarder's Paradise
Picture this: you start a new project with a clean CLAUDE.md file. A few helpful tips go in. A couple of context notes. A warning about that weird edge case in your authentication flow. Months later, you open the file and it's a sprawling novel of contradictory instructions, outdated reminders, and desperate appendices that no one fully understands anymore.
This isn't just your experience. It's a universal phenomenon.
Research analyzing 247,694 instruction lifetimes across 1,867 repositories reveals a startling pattern: agentic prompts don't just grow—they grow without bound, more than tripling over their operational lifetime (+226%). On average, these files gain +4.9 net instructions with every single commit. The file never shrinks. It only expands.
But here's what makes this genuinely fascinating: the older an instruction gets, the less likely it is to be deleted. The data shows a log-hazard of -0.032 per commit, meaning instructions become increasingly immortal the longer they sit there. It's not that nobody wants to clean house—it's that nobody knows if they can safely remove anything.
The O(2^|D|) Problem
Why is this happening? The researchers call it "catastrophic remembering"—the inverse of the well-known "catastrophic forgetting" problem in machine learning. But you don't need a PhD to understand why it occurs.
Think about the cost calculation: adding a new instruction is cheap. You see a problem, you write a fix, you move on. The immediate cost is low, and the perceived benefit is clear.
But removing an instruction? That's a different beast entirely. You have to understand every place where that instruction might matter. You have to reason about interactions with all the other instructions. You have to verify that removing it won't break something subtle and important. The researchers calculated this cognitive cost as O(2^|D|) in a prompt with |D| instructions—meaning it grows exponentially with the number of existing instructions.
So developers do what rational people do: they stop trying. New instructions get appended. Old ones remain. The file grows.
Comments: The Unsung Hero
Here's where the research gets genuinely exciting. The solution isn't better prompting techniques or smarter models. It's something developers have used since the dawn of programming: comments.
The researchers took an interesting approach—they inverted IFEval, a standard benchmark, to create "verifiable worlds" where the optimal prompts are actually known. When they added comments encoding latent reasoning to prompts, excess instruction growth dropped from +211.3% to just +1.4%.
That's a 99.3% reduction.
But the real kicker? These comments didn't just control growth—they improved actual instruction-following performance by up to 23.1% on real-world tasks. Comments aren't just organizational clutter. They're load-bearing structures that help AI assistants reason about context correctly.
Why This Matters Now
We're living through a fundamental shift in what "code" means. The researchers ask a provocative question: "If English is the new code, why don't we have comments yet?"
It's a fair point. For decades, developers have understood that code without comments is technical debt. Comments explain the "why," not just the "what." They capture intent, edge cases, and institutional knowledge that can't be inferred from syntax alone.
Yet in our rush to hand off more and more to AI coding assistants, we've been treating natural language instructions like they're different. We write imperatives—do this, don't do that, remember to check X—without explaining our reasoning.
The result is what we're seeing in those ballooning CLAUDE.md files: instructions that nobody fully understands, that may conflict with each other, and that grow without any mechanism for rationalization.
The Path Forward
If you maintain a CLAUDE.md or similar agentic prompt file, here's what the research suggests:
Comment your instructions, not just your code. Explain why a rule exists. Document edge cases. Capture the reasoning behind decisions.
Embrace periodic rationalization. Don't just append—rewrite. The research explicitly notes that wholesale rewrites are one of the only things that stop the growth.
Treat your AI instructions like onboarding documentation. Would you hand a new developer a 400-line file of undifferentiated rules? Your AI assistant deserves the same clarity.
The trajectory we're on isn't sustainable. Every new project starts with good intentions and ends with an unmaintainable mess. But the fix might be simpler than we thought: write for the human (or AI) who'll read your instructions in six months, not just the one answering your question today.
Comments aren't clutter. They're the architecture of understanding.