Skip to content

5.3 The Memory Layers

CLAUDE.md gave your project a brain. But you work on multiple projects, and some truths are about you, not any one of them. Memory in agentic systems comes in layers — each with a scope, a home, and a job. This lesson maps the layers and teaches the skill of filing each fact where it belongs.

What you will learn

  • Map the memory layers: session, project, user — and what lives where.
  • Use Claude Code's memory locations: project CLAUDE.md, user-level CLAUDE.md, and auto-memory.
  • Apply the filing rule: scope of the fact = layer of the memory.

Builder principle

A fact filed in the right layer is remembered exactly when it's relevant — and never clutters when it's not.

The three layers

┌──────────────────────────────────────────────────────┐
│ SESSION — the context window                          │
│ scope: right now  ·  lifetime: until /clear or exit   │
│ "the conversation, the files read, the work so far"   │
├──────────────────────────────────────────────────────┤
│ PROJECT — CLAUDE.md + project files                   │
│ scope: this project  ·  lifetime: life of the repo    │
│ "conventions, layout, boundaries, decisions"          │
├──────────────────────────────────────────────────────┤
│ USER — your user-level CLAUDE.md + agent memory       │
│ scope: every project you touch  ·  lifetime: yours    │
│ "who you are, how you like to work, your standards"   │
└──────────────────────────────────────────────────────┘

Session memory you already manage — it's the whiteboard (2.2), curated with scoped briefs and /clear (more in 5.5). Powerful, and gone by design.

Project memory you built last lesson. It travels with the repo: clone the project on a new machine — or hand it to a collaborator — and the agent's knowledge arrives with it. That's why project facts must live here, not in your head or your user file.

User memory is the new layer. Claude Code also reads a CLAUDE.md from your home configuration directory (~/.claude/CLAUDE.md) — loaded in every session, every project. This is where you live:

# About me & how I work

- I'm learning — explain non-obvious choices in one line as you make them.
- Ask before adding any dependency, always.
- I test at phone width religiously; assume mobile matters.
- Voice for anything user-facing: plain, warm, no jargon.
- When I say "ship it" I mean: commit, push, confirm deploy.

A short, accurate user file can reduce repeated explanations across projects. Inspect each session's behavior rather than assuming the instructions were loaded or followed correctly.

Alongside the files you write by hand, Claude Code can also write memory itself — noting durable facts it learns as you work, so they persist across sessions. You stay the editor: memory an agent wrote is memory you should occasionally read, prune, and correct, like any teammate's notes.

The filing rule

One question sorts every fact:

"Where is this true?" True right now → leave it in session. True of this project → project CLAUDE.md. True of you everywhere → user CLAUDE.md.

Misfiling is the failure mode in both directions:

  • Project facts in the user file → your bakery-site conventions haunt your data-pipeline project. Confusion, not memory.
  • Universal preferences repeated per-project → you maintain five copies, four go stale, the stale ones win at the worst time.
  • Everything left in session → Groundhog Day forever. The layer above exists precisely to end this.

Start your user file with just three lines — your experience level, your ask-first rule, your voice. Add lines only when you catch yourself telling another project's agent the same thing. Real usage, not imagination, should write this file.

Two power moves. First, CLAUDE.md files nest: a monorepo can carry a root file plus per-package ones (services/api/CLAUDE.md), and Claude Code picks up the relevant ones by location — scope granularity for free (this scales hard in 5.6). Second, wire the layers together deliberately: user file for your invariants, project file for team truth, and keep them non-overlapping — duplicated guidance drifts, and drifted guidance is worse than none.

Memory hygiene: the five-minute audit

Monthly, or when behavior feels off:

  1. Read your user CLAUDE.md — still true of you? (You're evolving; the you of Chapter 3 wrote some of it.)
  2. Read the project file — any rule the project outgrew?
  3. Read what the agent has written to memory, if anything — keep the good, delete the wrong.
  4. Look for facts filed at the wrong layer and move them.

Five minutes. The compounding asset stays compounding instead of calcifying.

Try it now

  1. Create ~/.claude/CLAUDE.md with 3–5 honest lines about how you work.
  2. Test the layering: /clear, then in your quick-win project ask What do you know about me, and what do you know about this project? Answer separately. Watch the two layers surface separately.
  3. Catch one misfiled fact in either file and move it to its right home.
  4. Journal: which fact have you repeated most across sessions? It's filed now, right?

Check your understanding

  • Name the three layers with their scope and lifetime.
  • What's the filing question, and where do these go: "this client hates carousels" / "I always want dependencies asked-first" / "the header bug we're fixing today"?
  • Why is project memory in the repo (not your head or user file) essential for collaboration?
  • What are the risks of agent-written memory, and what's your job as its editor?