“Didn’t we decide this yesterday?”
I was migrating my email out of Google. I’d spent two Claude Code sessions working on it: issues in Linear, decisions made, scripts executed. I open a third session and ask “what’s left pending from the degoogle?”
Silence. Total amnesia.
It’s like working with a brilliant teammate who shows up to the office every morning with absolutely no memory of what you did the day before. Not the decisions, not the mistakes, not the discoveries. Every session is a blank slate.
And it turns out there’s a file that solves exactly this problem. It’s been there for months. And almost nobody knows about it.
CLAUDE.md vs MEMORY.md: the manual and the notebook
If you use Claude Code, you probably already know about CLAUDE.md. It’s the file where you tell the AI how to work: what language to use, what tools you have, your coding conventions.
CLAUDE.md is your instruction manual. You write it. You maintain it.
MEMORY.md is something else. It’s a field notebook that the AI writes itself. It jots down what it learns while working with you: mistakes it made, decisions you made together, project patterns, things it tried that didn’t work.
Put simply:
| CLAUDE.md | MEMORY.md | |
|---|---|---|
| Who writes it | You | The AI |
| What it contains | Instructions | Learnings |
| When it changes | When you want | After each session |
| Analogy | The rulebook | The field notebook |
If CLAUDE.md is the contract you give the intern on their first day, MEMORY.md is the notes the intern takes in their notebook while working.
Where it lives
~/.claude/projects/<directory-hash>/memory/MEMORY.md
Each project directory has its own memory file. If you work in ~/code/project-a, it has a MEMORY.md. If you open Claude Code in ~/code/project-b, it has a different one. They don’t mix.
The file is automatically loaded into context at the start of each session. You don’t have to do anything.
Isn’t there a global MEMORY.md?
No. Only per project. And this is a problem.
Today I created a wrapper for op (the 1Password CLI) that caches secrets for an hour. It’s useful in all my projects, not just the one I was working in. But MEMORY.md only noted it in that directory’s memory.
CLAUDE.md does have a global version (~/.claude/CLAUDE.md), which loads in all sessions. MEMORY.md has no equivalent. If the AI learns something that applies to your entire environment (an alias, a system quirk, a preference), it has to note it in each project separately. Or not note it at all.
In practice, what I do is manually put that kind of cross-cutting knowledge in my global CLAUDE.md. It’s not ideal, but it works.
If I delete the project, does the memory get deleted?
No. Memory lives in ~/.claude/projects/, not in your code directory. If you delete ~/code/my-project/, the MEMORY.md stays there, orphaned, taking up space with nobody reading it.
Does anyone clean up? Not really. There’s no garbage collector that detects deleted project directories. Over time, ~/.claude/projects/ will accumulate memories from projects that no longer exist.
If you’re someone who deletes projects frequently, it’s worth occasionally taking a look:
| |
And deleting directories you no longer recognize. Nothing bad will happen — the worst that can occur is the AI starts from scratch next time.
What it looks like
This is a real example. Today, after a session migrating my email out of Google Workspace, my MEMORY.md looked like this:
| |
No philosophy. Concrete facts. Next time I open a session here, Claude already knows the degoogle is done, that I have an op wrapper, and that stat is GNU on my Mac.
The real problem it solves
It’s not just “remembering things.” It’s preventing the AI from repeating mistakes.
Today, the first time I wrote the op wrapper, I used stat -f %m (BSD syntax). It failed because my Mac has GNU coreutils via Homebrew. I fixed it with stat -c %Y.
Without MEMORY.md, next time I need stat in this project, it would try stat -f %m again. With MEMORY.md, it already knows not to do that.
It’s the difference between a teammate who writes things down and one who trusts their memory. The one who writes things down doesn’t repeat mistakes.
How to prevent it from filling up with junk
Here comes the obvious question: if the AI writes whatever it wants, won’t it end up being a dump of irrelevant notes?
There are several safeguards:
1. 200-line limit. Anything past line 200 gets truncated when loading. This forces conciseness.
2. Organization by topic. You can create separate files (debugging.md, patterns.md) and link them from MEMORY.md. The main file is an index, not a junk drawer.
3. You have the final say. It’s a text file on your disk. You can edit it, delete it, or tell Claude “clean up MEMORY.md, this is no longer relevant.”
4. The AI self-corrects. System instructions tell it to update or remove memories that turn out to be wrong or outdated.
In practice, it works surprisingly well. The AI tends to be more disciplined than many humans at taking notes — probably because it has no ego or attachment to its own ideas.
Why nobody knows about it
Good question. It’s been in Claude Code for months, works by default, and I don’t remember seeing it highlighted in any changelog or Anthropic blog post.
My theory: it’s a feature that was born as internal infrastructure to improve the experience between sessions, not as a user-facing feature. It has no UI, no toggle, no configuration panel. It’s a text file in a hidden directory.
And there’s the problem. The most useful features are often the most invisible, because nobody looks for them if they don’t know they exist.
The fourth layer of memory
If you read my post about Linear, Beads and Tasks, MEMORY.md fits as a fourth layer that complements the others:
| Layer | Horizon | Who writes | What it contains | Example |
|---|---|---|---|---|
| Linear | Weeks/months | Human | What you want | “Launch v2 in March” |
| Beads | Days/sessions | Human + AI | What needs to be done | “Fix cache bug” |
| Tasks | Hours | AI | What I’m doing | “Running tests” |
| MEMORY.md | Permanent | AI | What I’ve learned | “stat is GNU here” |
The first three are about work: what to do, in what order, who does it. MEMORY.md is about knowledge: what we’ve learned doing it.
And there’s the key. Beads and Tasks are ephemeral by design: a task gets completed and closed, an issue gets resolved and archived. MEMORY.md is what remains afterward. The lessons, not the homework.
A concrete example of how they complement each other: today I used Linear to track degoogle issues (PER-16 to PER-28). Tasks to follow steps within each issue. And MEMORY.md to note that Linear’s API needs UUIDs for teams, not keys. The issues closed. The Tasks disappeared. The UUID lesson stays there for next time.
How to start using it
You don’t need to activate anything. It’s already working.
All you have to do is tell Claude “note this in your memory” when something happens that’s worth remembering:
- Technical decisions (“we chose iCloud+ for email”)
- Errors and solutions ("
statis GNU, use-cnot-f") - Project context (“degoogle is completed”)
- Discovered preferences (“user prefers X over Y”)
And occasionally, review ~/.claude/projects/*/memory/MEMORY.md to see what it’s noted and prune what’s no longer needed.
The good apprentice’s notebook
There’s a Feynman quote that fits perfectly: “The first principle is that you must not fool yourself — and you are the easiest person to fool.”
An LLM doesn’t fool itself because it has no ego. It doesn’t think “I’ll remember” or “this is too obvious to write down.” If you tell it to note something, it notes it. If it discovers a note is incorrect, it corrects it.
In a way, it’s better at taking notes than most of us will ever be. It just needed a place to keep them.
Now it has one.