Claude Code's Memory System: CLAUDE.md and Beyond

By James Aspinwall

Claude Code remembers things between sessions. Not through magic — through a layered system of Markdown files that feed context into every conversation. Understanding how these files work is the difference between a generic AI assistant and one that knows your codebase, your conventions, and your preferences.

The Three Layers

Claude Code’s context system has three distinct layers:

CLAUDE.md — Instructions you write for Claude
Auto-memory — Notes Claude writes for itself
Modular rules — Topic-specific instructions in .claude/rules/

Each serves a different purpose. Together, they give Claude persistent, project-aware intelligence.

CLAUDE.md: Your Project’s Constitution

CLAUDE.md is the primary way to tell Claude how your project works. It lives at the root of your repo and gets loaded into every session automatically.

What Goes In It

Things Claude can’t figure out by reading your code:

Build and test commands
Code style rules that differ from language defaults
Architecture decisions and conventions
Branch naming and PR etiquette
Environment quirks and required variables
Common gotchas

What Stays Out

Standard language conventions Claude already knows
Detailed API docs (link to them instead)
Information that changes frequently
File-by-file codebase descriptions

Keep it concise. Bloated CLAUDE.md files get ignored.

The Hierarchy

CLAUDE.md files can live at multiple levels, each with different scope:

Location	Scope	Shared?
`./CLAUDE.md`	Project-wide	Yes (git)
`./.claude/CLAUDE.md`	Project-wide	Yes (git)
`./CLAUDE.local.md`	Project, personal	No (.gitignore)
`~/.claude/CLAUDE.md`	All your projects	No
Organization path	All users	Yes (IT-managed)

More specific files take precedence over broader ones. Your project CLAUDE.md overrides your user-level one. A CLAUDE.md in a subdirectory overrides the root when Claude is working in that subtree.

Loading Behavior

Claude walks upward from your working directory to the root, loading every CLAUDE.md it finds. Child directory CLAUDE.md files load on-demand — only when Claude reads files in that subtree.

Imports

CLAUDE.md supports pulling in other files:

See @README for project overview.
Git workflow: @docs/git-instructions.md
Personal overrides: @~/.claude/my-project-config.md

Relative paths resolve from the file containing the import, not your working directory. Max recursion depth is 5 hops.

Auto-Memory: Claude’s Own Notes

Auto-memory is Claude writing notes to itself — patterns it discovers, preferences you express, solutions to problems it solved. These persist across sessions without you having to repeat yourself.

Where It Lives

~/.claude/projects/<project-path>/memory/
├── MEMORY.md          # Index file — loaded every session
├── debugging.md       # Detailed debugging notes
├── patterns.md        # Code patterns and conventions
└── ...                # Any topic files Claude creates

The <project-path> is derived from your git repository root. All subdirectories within the same repo share one memory directory.

The 200-Line Rule

Only the first 200 lines of MEMORY.md are loaded into Claude’s system prompt at startup. Everything beyond that is invisible unless Claude explicitly reads the file. This is why MEMORY.md should be a concise index that links to detailed topic files.

What Gets Remembered

Project patterns: build commands, test conventions, code style
Debugging insights: solutions to tricky problems, common error causes
Architecture notes: key files, module relationships, important abstractions
Your preferences: communication style, workflow habits, tool choices

Telling Claude What to Remember

You can be direct: “Remember that we use pnpm, not npm” or “Always run tests with --verbose.” Claude saves these immediately.

To forget: “Stop remembering X” and Claude will remove the entry.

To manage manually: /memory opens your memory files in your editor.

Modular Rules: Organized Instructions

For larger projects, a single CLAUDE.md gets unwieldy. The .claude/rules/ directory lets you break instructions into topic files:

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    ├── testing.md
    └── security.md

All .md files in rules/ are automatically loaded. They can target specific file patterns using YAML frontmatter:

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.ts"
---
# API Development Rules
Use structured error responses. Always validate input at the boundary.

This rule only activates when Claude works on files matching those globs.

Practical Commands

Command	Purpose
`/init`	Generate a starter CLAUDE.md from your project structure
`/memory`	Open memory files in your editor
`/clear`	Reset context between unrelated tasks
`/compact`	Compress conversation, optionally with focus instructions

Tips From Production Use

Start with /init, then edit. It’s faster than writing from scratch and catches things you’d forget.

Review memory periodically. Claude’s auto-memory accumulates. Run /memory every few weeks and prune what’s outdated.

Use CLAUDE.local.md for personal quirks. Your teammates don’t need to know you prefer tabs or that your test database is on a non-standard port.

Keep CLAUDE.md under 100 lines. If it’s longer, move sections into .claude/rules/ files. Claude processes shorter, focused files more reliably than one massive document.

Don’t duplicate what code says. If your package.json has a test script, you don’t need “run tests with npm test“ in CLAUDE.md. Claude reads package.json.

The Big Picture

The memory system turns Claude Code from a stateless tool into a persistent collaborator. CLAUDE.md sets the rules. Auto-memory learns the patterns. Modular rules scale the instructions. Together, they mean you explain things once and Claude remembers — across sessions, across days, across the lifetime of your project.