The memory system
A new employee on their first day knows nothing about your company : its rules, its tools, its history. What turns them into a valuable collaborator is what they retain. Claude Code solves this with something refreshingly simple : plain text files that are read at the start of every session. No black box : you can open, read and edit every one of them.
Three files carry most of the weight. We call this the three-file memory pattern.
CLAUDE.md : the employee handbook
CLAUDE.md is the first thing Claude Code reads in a project. It contains your standing instructions : written by you, in plain language.
What goes in it : who you are and how you like to work ( « always answer in English », « be concise » ) ; the rules of the project ( « never touch the folder X », « always run the tests before saying done » ) ; how things are organized ( « the client files live in /clients, one folder per client » ).
Think of it as the employee handbook : nobody recites it aloud, but everyone is expected to follow it. The practical effect is enormous : you stop repeating the same instructions at every session, and the agent stops making the same category of error twice.
MEMORY.md : the personal notebook
While CLAUDE.md is written mostly by you, MEMORY.md is written mostly by the agent itself. When it learns something worth keeping : a preference you expressed, a fact about the project, the location of an important resource : it records a short note.
Each note is one fact, dated and titled. Over weeks, this becomes the agent's accumulated experience : the difference between a newcomer and a colleague who has been around for a year. You can ( and should ) review it occasionally : it reads like a notebook, not like code.
lessons.md : the mistake journal
The third file is the most distinctive : a journal of mistakes and the rules learned from them. When something goes wrong : the agent misunderstood an instruction, an automation failed for a subtle reason : the lesson is written down : what happened, why, and what rule prevents it next time.
The file is re-read at the start of every session. The result is an improvement loop that compounds : every error happens once. In our experience operating agents in production at eaQbe, this single habit separates systems that get better every week from systems that repeat themselves.
How the three fit together
| File | Written by | Contains | Analogy |
|---|---|---|---|
CLAUDE.md | You | Standing rules and instructions | Employee handbook |
MEMORY.md | The agent | Facts and preferences it learned | Personal notebook |
lessons.md | Both | Mistakes and the rules they produced | Post-mortem journal |
The beauty of the pattern is its transparency. The memory of your AI collaborator is not a mysterious neural state : it is three text files in your project that you can read in five minutes and correct with a text editor.
Frequently asked questions
Does Claude Code remember things between sessions?
Yes : through these files ( plus optional long-term memory tools, see MCP ). Anything in CLAUDE.md, MEMORY.md or lessons.md is re-loaded at every session start.
Do I need to be technical to write CLAUDE.md?
No. It is plain language. « Always reply in French. Never send an email without showing me a preview first. Our clients' folders are under /clients. » : that is a perfectly good CLAUDE.md.
What is the difference between CLAUDE.md and MEMORY.md?
Direction of writing. CLAUDE.md is your instructions to the agent ; MEMORY.md is the agent's own notes about what it learned. Handbook versus notebook.
Going further
- Next : Settings, permissions & hooks : how you decide what the agent may do.
- The complete memory setup is part of our Claude Code training.