Claude's Different Kinds of Memory

the short version

Same word, five unrelated mechanisms. This is the map before the detail:

Memory	Who writes it	Lives	Available in
Context window	nobody — automatic	this conversation only	every surface
`CLAUDE.md`	you	plain files, checked into the repo	Claude Code
Auto memory	Claude, as it works	markdown files on disk	Claude Code
Project knowledge & instructions	you	inside a Claude.ai Project	Claude.ai
Memory tool / context editing	your application code	wherever you store it	Claude API, custom agents

the context window: memory by default

The most basic form of memory needs no setup at all: everything said earlier in the same conversation is still there, which is why Claude can refer back to something from ten messages ago without being reminded. It's also the most fragile — it's scoped to one conversation, and a long enough session eventually gets automatically summarized, trading detail for room to keep going. See Effective Prompting for when it's worth ending a session deliberately instead of letting that happen.

Nothing here survives on its own past the conversation ending. Anything worth keeping longer has to land in one of the other four systems below.

CLAUDE.md: what you write down

A file read automatically at the start of every Claude Code session — the place for what you'd otherwise re-explain every time: build commands, conventions a linter won't catch, directories that are off-limits. Three scopes, depending on who and what it should apply to:

File	Scope
`./CLAUDE.md`	the project — committed, shared with the team
`~/.claude/CLAUDE.md`	you, every project
`./CLAUDE.local.md`	you, this project only — gitignore it

It's static until you edit it. Claude reads it, but never writes to it on its own — see Effective Prompting for the full section, including a sample file.

How to create one: the fastest way is to have Claude generate a first draft from the actual codebase rather than writing it blind.

/init | | reads the project and writes a starting ./CLAUDE.md for you to edit |'mem_init'

Or skip the command entirely and create the file by hand — it's just a plain markdown file at the repo root (or at ~/.claude/CLAUDE.md / ./CLAUDE.local.md for the other two scopes above). No special format is required; short, concrete bullet points work better than prose.

auto memory: what Claude writes itself

The mirror image of CLAUDE.md: Claude saves its own notes as it works — a build command it had to discover the hard way, a preference stated once in passing, a debugging dead end worth not repeating. You don't write these entries; Claude decides what's worth keeping and files them at ~/.claude/projects/<project>/memory/, behind a MEMORY.md index that loads automatically while the individual topic files load on demand.

Run /memory to browse, edit, or turn it off. It's plain markdown, so nothing about it is hidden — open a file and correct it directly if Claude misremembered something.

How to create an entry: normally you don't — Claude writes these on its own as it works, with no command needed. Two ways to influence it directly instead of waiting for it to notice something on its own:

Remember that we use pnpm, not npm. | | said in plain conversation, prompts Claude to save it as a memory entry |'mem_ask'

/memory | | opens the memory files directly, so you can add, edit, or delete an entry by hand like any other markdown file |'mem_cmd'

Claude Projects: memory on the Claude.ai side

A plain Claude.ai chat starts from zero every time, the same way a chat with no CLAUDE.md would. A Project fixes that with two separate mechanisms: project knowledge, files and documents Claude can pull context from without you re-uploading them each conversation, and custom instructions, steering text applied automatically to every conversation started inside that Project. Both persist across conversations within the Project, but neither exists once you step outside it.

How to set them up: both live in the Project itself, on claude.ai — there's no command for this, it's a UI flow.

Step	Where
Create the Project	"New Project" in the Claude.ai sidebar, give it a name
Add project knowledge	inside the Project, "Add content" — upload files or paste text directly
Add custom instructions	the Project's settings (pencil/gear icon) — a text box applied to every conversation started here

Both are editable any time — updating a file in project knowledge or rewriting the custom instructions takes effect starting with the next message, no re-upload of past conversations required.

the memory tool: for developers building agents

None of the above apply if you're building your own application on the Claude API rather than using Claude Code or Claude.ai directly — there, persistence is on you. For a long-running agent that would otherwise need to keep growing its context indefinitely, Anthropic's memory tool and context-editing capabilities let it explicitly save notes to its own storage and pull back only what's relevant, rather than carrying the entire history of a task in every request. See Claude API for Developers for where this fits alongside prompt caching and the rest of the API surface.

How to use it: unlike everything above, this isn't a UI toggle — it's something you wire into your own request code. In broad strokes: declare the memory tool alongside your other tool definitions in the Messages API call, then handle the save/retrieve calls Claude makes against it the same way you'd handle any other tool call, backed by whatever storage your application already uses (a file, a database row, a key-value store). It's opt-in per request, not something that turns on globally.

which one do I actually need?

Situation	Use
A rule that should never change for this codebase	`CLAUDE.md`
Something Claude figured out mid-session worth keeping	auto memory — Claude decides on its own
Reference docs and steering text for a Claude.ai workflow you repeat	a Project
Your own agent needs to recall things across separate API calls	the memory tool, in your own application code
Claude just needs to recall something said a few messages ago	nothing to set up — that's the context window

reference

code.claude.com — memory
platform.claude.com — prompt engineering overview