50 50. CLAUDE.md and Memory

Every Claude Code session starts with a blank slate: Claude does not remember yesterday’s conversation. This page covers the two ways Claude Code carries knowledge from one session to the next: CLAUDE.md files that you write, and auto memory notes that Claude writes for itself.

50.1 Why Claude needs a memory file

As of Oct 6, 2026 · Official docs: How Claude remembers your project

Each session begins with a fresh context window, Claude’s working memory for one conversation (more on the Context, Models, Effort, and Usage page). Imagine a skilled new teammate who forgets everything every night. You would leave them a short note: how to run the project, the team’s rules, the mistakes to avoid. That note is CLAUDE.md, a plain-text Markdown file that Claude Code loads at the start of every session.

	CLAUDE.md files	Auto memory
Who writes it	You	Claude
What it holds	Instructions and rules	Learnings: your preferences, corrections you gave, project facts Claude can’t get from the code
When it loads	Start of every session	Start of every session (the first 200 lines or 25 KB of its index)
Where it lives	In your project (and optionally your home folder)	In your home folder, under `~/.claude/projects/`

Both are guidance, not guarantees. Claude reads them and tries to follow them, but nothing forces it to. If something must never happen (for example, reading your .env file of secrets), use a permission rule or a hook instead (see Permissions, Modes, and Safety and Hooks).

50.2 Where CLAUDE.md files live

As of Oct 6, 2026 · Official docs: How Claude remembers your project

Scope	Location	Who it’s for
Project	`CLAUDE.md` or `.claude/CLAUDE.md` in the project folder	Everyone on the project: commit it to Git
Local	`CLAUDE.local.md` in the project folder	Only you, only this project: add it to `.gitignore`
User	`~/.claude/CLAUDE.md`	Only you, in every project
Managed policy	A system folder set up by an IT department	Everyone in an organization (not needed for this course)

(~ is your home folder: /Users/maria on Maria’s Mac, /c/Users/sam in Sam’s Git Bash.) How the files load:

They add up; they don’t replace each other. Claude Code joins all the files that apply. Your user file comes first, then the project files, so the instructions closest to your project are read last.
Parent folders count. Start claude in club-events/web and Claude Code loads the CLAUDE.md files in club-events/web and in club-events (and in any folder above it).
Subfolders load later. A CLAUDE.md inside a subfolder, such as club-events/web/api/CLAUDE.md, loads only when Claude reads or edits a file in that subfolder.
Edits apply at the next fresh start. Claude Code reads your CLAUDE.md files once, when the session starts. If you edit one mid-session, the change takes effect after /clear, /compact, or a restart.

50.3 Creating and editing CLAUDE.md

As of Oct 6, 2026 · Official docs: How Claude remembers your project · Commands

The easiest start is the /init command. In a Claude Code session inside your project folder, type:

/init

Claude looks through your project and writes a starter CLAUDE.md with the build commands, test instructions, and conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it. Read what it wrote, delete what isn’t useful, and add what Claude couldn’t discover on its own.

You want to…	Do this
Open (or create) a memory file in your editor	Run `/memory` and pick the file
Check which CLAUDE.md files actually loaded	Run `/context` and look under Memory files
Add a rule without leaving the chat	Ask: “add a rule to CLAUDE.md: run `npm test` before committing”
Turn a repeated mistake into a rule	Ask: “you keep forgetting X. Add a rule to CLAUDE.md so this stops happening”
Capture lessons at the end of a session	Ask: “summarize what we did this session and suggest what to add to CLAUDE.md”

CLAUDE.md is plain text, so you can also edit it in any text editor (not a word processor).

50.4 What to put in CLAUDE.md (and what to leave out)

As of Oct 6, 2026 · Official docs: Best practices for Claude Code

Write down what you would otherwise re-explain every session. Good moments to add a line: Claude makes the same mistake twice, you type the same correction you typed last session, or a new teammate would need the same information.

Include	Leave out
Commands Claude can’t guess (`npm run dev`, `npm test`)	Anything Claude can figure out by reading the code
Style rules that differ from the usual defaults	Standard conventions Claude already knows
How to run the tests, and which test tool you use	Long explanations or tutorials
Project decisions (“we use Supabase for login”)	Detailed API docs (link to them instead)
Gotchas (“the dev server runs on port 3001”)	Information that changes often
Team habits (branch names, commit message style)	Vague advice such as “write clean code”

Three rules of thumb from the official guide:

Keep it short. Aim for under 200 lines. Long files use more of the context window and Claude follows them less reliably. For each line ask: “Would removing this cause Claude to make mistakes?” If not, cut it.
Be concrete enough to check. “Use 2-space indentation” beats “format code properly”; “Run npm test before committing” beats “test your changes”.
Avoid contradictions. If two instructions conflict, even in two different CLAUDE.md files, Claude may pick either one.

If Claude keeps skipping one important rule, you can add emphasis such as “IMPORTANT” to that one line. If every line is important, none stands out.

50.5 Example: CLAUDE.md for a student web project

As of Oct 6, 2026 · Official docs: Best practices for Claude Code

Maria and Sam are building a small website where students sign up for club events. This CLAUDE.md sits in the project’s top folder and is committed to Git:

# Club Events

A website where students sign up for club events.
Built with Next.js (TypeScript) and Supabase.

## Commands
- Install packages: `npm install`
- Start the dev server: `npm run dev` (http://localhost:3000)
- Run the tests: `npm test`
- Check code style: `npm run lint`

## Project layout
- Pages live in `src/app/`, reusable components in `src/components/`
- Database changes go in `supabase/migrations/`

## Rules
- Use 2-space indentation and named exports
- Never put API keys in code; read them from `.env.local` (it is git-ignored)
- Run `npm test` and `npm run lint` before saying a task is done

## Working with us
- We are beginners: explain each change in plain English
- Make small commits with clear messages

Notice what is not there: no list of every file, no explanation of what React is, no copy of the Supabase documentation. Claude can read the code, and it already knows popular frameworks.

50.6 AGENTS.md and files from other tools

As of Oct 6, 2026 · Official docs: How Claude remembers your project

Other AI coding tools read a similar file named AGENTS.md. Claude Code (version 2.1.277 or later) reads it too:

The project has AGENTS.md but no CLAUDE.md: Claude reads AGENTS.md.
The project has both: by default Claude reads only CLAUDE.md. To share one file between tools, put the line @AGENTS.md at the top of your CLAUDE.md (an import, see the deeper dive below), or change the Project instructions option in /config.

If a project has rules from Cursor (.cursor/rules/ or .cursorrules) or GitHub Copilot (.github/copilot-instructions.md), /init reads them and carries the relevant parts into the new CLAUDE.md.

50.7 Auto memory: notes Claude writes for itself

As of Oct 6, 2026 · Official docs: How Claude remembers your project

Auto memory is on by default. As you work, Claude decides whether something is worth remembering for future sessions: your preferences (“Maria wants plain-English explanations”), corrections you gave it, or project facts it can’t get from the code (a deadline, where the issue tracker is). It skips anything it can read from the code or that your CLAUDE.md already says. You may see messages such as “Saved 2 memories” or “Recalled 2 memories”.

Where: on your computer only, in ~/.claude/projects/<project>/memory/. Each project (Git repository) gets its own folder, holding an index file, MEMORY.md, plus one small Markdown file per topic.
What loads: the first 200 lines (or 25 KB) of MEMORY.md at the start of every session. Topic files are read only when needed.
How to look: run /memory and open the auto memory folder. The files are plain Markdown: you can read, edit, or delete them.
How to turn it off: use the toggle in /memory (it saves "autoMemoryEnabled": false in your user settings), or put that same line in one project’s settings file to turn it off only there (see The .claude Folders and Settings Files).

“Remember” and “CLAUDE.md” go to different places. If you say “remember that the API tests need a local database”, Claude saves it to auto memory: private to you and this computer. If you say “add this to CLAUDE.md”, it goes into the file your teammates get through Git.

50.8 When Claude ignores your CLAUDE.md

As of Oct 6, 2026 · Official docs: How Claude remembers your project · Debug your configuration

Did it load? Run /context and look under Memory files. If it is missing, check the file’s name (CLAUDE.md) and which folder it is in.
Did you edit it mid-session? Run /clear or restart Claude Code.
Is the rule vague, or contradicted elsewhere? Make it specific and remove the conflict.
Is the file too long? Trim it. The /doctor command can propose cuts of content Claude could work out from the code.
Must it happen every time, no exceptions? Then it doesn’t belong in CLAUDE.md: use a permission rule or a hook, which Claude Code enforces.

Deeper dive: imports, rules, comments, and compaction

Imports. A line such as See @README.md for an overview pulls the whole README into context when the session starts. Paths are relative to the file that contains the import, and imports can nest up to four levels deep. Imports help you organize, but they don’t save context: imported files still load every session. To mention a path without importing it, wrap it in backticks.

Rules. Instead of one big file, a project can keep topic files in .claude/rules/, for example testing.md and api-design.md. A rule without special settings loads every session, like CLAUDE.md. A rule that starts with a paths: block loads only when Claude works on matching files:

---
paths:
  - "src/api/**/*.ts"
---

- All API endpoints must validate their input

Personal rules for every project can go in ~/.claude/rules/. For knowledge Claude needs only sometimes, a skill is often better, because it loads only when used (see Skills).

Comments for humans. HTML comments on their own lines () are removed before Claude sees the file, so they cost no context.

Compaction. When a long conversation is summarized (automatically, or with /compact), the project’s top-level CLAUDE.md and auto memory are reloaded from disk, so their instructions survive. Instructions you only typed in the chat may be lost; if you want them to last, put them in CLAUDE.md.

Practice Questions

Easy

Question 1 · Short answer

What is CLAUDE.md, and when does Claude Code read it?

Suggested answer

CLAUDE.md is a plain-text Markdown file of instructions that you write for Claude: build and test commands, conventions, project rules. Claude Code loads it automatically at the start of every session, so Claude doesn’t have to re-learn your project each time.

Question 2 · Multiple choice

Which statement about auto memory is correct?

You write it by hand, and it is committed to Git with your project.
Claude writes it, and it is stored on your computer under ~/.claude/projects/.
It is stored on Anthropic’s servers and shared across all your devices.
It is a section at the bottom of your project’s CLAUDE.md.

Suggested answer

b. Claude writes auto memory itself, in ~/.claude/projects/<project>/memory/ on your machine. You write CLAUDE.md, not auto memory (a). Auto memory is machine-local and not shared across devices (c). It is a separate folder of files, not part of CLAUDE.md (d).

Question 3 · Matching

Match each location with who its instructions are for.

Location		Who it’s for
1. `CLAUDE.md` in the project folder		A. Only you, in every project
2. `CLAUDE.local.md` in the project folder		B. Notes Claude writes for itself about this project
3. `~/.claude/CLAUDE.md`		C. Everyone working on the project (committed to Git)
4. `~/.claude/projects/<project>/memory/`		D. Only you, only this project (git-ignored)

Suggested answer

1 → C, 2 → D, 3 → A, 4 → B.

Question 4 · True or false

If your CLAUDE.md says “Never delete files in the data/ folder”, Claude Code makes it impossible for Claude to delete those files.

Suggested answer

False. Claude treats CLAUDE.md as guidance, not enforced configuration. It will usually follow the rule, but nothing guarantees it. To enforce a rule, use a permission deny rule or a hook, which Claude Code applies no matter what Claude decides.

Question 5 · Short answer

What does the /init command do? What happens if the project already has a CLAUDE.md?

Suggested answer

/init has Claude analyze the project and write a starter CLAUDE.md with the build commands, test instructions, and conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it. Either way, you should review and trim the result.

Question 6 · Multiple choice

Which command shows you which CLAUDE.md files were actually loaded into the current session?

/init
/context
/clear
/compact

Suggested answer

b. /context shows what fills the context window, including a Memory files list. /init creates a CLAUDE.md (a), /clear starts a new conversation (c), and /compact summarizes the conversation (d).

Medium

Question 7 · Rewrite

Rewrite each vague CLAUDE.md instruction so it is concrete enough to check.

“Format code properly.”
“Test your changes.”
“Keep files organized.”

Suggested answer

Possible rewrites (yours can differ, as long as each one can be checked):

“Use 2-space indentation” (or “Run npm run lint and fix all errors”).
“Run npm test before committing, and make sure all tests pass.”
“Put React components in src/components/, one component per file.”

Concrete instructions are followed more reliably because there is only one way to read them.

Question 8 · Scenario

Where should each of these instructions go? Choose from: project CLAUDE.md, CLAUDE.local.md, ~/.claude/CLAUDE.md.

“Our tests run with npm test.”
“I like short answers with a summary at the end.” (true for all of Maria’s projects)
“My personal test account for this project is maria-test@example.com.”

Suggested answer

Project CLAUDE.md: every teammate needs it, so commit it.
~/.claude/CLAUDE.md: a personal preference for every project.
CLAUDE.local.md: personal and project-specific, so keep it out of Git (add it to .gitignore). Never put real passwords or API keys in any of these files.

Question 9 · Predict

Maria starts claude in ~/code/club-events/web. These files exist:

~/.claude/CLAUDE.md
~/code/club-events/CLAUDE.md
~/code/club-events/web/CLAUDE.md
~/code/club-events/web/api/CLAUDE.md
~/code/other-project/CLAUDE.md

Which load when the session starts, which may load later, and which never load?

Suggested answer

At start: ~/.claude/CLAUDE.md (user), ~/code/club-events/CLAUDE.md (a parent folder), and ~/code/club-events/web/CLAUDE.md (the starting folder). They are joined together, not replaced.
Later: ~/code/club-events/web/api/CLAUDE.md, but only when Claude reads or edits a file in the api subfolder.
Never: ~/code/other-project/CLAUDE.md. It is neither above nor below the folder where Maria started.

Question 10 · Find the bug

Sam’s CLAUDE.md contains these lines. Name three problems with them.

- Write good code.
- Use tabs for indentation.
- Use 4 spaces for indentation.
- React is a JavaScript library for building user interfaces. It was created
  at Facebook in 2013 and uses a virtual DOM. Components are functions that...
  (40 more lines explaining React)

Suggested answer

“Write good code” is vague and can’t be checked; it adds nothing.
Tabs vs 4 spaces contradict each other. Claude may pick either one.
The React tutorial is wasted context. Claude already knows React; long explanations make the file longer and make Claude follow the important lines less reliably.

A fixed version keeps one indentation rule (for example “Use 4 spaces for indentation”) and deletes the rest.

Question 11 · Scenario

Halfway through a session, Sam adds “Use pnpm, not npm” to the project’s CLAUDE.md and saves it. Claude keeps using npm. Why, and what should Sam do?

Suggested answer

Claude Code reads the project and user CLAUDE.md files once, at the start of the session. An edit made mid-session doesn’t reach the running conversation. Sam should run /clear (or /compact, or restart Claude Code) so the new version loads. He can confirm with /context.

Question 12 · Short answer

What is the difference between saying “remember that our API tests need a local database” and “add to CLAUDE.md that our API tests need a local database”?

Suggested answer

“Remember…” makes Claude save the fact to auto memory (~/.claude/projects/<project>/memory/): private to you and stored only on this computer. “Add to CLAUDE.md…” puts it in the project’s CLAUDE.md file, which you commit, so every teammate’s Claude gets it too.

Question 13 · Multiple choice

A repository has an AGENTS.md file and a CLAUDE.md file in its top folder. With default settings, what does Claude Code read?

Only AGENTS.md
Only CLAUDE.md
Both, AGENTS.md first
Neither, until you run /init

Suggested answer

b. By default Claude reads AGENTS.md only when there is no CLAUDE.md, so (a) would be right only if CLAUDE.md were missing. Claude reads both (c) only if you add an @AGENTS.md import to CLAUDE.md or change Project instructions in /config. Neither file needs /init in order to load (d).

Question 14 · Write the JSON

Maria wants auto memory turned off for one project only. Write the setting she should put in that project’s settings file.

Suggested answer

{
  "autoMemoryEnabled": false
}

In the project’s .claude/settings.json (or in .claude/settings.local.json, if only Maria wants it off), this setting applies only to that project. The /memory toggle instead saves it in her user settings, which affects every project.

Hard

Question 15 · Scenario

Sam’s CLAUDE.md says “Never read the .env file.” Late in a long session, Claude reads .env anyway while debugging. Explain why this can happen and what Sam should use instead.

Suggested answer

CLAUDE.md is guidance, not enforcement: Claude reads it and usually follows it, but nothing stops it from deciding otherwise, especially in a long, crowded session where it may lose track of earlier instructions. For a hard rule, Sam should add a permission deny rule such as "Read(./.env)" to the project’s settings, which Claude Code itself enforces (or use a hook). See Permissions, Modes, and Safety.

Question 16 · True or false

Splitting a 500-line CLAUDE.md into five smaller files that it imports with @path lines reduces how much of the context window the instructions use.

Suggested answer

False. Imported files are loaded at the start of the session along with the CLAUDE.md that imports them, so the total stays the same. Imports help organize, not shrink. To actually save context, trim the content, move file-type-specific instructions into path-scoped rules in .claude/rules/, or move occasional knowledge into skills.

Question 17 · Long answer

Your team’s CLAUDE.md has grown to 600 lines and Claude now ignores about half of it. Describe a plan to fix it.

Suggested answer

A good plan includes most of these steps:

Cut what Claude can work out itself: file-by-file descriptions, explanations of common frameworks, standard conventions. For each line ask “would removing this cause mistakes?” (/doctor can propose such cuts.)
Remove contradictions and outdated rules.
Move part-time instructions out: rules that apply only to some files go into .claude/rules/ with paths:; occasional procedures (for example a release checklist) become skills.
Turn must-happen rules into hooks or permission rules, which are enforced.
Aim for under 200 lines, then test: start a fresh session, check /context, and watch whether Claude’s behavior improves.

Splitting the file with imports alone would not help, because imported files load every session too.

Question 18 · Scenario

At the start of a long session, Maria typed “always explain your changes in plain English.” Three hours later, after the conversation was automatically compacted, Claude stops doing it. Explain what happened and how to make the instruction last.

Suggested answer

When the context window fills, Claude Code compacts the conversation: it replaces the history with a summary. Details given only in the chat can be lost in that summary. The project’s top-level CLAUDE.md (and auto memory) are re-read from disk after compaction, so instructions there survive. Maria should add the rule to CLAUDE.md (project, or ~/.claude/CLAUDE.md if she wants it in every project).

Question 19 · Long answer

Write a short CLAUDE.md (about 10 to 15 lines) for this project: a Python Flask web app for a campus food pantry. Tests run with pytest. The app starts with flask run. Templates are in templates/. The team wants commit messages that start with a verb and wants Claude to never edit files in migrations/ without asking first.

Suggested answer

A model answer:

# Campus Food Pantry

Flask web app for tracking pantry inventory and pickups.

## Commands
- Start the app: `flask run`
- Run the tests: `pytest`

## Layout
- HTML templates are in `templates/`

## Rules
- Run `pytest` before saying a task is done
- Ask before changing anything in `migrations/`
- Commit messages start with a verb, e.g. "Add pickup form"

A good answer is short, uses concrete commands, and skips things Claude already knows (what Flask is). A strong answer also notes that “ask before changing migrations/” is only guidance: to guarantee it, add a permission rule such as an ask rule for Edit(./migrations/**) in the project’s settings.

Question 20 · Compare

For each item, choose the best home: CLAUDE.md, a path-scoped rule in .claude/rules/, or a skill. Explain briefly.

“Run npm test before committing.”
Twelve conventions that apply only to files in src/api/.
A 60-line checklist you follow when publishing a new release (about once a month).

Suggested answer

CLAUDE.md: short and relevant in every session.
A rule with paths: ["src/api/**"]: it loads only when Claude works on matching files, so it doesn’t use context the rest of the time.
A skill: a multi-step procedure needed only occasionally. Skills load only when invoked or relevant, keeping CLAUDE.md short (see Skills).

Challenge

Question 21 · Hands-on

In a practice project (for example the unzipped Git practice project), start Claude Code and run /init. Then:

Read the generated CLAUDE.md and cut it down to the lines you think really matter.
Add two concrete rules of your own.
Run /clear, then /context, and confirm the file is listed under Memory files.
Give Claude a small task that should trigger one of your rules and check whether it follows it.

Write down what you cut and why.

Suggested answer

There is no single right answer. A good write-up shows that you:

removed lines Claude could work out from the code (file lists, general descriptions of HTML or CSS);
kept or added concrete, checkable rules (commands, naming, “explain each change”);
used /clear (or a restart) so the edited file loaded, and confirmed it in /context;
observed whether Claude followed your rule, and reworded it if not.