Your agent's memory should not live in one markdown file

You start with three lines. Use TypeScript. Run tests with vitest. Deploy with git push. A week later you add a note about the API rate limit. Then a style preference. Then a debugging tip. Then the deploy process gets a second paragraph.

After a month you have fifty lines. API quirks sit next to style preferences. Architecture decisions share space with a reminder about the CI timeout. The file does its job the way a junk drawer does its job: everything is in there, nothing is easy to find.

One file is the path of least resistance. You add a line in five seconds. The alternative (create a file, name it, decide where it goes) takes a minute. The line wins every time.

Nothing ever leaves. You added a workaround note for a library bug. The library shipped a fix three weeks ago. The note stays because removing it means re-reading the file and hoping you do not delete something important. The agent cannot reorganize the file for you. So the file grows. Only grows.

Every line in CLAUDE.md rides in every context window. The agent reads fifty rules when the current task needs three. The irrelevant forty-seven lines cost tokens, which cost money. More importantly, they cost attention.

Contradictions accumulate quietly. Line 12 says "use Jest." Line 47 says "use Vitest." You migrated the test runner a month ago. The agent sees both instructions and picks one. Sometimes it picks wrong.

Code solved this problem decades ago. You do not put your entire application in one file. You use directories, imports, and split by concern. The entry point is small. It routes to the right module.

Agent memory can follow the same pattern. An entry point that lists topics. Each topic in its own file. The agent reads the index, decides which module is relevant, and reads that module. It loads ten lines instead of fifty. The ten lines are the right ten lines.

CLAUDE.md does not go away. It becomes a router. Ten lines instead of fifty. Each line points into state.

The single file becomes a table of contents, not a database. It stays short because each entry is a pointer, not the content itself. The content lives where it can be loaded on demand, updated independently, and shared across projects.