Claude Code memory: how it works and where it stops
Claude Code has two kinds of memory. CLAUDE.md files are instructions you write, and they load at the start of every session. Auto memory is notes Claude writes itself from your corrections, stored per repository on your machine, with a MEMORY.md index that loads at startup. Both work well inside one repo on one machine. Auto memory stays on that machine and in that repo by default, and other assistants do not read either layer. When you want the same notes across machines, repos and assistants, add a knowledge base Claude Code reads over MCP, like Hjarni.
CLAUDE.md: the memory you write
CLAUDE.md is plain Markdown that Claude Code reads when a session starts. There are four places it can live:
| Scope | Path | Who sees it |
|---|---|---|
| Managed policy | set by your organization | everyone on the machine |
| User | ~/.claude/CLAUDE.md |
you, in every project |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md |
your team, through git |
| Local | ./CLAUDE.local.md |
you, in this project (gitignore it) |
They do not override each other. Claude Code walks up from your working directory, finds every CLAUDE.md on the way, and concatenates them into context. A CLAUDE.md in a subdirectory loads later, the first time Claude touches a file in that folder.
Two more tools sit next to it. An @path line imports another file, up to four hops deep. Files in .claude/rules/ load at launch too, or only when matching files are touched if you give them a paths: header.
Use CLAUDE.md for short, stable instructions: build commands, test conventions, code style, "never touch the migrations folder". Anthropic recommends keeping each file under 200 lines. These instructions guide Claude; they do not enforce anything. For hard limits, Claude Code has permission settings.
Auto memory and MEMORY.md: the memory Claude writes
Auto memory is on by default in local sessions. When you correct Claude ("we use pnpm, not npm", "stop mocking the database in these tests"), it can save that as a note so the next session already knows.
It lives here:
~/.claude/projects/<project>/memory/
MEMORY.md # the index
feedback_testing.md
user_role.md
...
<project> comes from the git repository, so every worktree and subfolder of one repo shares one memory folder. MEMORY.md is an index with one line per note. At the start of every conversation Claude Code loads its first 200 lines or first 25 KB, whichever comes first. The topic files are not loaded up front; Claude reads them when they look relevant, so detailed notes stay available without filling the startup context.
Everything is plain Markdown. Run /memory to see every memory file in play, open the auto memory folder, or switch auto memory off. You can read and edit the notes like any other file. The full reference is in Anthropic's memory docs.
Where Claude Code memory stops
None of this is a flaw. It follows from where the memory lives: in files, on your machine, for one tool.
Auto memory stays on one machine. Anthropic's docs say it is machine-local and not shared across machines or cloud environments. Your laptop and your desktop each learn on their own. You can point it at another folder with the autoMemoryDirectory setting, but keeping that folder in sync is up to you.
Auto memory stays in one repo. It is scoped per repository. A lesson Claude learned in your API repo ("the staging database is read-only on Fridays") is not in the folder your frontend repo's sessions read. Your user CLAUDE.md does apply everywhere, but you write and maintain it by hand. If you keep pasting the same preferences into every repo, the router pattern for CLAUDE.md is worth a read.
Other assistants do not read it. Cursor, Codex and ChatGPT do not read ~/.claude. A shared AGENTS.md can carry project instructions between coding tools, but what Claude learned in auto memory stays with Claude Code.
The startup view is small. Claude sees 200 lines of index at startup, and Anthropic recommends 200 lines per CLAUDE.md. Detail can live in topic files, but what Claude knows to look for is decided by that index. That is a sensible budget for instructions and corrections, and a tight one for an index of months of decisions and research.
There is no revision history. The notes are files you can open, but there is no built-in record of earlier versions or which session changed what, unless you put the folder under git yourself.
What Claude learns is personal. Project CLAUDE.md is shared through git. Auto memory is not.
If you work in one repo, on one machine, in Claude Code only, none of this matters. The built-in memory is enough, and you should use it.
Adding memory that lives outside Claude Code
The limits above come from the memory being files for one tool on one machine. Move the durable part somewhere every machine and tool can reach.
A knowledge base with a built-in MCP server does that. The notes live in one place. Claude Code can search, read and write them over MCP, from any machine and any repo you connect. So can Claude, ChatGPT, Codex and Cursor, if you use them.
In practice the three layers split the work cleanly:
- CLAUDE.md: instructions for this repo. Short, stable, in git.
- Auto memory: small corrections Claude picks up while it works in this repo.
- Hjarni: decisions, project context, research and preferences that should outlive one repo, one machine or one tool.
To connect it, add the server once:
claude mcp add --transport http --scope user hjarni https://hjarni.com/mcp
--scope user makes it available in every project on that machine. Then start Claude Code, run /mcp, pick Hjarni and finish the sign-in in your browser. Do the same on each machine you use.
Then try it: ask Claude Code to save the last architecture decision you made as a note. Tomorrow, on another machine or in another repo, ask "check Hjarni: why did we switch queue libraries?" and it can find the note and answer from it.
Two things to know so you are not surprised. Claude Code decides when to call a tool, so a line in your user CLAUDE.md like "check Hjarni for project context before starting a task" helps it remember to look. And search is full-text, so notes with clear titles get found more reliably.
Two upgrades once the loop works:
- Session capture. A Claude Code Stop hook appends each prompt and reply to a session note in Hjarni as you work. Next time, ask Claude to read that note and pick up where you left off.
- History. Every note keeps a full revision history. Each version records its author, and edits made over MCP show the assistant client where it can be identified. If a session writes something wrong, read the diff and restore the earlier version.
When the memory is the team's
Everything above is about you. If the context belongs to a team (the billing subsystem only one engineer understands, the incident from last quarter), shared folders make it available to every engineer's connected assistant, within the folder permissions you set. That is its own post: shared team memory for Claude Code.
Hjarni is a Markdown knowledge base with a built-in MCP server: one set of notes that Claude Code, Claude and ChatGPT can each search and update, with a revision history you can check and restore. It is free to start, with 25 notes and full MCP access. Connect it to Claude Code.
Give your AI a memory. Free.
Connect Claude or ChatGPT to notes they can actually read and write.
Give your AI a memory. Free.
Common questions
FAQ
Does Claude Code have memory?
Yes, two kinds. CLAUDE.md files hold instructions you write, at user, project and local scope, and load at the start of every session. Auto memory holds notes Claude writes itself from your corrections and preferences, stored per repository in ~/.claude/projects//memory/, with a MEMORY.md index that loads at startup.
Where does Claude Code store its memory?
CLAUDE.md files live in ~/.claude/CLAUDE.md (you, every project), ./CLAUDE.md or ./.claude/CLAUDE.md (the project, shared through git) and ./CLAUDE.local.md (you, this project). Auto memory lives in ~/.claude/projects//memory/ on your machine, as a MEMORY.md index plus one Markdown file per topic.
How much of MEMORY.md does Claude Code load?
The first 200 lines or the first 25 KB, whichever comes first, at the start of every conversation. Topic files are not loaded at startup; Claude reads them when they are relevant. Anthropic also recommends keeping each CLAUDE.md under 200 lines.
Can I share Claude Code memory across machines or with other tools?
Partly. Project CLAUDE.md travels with the repo through git, and your user CLAUDE.md applies to every project on that machine. Auto memory is machine-local by default: Anthropic's docs say it is not shared across machines or cloud environments. Other assistants do not read ~/.claude, though Claude Code can read a shared AGENTS.md as project instructions. For notes you want available across machines, repos and assistants, keep them in a knowledge base each one connects to over MCP.