CLAUDE.md, memory and context management

In module 11 you opened the terminal, installed Claude Code and built something. If you came back the next day, you noticed something awkward: the agent remembered nothing. Not how to run the project, not the rules you gave it, not the bug you fixed together. That is not a problem with your install. It is the principle from module 2, the brilliant new hire who shows up every morning with no memory, now applied to an agent that edits files.

This module tackles it on two fronts: what persists between sessions and how to write a file that teaches the agent your project once, and how to manage the context window in a long session so the agent does not lose the thread halfway through. At the end you get a template, three prompts and an exercise on the project from module 11.

Why does Claude Code start every session from scratch?

The Claude Code documentation says it in one line: each session begins with a fresh context window. Everything the agent "knows" in a session is what it loaded at startup (its built-in instructions plus the instruction files you wrote) and whatever it reads and does from there. When you close the terminal, that conversation is saved and you can pick it back up, but a new session inherits nothing from it.

As of October 2026, two mechanisms carry knowledge from one session to the next. The first is the CLAUDE.md file: instructions you write, which Claude Code reads at the start of every session. The second is auto memory: notes the agent writes for itself about your corrections and preferences. CLAUDE.md is the one you will master in this module, because it is the builder’s version of the context document from module 2: what you would explain to a new developer on their first day, written once.

Where does CLAUDE.md live and how does Claude Code load it?

It is an ordinary text file in Markdown format, and it can live in several places with different scopes. The three you care about:

• The project’s: `CLAUDE.md` in the project’s root folder (or in `.claude/CLAUDE.md`). This is the one you share with the team through the repository, and the one you write first.
• Yours, for every project: `~/.claude/CLAUDE.md`, in your user folder. Personal preferences that apply to everything you do: "answer me in Spanish", "explain before deleting".
• Yours, for this project only: `CLAUDE.local.md`, next to the project one. Private notes that do not go into the repository (it has to be added to `.gitignore`, which you will see in module 13).

At startup, Claude Code loads the CLAUDE.md from the folder you opened it in and from the folders above it; files in subfolders load only when it works on a file there. They are all concatenated, not overridden: if your personal file and the project file contradict each other, the agent may follow either. There is also a managed location for companies and a `.claude/rules/` folder for splitting long rules into several files; a small project does not need either yet.

Three commands you will use from today. `/init` analyzes your project and writes a first draft of CLAUDE.md; if one already exists, it suggests improvements instead of overwriting it. `/memory` lists your memory files and opens them in your editor. `/context` shows what is taking up the context window; if your CLAUDE.md is not listed there under "Memory files", the agent is not seeing it.

What goes in CLAUDE.md, and what stays out?

Anthropic’s rule is brutally simple: for each line, ask whether removing it would cause the agent to make mistakes. If not, cut it. A long CLAUDE.md is not a safer one: the documentation warns that bloated files cause Claude to ignore the instructions that actually matter, and recommends staying under 200 lines. What belongs:

• How to run, build and test. The exact commands, which the agent cannot guess from the code.
• Conventions that differ from the defaults. Style, the language of the copy, how things are named. What any developer would do by default does not need writing down.
• What not to touch. Files with keys, generated folders, real customer data.
• What "done" means. Tests pass, it shows in both languages, no dashes as punctuation: the standard you would apply when reviewing.
• Project-specific decisions and traps. Why prices live in that file, which environment variable is required, the mistake everyone makes the first time.

What stays out: long documentation (link to it), anything that can be worked out by reading the code, file-by-file descriptions, empty advice like "write clean code" and whatever changes every week. An instruction that only applies to one part of the project, or a multi-step procedure, belongs in a skill, which loads only when needed (module 14).

And the most important clarification in the module: Claude Code treats CLAUDE.md as context, not enforced configuration. The agent reads it and tries to follow it, but there is no guarantee, especially with vague or conflicting instructions. Write things that can be checked ("use 2-space indentation", "run `npm test` before calling it done") rather than wishes ("test your changes well"). When something must happen every time, with no exceptions, the mechanism is different: hooks, which you will meet in module 14.

A template for a small project

Seven sections, two to five lines each. If the whole file does not fit on one screen, something is surplus.

1. 1What this is. Two lines: what the project does, for whom, and what it is built with (language and main tools).
2. 2How to run it. The commands to install, run, build and test, one per line.
3. 3Where things are. The three or four folders that matter, not the whole tree.
4. 4Style rules. Only the ones that differ from the defaults: language, format, what is forbidden.
5. 5Do not touch. Files and folders the agent does not edit without asking.
6. 6What done means. Tests that must pass, how to verify by hand, what to check before handing over.
7. 7Workflow. How commits or branches are named, and which actions need confirmation first. This section grows in module 13.

If writing it from a blank page is daunting, let the agent interview you: it is the technique Anthropic’s documentation recommends for specifying large features, applied to the file that governs all of them.

I want to write the CLAUDE.md for this project. Before writing anything, explore the folder to understand what it is and what it is built with, then interview me, one question at a time, about what you cannot infer from the code:

- Who the project is for and what it does, in one sentence.
- How it is run, built and tested (confirm the commands you found).
- Conventions that differ from the defaults: language, style, format, forbidden words.
- Which files or folders you must not touch without asking.
- What "done" means to me: which tests must pass and what I check by hand.
- Traps or mistakes that already happened and I do not want repeated.

Do not ask the obvious or anything you already saw in the code. When you have enough, write the CLAUDE.md at the project root: at most [NUMBER, for example 60] lines, sections with short headings, concrete and checkable instructions, no long explanations. At the end, tell me what you left out on purpose and why.

Review this project’s CLAUDE.md as if you were a new developer reading it for the first time, and compare it with what you see in the code. Give me three lists:

1. SURPLUS: lines you could infer by reading the code, generic advice, documentation that should be a link, and anything that has changed and is no longer true. For each one, say whether you would delete it or move it into a skill.
2. MISSING: what you had to guess or ask about in earlier sessions and should be written down: commands, conventions, files that are off limits, the definition of done.
3. CONTRADICTIONS: instructions that clash with each other, or with what the code actually does. Include clashes with [OTHER INSTRUCTION FILES, IF ANY: ~/.claude/CLAUDE.md, .claude/rules/, agents].

Then propose the full corrected version, at most [NUMBER] lines. Do not apply the change until I approve it.

Does Claude Code have a memory of its own?

Yes, and it pays to understand what it does so you do not confuse it with CLAUDE.md. As of October 2026, auto memory is on by default in local sessions. As you work, the agent decides whether something is worth remembering and writes it down: your role and preferences, corrections you gave it, project decisions that cannot be derived from the code. It skips whatever your CLAUDE.md already says. When you see "Saved 2 memories" on screen, that is what is happening.

Those notes live on your computer, in one folder per project inside `~/.claude/`, with an index called `MEMORY.md` whose first 200 lines load at the start of every session. They are not shared with your team or with other machines. You can read, edit or delete them, and switch the feature off from `/memory`. The practical difference: if you tell the agent "remember that we use pnpm", it goes into its auto memory, yours alone; if you say "add this to CLAUDE.md", it goes into the file the whole team sees. Project rules go in the file; auto memory is for what the agent learns about you.

What do I do when the session fills up?

In module 2 you saw that long conversations degrade. In Claude Code it happens faster, because the window holds every file the agent reads and the output of every command it runs: a single debugging session can consume tens of thousands of tokens. Anthropic’s best-practices guide calls this the number one constraint: as the window fills, the agent starts "forgetting" instructions and making more mistakes. Managing that space is context engineering in its most concrete form.

The tools, with their exact names as of October 2026:

• `/context` shows, as a colored grid, what is taking up the window: instructions, memory files, tools, conversation.
• `/clear` starts a new conversation with an empty window. The previous one is saved and you can return to it with `/resume`. Use it between unrelated tasks.
• `/compact` replaces the history with a summary and frees space without leaving the task. You can steer it: `/compact focus on the pricing changes`. Claude Code does this on its own as it nears the limit, but doing it yourself before a long task lets you choose what survives.
• `/btw` asks a quick side question about what is going on without the question or the answer entering the history.
• `/rewind` (or Esc twice) takes you back to an earlier point in the conversation or the code, or summarizes just part of it.

What survives a compaction, according to the documentation: CLAUDE.md and auto memory are reloaded from disk, and the agent re-reads up to five of the files it modified most recently. Whatever the summary leaves out, the agent no longer has. That is why it is worth putting an instruction in your CLAUDE.md such as "when compacting, keep the list of modified files and the test commands".

Two habits the documentation recommends. One: if you have corrected the agent twice on the same thing and it is still wrong, run `/clear` and write a new prompt that includes what you learned; a clean session with a good prompt almost always beats a long one full of failed attempts. Two: do not mix tasks in one session. Rule of thumb: `/compact` when you are staying on the same task and only need room, `/clear` when you are switching tasks.

To pick up unfinished work you do not need summaries: Claude Code saves every conversation on your computer, tied to the project folder. `claude --continue` reopens the most recent one in that folder, `claude --resume` opens a picker, and `/resume` switches conversations from inside a session; `/rename` gives them names so you can find them later. A written summary is still useful for handing the work to another person, another tool or a clean session without dragging the noise along.

This session has grown long and I am going to continue it in a new one. Write a summary so that another Claude Code session, with no memory of this one, can pick up exactly where we are. In this order:

1. GOAL: what we are building or fixing, in two lines.
2. FILES TOUCHED: every file created or modified, with one line on what changed and why.
3. DECISIONS: what was settled, what we ruled out and why, so it is not proposed again.
4. STATUS: what already works (and how we verified it), what is half done, what is left.
5. COMMANDS: the exact commands we used to run, test and verify.
6. NEXT STEP: the first thing the new session should do.
7. FOR CLAUDE.md: what we learned in this session that should become permanent in the file, if anything.

Save it as [NAME, for example SESSION-NOTES.md] at the project root. Do not invent anything that is not in this conversation; mark anything ambiguous as pending.

And when answering one question requires reading thirty files, there is a third route: ask the agent to use a subagent, which investigates in its own context window and returns only the summary. Just say it: "use a subagent to investigate how prices are calculated". In module 14 you will define your own.

To go deeper, Anthropic Academy’s free course Claude Code in action has a lesson on writing a CLAUDE.md the agent actually follows and another on steering long sessions. The next module, "Planning, permissions and working with Git", is where the agent starts changing real things with a safety net underneath.