Claude Code · Series · Part 2 of 3

CLAUDE.md: the project memory that Claude reads every time

In Part 1 we installed Claude Code and had a first session. Now the important question: what happens tomorrow? Open a new session and Claude has no idea who you are, what the project is, or the three things you corrected yesterday. This part explains why that happens and how a plain text file solves it.

1. Why Claude forgets

If you read my earlier post on how AI chat works, this will sound familiar. A language model does not store your conversation. Every time you send a message, the app packs the conversation so far into one block of text, called the context, and hands it to the model. The model can only look at a fixed amount of text at once, the context window.

When you close the session, that block is gone. A new session starts with an empty window. The model is the same, but it is meeting you for the first time.

2. What CLAUDE.md is

It is exactly what the name says: a file called CLAUDE.md, written in markdown (the same simple format as a README). When Claude Code starts, it finds these files and adds their text to the context, ahead of your first message. The model then treats the contents as standing instructions.

It is different from your README.md. A README is written for humans who might contribute. A CLAUDE.md is written for the assistant, and contains the things you would otherwise keep repeating in chat.

3. All the ways Claude “remembers”

Before going further, one important fact: Claude does not remember anything on its own. The model is the same on day 10 as on day 1, and it forgets when a session ends. Everything that looks like memory is Claude Code putting saved text back into the context window. There are only a few ways that happens:

This is also why plan mode (Part 1) does not remember anything: a plan lives in the conversation, so it is gone with it unless it is saved to a file.

Where Claude Code stores things on your computer

If you open ~/.claude/projects/ in Finder or a file manager, you will find one folder per project. According to the official Manage sessions page, each transcript is saved as ~/.claude/projects/<project>/<session-id>.jsonl, where <project> is your working folder's path with every non-alphanumeric character replaced by -. So /Users/me/work/my-app becomes -Users-me-work-my-app, and a session started in / shows up as a folder called just -. Auto memory lives in a memory folder inside the same project folder, and per the memory docs it is shared by all sub-folders and git worktrees of one repository.

What auto memory saves, and how to control it

The official docs describe four kinds of notes Claude may save for itself:

• It is selective. Claude skips anything it can derive from the codebase and anything your CLAUDE.md already says, and it does not save something every session.
• You can see it happen. Messages like “Saved 2 memories” or “Recalled 2 memories” appear in the interface.
• You can switch it off. Run /memory and use the auto memory toggle, set "autoMemoryEnabled": false in a project's settings, or set the environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

It is still just text. It helps only if the notes are correct and short, and it takes up context like any other file, so review it from time to time just as you would CLAUDE.md. Details: auto memory in the official docs.

What happens if you say “remember this session”?

By itself, nothing is guaranteed. Saying it does not change the model. Whether anything survives depends on whether Claude actually writes a file:

• It edits a file (you see an Update(CLAUDE.md) or Write(...) line and a diff). That text loads next session.
• It only replies “Okay, I'll remember” and no file changes. Nothing is saved, and a fresh session will not know.
• Auto memory may save something if it is on. Claude decides what is worth remembering, so it is not guaranteed. You will see “Saved N memories” when it happens.
• Vague wording may give you a short note, a long summary or nothing.

To check, look for the file write in the session or run git diff. Part 3 shows a better way, an explicit handoff note.

4. Where the file can live

You can have several, and Claude Code combines them. Each location has a different audience:

A good split is: personal taste at the user level, how this project works at the root, and how this one area works in the sub-folder. Commit the root file so your whole team gets the same assistant behaviour.

How they combine, per the official docs: Claude Code loads the CLAUDE.md in your working folder and in every folder above it at launch, and files in sub-folders on demand. They are added together, not overridden, ordered from the filesystem root down, so the instructions closest to where you started are read last. If your repository already has an AGENTS.md for other coding tools, Claude Code can read that when there is no CLAUDE.md, or you can import it from one. See How Claude remembers your project.

5. Creating one with /init

You do not have to start from a blank page. Run /init and Claude reads your project (build files, folders, existing docs) and drafts a CLAUDE.md.

> /init

● Analyzing your codebase…
  Read(build.gradle.kts)
  Read(README.md)
  List(app/src)

● Created CLAUDE.md
  Build commands, module layout, and conventions found in the code.
  Review it, then trim anything that is not useful.

The draft is usually decent about commands and structure. It cannot know your team's unwritten rules or what has gone wrong before, so that part is yours to add. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it. To confirm a file really loaded, run /context and look under Memory files.

6. What to put in it

The test for every line is simple: would Claude get this wrong, or waste time finding it, without being told? If not, leave it out.

Specific beats vague. Compare these two lines:

7. A complete example

Here is a realistic root file for the Android chat app from my earlier post. It is deliberately short.

# Private AI Chat (Android)

Kotlin + Jetpack Compose app that chats with an on-device model
(llama.cpp) or an online model, with fallback between them.

## Commands
- Build debug:   ./gradlew assembleDebug
- Unit tests:    ./gradlew testDebugUnitTest
- Lint/format:   ./gradlew ktlintFormat
- Release bundle: ./gradlew :app:bundleRelease

## Structure
- app/ui/        Compose screens (no business logic)
- app/chat/      ViewModels, builds the prompt
- app/engine/    LlmEngine interface + local / online / rules impls
- app/data/      Room database (chats, memories, settings)
- native/        llama.cpp + JNI bridge (C++)

## Conventions
- Screens never call an engine directly: go through the ViewModel.
- Every engine returns Flow<String> of text pieces.
- All native calls run on the single dedicated native thread.
- Use https only for online models; never log prompts or API keys.

## Gotchas
- The native build must target plain armv8-a, or older phones crash (SIGILL).
- Test release builds on a real device: R8 can strip JNI classes.

## Definition of done
- Unit tests pass and ktlint is clean.
- New user-visible strings are in strings.xml.

It is about thirty lines. It answers the questions Claude would otherwise spend time on: how to build, where things live, and the two traps that already cost me a day each.

8. Splitting it up with imports

A CLAUDE.md can pull in other files by writing @ followed by a path. That keeps the main file small while still pointing at the detail.

See @README.md for the project overview.

Architecture details: @docs/architecture.md
Release checklist:    @docs/release.md

Imported files are expanded and loaded at launch along with the main file, so they count toward its size: imports help you organise a long file but do not make it cheaper. A few rules from the official docs:

• Relative paths resolve from the file that contains the import, not from your working folder.
• Imported files can import others, up to four levels deep.
• Imports inside backticks or code blocks are ignored, so write `@README` in backticks to mention a path without importing it.
• The first time a project imports a file from outside the working folder (for example your home folder), Claude Code asks you to approve it.

Use imports to organise, not to hide an enormous document. In Part 3 we will look at the cost side of this.

9. Growing up: the .claude folder

One CLAUDE.md is enough for a small project. As a project grows, a single file turns into a long list that is expensive to load and hard to maintain. Claude Code lets you spread the knowledge across a .claude/ folder in the project, so each piece has a clear job and loads only when it is useful. A typical layout looks like this (the official reference for all of it is the memory documentation):

The pieces, one by one

The most useful distinction is the last column. CLAUDE.md, rules and skills ask Claude to behave a certain way. Settings make it happen. If Claude must never read a file, do not rely on a sentence in CLAUDE.md. Use a deny rule in settings.json.

Rules: split by topic

Move a long section out of CLAUDE.md into its own file and keep one line behind:

# Testing rules
- Unit tests live next to the code in src/test/.
- Name tests: methodName_condition_expectedResult.
- Run ./gradlew testDebugUnitTest before saying a task is done.
- Do not mock the database; use the in-memory one.

Each file stays short, has an obvious owner, and a pull request that changes testing rules touches only testing.md. A modules/ sub-folder works well for one rule file per module. Official reference: Organize rules with .claude/rules/.

A rule can also be limited to certain files with a paths list at the top. It then loads only when Claude works on a matching file, so it costs nothing elsewhere:

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

# API rules
- Every endpoint validates its input.
- Use the standard error response format.

A rule without paths loads every session, like CLAUDE.md.

Skills: a recipe that loads on demand

A skill packages a procedure you would otherwise paste into chat again and again, such as “how we write release notes”. Claude sees only a short description until the task matches, then reads the full instructions. That is the token saving: long how-to text costs nothing on unrelated tasks.

---
name: create-release-notes
description: Write release notes from merged changes. Use when asked to
  prepare or draft release notes for a version.
---

1. List merged pull requests since the last tag.
2. Group them: Features, Fixes, Internal.
3. Write one plain-language line per change; no ticket numbers.
4. Follow the layout in reference.md.

Extra files beside SKILL.md (like reference.md) are read only if the skill points to them. Official reference: Extend Claude with skills.

A fuller settings.json: a deny list

Here is a more complete project .claude/settings.json with the thing I find most useful on a real project: a list of files Claude must not read. The file names are examples; replace them with your own.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets.properties)",
      "Read(./**/*.keystore)",
      "Read(./**/*.pem)",
      "Read(./node_modules/**)",
      "Read(./package-lock.json)",
      "Read(./build/**)",
      "Read(./.idea/**)"
    ]
  }
}

The deny list does two jobs

• Protects secrets. Keystores, key files and local credential files are blocked by the tool itself, so Claude cannot read them even if asked. This is enforced by Claude Code, not by a sentence in CLAUDE.md.
• Saves tokens. Lock files, dependency folders, build output and IDE folders are huge and tell Claude almost nothing. Without a deny rule, one broad search can pull thousands of lines of package-lock.json into the context for no benefit.

Treat the list as a guardrail, not a vault. The safest secret is one that is not in the project folder at all.

Exact rule syntax changes between versions, so confirm it against the official settings and permissions pages before copying it.

What goes in git, and what does not

• Commit: CLAUDE.md, rules/, skills/, settings.json. The whole team gets the same assistant.
• Do not commit: settings.local.json and your personal ~/.claude/ folder. Add the local file to .gitignore.
• Never store keys, tokens or customer data in any of these files, committed or not.
• Review changes to these files in pull requests like code, because a bad rule or setting affects every future session.

10. Keeping it up to date

Three easy ways to change the file:

1. Type /memory to list your CLAUDE.md and memory files, open one in your editor, and toggle auto memory.
2. Tell Claude in plain words: “Add to CLAUDE.md that we always run ktlint before commits.” It will edit the file for you.
3. Edit it like any other file and review the change in a pull request.

> Remember: the debug build needs JAVA_HOME set to JDK 17.
  Add it to CLAUDE.md.

● Update(CLAUDE.md)
  + - Needs JDK 17: set JAVA_HOME before running Gradle.

● Added under ## Commands.

Make this a habit: if you correct Claude twice, put the correction in the file. Equally, when a line stops being true, delete it. A wrong note is worse than none, because Claude will follow it with confidence.

Two more tips from the official docs. First, /doctor prompt-audit asks Claude to check your instruction files for outdated or conflicting content and proposes edits (it changes nothing until you agree, and it needs a recent version). Second, block-level HTML comments such as <!-- maintainer notes --> are stripped before CLAUDE.md is sent to Claude, so you can leave notes for people without spending tokens on them.

11. What it cannot do

• It is guidance, not enforcement. Claude usually follows it, but nothing guarantees it. For rules that must never break, use the permission settings from Part 1's settings file.
• It takes up space. The file sits in the context window for the whole session, using room that could hold your code or conversation.
• It is not learning. Claude does not get smarter from your usage. The model is fixed, and a new session on day 10 starts as blank as on day 1. Only what is written in the file carries over, so the file is your memory, not Claude's.
• It is not secret. It is plain text, usually committed to git. Never put credentials in it.
• It can go stale. Nobody updates what nobody owns. Treat it as code: review it, and prune it.

That second point, the cost of space, is where Part 3 begins: how to make the file earn its tokens, and how it helps when you join a new project or start a new feature.