You know the story. One night in 48 BC, Caesar's fire swept through the Library of Alexandria. Scrolls burned, and the collected knowledge of the ancient world was gone by morning.

It's a great story. It's mostly wrong.

The library declined gradually over several centuries. The decline started in 145 BC, when Ptolemy VIII purged the city's intellectuals. The head librarian, Aristarchus of Samothrace, resigned and went into exile on Cyprus. Other scholars fled to other cities, "where they continued teaching and conducting scholarship." Caesar's fire did happen, but nobody knows how much it destroyed, and the library seems to have survived or been rebuilt soon after.

There was no single night, just a slow loss of the people who used it. The scrolls stayed on the shelves while the readers walked out the door. And the knowledge that survived didn't survive on a shelf. It survived in the scholars who kept teaching it.

Alexandria didn't burn. It stopped being read.

Now look at your repo.

Everyone recognizes the pile. Specs. Plans. Lessons learned. Session notes. Most of us have one. Mine is smaller, but it's growing.

We're building Alexandria in every repo: shelves of markdown, written for AI, that no agent ever reads. Specs nobody loads are bloat, and so are lessons nobody uses. A lesson no agent consumes isn't memory. It's a diary entry.

Here's the test I now apply to anything written for an agent: will the next agent actually load it?

Agents don't browse the stacks. They auto-load one root instruction file, AGENTS.md (or CLAUDE.md, same idea). Everything else gets read only if something points to it or an agent happens to grep its way there. The rest is the scroll on the shelf after the scholars left.

Knowledge survives by circulating. A text that gets copied and taught lives. A text that gets filed dies, fire or no fire. Your docs folder is the building. What survives is what gets executed.

I've been reading through the spec-driven and context-preserving projects that all chase this same problem. The idea that stuck came from Capital One's open-source Context Specs: after a merge, propose edits to the agent's memory, instead of letting lessons pile up. Their announcement puts the whole problem in two lines:

So I built my own version, a post-merge lesson tool that reads a merged PR and proposes lessons for the agent docs. Then I ran three past merges from one of my repos through it to see what it would keep.

I've argued before that a spec is mostly a copy of what the code and tests already say, minus the part where it runs. Even my mostly vibe-coded repo had piled up docs and histories full of old vibes. The tool found eleven candidate lessons. Seven were already obvious from the code or already written down somewhere. The value wasn't in collecting knowledge. It was in knowing what to drop. Saying no is the hard job.

The tool kept four and wrote them up as 277 words across three new files. Then I asked the question that matters: would a fresh agent behave any differently?

No. Nothing linked the three new files. No root instruction file pointed at them. A fresh agent would never open them. The tool had written a perfect diary entry.

It got better. Or worse.

The best catch was a count drifting between the README and the manifest. The README said "Ten." The manifest listed eleven. Great catch, except the drift only existed on the tool's own branch. The tool's own PR introduced the bug it then wrote a lesson about.

And that lesson? As prose, it sits in an unlinked file. As a lint that compares the count word to the manifest's list, it's a few lines, and it catches the drift on every commit, forever, with no reading required.

One more, because honesty is the point of this exercise. A bug in how the tool picked its diff base pulled unrelated features into the analysis. One merge's diff grew from about 1,260 added lines to about 2,090. The tool meant to extract signal was quietly feeding itself noise.

That's the thesis. So far it has made my repos saner, and I suspect it makes the agents working in them better too.

A paragraph in a markdown file that says "keep the README count in sync" is a claim. It's true until someone forgets. It depends on an agent loading the file, reading the paragraph, weighing it against everything else in context, and choosing to act on it.

A lint that fails the build when the count is wrong is a fact. It doesn't need to be loaded. It doesn't compete for attention. It runs.

So the fix isn't a better lesson. It's a check. Mine caps AGENTS.md at 400 words and fails when a file under docs/topics/ isn't linked from it. The lesson "unlinked docs are invisible" became something the repo enforces on itself.

I'd already seen this work. Using an AGENTS.md-trimming skill I wrote a while back, I had rewritten another project's AGENTS.md as a 313-word map, with the detail moved into linked topic files. Always-loaded context for Claude Code dropped from roughly 2,975 tokens to under 500. What keeps it that way isn't discipline. It's the check wired into pre-commit.

I don't think the answer is "delete your docs." The research doesn't say that either.

An ETH Zurich study (Gloaguen et al., "Evaluating AGENTS.md") found that context files don't generally improve task success and raise inference cost by more than 20% on average. But one finding stood out:

That's the job: the why behind a weird decision, the thing no diff shows.

My experiment backs this up. Some of the best lessons came from notes an agent wrote down mid-session, not from the merged diffs. By merge time, the why was gone from the code. If nobody captures it while it's happening, no tool can mine it later.

OpenAI's harness engineering post describes the shape that works:

Short. Linked. A map, not a library.

The obvious pushback: won't smarter models make all of this moot? Boris Cherny, who leads Claude Code, keeps saying some version of that:

I think he's right, and it makes the case stronger. A smarter model needs less of the library up front, not more. What it still can't do is find a lesson nobody wrote down, follow a pointer nobody added, or notice that a doc is quietly wrong. His answer for that is verification, which he calls "probably the single most important thing that people do not get right" (via Search Engine Journal).

Kent Beck worked this out for tests twenty years ago. In Test-Driven Development: By Example he answers the question "When should you delete tests?" with two criteria, confidence and communication:

He's even blunter in his newsletter, about a test that no longer tells you anything:

Swap "test" for "markdown" and the rule holds. A spec, plan or lesson that doesn't change what the next agent does creates no new feedback. It just consumes resources: tokens, context, the reader's attention, and someone's time to maintain it. Tests pile up, markdown piles up, and every run pays for the whole stack.

So apply Beck's criteria to your docs. Does this file raise confidence that the agent will do the right thing? Does it communicate something no other file or check does? If neither, delete it.

Sometimes the honest move is bigger than pruning. Let the old library go, keep what's still in use, and rebuild something smaller that teaches the same lessons without the tomes.

You don't need a bigger library. You need fewer scrolls and more scholars.

So prune your AGENTS.md this week. Keep it short, make it a map, and turn every lesson you can into a check. I'm reworking my own tooling around these rules. More soon.

What's one lesson sitting in your agent docs right now that should be a test instead?