Claude Code memory
Plain notes files a coding agent reads every session: rules you write, plus notes it keeps for itself.
by Anthropic · Built this? Edit this page on GitHub
In short
Claude Code has two kinds of memory, both plain text files. CLAUDE.md files are instructions you write: for your whole company, for you, for a project, or just for you in one project. They load at the start of every session. Auto memory is a folder of notes Claude writes for itself as it works, like “you prefer pnpm” or “the API tests need a local Redis”. A short index of those notes is read every session, and Claude opens the full notes when it needs them.
Who it’s for
Developers using Claude Code in the terminal, their editor or the desktop app, and teams who want one set of project rules everyone’s Claude follows.
What it remembers
Your rules and project conventions (CLAUDE.md), and Claude’s own notes: who you are and how you like to work, corrections you gave it, ongoing project decisions, and where to find things outside the code.
- Memory lives
- Your machine (plain files)
- API keys
- A Claude plan login, an API key, or a cloud provider
- Works with
- Claude Code CLI, VS Code, Claude desktop app, Agent SDK, AGENTS.md files
- License
- Closed sourceProprietary (Anthropic Commercial Terms)
- Price
- Comes with Claude Pro, Max, Team or Enterprise, or pay per use with an API key
Under the hood
- Who writes memories
- You write CLAUDE.md files. Claude writes its auto memory notes itself during the session, deciding what will be useful next time and skipping what the code already shows.
- Where they're kept
- Markdown files: CLAUDE.md in your project and home folder, and a per-project memory folder under ~/.claude with a MEMORY.md index and one file per note.
- How they're found
- No search engine. CLAUDE.md and the index load at the start; nested CLAUDE.md files and path rules load when Claude reads matching files; Claude opens notes with its normal file tools.
- Extra AI calls
- No separate AI call is documented: notes are written by the same Claude, as part of the session, using the context they take up.
How it works
- 1Session startsCLAUDE.md files and the first 200 lines of the memory index load.
- 2It worksFolder rules load as Claude reads matching files; it opens notes when it needs them.
- 3It takes notesCorrections and preferences worth keeping become short markdown notes.
- 4It tidies the indexWhen the index grows long, Claude trims it and moves detail into topic files.
What stands out
- Radically simple and inspectable: every memory is a markdown file you can read, edit, or delete, and the /memory command opens them.
- Layered instructions that fit real teams: company-wide, personal, per project and per folder, with rules that load only when Claude touches matching files.
- Instructions survive long sessions: after the conversation is compacted, the project’s CLAUDE.md and the memory index are read back from disk.
- Honest about limits: the docs say plainly that memory is context Claude tries to follow, not enforced settings, and point to hooks for hard rules.
What it doesn’t do
- Nothing fades on its own. Notes stay until you or Claude edit or delete them, and only the first 200 lines of the index are read at the start.
- When a note is rewritten, what it used to say isn’t kept anywhere.
- Auto memory stays on one machine; it isn’t shared across computers or with cloud sessions (cloud Projects keep a separate memory).
- It’s work memory for a coding agent, not the AI’s own sense of self. No emotional weighting is documented.
Measured against human memory
0 built, 8 partly, 2 not, 1 not known of the Field Guide’s 11 mechanisms
Encoding
Salience
Decides what's worth keeping, and how much, as a memory is written.
Claude decides what’s worth saving and sorts notes into four kinds, skipping what the code already shows. There’s no importance score. source
Emotion
Gives memories written with feeling more weight.
The docs describe four kinds of note and never mention weighting by feeling.
Storage
Forgetting
Lets unused memories fade over time on its own.
Notes stay until you or Claude edit or delete them, and they’re kept out of the old-transcript cleanup. The 200-line index cap is a size limit, not fading. source
Interference
When a new memory closely matches an old one, notices and lets the newer one win.
Each note carries its last-changed date, and when the index gets long Claude is told to merge or drop stale entries. Old and new are sorted out by Claude’s judgement. source
Retrieval
Retrieval
Remembering something makes that memory stronger.
Notes load by their place in the index or when Claude opens them. The only date kept is when a note was last written, so reading one doesn’t strengthen it. source
Association
Links memories, so recalling one brings its neighbours.
The always-loaded index works as signposts to the notes behind it. There are no automatic links between notes. source
Prospective
Brings a memory back at the right time without being asked.
Folder CLAUDE.md files and path rules come back on their own when Claude touches matching files, but only for rules you wrote. Its own notes wait to be opened. source
Transformation
Consolidation
Reworks memories between sessions: strengthening, merging, reorganising.
Claude tidies the index when it nears its size limit, moving detail into topic files and merging entries, but during a session. No pass between sessions is documented. source
Reconsolidation
Corrects a memory when it's contradicted, and keeps what it used to say.
Claude edits a note in place when things change and the date updates, but the docs describe no history of what it said before. source
Gist
Turns many specific moments into general knowledge.
Notes are lessons drawn from sessions (corrections, approaches you confirmed), written by Claude rather than a separate mechanism. source
Schemas
Forms beliefs about people and projects, and weighs new facts against them.
Notes about you and the project are read every session and shape how it works, but new facts aren’t explicitly weighed against them. source
Not every system is trying to be a human memory, so a hollow dot isn’t a flaw. It just says what the system doesn’t do. What the mechanisms are.
Claude Code memory’s makers haven’t shared what they’re building next, so only today shows here. Makers can add their roadmap the same way they correct an entry.
Compare Claude Code memory with the others, side by sideQuestions
- Who is Claude Code memory for?
Developers using Claude Code in the terminal, their editor or the desktop app, and teams who want one set of project rules everyone’s Claude follows.
- Where does Claude Code memory keep its memories?
Your machine (plain files). Markdown files: CLAUDE.md in your project and home folder, and a per-project memory folder under ~/.claude with a MEMORY.md index and one file per note.
- Does Claude Code memory forget?
Forgetting: not built. Notes stay until you or Claude edit or delete them, and they’re kept out of the old-transcript cleanup. The 200-line index cap is a size limit, not fading. source
- Does Claude Code memory correct a memory when it turns out to be wrong?
Reconsolidation: a little. Claude edits a note in place when things change and the date updates, but the docs describe no history of what it said before. source
- Is Claude Code memory open source?
No, it's closed source. License: Proprietary (Anthropic Commercial Terms).
- Does Claude Code memory need an API key?
API keys: A Claude plan login, an API key, or a cloud provider.
- How much does Claude Code memory cost?
Price: Comes with Claude Pro, Max, Team or Enterprise, or pay per use with an API key.