CLAUDE.md: memory that compounds

The blank-session problem

Every new session, Claude starts from zero. You re-explain the project, the conventions, where the files are, how to reference the API key… That's repeated wasted time, but it's worse than that: it's lost reliability. One day you forget to mention a convention, and Claude displays an API key in plain text in a command, or files something in the wrong place. The quality of your system then depends on your memory in the moment — exactly what we've been trying to eliminate since the start of the course.

The solution is called CLAUDE.md. It's a file at the root of your project that Claude Code reads at the start of every session, before your first message. Everything you put in it becomes persistent context: Claude knows it before you speak. It's the difference between a temp you rebrief every morning and a collaborator who knows the house.

A memory with several floors

CLAUDE.md doesn't exist only at the project root. Claude Code actually reads a hierarchy of memory files, from most general to most specific: your personal file ~/.claude/CLAUDE.md (your preferences valid across all your projects — language, response style, personal conventions), the project's CLAUDE.md (versioned in Git, shared with the team), and optional CLAUDE.md files in subfolders for rules specific to one part of the project.

• ~/.claude/CLAUDE.md — your personal preferences, across all projects.
• CLAUDE.md at the project root — the project's conventions and context, shared via Git.
• subfolder/CLAUDE.md — rules specific to one area, loaded when Claude works there.

This hierarchy answers the "where does what go" question. The rule is the same as in chapter 3 for skills: what's personal goes with you, what belongs to the project goes in the project. "Always answer me in French" → personal. "The API key is referenced via the .env file, never in plain text" → project.

Creating your CLAUDE.md

Two possible paths. The first: the /init command, which analyzes your project and generates a first CLAUDE.md — the right reflex on an existing project Claude doesn't know. The second, more precise for our case: asking Claude to codify what you built together, since it has all the context. Paste this prompt:

create a CLAUDE.md file that codifies everything we've built in this project:
- link to the docs of the API we use
- where the API key lives and how to reference it in commands
- command conventions (always inline, etc.)
- link to the brand voice file
- link to the quality gate config
- link to the post log
- any other pattern we've established

Claude walks through the project, gathers the recurring patterns that worked well, and codifies them. From now on every session starts with the full context: the structure of Lea's project, her conventions, her guardrails. Open the generated file and read it — it's a snapshot of everything you've learned in this course.

What goes in CLAUDE.md (and what doesn't)

Once you grasp the mechanism, the temptation is to put everything in it. Mistake: CLAUDE.md is loaded into the context of every session, so every word has a permanent cost. A 400-line file clutters all your conversations with details that are useless 95% of the time — exactly the noise we've been fighting since chapter 2. The target: a short, dense file where every line deserves to be read in every session.

The # shortcut: memorize on the fly

Maintaining this memory mustn't be a chore, or you won't do it. Claude Code has a dedicated shortcut: start a message with # and what you write is proposed for addition to the memory, without interrupting your work. Mid-session, you notice Claude used a date format you dislike again? Type # dates are always in DD/MM/YYYY format — the rule is captured, the session continues.

The other maintenance mechanism, more structural: at the end of a rich work session, ask "reread our conversation and update CLAUDE.md with the patterns we've established." Claude extracts the durable decisions from the conversation and folds them into the memory. It's the equivalent of meeting minutes — ten seconds to ask, and nothing gets lost.

Knowledge that compounds

Like your skills, your CLAUDE.md evolves continuously — and that loop is what changes everything. Each session builds on the previous one instead of starting from zero: that's how your expertise compounds over time, in the compound-interest sense. Most people use AI linearly: 100 sessions, 100 times the same level. With a maintained memory, your session 100 starts with the distillation of the previous 99.

flowchart LR
  S["Work session"] --> U[""update CLAUDE.md""]
  U --> M["Enriched CLAUDE.md"]
  M -->|"Read at startup"| N["New session"]
  N --> S

And the loop closes with chapter 2: you can now /clear without a second thought. The conversational noise disappears, the essentials come back through CLAUDE.md. Clean context and durable memory — the two requirements that seemed contradictory at the start of the course are reconciled.

What now?

Take stock of Lea's system: a multi-platform /post skill with her brand voice, a quality gate that makes public mistakes impossible, subagents that publish in parallel, a /plan-week command that orchestrates the week, and a project memory that holds it all together over time. Lea types one sentence; the system does the rest, under her control.

To go further, three natural directions: plug in more external tools via MCP (CRM, analytics, calendars — the claude mcp add command is your entry point), explore the browser mode so Claude can test what it publishes itself, and above all: replay this course's method on another process in your professional life. The method — skill, guardrail, parallelization, validation, memory — is the real deliverable of this course. Lea was just the pretext.