How Claude Code remembers your project

Every Claude Code session starts with a fresh context window. Two things carry knowledge from one session to the next: a CLAUDE.md file you write, and notes Claude writes for itself, called auto memory. They do different jobs, and knowing which is which saves a lot of confusion.

The two, side by side

CLAUDE.mdWritten by you. Instructions and rules: coding standards, workflows, how the project is laid out. Can live at project, user or organization level. Loaded at the start of every session.
Auto memoryWritten by Claude. Learnings and patterns: your preferences, corrections you gave it, project context it cannot work out from the code. Kept per repository. Only the start of its index file is loaded each session.

Use CLAUDE.md when you want to steer Claude's behavior. Auto memory is there so Claude can learn from your corrections without you having to write anything down.

What auto memory saves

Claude files its notes under four kinds: user (your role and how you like to work), feedback (corrections and approaches you confirmed), project (ongoing work and decisions it cannot derive from the code or git history) and reference (where to find things outside the project, such as a tracker or a dashboard). It skips what it can read from the codebase, and what your CLAUDE.md already says. It does not save something every session.

Where it lives

Each project gets a folder at ~/.claude/projects/<project>/memory/. All worktrees and subdirectories of the same git repository share it. It holds a MEMORY.md index, one line per memory, and one file per topic. At the start of a session Claude loads the first 200 lines or 25 KB of the index, whichever comes first. The topic files are read on demand. The files are plain markdown on your machine: not shared across machines, and yours to read, edit or delete.

Look, edit, switch off

/memory lists the memory files, opens one in your editor and has the auto memory toggle and a link to its folder.
Ask Claude to "remember that the API tests need a local Redis" and it saves that to auto memory. To put something in CLAUDE.md instead, say so: "add this to CLAUDE.md".
To turn it off for one project, set autoMemoryEnabled to false in that project's settings. An environment variable, CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, does the same.

When Claude ignores your CLAUDE.md

The documentation is direct about this: CLAUDE.md is context, not enforced configuration. Claude reads it and tries to follow it, but there is no guarantee, especially with vague or conflicting instructions. Check, in this order:

Is it loaded? Run /context and look under Memory files. If your file is not listed there, Claude cannot see it. (A CLAUDE.md in a subdirectory loads on demand, so it will not be listed at launch.)
Is it in the right place? Project, user and organization files load from different locations. See the .claude folder explained.
Is it specific? "Use 2-space indentation" works better than "format code nicely".
Do two files disagree? If two files give different guidance for the same thing, Claude may pick one arbitrarily.
Is it too long? The docs say files over 200 lines use more context and may reduce adherence. Trim what Claude can find in the code, such as directory listings and dependency lists. Splitting into @path imports tidies the file but does not save context, because imported files load with the file that imports them. Our CLAUDE.md checklist goes through this.
Must it happen every time? Then it is not a CLAUDE.md job. A hook runs as a shell command at a fixed point whatever Claude decides. See CLAUDE.md, skill, hook or subagent for how to choose.

When it seems to forget after /compact

According to the documentation, the project-root CLAUDE.md survives compaction: Claude re-reads it from disk afterwards. Nested CLAUDE.md files and path-scoped rules load again when needed. If an instruction vanished, it was probably given only in the conversation. Put anything that must persist in CLAUDE.md. For carrying work between sessions, a handoff note helps too.

Already have an AGENTS.md?

Recent versions of Claude Code can read a repository's AGENTS.md as the project instructions, but by default only when there is no CLAUDE.md in your working directory or above. If both exist, it reads CLAUDE.md. The simple way to share one file is a CLAUDE.md that imports it with an @AGENTS.md line. This depends on your version and settings, so check the memory page of the documentation for yours.

Try it on something harmless

Run /memory and open the auto memory folder. Read what is in there.
Run /context and check that the CLAUDE.md files you expect are listed.
Find one vague line in your CLAUDE.md and rewrite it so a stranger could check whether it was followed.

This follows Anthropic's memory documentation as we read it in October 2026. We are not affiliated with Anthropic. We wrote this from the documentation and have not tested every case. Where this page and the documentation disagree, the documentation wins.

The free loop-stop skill gives long tasks a limit and a stop rule. If you want a second pair of eyes on your CLAUDE.md and settings, the Tune-Up Kit is a checklist for exactly that.