Two memories: your rules and Claude’s notes
Every Claude Code session starts with an empty context window. So that you don’t have to keep explaining the basics of your project to Claude Code over and over, there are two mechanisms for handling knowledge, and they differ mainly in who writes them.
You write CLAUDE.md. These are instructions in Markdown: build and test commands, code conventions, project structure, rules of the “always do X” kind. The files can live at four levels:
| Level | Location | Who sees it | What it’s for |
|---|---|---|---|
| Company policy | /etc/claude-code/CLAUDE.md (Linux), /Library/Application Support/ClaudeCode/ (macOS) | all users on the machine | company standards, security, compliance |
| User | ~/.claude/CLAUDE.md | only you, in all projects | personal habits |
| Project | ./CLAUDE.md or ./.claude/CLAUDE.md | the whole team via git | architecture, conventions, workflow |
| Local | ./CLAUDE.local.md | only you, in one project | your test URLs, personal data |
The files are concatenated in the prompt, from the disk root down to the working directory, so Claude reads the instruction closest to where you launched it last. CLAUDE.md files in subdirectories are loaded only when Claude touches a file in that subdirectory. For larger projects there is a .claude/rules/ folder where you can split the rules by topic and tie them to specific paths, for example only to src/api/**/*.ts. And if the repository already uses AGENTS.md for other coding agents, Claude Code (since version 2.1.277) reads it on its own when it doesn’t find any CLAUDE.md.
Many people overlook how Claude actually receives CLAUDE.md. The model gets the file’s contents as a user message after the system prompt. It is context that Claude tries to comply with, and nobody guarantees compliance. The documentation says so openly and recommends keeping the file under 200 lines, because longer files reduce the willingness to follow the instructions. Whatever must hold every time (say, “never push to main”) belongs in hooks, that is, scripts the harness runs at fixed moments regardless of what the model feels like doing.
Claude writes auto memory itself. It is on by default, and Claude stores four kinds of notes in it, which it labels in the file header:
user- your role, expertise and working habits,feedback- your corrections and approaches you have approved,project- work in progress, deadlines and decisions that can’t be read from the code or from git,reference- where to look for information outside the project, such as a bug tracking system.
Claude leaves out everything it can derive from the code (architecture, file paths, bug fixes) and everything already in CLAUDE.md. It doesn’t save something in every session; it decides what is worth remembering based on whether it will be useful next time. Or you have to tell it explicitly. If you write “remember that we use pnpm,” it ends up in auto memory. If you want it in CLAUDE.md, you have to say so explicitly.
How the notes get back into context
The memory lives in the ~/.claude/projects/<projekt>/memory/ folder. Inside is an index, MEMORY.md, with one line per note, and next to it separate files with the individual notes.
The index is always loaded, the notes only on demand. At the start of every conversation Claude receives the first 200 lines or the first 25 KB of the index, whichever comes first. The individual notes stay out of context until Claude opens them itself using the ordinary file-reading tools.
The harness watches the size of the index. When MEMORY.md approaches the limit, Claude Code reminds the model to shorten it: one line per entry, details into separate files, merge or drop outdated items. When it overflows the limit, the write goes through, but Claude gets an error message asking it to rewrite the index, because everything beyond the limit would vanish on the next load. In addition, Claude Code writes the time of the last change into every note with a header, so when reading, Claude can see how fresh the information is. This detail is missing from the Supermemory analysis.
What does it cost? A full 25 KB index corresponds, by my estimate, to roughly six to eight thousand tokens, and in Czech more. You pay that in every session before the first message. For a typical index of a few dozen lines it’s negligible.
The weak spot is the decision whether to look. Let’s illustrate it with two behaviors. In the first, the index alone was enough: Claude correctly answered which version of the film the team had picked without opening the note. In the second, on a repository the author has been working on for over three years, they asked about an embedding model used earlier. Claude went looking in git history (a reasonable guess) and didn’t open the note where the answer lay. I know this from my own habits too: I have a notebook full of useful things, and I open it only when I remember there’s something in it.
Where it chafes
Notes are ordinary files, so they behave like files. Practical consequences follow:
| Property | How it behaves | What it means for you |
|---|---|---|
| Tied to the project | the folder is derived from the git repository, worktrees share one memory | after renaming or moving a project, you may end up with an empty memory |
| One machine | memory isn’t shared between computers or with cloud environments | Claude has two different memories on your laptop and on your workstation |
| No expiration | notes survive even the automatic cleanup of old session transcripts | “we have a freeze this week” stays true until someone deletes it |
| Latest version only | the file contains the current wording, and the folder isn’t in git by default | you can’t trace how a fact evolved; only the last-modified timestamp helps |
| Subagents | the main memory isn’t loaded into subagents (the exception is a conversation fork) | a subagent may have its own memory, but it doesn’t know about the main one |
| Compaction | after /compact the project CLAUDE.md is reloaded from disk | instructions given only in the conversation are lost when the context is condensed |
Renaming can break memory. I recently renamed a working directory and manually copied several dozen notes into the new folder. More than a third of the copies then gradually diverged from the originals, because Claude kept editing only one set. The documentation says the folder is derived from the repository, but it doesn’t say whether from its location on disk or from something more stable. Experience suggests the former. The fix is to set a custom memory location in the project settings. It’s interesting how Anthropic guards this setting: if someone else slips it into the repository, Claude Code respects it only after you’ve trusted the folder, just as with hooks. I’ll come back to this safeguard.
Compaction discards work in progress. Compaction (the automatic condensing of a long conversation into a summary) belongs to short-term memory and has nothing to do with notes, but in practice the two get mixed up. The documentation confirms that after compaction only the root CLAUDE.md is reloaded. Whatever you want to be certain of must live in a file.
Where memory fits among the six types of context
The context an AI agent works with can be divided into six groups: instructions, examples, knowledge, memory, tools and tool results. Memory is further divided into short-term (conversation history, state of the task in progress) and long-term, which has three forms: semantic (facts and preferences), episodic (what happened when) and procedural (how things are done). Applying this division to Claude Code looks like this:
| Context type | What covers it in Claude Code | Rating |
|---|---|---|
| Instructions | CLAUDE.md, .claude/rules/, AGENTS.md | good, but not enforced |
| Short-term memory | session history, compaction | works, loses details on condensing |
| Semantic memory | notes of type user, project, reference | good, if Claude remembers |
| Procedural memory | notes of type feedback, skills | partial |
| Episodic memory | session transcripts, which are deleted after a while | practically missing |
By the same scheme, long-term memory can be stored in a database or file system, automatically attached by the orchestration layer, or made available as a tool. Claude Code combines all three routes: the data lives in files, the harness attaches the index by itself, and the model reads the notes with file tools. The episodic part is the weakest. Claude knows what holds, but not how we got there.
What to take away
What I like about the built-in memory is its transparency. Everything is readable Markdown that you can open, fix or delete, and if you ask Claude to look into its memory, it does. For one developer on one machine that’s more than enough. Problems begin with teams, multiple computers and long projects where facts change.
Rules belong in CLAUDE.md (unless you want to enforce them right away via hooks). Whatever should hold in every session, write it into CLAUDE.md. The auto memory index gets truncated; CLAUDE.md is loaded in full.
What must always hold belongs in a hook. Both CLAUDE.md and memory are just context. Enforcement comes only from a hook or a deny rule in the permission settings. Generally speaking, I start by putting a rule into CLAUDE.md, and only when it proves itself and I see it would pay off to have it “hard-coded” do I move it to hooks, which are still more work…
Go through the memory once in a while. The /memory command opens the folder with the notes. Delete the outdated ones, fix the wrong ones. Nobody else will do it for you.
Think about memory before renaming a project. Either pin the memory location in the settings, or expect to start from zero.
If you want history, put the folder under git. This is my advice; the documentation is silent on it. You lose a bit of privacy, and you gain an overview of what Claude wrote down and when.
Consider add-ons only once you hit the limits. Supermemory and similar services make sense for teams and work across multiple machines. The price is your data in someone else’s cloud and another dependency that you have to vet as carefully as any code from a foreign repository. Some day we’ll put together an overview of these external tools, but for individual work I have no fundamentally good experience with them.
Memory in Claude Code is today an honest notebook. What it mainly lacks is the ability to remind itself at the moment it’s needed. My guess is that this is exactly the direction the built-in memory will evolve in, and add-ons like Supermemory will have to find another reason to exist.
Sources: Claude Code memory documentation (as of November 1, 2026). Claude Code’s behavior changes with every version, so verify limits and settings in the current documentation before use.
