Claude Code's memory – the notes the AI writes itself

Claude Code reads a file called CLAUDE.md at the start of every chat. If you don’t have one yet, start with the lesson on your first CLAUDE.md and come back here.

CLAUDE.md has one quality that is easy to forget: even when the AI writes it for you, nothing lands there without your decision.

Claude Code keeps a second notebook alongside CLAUDE.md, and that one is its own. It writes down what it picks up along the way – that you correct it the same way every time, that some folder is better left alone, that you call a thing something other than it assumed. You never have to ask for this, and there is a fair chance something is in there already.

This lesson is about that second notebook: where it sits, what it holds, and what to do when something untrue gets written into it.

Two notebooks, not one

CLAUDE.md and Claude Code’s notebook differ in one thing, and everything else follows from it: what goes into CLAUDE.md is your decision. What goes into the notebook is Claude Code’s.

CLAUDE.md is where you put what you want settled in advance – how you work, what things are called, “don’t touch this without asking”. The file itself usually comes together in a conversation, but every sentence in it stands there because you decided it should.

Claude Code’s notebook holds what the AI worked out along the way, usually from your corrections. Nobody dictates any of it. Correct the same thing twice and there is a good chance it writes that down, rather than hear it a third time.

Claude Code’s notebook is called memory, and that is what we’ll call it for the rest of this lesson. The documentation lists it as auto memory.

Claude Code reads CLAUDE.md and memory at the start of a chat, but not in the same way. CLAUDE.md goes in whole, however long it is. From memory it takes only the main file at startup, and only up to a certain length, while the files holding individual memories get opened later, once they turn out to be needed.

Splitting memory into a main file (MEMORY.md) and separate memory files has one consequence worth knowing straight away. Whether to reach for a memory file is something Claude Code decides on its own, mid-conversation, and it may well decide it doesn’t need to. A fact tucked away in one of those files is therefore no guarantee of being taken into account; the only certainty is an instruction written in CLAUDE.md.

Check that memory is switched on

Memory is on by default, so most likely there is nothing for you to do here. Treat this as a glance rather than a setup step.

Start Claude Code in your folder and type:

/memory

If Claude Code isn’t on your computer yet, installing it is a separate lesson.

At the top you’ll see the Auto-memory status, and under it a list with three entries: User memory with the path ~/.claude/CLAUDE.md, Project memory with the path ./CLAUDE.md, and Open auto-memory folder.

That status at the top is all you need to check here. If it reads on, memory is working and you can move on.

If it reads off instead, move to that entry and press Enter. The same key switches memory both ways, so turning it off again later works exactly the same.

The third entry, Open auto-memory folder, comes in handy shortly. Leave it alone for now – first there should be something in that folder worth looking at.

Tell Claude Code something about yourself

Memory also writes on an explicit request, and that is the easiest place to start: you can simply ask, instead of waiting for Claude Code to notice something by itself.

In an open chat with Claude Code, write a sentence about yourself or about your work. Something true, and specific enough that you can check later whether it worked:

Remember that I like Hawaiian pizza.

Claude Code confirms the write with a short message – you’ll see something along the lines of Saved 1 memory – and that is the whole of it from your side. There is no form to fill in, no category to pick.

Add two more sentences like that one, so memory has some content at all. At this stage they can be as trivial as the first – the point is that you’ll recognise them in the file afterwards, not that they be useful yet.

Open a new chat and see whether Claude Code remembers

The whole proof that memory really works fits into one step and takes a moment.

Close the current chat and start Claude Code again, in the same folder. A new chat carries nothing over from the previous one, and the AI assistant can no longer see what was said there, so whatever survived, survived in files.

Now ask about the fact you just saved, but not head-on – not “what do you know about me”, but something that needs that knowledge:

What is my favourite dish?

If the AI comes back with Hawaiian pizza, memory did its job. Sometimes a message like Recalled 1 memory shows up alongside the answer, which is Claude Code telling you it reached for its earlier notes. It doesn’t show that every time, so its absence settles nothing.

And if memory didn’t work, that is no cause for alarm and doesn’t mean anything is broken. The AI decides for itself what is worth saving, and it doesn’t save everything – in the next step you’ll see what exactly ended up in the file.

Every folder has its own memory

Memory isn’t one big pile for the whole computer. Claude Code keeps a separate one per project, and a project, as far as it is concerned, is the folder you start it in. Whatever got written during this exercise won’t turn up in a chat you hold somewhere else.

That split earns its keep, because notes from one line of work rarely fit another. Decisions about invoicing have no business in a chat about holiday photos, and whatever Claude Code worked out while writing proposals would only get in the way of sorting out household paperwork.

One piece of everyday advice follows from it: start Claude Code in the folder of the task you are actually working on, rather than always in one folder above everything else. Start it from the same place every time and Claude Code collects everything into one memory, and after a few weeks you have a sack of notes on topics that don’t belong together. A folder per task means a separate, clean memory. If you work with Git, Claude Code treats a whole repository as one project – memories are then split by repository, not by the subfolders inside it.

Changing folders deletes nothing. Go back to the previous one, start Claude Code there, and its earlier notes are where you left them.

Open the memory files

The simplest way to see the memory files is to ask Claude Code in the chat:

Show me the contents of your memory files for this folder.

The other route is /memory and the Open auto-memory folder entry, which opens that folder in your system.

What you’ll find are ordinary text files. No database, nothing encrypted: markdown, the same plain text your CLAUDE.md is written in. The main file is called MEMORY.md and works as a table of contents: short entries, one line each, with longer memories in separate files beside it.

Read MEMORY.md from top to bottom. This is where most of the lesson pays off. You’ll see with your own eyes what the AI assistant considered worth keeping and what it let pass, and now and then it will have saved something you never meant to pass on.

Give the most attention to the short descriptions next to each entry, because they do all the work here. MEMORY.md loads at the start of every chat and tells Claude Code what sits in the other files. Those descriptions are what Claude Code goes on when deciding whether to open a memory file at all.

A description that doesn’t match its file is therefore more dangerous than it looks. The file can be full of accurate notes and never get opened, because nothing in the index suggested it had anything to say. Go through the descriptions one by one and check that each really announces what is inside.

Tidying up the memory

Memory files go out of date over time. The simplest way to remove or fix a poor entry is in the chat, and the pizza is there to practise on:

Forget that I like Hawaiian pizza.

Claude Code finds that entry in its files and deletes it. That is what this usually looks like day to day: you say what changed, and the AI assistant handles the rest.

Fixing entries one at a time won’t hold up in the long run. In our experience Claude Code creates new memories more readily than it edits or deletes old ones, so duplicates and long-expired entries build up in the memory files.

Every now and then, a pass over the whole thing is worth it. The easiest way to ask for one:

Read all your memory files, check them for duplicates and check whether the rest is still current. Where you don't know, ask me – I'll help you sort it out.

That last sentence is the important part. Without it, Claude Code decides on its own which of two contradictory entries is the truer one, and that particular question is yours to answer.

What to take away from this lesson

Memory is a second notebook, next to CLAUDE.md. What goes into CLAUDE.md is your call; what goes into memory is Claude Code’s, usually off the back of your corrections. The only certainty is an instruction written in CLAUDE.md.

Every folder has its own memory. So start Claude Code in the folder of the task you’re working on rather than in the same place for everything, or it all ends up in one sack.

The descriptions in MEMORY.md decide the rest. They load at the start of every chat, and Claude Code goes on them when deciding whether to open a memory file. A description that misses what the file holds buries it more thoroughly than no description would.

Memory needs tidying. Entries arrive faster than they leave, so every now and then ask for a pass over the lot – with the proviso that Claude Code brings contradictions to you.

Tasks

• Memory checked with /memory
• Three facts saved to memory at your request
• New chat opened, Claude Code using the saved facts in it
• MEMORY.md read from top to bottom
• Descriptions checked against their entries: each announces what is inside
• One poor entry fixed or deleted