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

Claude Code memory best practices from a real audit: seven ways my knowledge base broke, the rule that now prevents each, and a free template to start from.

Topic: Claude & MCP
Published: 2026-10-23
URL: https://productivitytech.io/claude-code-memory-lessons/

In March I wrote up the [five-layer Claude Code memory system](/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)

| What I measured | Before | After |
| --- | --- | --- |
| `MEMORY.md` (the index the agent reads first) | **305** lines, **60 KB** | **133** lines + **3** sub-indexes |
| `CLAUDE.md` (global instructions) | **460** lines, **4,815** words | **195** lines |
| Claude Code auto-memory index | **202** lines; the **13** newest memories were never read | **102** lines; all **239** memories linked |
| Changelog | **1 MB**, **1,754** entries, nobody read it | Current month only (**37 KB**), the rest archived |
| Dead links | **31** | **0**, and a check blocks new ones at every commit |
| Skills with a version | **30** of **64**, no changelog | All **64**, changelog generated from git |
| Search finds the right file in the top 3 (**20** test questions) | **50%** | **85%** |

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**](https://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](https://code.claude.com/docs/en/memory) 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`](https://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](/claude-code-automation/), and they're written in the same spirit as my [custom MCP server lessons](/custom-mcp-server-lessons/).

The overall pattern is the one in [Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): 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](https://github.com/Sinfjell/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](#foot-sub) to get them by email when they're published.

👉 [**Use the template on GitHub**](https://github.com/Sinfjell/personal-memory-template)

## FAQ: Claude Code memory

<!-- faq -->