Four Memory Layers in Claude Code: Stop Putting Everything in CLAUDE.md

Claude Code has four distinct surfaces for persistent context — CLAUDE.md files, hooks, skills, and auto-memory — and most developers only use one. Knowing which to use triples session effectiveness.

The common failure mode: a 600-line CLAUDE.md that buries critical rules in the middle, where the "lost in the middle" attention effect means the model reads them but doesn't weight them. The fix is matching each type of persistent information to the surface designed to carry it.

The four surfaces

1. CLAUDE.md files (three scopes, additive)

CLAUDE.md loads into every session's context at startup. Three scope layers stack additively — all contribute simultaneously, with narrower scopes taking precedence on conflicts:

Scope	Location	Use for
Project	.claude/CLAUDE.md	Codebase conventions, architecture notes, run commands — things Claude would get wrong without them
Local	.claude/CLAUDE.local.md	Your personal machine overrides, test credentials, local paths — gitignored, never shared
User	~/.claude/CLAUDE.md	Cross-project preferences you always want: output style, preferred tools, personal workflow rules

Keep each file under ~200–300 lines. The "lost in the middle" effect means accuracy drops 30%+ for content buried in a long context. Front-load the most critical instructions at the top.

2. Hooks — enforced, deterministic side effects

If a rule must be enforced regardless of what Claude decides, put it in a hook. Hooks run shell commands on specific events and block or allow based on exit code. They can't be "ignored" the way a CLAUDE.md instruction can:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{"type": "command", "command": "node scripts/validate-blog.mjs"}]
    }]
  }
}

Use hooks for: linting on save, secret scanning before push, running tests after edits, blocking banned commands.

3. Skills (.claude/skills/) — reusable multi-step workflows

A skill is a markdown file with instructions Claude loads on demand. Use skills for complex, repeatable multi-step workflows (publish a post, scaffold a feature, run a review) that shouldn't be in every session's context budget.

Unlike CLAUDE.md, skills only load when invoked with the Skill tool or a slash command — zero context cost at startup.

4. Auto-memory

When you correct Claude ("always use single quotes in this project"), Claude writes a note to .claude/memory/ that persists across sessions without any manual CLAUDE.md editing. This is behavioral learning built into the loop.

What goes where: the cheat sheet

Type of information	Right surface
"How this codebase works"	CLAUDE.md (project scope)
"My local environment quirks"	CLAUDE.md (local scope)
"Preferences across all my projects"	CLAUDE.md (user scope)
"Always lint before commit"	Hooks
"Do this 10-step workflow on request"	Skill
"Remember my style correction"	Auto-memory

Sources: How Claude remembers your project — code.claude.com · Explore the .claude directory — code.claude.com · Claude Code settings — code.claude.com