Lesson 07: The Memory System

How Claude Remembers

Every time you start a Claude Code session, it loads a set of markdown files into its context. These files form Claude's memory — the accumulated knowledge, rules, and preferences that persist across sessions. There is no hidden database. Memory is just files, and you have full control over them.

This lesson covers the complete memory system: every file type, where each one lives, how they interact, and how to use them day-to-day.

Relationship to Lesson 04: Lesson 04 covers what to write inside a CLAUDE.md file (project context, coding standards, workflow commands). This lesson covers how the memory system works as a whole — the full hierarchy, auto-memory, imports, rules, and the daily workflow of managing Claude's knowledge.

The Full Memory Hierarchy

Claude Code loads memory from six locations, listed here from broadest scope to most specific. When instructions conflict, more specific files win.

How loading works

• CLAUDE.md files in parent directories above the working directory are loaded in full at launch. Claude walks up from your cwd to the root looking for them.
• CLAUDE.md files in child directories are loaded on demand when Claude reads files in those subdirectories.
• .claude/rules/*.md files are all discovered recursively and loaded automatically. Files with paths: frontmatter only apply when Claude works with matching files.
• Auto-memory loads the first 200 lines of MEMORY.md at session start. Topic files are read on demand.

User Memory (`~/.claude/CLAUDE.md`)

This file applies to every project you open. Use it for preferences that are always true about how you work.

# My Preferences

- Use bun, not npm
- Prefer concise responses — skip preamble
- Use conventional commits: feat:, fix:, chore:, docs:
- Never add TODO comments without issue numbers
- 2-space indentation everywhere

You can also create personal rules that apply everywhere at ~/.claude/rules/:

~/.claude/rules/
├── preferences.md    # Coding preferences
└── workflows.md      # Preferred workflows

User-level rules load before project rules, so project rules take higher priority.

Project Memory (`./CLAUDE.md`)

This is the team-shared file committed to source control. Lesson 04 covers writing effective project instructions in depth. Either ./CLAUDE.md or ./.claude/CLAUDE.md works — pick one location and stick with it.

You can bootstrap a project memory file with:

> /init

Modular Rules (`.claude/rules/`)

For larger projects, a single CLAUDE.md can become unwieldy. The .claude/rules/ directory lets you split instructions into focused, topic-specific files that are all loaded automatically.

Basic structure

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       ├── security.md
│       └── frontend/
│           ├── react.md
│           └── styles.md

All .md files in .claude/rules/ are discovered recursively — subdirectories work fine for organization.

Path-specific rules

Rules can be scoped to certain files using YAML frontmatter with the paths field. These conditional rules only apply when Claude is working with files that match the patterns.

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format from /lib/errors.ts
- Include OpenAPI documentation comments

Rules without a paths field load unconditionally.

Supported glob patterns:

Sharing rules across projects with symlinks

# Symlink a shared rules directory
ln -s ~/shared-claude-rules .claude/rules/shared

# Symlink an individual file
ln -s ~/company-standards/security.md .claude/rules/security.md

Circular symlinks are detected and handled gracefully.

Local Overrides (`CLAUDE.local.md`)

CLAUDE.local.md is automatically gitignored, making it the right place for personal per-project preferences that should not be committed.

Common uses:

• Your personal sandbox/staging URLs
• Local dev environment paths
• Preferred test data or fixtures
• Overrides for team rules that don't match your setup

# My Local Config

- My dev server runs on port 4000 (not the default 3000)
- Use the staging API at https://staging.internal.example.com
- Skip e2e tests locally — they require VPN access

Similarly, .claude/rules/*.local.md files are gitignored and let you add personal rule files alongside the team's shared rules.

Auto-Memory

Auto-memory is different from everything above. Instead of you writing instructions for Claude, this is where Claude writes notes for itself based on what it discovers during sessions.

What Claude remembers

As Claude works, it may save things like:

• Project patterns: build commands, test conventions, code style it observed
• 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

Where it lives

Each project gets its own memory directory at ~/.claude/projects/<project>/memory/. The <project> path is derived from the git repository root, so all subdirectories within the same repo share one auto-memory directory.

~/.claude/projects//memory/
├── MEMORY.md            # Concise index (first 200 lines loaded at startup)
├── debugging.md         # Detailed notes on debugging patterns
├── api-conventions.md   # API design decisions
└── ...                  # Other topic files Claude creates as needed

MEMORY.md acts as an index. Claude keeps it concise by moving detailed notes into separate topic files. Only the first 200 lines of MEMORY.md are loaded into context at session start — topic files are read on demand when Claude needs them.

Saving things explicitly

You can tell Claude what to remember at any point:

"Remember that we use pnpm, not npm."
"Save to memory that the API tests require a local Redis instance."
"Forget what you saved about MySQL — we migrated to PostgreSQL."

Enabling or disabling auto-memory

Auto-memory is being rolled out gradually. You can control it with an environment variable:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0  # Force ON
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1  # Force OFF

The @import Syntax

Any CLAUDE.md file can pull in other files using @path/to/file syntax. This is powerful for keeping memory files focused while still providing Claude with rich context.

See @README.md for project overview and @package.json for available commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- API reference: @docs/api-reference.md

Import rules

• Relative paths resolve relative to the file containing the import, not the working directory.
• Absolute paths and home-directory paths (@~/...) are supported.
• Recursive imports work up to 5 levels deep — an imported file can import other files.
• Code blocks are excluded — @some-package inside a backtick code span or fenced code block is not treated as an import.
• First-time approval — the first time Claude encounters imports in a project, it shows an approval dialog listing the files. This is a one-time decision per project.

Sharing preferences across worktrees

If you work with multiple git worktrees, CLAUDE.local.md only exists in one. Use a home-directory import so all worktrees share your personal instructions:

# Individual Preferences
- @~/.claude/my-project-instructions.md

The `/memory` Command

The /memory command opens a file selector that lists all your active memory files — CLAUDE.md files, rules, local overrides, and your auto-memory entrypoint. Select any file to open it in your system editor for quick edits.

This is the fastest way to:

• Check what memory is currently loaded
• Add or update a rule mid-session
• Clean up auto-memory that has grown stale
• See the full picture of what Claude is reading

What to Store Where

When to promote auto-memory to CLAUDE.md

If you find the same thing appearing in auto-memory across multiple sessions, promote it:

1. Open /memory and find the entry in MEMORY.md or a topic file
2. Move the content to your project's CLAUDE.md or a file in .claude/rules/
3. Remove it from auto-memory to avoid duplication

This keeps auto-memory lean and ensures important knowledge is versioned and shared with your team.

Day-to-Day Workflow

Starting a new project

1. Run /init to bootstrap a CLAUDE.md
2. Add your tech stack, build commands, and coding standards
3. Create a CLAUDE.local.md for any personal dev environment details
4. Work normally — Claude will begin accumulating auto-memory as it learns your project

Growing a project

1. When CLAUDE.md gets long, split rules into .claude/rules/ files
2. Use paths: frontmatter to scope rules to relevant file types
3. Periodically review auto-memory with /memory — promote stable patterns, remove stale entries

Joining an existing project

1. The team's CLAUDE.md and .claude/rules/ are already in the repo
2. Create your CLAUDE.local.md for personal preferences
3. Claude's auto-memory will build up as you work — no manual setup needed

Practical Exercise

1. Run /memory and review every file that is currently loaded in your project
2. Create a .claude/rules/ directory in a project and add at least two focused rule files (e.g., testing.md and code-style.md)
3. Add a paths: frontmatter block to one rule file so it only applies to a specific file type
4. Create a CLAUDE.local.md with at least one personal override
5. Add an @import to your project CLAUDE.md that pulls in your README or another reference doc
6. Tell Claude to "remember that [something specific about your project]" and verify it appears in auto-memory
7. Start a new session and confirm Claude recalls what you saved