Claude Code Memory: 7 Failures and the Rules That Fixed Them

In March I wrote up the five-layer Claude Code memory system I use for client work. I have run it daily since then, and by October the knowledge base held about 860 markdown files. Most of it still helped. Some of it had quietly stopped working, so on 22 October 2026 I audited it and measured what I found.

This post is the result: seven failures, the rule that now prevents each one, and the free template that packages those rules. The examples use Acme and Example Client, never real clients.

The before and after (measured 22 October 2026)

These numbers describe my own knowledge base, not the template. The template ships the rules and the limits, not my files.

If you want the rules without doing the cleanup yourself, start from the scaffold:

👉 github.com/Sinfjell/personal-memory-template: click Use this template, make the copy private, run /setup.

The 7 failures

Each one follows the same pattern: what I saw, why it happened, and the rule I run now.

The index became a dump

Symptom. The agent stopped reading the whole index, so it missed rows that pointed to the right file, like the one for clients/acme.md.

Cause. My rule said the index should stay under 200 lines. It was 305. Rows had grown into paragraphs, and nothing enforced the limit.

Rule. The index routes; the files explain. Use fixed limits and a sub-index per folder. My MEMORY.md is now 133 lines with 3 sub-indexes. The template sets the limit at 150 lines with rows of at most 150 characters, and its lint script checks both.

Claude Code's auto-memory index hid my newest memories

Symptom. Corrections I had saved recently never showed up in new sessions.

Cause. The Claude Code memory docs say only the first 200 lines or 25 KB of the auto-memory index are loaded. Mine was 202 lines, and new memories were appended at the bottom, so the 13 newest were never read. Nothing warned me. The docs now say Claude Code returns an error telling Claude to rewrite the index when a write puts it over the limit, so you may catch this sooner than I did.

Rule. Group the auto-memory index by topic and keep it short. Move durable facts into the knowledge base. Mine is now 102 lines, and all 239 memories are linked from it.

A copied rules file drifted to the opposite

Symptom. Codex and Claude Code followed different rules in the same repo.

Cause. I had copied my rules file for Codex. The two copies were edited separately until one said the opposite of the other.

Rule. One rules file. In my setup the copy for the other tool is generated, never edited by hand. The template uses one AGENTS.md and a CLAUDE.md that only imports it.

One debugging.md that nobody could search

Symptom. A question like "How did we fix the Example Client webhook timeout?" didn't find the answer, even when it was written down.

Cause. The rule was "put bugs in debugging.md". It became one 327 KB file that nobody, human or agent, found anything in.

Rule. One file per topic, plus an index. The template has engineering/debugging/ with an INDEX.md, and its lint script flags any topic file over 40 KB.

Client files turned into diaries

Symptom. Opening clients/acme.md meant scrolling past months of dated notes before reaching the current stack and contacts.

Cause. Every update was added as a new dated heading on top of the facts. One file had 46 of them.

Rule. Current state in the client file, history in a separate log. In the template the entry file holds the current state (at most 120 lines), and dated events go to clients/<slug>/changelog.md.

The health check died quietly

Symptom. Dead links and oversized files piled up. Nothing failed loudly.

Cause. My weekly health check stopped running, and nobody noticed for three months.

Rule. A check that runs without me remembering it. In my knowledge base a lint script now runs before every commit, which took dead links from 31 to 0 and blocks new ones. The template ships the same kind of script (python3 scripts/lint.py) and recommends running it monthly. If you want it on every commit, add it as a git hook yourself.

Search needed every word to match

Symptom. A question like "What invoice format does Example Client need?" returned nothing if I used one word that wasn't in the file.

Cause. My search required every word of the query to be in the file. One unknown word meant zero hits.

Rule. Partial word matching, measured with real questions. I wrote 20 test questions from real work and checked whether search put the right file in the top 3. That went from 50% to 85%. File count tells you nothing about whether the agent finds things. A small fixed question set does.

The rules I run now

1. The index routes; the files explain. Fixed limits and a sub-index per folder.
2. Keep the auto-memory index short and grouped by topic. Respect the documented 200 lines / 25 KB.
3. One rules file. Any copy for another tool is generated.
4. One topic per file, plus an index. Debugging is a folder, not a diary.
5. Current state in the file, history in a log.
6. Automate the health check. A lint script that runs without you remembering it.
7. Test search with real questions. Measure it, don't assume it.

These sit next to the ingest loop from Claude Code automation, and they're written in the same spirit as my custom MCP server lessons.

The overall pattern is the one in Karpathy's LLM Wiki: raw sources stay as they are, the wiki holds the synthesis, and a short schema says how to write. Most of what went wrong for me was size, placement, and not checking what the agent actually sees.

Start from the template

I packaged the working rules into personal-memory-template:

• One rules file (AGENTS.md, with CLAUDE.md importing it) and the size limits above
• Client folders with reading maps, and a folder layout for engineering, playbooks and policies
• Versioned skills: ingest and an example invoice-client skill
• A lint script (scripts/lint.py) for limits, links and skill versions
• /setup, an onboarding interview that builds the first version of your knowledge base
• A simple Norwegian variant for non-coders, for a Claude Project or Notion

Use it as a template, make your copy private, run /setup, and point your global Claude Code instructions at its MEMORY.md. The March post still explains the architecture. This post is what broke when I used it every day.

I'm writing up the rest of this in a short series: trimming CLAUDE.md, troubleshooting auto-memory, the template itself, and versioning skills. Subscribe below to get them by email when they're published.

👉 Use the template on GitHub

FAQ: Claude Code memory