Today we'll look at how Claude Code remembers things between sessions with auto memory, and how it fits next to the CLAUDE.md files we write ourselves.
The split is simple. We write CLAUDE.md to give Claude instructions. Claude writes auto memory to keep notes for itself. Auto memory is on by default in local sessions.
Let's dive in.
What Gets Saved
As it works, Claude saves four kinds of notes, and records the kind in each file's frontmatter:
- user: our role, expertise, and how we like to work
- feedback: corrections we give and approaches we confirm
- project: ongoing work, deadlines, and decisions the code doesn't show
- reference: where to find things outside the project, like an issue tracker
It skips anything it can work out from the codebase, and anything our CLAUDE.md files already say. It also doesn't save something every session, only what looks useful later. When it does, we'll see a message like "Saved 2 memories".
Where It Lives
Each project gets its own folder:
~/.claude/projects/<project>/memory/
MEMORY.md # the index, one line per memory
user_role.md # one memory per file
feedback_testing.md
reference_dashboards.mdThe <project> comes from the git repository, so every worktree and subdirectory of the same repo shares one memory folder. It stays on our machine, and isn't synced to other machines or cloud sessions.
What Loads
At the start of each conversation, Claude Code loads the first 200 lines or 25KB of MEMORY.md, whichever comes first. The topic files don't load at startup. Claude reads them when it needs them.
- [Prefers bun](feedback_bun.md): use bun, never node or npm
- [Staging deploys](reference_staging.md): how we ship to staging
- [Q4 freeze](project_freeze.md): no schema changes until Jan 5That's why the index stays short. When MEMORY.md gets close to the limit, Claude Code reminds Claude to tighten it up. Neat!
The /memory Command
/memory is the control panel:
> /memoryIt lists our CLAUDE.md and CLAUDE.local.md files, has a toggle for auto memory, and opens the memory folder. Picking a file opens it in our editor. Memory files are plain markdown, so we can edit or delete anything that's wrong.
Telling It What To Remember
When we say something like "remember that the API tests need a local Redis", Claude saves it to auto memory. If we want it in CLAUDE.md instead, we just ask: "add this to CLAUDE.md".
For instructions that only matter in part of the codebase, .claude/rules/ is the tidier spot:
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Validate every request body with zod
- Use the shared error response formatA rule with paths only loads once Claude reads or edits a matching file. Rules without paths load at launch, like CLAUDE.md does.
Turning It Off
The /memory toggle saves autoMemoryEnabled to our user settings. To switch it off for one project, set it in that project's settings:
{
"autoMemoryEnabled": false
}And autoMemoryDirectory moves the whole thing somewhere else, if we'd rather keep it in a synced folder.
Watch Out
Subagents don't get the main conversation's auto memory, apart from forks, which inherit the whole parent conversation. And memory files are never cleaned up automatically. They stay until we or Claude edit or delete them, so it's worth a look through /memory every so often.
More info about auto memory can be found at the Claude Code docs.