Beginner 1 concept to know first · leads to 1

Memory

CLAUDE.md files you write and auto memory notes Claude writes for itself: plain markdown on disk, loaded at the start of every session so Claude doesn't start from zero.

The animation needs JavaScript; every step is described below.

0:15

Know these first

1 concept · basics first
  1. Context

    The context window is everything Claude can see in a session: your messages, the files it reads, tool output and auto-loaded instructions. It fills as you work, and Claude Code compacts it when it gets full.

  2. Memory · you are here

Each Claude Code session starts with a fresh context window: nothing from yesterday’s conversation carries over on its own. Memory is how knowledge survives between sessions. There are two kinds, and both are plain markdown files on disk that load into context when a session starts.

CLAUDE.md: what you write

A CLAUDE.md file holds what you’d otherwise re-explain every session: build and test commands, conventions, project layout, “always do X” rules. Where you put it sets its scope:

  • ~/.claude/CLAUDE.md: your personal preferences, in every project.
  • ./CLAUDE.md or ./.claude/CLAUDE.md: the project’s instructions, committed so your whole team gets them.
  • ./CLAUDE.local.md: your private notes for this one project; add it to .gitignore.

Files in the directory you launch from and the ones above it load at startup, and they are concatenated, not overridden: broader files come first, so the ones closest to where you launched are read last. A CLAUDE.md in a subdirectory loads only when Claude reads files in that folder. Run /init to generate a starter file from your codebase, and /memory to open and edit them.

Auto memory: what Claude writes

Auto memory is the notes Claude keeps for itself: your preferences, corrections you’ve given it, project context it can’t work out from the code. It lives in ~/.claude/projects/<project>/memory/, with a MEMORY.md index whose first 200 lines (or 25KB) load every session; the topic files it points to are read only when needed. When you ask Claude to remember something, this is where it goes. Auto memory is on by default, stays on your machine, and can be switched off from /memory.

The catch

Memory is context, not configuration. Claude reads these files as instructions and usually follows them, but nothing enforces them; if something must never happen, use a hook. Every line also costs context in every session, so the docs suggest keeping each CLAUDE.md under about 200 lines and moving long procedures into skills. If two instructions contradict each other, Claude may pick either, so prune old ones. When an instruction seems ignored, run /context to check that its file actually loaded.

Where it sits

Before this

Context
Memory

Leads to

Skills

The ideas underneath · Field Guide

System Prompt Context Window

Sources

  1. How Claude remembers your project . Claude Code docs: CLAUDE.md locations and load order, auto memory, /memory
  2. Explore the context window . Claude Code docs: where memory files sit in context and what survives compaction

Verified against the official Claude Code docs on October 1, 2026 · next review by January 1, 2027. Claude Code changes quickly; the docs are the source of truth.