← All guides

claude memory md

Claude MEMORY.md: What It Is, Where It Lives, Limits

By Neo Zino - builder of ClockedCode·October 31, 2026·9 min read

MEMORY.md is the file Claude Code writes for itself. See where it lives, what its 200-line cap cuts off, and how to inspect, pin or disable it.

TL;DR: Claude memory md refers to MEMORY.md, the notes file Claude Code writes for itself, while CLAUDE.md holds instructions you write. Only the first 200 lines or 25 KB of MEMORY.md load at the start of a session, so anything past that cap is cut. Run /memory to see what is active, and set autoMemoryEnabled to false if you want it off.

What is MEMORY.md, and how is it different from CLAUDE.md?

The difference is authorship. According to a 2026 post on empowered.house, you write CLAUDE.md, whereas Claude Code writes MEMORY.md as notes to itself (empowered.house). If you open a file and do not recognize its contents, it is almost certainly the second kind.

The file does not sit next to your code. Auto memory is saved to a MEMORY.md inside a per-project directory under ~/.claude/projects/, not into CLAUDE.md (github.com). That surprises people. One bug report describes typing a note with the # prefix, expecting to be asked where in CLAUDE.md it should go, and finding it had been written to ~/.claude/projects/<encoded-path>/memory/MEMORY.md instead.

Quick test for which file you are holding: if you typed it deliberately, it is CLAUDE.md. If Claude added it during a session, it is MEMORY.md. For the instruction side in depth, see CLAUDE.md Explained: Claude Code Memory Guide.

Where is MEMORY.md stored on your machine?

Follow these steps to find it.

1. Open ~/.claude/projects/. Each project gets its own memory directory there (empowered.house).
2. Open the folder for your project, then the memory folder inside it. The index is MEMORY.md, and the topic files it points to sit beside it (github.com).
3. Do not build the folder name yourself by encoding your working directory. The agent-context-os docs warn that this convention is not a stable API (github.com). Use /memory to find the real path (covered below).
4. Remember that Claude Code resolves the default store from the repository, so worktrees and subdirectories of one repo can share the same memory (github.com).

Because the directory is inside Claude Code's internal data folder, the file is not version-controlled, not visible in your project and not portable, as the issue reporter put it (github.com). It is also machine-local and not shared across machines or cloud environments (empowered.house). Two consequences follow. A teammate will never see what your Claude learned, and a fresh laptop starts with an empty memory.

That is also why you should never assume a rule is "saved for the team" because Claude remembered it. If it must reach other people, it belongs in a committed file.

How much of MEMORY.md does Claude actually see?

Less than you might think. Each conversation starts with only the first 200 lines or 25 KB of MEMORY.md, and the topic files it points to are opened when needed (empowered.house). The auto memory system prompt itself says lines after 200 are truncated, so the file should stay concise and link out to other files (github.com). One walkthrough adds that going over the cap truncates the index with a warning (harrisonsec.com).

Two limits stack on top of each other.

The index cap. Once the index grows past the cap, the entries beyond it are cut, and the picker that chooses which memories to load cannot even see them (harrisonsec.com).

The picker cap. According to the HarrisonSec author's reading of the leaked source, a Sonnet side query picks up to 5 memory files to load (harrisonsec.com). Their blunt arithmetic: with 200 memory files, only 5 get loaded per turn and the other 195 are invisible, however relevant they are. Treat that as one author's reading of source code, not Anthropic documentation, but it matches the symptom people report.

What to do with this:

• Keep the index well under 200 lines. Merge duplicates and delete notes about finished work before you hit the cap, not after.
• Put the one-line summary in the index and the detail in a topic file, so the index stays short.
• If a note must be seen every session, do not rely on it surviving the picker. Move it to CLAUDE.md, where root files load at launch (empowered.house).

When this advice is the wrong call: if your memory folder holds a dozen small files, ignore all of it. The caps only bite on long-lived projects.

How do you read what Claude has written to memory?

1. Run /memory inside Claude Code. It shows the active memory and its source (github.com).
2. Open the path it reports and read MEMORY.md first, then the topic files it links.
3. Sort each note by kind. One walkthrough says there are exactly four memory types: user, feedback, project and reference (harrisonsec.com). A note filed under the wrong kind is usually a sign it should be rewritten or deleted.
4. Delete or edit anything wrong. They are plain files, and the author of that walkthrough counts this transparency as the design's main strength: you can see, edit and delete exactly what Claude remembers (harrisonsec.com).

The visibility point matters because one commenter on the bug thread argued that auto memory writes session-specific details into a file loaded into every future session, with no view of it from the CLI (github.com). In practice /memory plus a file browser closes most of that gap, but only if you actually look. Make it a habit after long sessions, the same way you would skim a diff.

Our own guide, Claude Code Memory: CLAUDE.md vs Auto Memory, covers editing and moving these notes in more detail.

Which file should a given note go in?

Work down this list and stop at the first rule that matches.

• If breaking the rule would be harmful and must never happen, use a hook. Anthropic's documentation, as relayed by empowered.house, treats CLAUDE.md as context rather than enforced configuration and points to hooks for blocking an action regardless of what Claude decides (empowered.house). CLAUDE.md is not a system prompt.
• If it is an instruction you wrote and your team shares it, put it in CLAUDE.md or AGENTS.md and commit it. Aim to keep each file below 200 lines, because longer files eat context and weaken how well Claude follows them (empowered.house).
• If you use only Claude Code, begin with CLAUDE.md by itself. If your team works across several tools, make AGENTS.md the single source and have CLAUDE.md import it (empowered.house). We would pick the same.
• If it is a fact Claude learned about your habits or the project, let it live in MEMORY.md and review it occasionally.
• If it must be present at every launch, prefer CLAUDE.md. Files at the project root and in the directories above it load at launch, while subfolder files load only once Claude reads files there (empowered.house).

How do you turn auto memory off or pin where it lives?

Claude Code enables auto memory by default and may write to it during ordinary sessions (github.com). That was not always so. In February 2026 Anthropic described a slow rollout with opt-in during the preview via /memory (github.com). If you want out now, you have two routes:

1. Setting. Set autoMemoryEnabled to false in the settings scope you intend, then verify with /memory (github.com).
2. Environment variable. An Anthropic contributor said you can disable it by setting CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 (github.com).

To keep memory but control where it lives:

1. Choose an absolute path outside your working tree.
2. Set autoMemoryDirectory to that exact path in the project-local .claude/settings.local.json, which the agent-context-os repository ignores, so personal paths stay uncommitted (github.com).
3. Repeat for each linked worktree. Each one needs its own ignored memory-directory record and applicable autoMemoryDirectory setting (github.com).

Avoid a store inside the working tree or the git directory. The same docs reject it because private memory in a shared checkout is one git add -A from being staged (github.com).

Turning memory off is the right call when you work on client code you cannot let notes leak from, or when you want every session to start identical. It is the wrong call if you work alone on one long project, where the notes are cheap and useful.

Why does Claude ignore or misuse its own memory?

Run through this checklist before blaming the model.

• The note was cut. Check the line count of MEMORY.md. Past 200 lines or 25 KB, the picker cannot see the rest (harrisonsec.com). Fix: prune and move detail into topic files.
• The note lost the picker. Only 5 files load per query in the reported design, so a large set hides most notes (harrisonsec.com). Fix: merge related notes, or promote the important ones to CLAUDE.md.
• The note is written but not used. A GitHub issue (#37314) reports memory files being written correctly but consistently ignored across sessions (harrisonsec.com). Fix: restate the rule in CLAUDE.md, where it loads at launch.
• Another project's habits leaked in. Global memory can make suggestions from Project A bleed into Project B (harrisonsec.com). Fix: keep per-project notes per project and delete anything global that is really project-specific.
• A stale note is trusted. Nothing in the sources expires a note on its own, so audit dates and delete finished-work entries.

The trade-off is built in. The HarrisonSec author argues the design buys transparency at the cost of reliability: it is easy to save a memory and unreliable to retrieve the right one at the right time (harrisonsec.com). That is a fair summary of what you should expect. Slowness from a bloated context is a separate problem, covered in Claude Code Slow? Causes and Fixes.

Your next step: run /memory now, open the path it shows, and count the lines in MEMORY.md. If it is anywhere near 200 lines or 25 KB, prune it today and move any rule you truly need into a committed CLAUDE.md.