The CLAUDE.md Memory System

The CLAUDE.md file is Claude Code's persistent memory system that configures the agent's behavior between sessions. Master the memory hierarchy - from the root file to modular rules - to get consistent responses tailored to your project and aligned with your team's conventions. This guide details how to write, structure, and optimize each memory layer.

The CLAUDE.md memory system is the central mechanism through which Claude Code retains your preferences, conventions, and instructions from one exchange to another. This text file, automatically injected into the system prompt, transforms a generic assistant into a development partner calibrated to your stack. the CLAUDE.md file is read at the start of every session and its content directly influences 100% of the generated responses.

How does the CLAUDE.md memory system work in Claude Code?

The CLAUDE.md file acts as a persistent declarative memory. Unlike a conversation history that disappears, this file stays on your disk and is loaded at each new session. Claude Code v2.1 reads its content before even your first instruction.

In practice, the mechanism follows three steps:

1. Detection - Claude Code scans the current directory and its parents looking for CLAUDE.md files
2. Injection - The content is concatenated and injected into the system prompt
3. Application - Every response follows the directives found

The CLAUDE.md file supports standard Markdown. You can place rules, code examples, file paths, or style preferences in it. The recommended size is 200 lines maximum for the main file - beyond that, lines are truncated.

For a complete introduction to the tool, check the Claude Code home page which presents all available features.

Key takeaway: CLAUDE.md is a text file automatically read at each session, transforming your instructions into persistent agent behavior.

Why is the CLAUDE.md file crucial for your productivity?

Without CLAUDE.md, you repeat the same instructions at every session. developers who configure a structured CLAUDE.md reduce manual corrections on generated responses by 40%.

Here are the measurable gains:

Open your terminal and check if a CLAUDE.md file already exists at the root of your project:

$ ls -la CLAUDE.md
$ cat CLAUDE.md

In practice, a well-written CLAUDE.md eliminates 90% of the reminders you would otherwise give manually. You save an average of 15 minutes per hour of work with the agent. To discover how to leverage this gain from your very first exchanges, explore the guide on your first conversations with Claude Code.

Key takeaway: a structured CLAUDE.md reduces corrections by 40% and eliminates re-contextualization time at each session.

What is the memory hierarchy in Claude Code?

Claude Code is not limited to a single file. It orchestrates a hierarchy of four memory levels, each with a specific scope and priority.

The four memory levels

Configure the user level first with your global preferences:

$ mkdir -p ~/.claude
$ touch ~/.claude/CLAUDE.md

The user level contains your personal conventions: preferred language, commit style, favorite tools. The project level contains specific rules: tech stack, folder structure, architectural patterns.

Conflict resolution

When two levels contradict each other, Claude Code applies the most specific rule. In practice, a .claude/rules/testing.md file that enforces Jest will override a root CLAUDE.md that mentions Vitest. This specificity logic covers 95% of conflict cases.

To understand how this hierarchy interacts with overall context management, check out the context management guide which goes deeper into injection mechanisms.

Key takeaway: four memory levels stack from global (user) to specific (modular rules), with priority given to the most precise rule.

How to write an effective CLAUDE.md in 5 steps?

A poorly structured CLAUDE.md is worse than no CLAUDE.md at all. Follow these five steps to create a file that produces immediate results. For a detailed step-by-step tutorial, refer to the dedicated CLAUDE.md memory system tutorial.

Step 1 - Declare the tech stack

List each technology explicitly with its version:

# Tech Stack
- Runtime: Node.js 22.x
- Framework: Next.js 15.1 (App Router)
- Language: TypeScript 5.7 strict
- Database: PostgreSQL 16
- ORM: Prisma 6.2

Step 2 - Define code conventions

Specify your naming, formatting, and architecture rules:

# Conventions
- Naming: camelCase for variables, PascalCase for components
- Imports: use @ aliases (e.g., @/lib/utils)
- No `any` in TypeScript - use `unknown` if necessary
- Functions < 30 lines

Step 3 - Specify common commands

Document the commands Claude Code should use:

# Commands
- Tests: `pnpm test`
- Lint: `pnpm lint --fix`
- Build: `pnpm build`
- Dev: `pnpm dev --port 3001`

Step 4 - Add prohibited patterns

Indicate what Claude Code should never do. This is often the most useful section:

# Prohibitions
- NEVER use `console.log` in production - use the logger
- NEVER modify existing migration files
- NEVER commit without running tests
- NEVER use `any` - prefer `unknown` or a specific type

Step 5 - Keep the file concise

In practice, a CLAUDE.md of 80 to 150 lines covers 98% of needs. Beyond 200 lines, content is truncated. Move specific rules into modular files (see next section). The memory system optimization guide details compression techniques.

Key takeaway: an effective CLAUDE.md fits in 5 blocks - stack, conventions, commands, prohibitions - and stays under 150 lines.

How to use modular rules in .claude/rules/?

Modular rules allow you to split your configuration into thematic files. Each .md file placed in .claude/rules/ is loaded automatically, which solves the size limit problem of the main CLAUDE.md.

Recommended structure

.claude/
  rules/
    testing.md        # Testing rules
    api-design.md     # API conventions
    security.md       # Security rules
    git-workflow.md   # Git workflow
    code-style.md     # Code style

Create your first rule file:

$ mkdir -p .claude/rules
$ touch .claude/rules/testing.md

Conditional rules

Since Claude Code v2.0, you can add a frontmatter header to conditionally activate a rule:

---
globs: ["**/*.test.ts", "**/*.spec.ts"]
---
# Testing Rules
- Use `describe` / `it` (not `test`)
- Mock network calls with MSW
- Aim for 80% minimum coverage

This rule only triggers when Claude Code is working on test files. In practice, conditional rules reduce system prompt noise by 30% because only relevant directives are injected.

To learn more about the interactions between rules and security permissions, including command execution restrictions, check out the dedicated guide. You can also browse the common memory system errors to avoid classic configuration pitfalls.

Key takeaway: modular rules in .claude/rules/ split configuration by theme and support conditional activation by file pattern.

How does Auto Memory work with MEMORY.md?

Auto Memory is a mechanism through which Claude Code writes its own observations into a MEMORY.md file. This file is located in .claude/projects//memory/MEMORY.md and persists between sessions.

Differences between CLAUDE.md and MEMORY.md

In practice, Auto Memory records:

• Recurring errors and their solutions
• Architectural patterns detected in your code
• Your implicit preferences (commit style, branch names)
• Important file paths discovered during work

Triggering memory writes

You can explicitly ask Claude Code to memorize information:

$ claude
> Remember that in this project, we always use bun instead of npm

Claude Code will write this preference into MEMORY.md. In the next session, it will automatically use bun without you having to remind it.

To interact effectively with the agent via built-in commands, explore the Claude Code essential slash commands guide. You will find shortcuts for managing memory directly from the terminal.

Best practices for Auto Memory

1. Check the MEMORY.md content regularly - remove outdated observations
2. Avoid duplicates with CLAUDE.md - if a rule is stable, move it to CLAUDE.md
3. Limit the size to 200 lines to avoid truncation
4. Organize by theme by creating separate files (debugging.md, patterns.md)

The memory system tips guide offers 12 advanced techniques to get the most out of Auto Memory.

Key takeaway: MEMORY.md is the self-fed memory of Claude Code - check it regularly and move stable observations to CLAUDE.md.

What are the common pitfalls to avoid with CLAUDE.md?

70% of agent behavior issues come from three memory system configuration errors.

Pitfall 1 - File too long

A 500-line CLAUDE.md drowns critical instructions. Claude Code processes the first 200 lines with maximum attention. Beyond that, weighting decreases. Split the content into modular rules.

Pitfall 2 - Contradictory instructions

Writing "use arrow functions" in CLAUDE.md and "use function declarations" in .claude/rules/code-style.md creates a conflict. Check consistency across all memory levels:

$ cat CLAUDE.md
$ ls .claude/rules/
$ cat .claude/rules/*.md

Pitfall 3 - Missing project context

A CLAUDE.md that contains only personal preferences without describing the project forces Claude Code to infer the stack. In practice, 25% of the first session's time is wasted on clarification questions if the project is not described.

To go further in understanding agentic coding and see how memory fits into this approach, read the dedicated article. You will also find detailed solutions in the CLAUDE.md memory system FAQ.

Key takeaway: the three major pitfalls are a file that is too long, contradictions between levels, and a missing project description.

How to integrate CLAUDE.md into your team workflow?

The CLAUDE.md file at the project root is committed to Git. It becomes living documentation of team conventions. Every developer benefits from the same directives as soon as they clone the repository.

Recommended workflow

1. Create an initial CLAUDE.md with team conventions
2. Commit the file to the shared repository
3. Add .claude/projects/ to .gitignore (personal data)
4. Review the CLAUDE.md during team retrospectives

$ git add CLAUDE.md .claude/rules/
$ git commit -m "feat: add Claude Code memory configuration"
$ echo ".claude/projects/" >> .gitignore

Separating shared from personal

To learn how to set up your environment before customizing memory, follow the Claude Code installation and first launch guide. The in-depth memory system analysis covers advanced use cases for teams of more than 10 developers.

If you want to master these mechanisms in real-world conditions, the Claude Code training from SFEIR Institute (1 day) includes hands-on labs where you configure a complete CLAUDE.md, test modular rules, and leverage Auto Memory on a concrete project. For those who want to go further, the AI-Augmented Developer training (2 days) covers integrating Claude Code into a complete professional development workflow.

Experienced profiles can turn to the AI-Augmented Developer - Advanced training (1 day) to explore multi-project configuration patterns and advanced context optimization.

Key takeaway: commit CLAUDE.md and .claude/rules/ to Git, but keep personal MEMORY.md files out of the repository.

What concrete results to expect from a well-configured memory system?

A well-optimized memory system produces measurable results from the first week. teams that structure their CLAUDE.md observe these gains:

• Code convention consistency goes from 60% to 95% on average
• The number of manual corrections drops from 8-12 to 3-5 per session
• Re-contextualization time falls to 0 seconds (versus 45 seconds without memory)
• New developers become productive with Claude Code in 10 minutes instead of 2 hours

In 2026, the memory system remains the most underutilized productivity lever in Claude Code. Only 35% of users configure a structured CLAUDE.md, even though the return on investment is immediate.

Start your configuration right now by creating a minimal CLAUDE.md file:

$ echo "# My Project\n- Stack: Node.js 22, TypeScript 5.7\n- Tests: pnpm test\n- NEVER use any" > CLAUDE.md
$ claude

In 30 seconds, you have an agent calibrated to your project. Gradually enrich the file by adding rules over the course of your sessions.

Key takeaway: a minimal CLAUDE.md takes 30 seconds to create and immediately improves the relevance of every Claude Code response.