The CLAUDE.md Memory System - FAQ

The CLAUDE.md file is Claude Code's persistent memory system that stores your preferences, conventions, and project instructions between sessions. This FAQ guide answers the most frequently asked questions about CLAUDE.md configuration, the memory hierarchy, and modular rules to optimize your productivity with the AI agent.

The CLAUDE.md memory system is the central mechanism through which Claude Code preserves your project context from one session to the next. This system relies on a hierarchy of files (CLAUDE.md, .claude/rules/, and MEMORY.md) that allow you to customize the agent's behavior without repeating your instructions. Most teams adopt a CLAUDE.md early because it removes the need to repeat the same instructions every session.

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

CLAUDE.md is a Markdown file automatically loaded into Claude Code's context at each new conversation. It is delivered as a user message after the system prompt, not as part of the system prompt itself. It works as a persistent memory that transmits your instructions, conventions, and preferences to the agent.

Specifically, Claude Code searches for this file at multiple locations on startup. The content is loaded before your first message, allowing the agent to follow your rules from the very first interaction.

In practice, a concise CLAUDE.md consumes only a small amount of context, far less than 1% of the available window with a current model such as Claude Opus 4.8 and its 1M-token context window.

Verify that your CLAUDE.md exists by running this command:

$ cat CLAUDE.md

To understand how Claude Code manages its context window with these files, check the context management FAQ which details the compression mechanisms.

Key takeaway: CLAUDE.md is automatically loaded at each session. It is your persistent communication channel with the agent.

What is the hierarchy of Claude Code's memory files?

Claude Code loads several memory levels, from the broadest authority to the most specific. The discovered files are concatenated rather than overridden, and files closer to your working directory are read last.

The file at the repository root (./CLAUDE.md) is the most commonly used. It is versioned with Git and shared with the entire team. The user file ~/.claude/CLAUDE.md applies to all your projects: ideal for universal preferences like your language or commit style. Managed policy files (on OS-specific paths such as macOS /Library/Application Support/ClaudeCode/CLAUDE.md, Linux/WSL /etc/claude-code/CLAUDE.md, or Windows C:\Program Files\ClaudeCode\CLAUDE.md) are loaded first and cannot be excluded.

Create your global CLAUDE.md with:

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

In recent versions of Claude Code, memory files support importing modular rules via the .claude/rules/ folder. To learn more about permissions management related to these files, check the permissions and security FAQ.

Key takeaway: the memory files are concatenated from broadest to most specific, with files closer to your working directory read last.

How to write an effective CLAUDE.md for your project?

Structure your CLAUDE.md with clear sections and short, actionable directives.

An effective CLAUDE.md contains between 30 and 100 lines. Keep your CLAUDE.md concise: an overly long file wastes context unnecessarily. Concise, bullet-point instructions tend to be followed more reliably than long prose paragraphs.

Here is how to structure a performant CLAUDE.md:

# Project Conventions

- Language: TypeScript strict, no `any`
- Tests: Vitest, minimum 80% coverage
- Commits: Conventional Commits format
- Style: Prettier + ESLint, no `console.log`

# Architecture

- Framework: Next.js 15 App Router
- Database: PostgreSQL via Prisma
- Deployment: Vercel

# Behavior Rules

- Always read a file before modifying it
- Never commit without asking
- Use absolute imports (@/lib, @/components)

Avoid vague instructions like "write good code". Prefer measurable directives: "each function must have fewer than 30 lines". You will find more concrete examples in the CLAUDE.md tips.

Key takeaway: a targeted 50-line CLAUDE.md is worth more than a vague 300-line document.

What are the use cases for modular rules in .claude/rules/?

Modular rules are Markdown files placed in .claude/rules/ and automatically loaded alongside CLAUDE.md.

Each .md file in this folder is loaded into context at launch, with the same priority as .claude/CLAUDE.md. This mechanism allows separation of concerns: one file for style, one for tests, one for deployment.

As an illustrative example, a team might split its rules into several focused files (style, tests, deployment, security) for a Next.js project. Here is a typical structure:

.claude/
 rules/
 coding-style.md # 15 lines
 testing.md # 20 lines
 git-workflow.md # 10 lines
 security.md # 12 lines

Create a rule file with:

$ mkdir -p .claude/rules
$ echo "- Always write tests before code" > .claude/rules/testing.md

To understand how these files interact with agentic coding, think of rules as guardrails that the agent follows even in autonomous mode.

Key takeaway: modular rules facilitate code review and governance of instructions given to the agent.

How to configure Auto Memory and MEMORY.md?

Auto Memory is a system where Claude Code writes its own notes in a MEMORY.md file stored at ~/.claude/projects//memory/MEMORY.md. The segment is derived from your Git repository, and that memory/ directory may also contain additional topic files alongside the MEMORY.md entrypoint.

Unlike CLAUDE.md which you write manually, MEMORY.md is fed by the agent over the course of your sessions. It records recurring patterns, corrected errors, and your observed preferences. MEMORY.md is loaded into context. Beyond approximately 200 lines, content may be truncated.

Auto Memory is enabled by default (it requires Claude Code v2.1.59 or later). You can toggle it with the /memory command, set "autoMemoryEnabled": false in your settings, or set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 to disable it.

Over several sessions on the same project, MEMORY.md gradually accumulates contextual notes. You can manually edit this file to correct or remove obsolete information.

To go further on memory management, the complete CLAUDE.md memory system guide details each mechanism in depth.

Key takeaway: MEMORY.md is the agent's learned memory. CLAUDE.md is the memory you impose on it.

Can you share CLAUDE.md with your team via Git?

Yes, the CLAUDE.md file at the project root is designed to be versioned and shared via Git.

Commit your CLAUDE.md like any configuration file. The entire team will benefit from the same instructions. However, MEMORY.md and .claude/settings.local.json should remain in .gitignore as they contain personal data.

Here is how to configure your .gitignore:

# Claude Code - personal files
.claude/settings.local.json
.claude/memory/

# Claude Code - shared files (DO NOT ignore)
# CLAUDE.md
# .claude/rules/

Teams that share their CLAUDE.md tend to need fewer style corrections during code reviews because everyone's agent follows the same conventions. To discover how to automate rule enforcement in CI/CD, check the headless mode FAQ.

Key takeaway: version CLAUDE.md and .claude/rules/, keep MEMORY.md local.

How many tokens does the memory system consume?

A typical CLAUDE.md adds a small amount of context, at most a few thousand tokens, which is well under 1% of a large context window. The official docs do not publish a token-per-line figure; they recommend keeping each CLAUDE.md file under 200 lines so it stays focused.

Each modular rule file in .claude/rules/ and your MEMORY.md add further context on top of that. Keep the whole memory budget lean so the bulk of the window stays free for code and exchanges.

In practice the entire memory system represents a small fraction of a large context window, a reasonable investment for the consistency gained. To understand how to optimize the remaining context, the context management FAQ offers concrete strategies.

Key takeaway: aim for a lean memory budget so the bulk of your context window stays free for code and exchanges.

What errors should you avoid in your CLAUDE.md file?

The most frequent error is writing a CLAUDE.md that is too long with contradictory instructions.

Here are the 5 most common errors, ranked by frequency:

1. Contradictory instructions: "use semicolons" in one section and "no semicolons" in another
2. Vague paragraphs: "pay attention to code quality" without measurable criteria
3. Duplication: repeating the same rules in CLAUDE.md and .claude/rules/
4. File too large: an overly long CLAUDE.md dilutes critical instructions
5. No structure: no Markdown sections, everything in a jumble

Test your CLAUDE.md by asking Claude Code to summarize it:

$ claude "Summarize my CLAUDE.md instructions in 5 points"

If the agent cannot clearly summarize your instructions, they are too vague or contradictory. The common CLAUDE.md errors guide documents each pitfall with concrete solutions.

Key takeaway: a CLAUDE.md should be readable by both a human AND an LLM: test both readings.

How to ask Claude Code to memorize a preference?

Simply say "Remember that I always use Bun instead of npm" and the agent will record this preference in MEMORY.md.

Claude Code's auto memory records the preferences and corrections it observes during your sessions. Asking it to remember a preference (for example, "Remember that I always use Bun instead of npm") is a natural way to prompt it to persist that note in MEMORY.md, while instructions framed for the current session stay temporary.

Here is how to formulate your memorization requests:

# Requests that will be memorized
"Remember that I prefer arrow functions"
"Remember to always use pnpm"
"Don't forget: never console.log in production"

# Session-only requests (not memorized)
"For this session, use tabs"
"Today, don't touch the /legacy folder"

Specifically, each memorized preference takes up 1 to 3 lines in MEMORY.md. Keep MEMORY.md concise so your preferences remain well followed. For your first interactions with the agent, the first conversations FAQ guides you step by step.

Key takeaway: use "remember" for lasting preferences, reserve CLAUDE.md for team rules.

Should you have a different CLAUDE.md per Git branch?

No, a single CLAUDE.md at the project root is sufficient in the majority of cases.

The file follows Git rules: if you modify it on a branch, the modification stays on that branch until merge. This can be useful for major refactoring branches with temporarily different conventions.

The practice recommended by SFEIR Institute is to maintain a stable CLAUDE.md on main and add specific modular rule files on feature branches when necessary.

# On a TypeScript migration branch
$ echo "- Convert all .js to .ts before modification" > .claude/rules/migration.md
$ git add .claude/rules/migration.md
$ git commit -m "chore: add migration rules for Claude Code"

This approach avoids merge conflicts on CLAUDE.md while adapting the agent's behavior to the branch context. To configure Claude Code on a new project from installation, remember to create your CLAUDE.md from day one.

Key takeaway: keep a stable CLAUDE.md on main and use modular rules for per-branch variations.

What are the links between CLAUDE.md and the Model Context Protocol (MCP)?

CLAUDE.md and MCP are two complementary systems: CLAUDE.md provides static instructions, MCP connects Claude Code to dynamic data sources.

MCP (Model Context Protocol) is an open standard that allows Claude Code to interact with external servers (databases, APIs, remote file systems). You can reference your MCP servers in CLAUDE.md so that the agent uses them automatically.

# In CLAUDE.md
## Available MCP Servers

- PostgreSQL server: customer data (read only)
- GitHub server: access to issues and PRs
- Use the PostgreSQL MCP server for any query on customer data

In practice, many with a configured CLAUDE.md also set up at least one MCP server. To understand how to configure and use MCP, check the complete Model Context Protocol FAQ.

Key takeaway: CLAUDE.md gives the instructions, MCP provides the tools. The two complement each other for a more capable agent.

How to audit and maintain your CLAUDE.md over time?

Plan a quarterly review of your CLAUDE.md, just like any technical documentation.

An unmaintained CLAUDE.md accumulates obsolete instructions: outdated dependency versions, abandoned conventions, contradictory rules added by different team members. The best practice is to date each modified section.

Here is a 4-step audit process:

1. Run an analysis by Claude Code: claude "List the potentially obsolete instructions in CLAUDE.md"
2. Verify consistency with your package.json and tsconfig.json
3. Remove rules that duplicate your ESLint or Prettier configuration
4. Validate that the total stays under 100 lines

A periodic audit takes only a few minutes and trims obsolete instructions, lowering your memory token usage. To learn more about maintenance techniques, the CLAUDE.md tips offer ready-to-use checklists.

If you want to master these techniques in real-world conditions, the Claude Code training from SFEIR Institute (1 day) lets you configure a complete environment with CLAUDE.md, modular rules, and MCP servers during supervised hands-on labs.

To go further, the AI-Augmented Developer training (2 days) covers integrating these tools into a complete professional development workflow, while the AI-Augmented Developer - Advanced module (1 day) deepens advanced automation and customization patterns.

Key takeaway: treat CLAUDE.md like code: version, review, and clean regularly.