Auto Memory and the .claude Directory

The last lesson was about instructions you write. This one is about the notes Claude writes without being asked, and about where all of this configuration physically lives on your disk.

The second half is less exciting than the first but pays off later, because when something is misconfigured you need to know which file to open.

Two kinds of memory

Both mechanisms exist to solve the same problem — a session starts with nothing — and both load at the start of every conversation. What separates them is who does the writing.

What auto memory actually is

As Claude works, it occasionally decides that something is worth keeping: that the build takes forty-five seconds, that the integration tests need a local Redis running, that you always want conventional commit messages, that a particular failure mode has a known cause. It writes those down.

It does not save something every session. It is making a judgement about whether the information would be useful in a future conversation, which means it is sometimes wrong in both directions — saving something trivial, or failing to save something you would have wanted.

You will see this happen. Messages like "Saved 2 memories" or "Recalled 2 memories" appear in the interface when Claude is writing to or reading from the store. It is on by default.

You can also push things into it deliberately. Telling Claude "remember that the API tests need a local Redis instance" saves it to auto memory. If you want something in CLAUDE.md instead, say so explicitly — ask it to add the line to CLAUDE.md, or open the file yourself.

Where it lives and what loads

Each project gets a memory directory under your home folder, at ~/.claude/projects/<project>/memory/. The <project> part is derived from the git repository, so every worktree and every subdirectory of the same repo shares one set of notes. Outside a git repository, the project root is used instead.

Inside, there is an index and however many topic files Claude has created:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # the index, loaded every session
├── debugging.md       # detailed notes on debugging patterns
├── api-conventions.md # API design decisions
└── ...

The loading rule is specific and worth knowing exactly, because it explains the shape of the files. The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation. Anything past that is not loaded at all.

Topic files are never loaded at startup. MEMORY.md works as an index that points at them, and Claude reads one on demand when the task turns out to relate to it. That is why the index tends to be one line per entry with a link — it is deliberately compressed to survive the limit.

Claude Code enforces this. After Claude writes to MEMORY.md, the file is measured; if it is near the limit Claude is reminded to shorten it, and if it is over, the write succeeds but Claude is told to rewrite the index, because everything past the cut-off would be silently dropped on the next load.

Note the contrast with the previous lesson. CLAUDE.md files load in full no matter how long they are — the 200-line guidance there is about adherence, not a hard limit. For MEMORY.md, the limit is real and content past it disappears.

Two more properties are worth knowing. Auto memory is machine-local: it is not synced between your laptop and a cloud environment. And everything in it is plain markdown, so you can read, edit or delete any of it.

If you want it off, the /memory command has a toggle, which writes autoMemoryEnabled into your user settings. Setting the same key to false in a project's settings turns it off for that project only.

A tour of the .claude directory

Now the geography. Two directories matter: .claude/ inside a project, and ~/.claude/ in your home folder. The split is simple — the project one is shared with your team through git, the home one is yours across every project.

Most people only ever touch CLAUDE.md and settings.json. Everything else is optional and appears as you need it.

Inside a project, at the repository root:

And in your home directory, ~/.claude/ mirrors most of that at a personal scope: your own CLAUDE.md, your own settings.json, your own skills/, rules/ and agents/ that apply in every project you open. Alongside it sits ~/.claude.json, which is application state rather than configuration — your theme, your login, per-project trust decisions, your personal MCP servers. That one is mostly managed through /config rather than edited.

The precedence rules differ between the two kinds of file, which catches people out. Settings merge with precedence: a project settings.json overrides matching keys in your personal one. CLAUDE.md files accumulate: the personal and project files are both loaded into context together.

Where your sessions are kept

~/.claude also holds data Claude Code writes as you work, which is worth knowing about for two reasons — recovering things, and privacy.

Session transcripts live under ~/.claude/projects/, one directory per project, containing every message, tool call and tool result. That is what --continue and --resume read. Pre-edit file snapshots live in ~/.claude/file-history/, and they are what checkpoint restore uses when you rewind. Every prompt you have ever typed is appended to ~/.claude/history.jsonl, which is how up-arrow recall works.

The privacy consequence follows directly. These are plaintext files, not encrypted at rest, and anything that passed through a tool is in them. If Claude read a .env file or a command printed a token, that value is now on your disk. Most of these paths are swept automatically once they are older than cleanupPeriodDays, which defaults to 30 — but history.jsonl is not, and persists until you delete it. There is a claude project purge command that removes the stored state for a single project, and it prints the full deletion plan and asks for confirmation before removing anything.

None of this is alarming on a machine only you use. It is worth knowing before you run Claude Code somewhere shared.

What to take away

Auto memory is the half of memory you do not write: notes Claude saves itself about build commands, debugging insights and preferences it picked up from your corrections, stored per repository under your home directory rather than in the project. Only the first 200 lines or 25KB of MEMORY.md load at the start of a session, whichever comes first, which is why Claude keeps that file as a terse index and pushes detail into topic files it reads on demand. It is all plain markdown, it goes stale like anything else, and /memory is how you open and prune it. Underneath, a project's .claude/ directory holds the settings, rules and extensions your team shares, ~/.claude/ holds the same things scoped to you, and it is also where your transcripts, file snapshots and prompt history are kept in plaintext.

Next: skills, which are the right home for knowledge that only matters sometimes — the first extension that lets you add capability without paying for it in every session.