Claude Code memory is not a database and it is not recall. It is a set of text files the tool re-reads at the start of each session. That makes it easy to inspect, easy to fix, and just as easy to let rot.
- There are two systems. CLAUDE.md files are instructions you write. Auto memory is notes Claude writes for itself.
- Both are plain markdown on your disk. Auto memory sits under
~/.claude/projects/, one folder per project, with aMEMORY.mdindex. - Only the start of the index loads. The first 200 lines or 25KB of
MEMORY.md, whichever comes first. Notes are opened on demand. - Memory is context, not enforcement. If a rule cannot have exceptions, it belongs in a hook.
- Memory goes stale. A note records one day. The repository and the live system are today.
- Keep it edited. One fact per file, the rule instead of the incident, absolute dates, corrections made in place.
We run this system hard. Our studio's memory directory holds 187 notes and one index, built up over about six months of client work. This post explains how the system works, using Anthropic's documentation as fetched on 18 November 2026, and then what we have learned from keeping ours honest. It sits inside our wider guide to AI agents.
Two memory systems, not one
Anthropic's memory documentation opens with the fact everything else follows from: "Each Claude Code session begins with a fresh context window." Two mechanisms carry knowledge across sessions.
| CLAUDE.md files | Auto memory | |
|---|---|---|
| Who writes it | You | Claude |
| What it holds | Instructions and rules | Learnings and patterns |
| Scope | Project, user or organisation | Per repository, shared across its worktrees |
| What loads each session | The whole file | The first 200 lines or 25KB of the index |
| Good for | Standards, workflows, how to verify work | Your corrections, preferences, context Claude cannot get from the code |
Both are loaded at the start of every conversation. And both carry the same caveat, in the docs' words: "Claude treats them as context, not enforced configuration." Claude reads a memory and usually acts on it. Nothing guarantees it. The docs point to the alternative in the same paragraph: to block an action regardless of what Claude decides, use a PreToolUse hook. We cover that in Claude Code hooks.
A third piece is easy to miss. If your repository already has an AGENTS.md for other coding tools, Claude Code can read it in place of a CLAUDE.md, as of v2.1.277. The rules for which file wins are in our comparison of CLAUDE.md vs AGENTS.md.
Claude Code memory location: where the files live
Everything is a file, so the first thing to learn is where the files are.
Instruction files, in load order from broadest to most specific, per the docs:
| Scope | Location |
|---|---|
| Managed policy | A system path set by your organisation, for example /etc/claude-code/CLAUDE.md on Linux |
| User | ~/.claude/CLAUDE.md |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md |
| Local | ./CLAUDE.local.md, kept out of git |
Rule files under .claude/rules/ and ~/.claude/rules/ load too, and a rule with a paths: filter only loads when Claude works on matching files.
Auto memory has its own home:
~/.claude/projects/<project>/memory/
├── MEMORY.md # Index, one line per memory, loaded into every session
├── user_role.md # One memory
├── feedback_testing.md # One memory
└── ...
That layout is from the docs. Three properties of it matter in practice.
The project key comes from the git repository. All worktrees and subdirectories of one repository share one memory directory. Outside a git repository, the project root is used instead. This explains something about our own setup: we usually launch sessions from the home directory, which is not a repository, so one memory directory serves every client and side project we have. That is why our index has to be organised by client and by topic. If you launch from inside each repository, you get one directory per repository.
It is machine-local. The docs say memory files "are not shared across machines or cloud environments". A cloud session does not see your laptop's memory. Neither does a colleague.
You can move it. Set autoMemoryDirectory in settings.json to an absolute path or one starting with ~/:
{
"autoMemoryDirectory": "~/my-custom-memory-dir"
}
Session transcripts are deleted after a retention period, but the docs say memory files are excluded from that sweep. They stay until you or Claude edit or delete them. Which is exactly why they need maintenance.
What a memory file looks like
According to the docs, Claude saves four kinds of notes and records the kind in a type field in the file's frontmatter:
user: your role, expertise and working preferencesfeedback: corrections you give and approaches you confirmproject: ongoing work, deadlines and decisions that are not in the code or git historyreference: where to find information outside the project
The docs also say what Claude skips: anything it can derive from the codebase, and anything your CLAUDE.md files already say.
Here is the top of a real note from our directory, with one identifying line removed. It records two ways a browser layout check can pass without testing anything:
---
name: playwright_layout_assertions
description: "Two ways a Playwright layout/overlap assertion passes without testing anything — offsetParent on fixed elements, and border boxes of full-width blocks."
metadata:
node_type: memory
type: reference
modified: 2026-11-18T18:35:30.258Z
---
The modified line is written by Claude Code, not by the model. The docs: when Claude writes a memory file that begins with YAML frontmatter, Claude Code "records the write time in a modified frontmatter field as an ISO 8601 timestamp". It shows how current the fact is, to you and to Claude when it reads the note back.
Counted on 18 November 2026, our 187 notes break down as 95 project, 50 reference and 42 feedback. None is typed user. And 134 of them carry a modified timestamp; the rest predate the field or have not been rewritten since. That last number is useful on its own: a note with no timestamp is one nobody has touched in a while.
The file naming is ours, and worth copying. Notes that record a correction start with feedback_. Notes about a client or project start with its name. Reusable technique gets a plain descriptive name. A directory listing then reads as a table of contents.
The /memory command and the phrases that write memory
You do not have to find these files by hand. Inside a session:
/memory
Per the docs, this lists your CLAUDE.md, CLAUDE.local.md and other memory file locations across user and project scopes, including entries for files that do not exist yet. Select one and it opens in your editor. The same screen lets you toggle auto memory and open the auto memory folder.
Two more commands complete the picture:
/context all
shows what actually loaded, with a Memory files list. If a file you expected is missing from that list, Claude cannot see it. And:
/doctor prompt-audit
checks your instruction files for outdated or conflicting content, per the docs, on v2.1.283 or later.
Writing memory is conversational. The documented behaviour: when you say something like "remember that the API tests require a local Redis instance", Claude saves it to auto memory. To put an instruction in CLAUDE.md instead, ask for that directly, "add this to CLAUDE.md", or edit the file yourself through /memory.
Claude also writes memory without being asked, though not every session. The docs say it decides "based on whether the information would be useful in a future conversation". You will see lines such as "Saved 2 memories" when it does.
To turn auto memory off for one project:
{
"autoMemoryEnabled": false
}
What belongs where: memory, CLAUDE.md or the repo
Most memory problems are filing problems. The same fact can live in three places, and each place has a different reader and a different lifespan.
| It is... | Put it in | Why |
|---|---|---|
| A rule every session must follow | CLAUDE.md |
Loaded in full, every time, for everyone on the project |
| A rule that cannot have exceptions | A hook or a deny rule | Enforced by the tool, not left to the model |
| A correction or preference you gave once | Auto memory, type feedback |
Claude writes it; you edit it |
| Current state of a system or a project | Auto memory, with a date | Useful, and the first thing to go stale |
| A script, plan or tool you will reuse | The repository | Versioned, reviewable, available to every session and machine |
| A long procedure used occasionally | A skill | Loads only when needed |
| A secret | None of these | Environment files outside git |
Our own operating file draws the line for memory in one sentence: "Memory is for durable facts: rules, live system configuration, and reusable technique."
The repository row is the one people get wrong, including us. A memory note that says where something is kept is only as good as the place. One of our notes exists because a session's scratch folder, which lives under the system temp directory, lost its files after about three idle days: helper scripts and fetched pages were gone while the folders remained. The rule we wrote down afterwards: a test tool you will run again belongs in the project repository, and "a memory should never point at a scratchpad path as the place something is kept."
The second filing error is using memory for rules. A preference in auto memory is seen by you alone, on one machine. If your whole team needs it, it belongs in the project's CLAUDE.md, which is checked in. We go through that file in CLAUDE.md best practices.
How memory goes stale
A memory note is a photograph. It was true when it was taken. Three things go wrong after that.
The world moves and the note does not. Our operating file says it bluntly: "Verify against the repo or the API, not a memory file. Memory records a point in time; the repo is now." The same file records why the rule exists: "Past sessions have wasted work fixing problems that no longer existed." Read the current state first, then diagnose.
The first diagnosis was wrong. One of our notes about stalled browser test runs originally blamed the laptop's display going to sleep. A later session found the real cause, which was the network dropping. The note now reads, in place: "Corrected 2026-11-13: a first reading of three ... failures blamed the display sleeping on battery." The wrong explanation is not sitting beside the right one. It was replaced, and the replacement says it is a correction.
Two notes disagree. With 187 files this happens. Our rule for it comes from a section of our global instructions called "Correct the record":
- When a prior conclusion turns out to be wrong, state the correction plainly and update the affected memory file. Do not leave a superseded fact in place next to its replacement.
- If two memory files disagree, the disagreement itself is the finding — resolve it before acting on either.
- Distinguish "this was fixed" from "this was diagnosed." Do not report a diagnosis as a fix.
The third bullet is subtle and it matters. An agent that writes "diagnosed the queue stall" and an agent that writes "fixed the queue stall" leave very different notes for the next session. Only one of them is safe to build on.
Relative dates are the smallest version of the same problem. "Last week" in a note means nothing a month later. Our hygiene rules say to convert relative dates to absolute ones, and every status in our index carries a date for that reason.
Keeping the index
MEMORY.md is the only part of auto memory that loads automatically, and only the start of it. The docs: "The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation. Content beyond that threshold is not loaded at session start."
So the index has a hard budget. Claude Code watches it: after Claude writes to MEMORY.md, the file is measured against both limits, and Claude is reminded to shorten it when it gets close. If it goes over, the docs say the write still succeeds, but Claude gets an error telling it to rewrite the index, because everything past the limit is dropped on the next load.
Ours is at 111 lines and about 18KB for 187 notes. It fits because of four habits.
One line per note, with the rule in the line. The index line is often all a session needs:
- [Playwright layout assertions that can't fail](playwright_layout_assertions.md) — test a check against the broken state
- [Scratchpad files vanish after ~3 idle days](scratchpad_tmp_purge.md) — keep plans and tools in the repo
- [No `timeout` on this Mac](macos_no_timeout_command.md) — use the Bash tool's timeout
A session that reads "test a check against the broken state" may never need to open the file.
Sections that match how work arrives. Ours are: working rules, reusable technique, platform gotchas, our own site, clients, and personal projects. The working rules come first, under a heading that says to read them first.
Related notes share a line. Several notes about one client's project sit on one line, separated by a dot, each still linked to its own file. That is how 187 notes fit in 111 lines.
Status words in the index. We mark lines with a small fixed vocabulary: FIRM for rules that do not bend, OPEN for unresolved items, LIVE, PAUSED, PARKED or ARCHIVED for project state, each with a date where it matters. A session scanning the index can tell a standing rule from a snapshot.
One caution from experience: the index is at 18KB of a 25KB budget. The line limit is not the one we will hit first. Long, comma-heavy lines are how an index quietly runs out of room, so check both numbers:
wc -l -c ~/.claude/projects/<project>/memory/MEMORY.md
A memory hygiene routine
This is the section of our global instruction file that governs memory, quoted as written:
## Memory hygiene
Memory is for durable facts: rules, live system configuration, and reusable technique.
- Write the rule, not the incident. "Verify the scheduled trigger, not just dispatch" outlives the outage that taught it.
- Completed work, resolved bugs, and delivered one-offs do not need memory entries. Close them out instead of accumulating them.
- Convert relative dates to absolute ones.
- Before writing a new memory, check whether an existing file covers it and update that file instead.
As a routine, that becomes five steps you can run whenever the index feels heavy:
- Open the folder. Run
/memoryand open the auto memory folder. Sort by date modified. - Delete the finished. A note about a launched page or a closed bug is history. Git already has it.
- Merge duplicates. Two notes on one topic become one, and the index loses a line.
- Rewrite incidents as rules. Keep the one sentence the next session needs. Keep the date. Drop the story.
- Check the claims that matter against reality. For any note a session is about to act on, look at the repository or the live system first.
You can ask Claude to do the first four. Review what it proposes before it deletes anything, because a note you no longer recognise might be the one rule holding something up.
Honest caveat: we have not solved this. Our index still carries lines marked OPEN from weeks ago. A memory system does not finish. It gets edited.
The limits worth knowing
Four limits, all from the documentation, explain most surprises.
- Subagents do not get your auto memory. The main conversation's memory is not loaded into subagents, except a fork, which inherits the parent conversation. A subagent can be given its own memory directory. More in Claude Code subagents.
- CLAUDE.md survives compaction; conversation does not. After
/compact, the project-rootCLAUDE.mdis re-read from disk. An instruction you gave only in chat can be lost. If it mattered, write it down. - Imports do not save context. A
CLAUDE.mdcan pull in other files with@pathsyntax, but imported files load together with the file that imports them. - Some sessions cannot switch auto memory back on. In a background session, or one started by another Claude Code session, the docs say the
/memorytoggle can turn auto memory off but not on again. Startclaudedirectly in your terminal to re-enable it.
What to do this week. Claude Code memory works best when you treat it as documentation with a strict editor. Run /memory, read what is actually there, delete what is finished, and make sure the first screen of MEMORY.md holds rules instead of history. Then pick the three notes your sessions lean on most and check each against the system it describes.
We use this setup to run client sites and our own AI SEO agent. If you want agents that carry real working knowledge of your business from one day to the next, that is part of our AI integration work, and you can tell us about your setup.
Common questions
How does the Claude Code memory system work?
Each session starts with a fresh context window, and two mechanisms carry knowledge across. CLAUDE.md files are instructions you write, loaded in full at the start of every session. Auto memory is a folder of notes Claude writes for itself, with an index file called MEMORY.md whose opening part is loaded each session. Anthropic's documentation is explicit that both are context, not enforced configuration: Claude reads them and tries to follow them. Anything that must always happen belongs in a hook instead.
What are Claude Code memory files?
There are two kinds. Instruction files are named CLAUDE.md or CLAUDE.local.md, plus optional rule files under .claude/rules/. Auto memory files are plain markdown notes, one topic per file, stored beside an index named MEMORY.md. Each auto memory note can begin with YAML frontmatter that records a type, such as feedback, project or reference, and a modified timestamp. All of them are ordinary text files you can open, edit or delete in any editor.
Where is the Claude Code memory location on disk?
As of November 2026, auto memory lives at ~/.claude/projects/
How do I handle Claude Code memory management?
Treat it like a small knowledge base that needs an editor. Keep one fact per file. Keep the MEMORY.md index to one line per note, because only its first 200 lines or 25KB load at session start. Write the durable rule, not the story of the incident. Give every note an absolute date. When a fact changes, correct the existing note and say so, instead of adding a second note that disagrees. Delete notes about finished work.
What does the Claude Code memory command do?
The /memory command lists your CLAUDE.md, CLAUDE.local.md and other memory file locations across user and project scopes, including entries for files that do not exist yet. Selecting a file opens it in your editor. The same screen has a toggle that turns auto memory on or off and an option to open the auto memory folder. To confirm which instruction files actually loaded in the current session, run /context all and look under Memory files.
How does Claude Code remember things between sessions?
It does not remember conversations. It re-reads files. At the start of each session Claude Code loads your CLAUDE.md files and the opening part of the MEMORY.md index, and Claude opens individual memory notes when a task needs them. If you say remember that we use pnpm, Claude saves a note to auto memory. If you want a rule to hold in every session for everyone on the project, ask Claude to add it to CLAUDE.md or edit the file yourself.
Can I turn off Claude Code auto memory?
Yes. Auto memory is on by default in local sessions. Open /memory and use the auto memory toggle, which saves autoMemoryEnabled to your user settings. To turn it off for one project, set autoMemoryEnabled to false in that project's settings file. There is also an environment variable, CLAUDE_CODE_DISABLE_AUTO_MEMORY, set to 1. Turning it off does not delete existing notes; they stay on disk until you remove them.

