Claude Code Memory Explained: CLAUDE.md, Auto Memory and What Survives a Session

Every Claude Code session starts with an empty context window. Nothing from yesterday's session is in it unless something puts it there. Claude Code has two built-in ways to do that, and once you know what each one loads, and when, most "why did it forget that" moments stop being a mystery.

The two memory systems

Claude Code reads two kinds of memory at the start of a session.

CLAUDE.md files are instructions you write. They hold facts that should be true in every session, such as the command that runs your tests or a rule the agent must never break.

Auto memory is notes Claude writes for itself. When it learns something about you or the project, such as a preference you stated or a correction you made, it can save that as a small file and read it back next time.

Both are context, not configuration. Claude reads them and tries to follow them, but nothing enforces them. A vague or contradictory instruction in either one can be ignored.

Where CLAUDE.md files live

Claude Code looks for CLAUDE.md in several places and loads them from broadest to most specific:

A project file loads in full at launch, so every line costs context in every session. Anthropic's own guidance is to keep each one under 200 lines. Subfolder files load on demand, which makes them the right place for rules that only matter in one part of the codebase.

To see which files loaded, run /context all in a session and look under Memory files.

Where auto memory is stored

Auto memory lives outside your repo, in your home folder:

~/.claude/projects/<project>/memory/
├── MEMORY.md            # the index, one line per memory
├── user_role.md         # one memory
├── feedback_testing.md  # another memory
└── ...

MEMORY.md is the index. Each line points at a topic file that holds the detail. Every worktree and subfolder of the same git repo shares one memory folder, but the folder stays on your machine. It does not follow you to another computer or a cloud session.

The 200-line limit that causes most forgetting

Only the first 200 lines of MEMORY.md, or its first 25KB, whichever comes first, load at the start of a session. Anything past that point is not read.

Claude Code warns Claude when the index gets close to the limit and tells it to shorten the file: one line per entry, detail moved into topic files, stale entries merged or dropped. If the index goes over anyway, the write still succeeds, and the end of the file silently drops out of the next session.

So if Claude remembered something last week and has no idea about it today, check the length of MEMORY.md first. The entry may simply be below the cut.

The topic files are a different story. They are not loaded at launch. Claude reads one only when the index line tells it the file is relevant, so a vague index line means the detail behind it never gets read.

What each one is good for

Put a fact in CLAUDE.md when it should hold in every session and you want to control the wording:

## Commands
- npm test: unit tests. Run before saying a change is done.

## Rules
- Never run db push. Schema changes go in supabase/migrations.

Leave a fact to auto memory when it is something Claude learned from working with you, such as the fact that you prefer one bundled pull request over several small ones. You did not write it down. Claude picked it up and will apply it next time.

Neither one is a good place for long procedures. A twelve-step deploy written into CLAUDE.md is read in full every session, including the sessions that never deploy. Anthropic's docs suggest moving procedures like that into a skill or a path-scoped rule, which loads only when it applies.

Why it still redoes work

Here is the gap both systems leave. You spend an hour with Claude getting a flaky test to pass. It finally works out that the test needs a fixed clock and a seeded random generator. The session ends.

Next week the same kind of test fails in another file. CLAUDE.md does not mention it, because you never wrote it there. Auto memory may hold a line like "tests need a fixed clock," but not the full fix, and not the check that proves it worked. So Claude works it out again, from the start.

What you want saved in that moment is the solved problem: when it applies, the steps that worked, how to check them, and the thing that looked right but failed. That is more than a preference and more specific than a project rule.

This is the job FixMyPrompt Memories does for Claude Code. When the agent solves something, it saves the lesson as a memory with those parts. At the start of the next session in that folder, the FixMyPrompt plugin tells Claude to call the memory index for the folder, so the fix is found instead of rediscovered.

A checklist when Claude Code forgets

1. Run /context all and confirm the CLAUDE.md you expect actually loaded.
2. Count the lines in ~/.claude/projects/<project>/memory/MEMORY.md. Over 200 means the end of it is not loading.
3. Look for two instructions that disagree. Claude may follow either one.
4. Rewrite vague rules so they can be checked. "Use 2-space indentation" works. "Format code properly" does not.
5. Check your CLAUDE.md length and missing rules with the free CLAUDE.md checker.

If you are still re-explaining the same fix every week, that fix needs to be saved somewhere Claude will look it up, with the steps intact.