What does Claude Code's auto memory save, where is it stored, how much loads each session, and how do you turn it off?
answer
- notes Claude writes, not you
- four kinds in frontmatter
- one directory per git repository
- an index with a load limit
- a /memory toggle, a setting, an env var
basics
~20 sAuto memory is notes Claude writes about your preferences, corrections and project context, kept per repository in ~/.claude/projects/<project>/memory/. Each session loads the first 200 lines or 25KB of MEMORY.md; switch it off with /memory or autoMemoryEnabled.
solid answer
~40 sAuto memory is on by default in local sessions. Claude saves four kinds of notes, tagged by a `type` frontmatter field: `user`, `feedback`, `project` and `reference`, and skips anything derivable from the code or already in CLAUDE.md. It lives in `~/.claude/projects/<project>/memory/`, where `<project>` comes from the git repository, so worktrees and subdirectories share it; it is machine-local. The directory holds a `MEMORY.md` index plus one topic file per memory. Each session loads the first 200 lines or 25KB of `MEMORY.md`, whichever comes first; topic files are read on demand. To turn it off, use the toggle in `/memory` (it writes `autoMemoryEnabled` to `~/.claude/settings.json`), set `"autoMemoryEnabled": false` in one project's settings, or set `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`, which overrides the setting for that session.
go deeper
Recall that Claude writes auto memory itself, that it loads each session, and that /memory shows and toggles it.
Explain the MEMORY.md index against topic files, the 200-line or 25KB load limit, and the three ways to switch it off.
Reason about where it lives and who shares it: per git repository, across worktrees, machine-local, and relocatable only under workspace trust.
Decide what a team keeps in reviewed CLAUDE.md against what it lets each developer's auto memory learn privately.
## Two memory systems Claude Code carries knowledge across sessions in two ways. **CLAUDE.md files** are written by you. **Auto memory** is written by Claude: notes it takes as it works, based on your corrections and preferences. Both load at the start of every conversation, and both are context rather than enforced configuration. | | CLAUDE.md | Auto memory | | --- | --- | --- | | Who writes it | You | Claude | | Contains | Instructions and rules | Learnings and patterns | | Scope | Project, user or organization | Per repository, shared across worktrees | | Loaded | Every session, each file in full up to 4 MiB | Every session, the first 200 lines or 25KB of `MEMORY.md` | ## What Claude saves Claude saves four kinds of notes and records the kind as a `type` field in each memory file's frontmatter: - `user`: your role, expertise and working preferences; - `feedback`: corrections you give and approaches you confirm; - `project`: ongoing work, deadlines and decisions that the code and git history do not show; - `reference`: where to find information outside the project, such as an issue tracker or a dashboard. It deliberately **skips** anything it can derive from the codebase (architecture, file paths, debugging fixes) and anything your CLAUDE.md files already say, and it does not save something every session. Asking Claude to "remember that the API tests need a local Redis instance" goes to auto memory; to put a line in CLAUDE.md instead, say "add this to CLAUDE.md" or edit the file through `/memory`. Interface messages such as "Saved 2 memories" or "Recalled 2 memories" show it at work. ## Where it lives Each project gets its own directory, `~/.claude/projects/<project>/memory/`. The `<project>` part is derived from the **git repository**, so every worktree and subdirectory of one repository shares a directory; outside a git repository the project root is used. The directory holds: - `MEMORY.md`, an **index** with one line per memory; - one **topic file** per memory, such as `user_role.md` or `feedback_testing.md`. Auto memory is **machine-local**: nothing syncs across machines or cloud environments. The transcript clean-up governed by `cleanupPeriodDays` leaves memory files alone; they stay until you or Claude edit or delete them. To keep memory elsewhere, set `autoMemoryDirectory` to an absolute or `~/` path. When a repository's own settings file supplies that key, Claude Code honors it only under the workspace-trust rule that also governs hooks. ## How much loads 1. At session start Claude Code loads **the first 200 lines or the first 25KB of `MEMORY.md`, whichever comes first**. Anything beyond is not loaded. 2. **Topic files are not loaded at startup.** Claude reads them on demand with its normal file tools when the index points to something it needs. 3. After each write, Claude Code measures `MEMORY.md` against those limits. Near a limit it reminds Claude to shorten the index; over a limit the write still succeeds, but Claude receives an error telling it to rewrite the index, because everything past the limit drops off at the next load. That ceiling applies only to `MEMORY.md`. A CLAUDE.md file is loaded in full up to 4 MiB, and skipped above that, although shorter files are followed better. ## Turning it off Auto memory is **on by default** in local sessions. Three switches cover most cases (`--bare` mode also turns it off for a session): - **The `/memory` toggle** saves `autoMemoryEnabled` to your user settings, `~/.claude/settings.json`, so it applies to all your projects. - **One project**: set `"autoMemoryEnabled": false` in that project's settings file. - **One session or environment**: `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`. The variable takes precedence over the setting **in either direction**; `0` forces auto memory on even where the setting says `false`. While it is off, Claude neither reads from nor writes to the memory directory. ## Reviewing what it learned - Open `/memory` and choose the auto memory folder to browse what Claude saved; every file is plain Markdown. - Delete or correct a wrong note directly; Claude reads the files as they are on disk. - Promote anything the whole team needs into the project CLAUDE.md, because auto memory is personal and stays on one machine. Deleting `MEMORY.md` is not a switch: it clears the notes, and Claude starts writing new ones. Everything in the folder is plain Markdown you can read, edit or delete, and `/memory` opens the folder for you.
- Why do all git worktrees of one repository see the same Claude Code auto memory?Because the `<project>` part of `~/.claude/projects/<project>/memory/` is derived from the git repository, not from the checkout path, so every worktree and subdirectory resolves to one directory. The sharing stops at the machine: auto memory is machine-local and does not follow you to another computer or a cloud session.
- What happens when Claude Code's MEMORY.md index grows past its load limit?The write still succeeds, but Claude Code returns an error telling Claude to rewrite the index, because only the first 200 lines or 25KB load at the next session start and the rest would be dropped. Near the limit it nudges Claude to keep one line per entry and move detail into topic files.
- Auto memory is opt-in and off by default
- All of MEMORY.md and every topic file load at startup
- Auto memory syncs across machines with your account
- Each git worktree keeps its own separate auto memory
- Auto memory records the codebase's architecture and file paths