The CLAUDE.md Memory System - Tutorial

This tutorial guides you step by step through configuring and leveraging Claude Code's memory system using CLAUDE.md files, modular rules, and Auto Memory. You will learn to structure your AI assistant's persistent memory so that it retains your conventions, preferences, and project architecture from one session to the next.

The CLAUDE.md memory system is Claude Code's native mechanism for storing persistent instructions that are automatically injected into the system prompt at each new conversation. This system relies on a hierarchy of Markdown files read by Claude Code at startup, offering precise control over the agent's behavior without complex configuration.

projects using a well-structured CLAUDE.md file reduce the number of manual reminders needed during a session by 40%. This tutorial covers the creation, structuring, and optimization of each memory layer available in Claude Code v1.0+.

---

What are the prerequisites before starting?

Before configuring your memory system, verify that your environment meets these conditions:

• Node.js 22 or higher installed
• Claude Code v1.0+ installed and functional (claude --version)
• A Git-initialized project in your working directory
• A terminal with write access to the ~/.claude/ folder

claude --version
node --version
git status

If you are new to Claude Code, the installation and first conversations tutorial guides you through the complete initial setup.

Estimated total duration: 25-35 minutes for the entire tutorial.

Key takeaway: verify your versions before starting - an up-to-date environment avoids 90% of memory configuration problems.

---

How does the memory hierarchy work in Claude Code?

Claude Code's memory system relies on three distinct levels, each with a specific scope and priority. Understand this hierarchy before creating your files.

The first level is the ~/.claude/CLAUDE.md file, called "user memory". It applies to all your projects and contains your global preferences: code style, language, naming conventions.

The second level is the CLAUDE.md file at your project root. It contains the instructions specific to the repository: tech stack, architectural patterns, build commands. This file is versioned with Git.

The third level consists of the project's .claude/rules/*.md files. Each file targets a specific case through file globs. This modular approach avoids an unreadable monolithic file.

To learn more about the internal workings of this hierarchy, check the CLAUDE.md memory system deep dive which details each layer.

In practice, Claude Code concatenates these files in the order user -> project -> rules before injecting them into the system prompt, with approximately 200 lines maximum read at startup.

Key takeaway: memory follows a three-level hierarchy - global, project, modular - with automatic concatenation at startup.

---

How to create your user CLAUDE.md file? (Step 1 - ~2 min)

Create the global memory file with a clear structure. This file will apply to every project you open with Claude Code.

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

Open the file and add your global preferences:

# Global Preferences

- Response language: English
- Code style: functional, strict typing
- Always use named imports (no default export)
- Commits in English, conventional format (feat:, fix:, chore:)
- Never auto-commit without confirmation

This file should not exceed 100 lines. Focus on universal rules that apply regardless of the project.

Verification: run cat ~/.claude/CLAUDE.md and confirm the content displays correctly.

If you see No such file or directory, verify that the ~/.claude/ folder exists with ls -la ~/.claude/.

Key takeaway: the ~/.claude/CLAUDE.md file contains your universal preferences - keep it concise, under 100 lines.

---

How to configure your project's CLAUDE.md? (Step 2 - ~5 min)

Create a CLAUDE.md file at the root of your Git repository. This is the most strategic file: it defines the context Claude Code will use to understand your codebase.

touch CLAUDE.md

Here is how to structure an effective project file. Organize it into distinct sections:

# Project: My Application

## Tech Stack
- Next.js 15 / React 19 / TypeScript 5.7
- Database: PostgreSQL 16 via Prisma 6
- Tests: Vitest + Testing Library

## Architecture
- /app: Next.js routes (App Router)
- /lib: pure business logic
- /components: reusable React components

## Essential Commands
- Build: `npm run build`
- Tests: `npm run test`
- Lint: `npm run lint`

## Conventions
- Components in PascalCase, hooks in camelCase with "use" prefix
- One component per file
- Co-located tests: Button.test.tsx next to Button.tsx

This file is versioned with Git, allowing the entire team to share the same context. a well-structured project CLAUDE.md reduces code generation errors related to missing conventions by 35%.

To manage access permissions for sensitive files in your project, check the permissions and security tutorial.

Verification: launch claude in your project and ask "What is the project's tech stack?". Claude Code should respond by citing the technologies listed in your CLAUDE.md.

If Claude Code does not read your file, verify it is located at the Git repository root (at the same level as .git/).

Key takeaway: the project CLAUDE.md is the most impactful file - version it with Git so the whole team benefits.

---

How to add modular rules with .claude/rules/? (Step 3 - ~5 min)

Create the modular rules folder to separate your instructions by context. Each .md file in this folder can target specific file types using globs.

mkdir -p .claude/rules

Add a first rule targeting TypeScript files:

---
globs: "**/*.ts,**/*.tsx"
---

# TypeScript Rules

- Explicit typing for public function parameters
- Use `satisfies` rather than `as` for type assertions
- Interfaces for objects, types for unions and intersections
- No `any` - use `unknown` if the type is unknown

Create then a rule for tests:

---
globs: "**/*.test.ts,**/*.test.tsx"
---

# Testing Rules

- Use describe/it (not test())
- One test file per component/module
- Test names in English: "should display the button"
- Mock API calls with msw, never manual mocks

Specifically, when you open a .tsx file, Claude Code automatically loads the TypeScript rule. When you work on a .test.tsx file, both rules apply simultaneously.

This modular approach is complementary to the context management that you can configure to optimize the available context window.

In practice, teams of more than 5 developers use an average of 4 to 8 modular rule files to cover their use cases.

Verification: run ls .claude/rules/ and confirm your .md files appear. Then open Claude Code on a TypeScript file and ask "What rules apply here?".

Key takeaway: modular rules in .claude/rules/ target files by glob - specifically, they allow surgical instructions without overloading the main CLAUDE.md.

---

How to activate and leverage Auto Memory? (Step 4 - ~3 min)

Auto Memory is an automatic mechanism through which Claude Code records persistent notes in a folder dedicated to each project. This folder is located in ~/.claude/projects//memory/.

Verify that the automatic memory folder exists for your project:

ls ~/.claude/projects/

The main file is MEMORY.md, limited to 200 lines. Claude Code reads it at the start of each session and records patterns it detects over the course of your interactions.

Here is how to trigger explicit memorization. Simply tell Claude Code:

"Remember that in this project, we always use pnpm and never npm"

Claude Code will write this instruction into its MEMORY.md file automatically. You can also ask it to forget information:

"Forget the rule about pnpm, we switched back to npm"

Auto Memory stores an average of 15 to 30 entries per active project, covering code conventions, important file paths, and recurring architectural decisions.

To go further in optimizing this automatic memory, the memory system optimization guide details advanced structuring strategies.

Verification: after asking Claude Code to remember something, run cat ~/.claude/projects/*/memory/MEMORY.md and confirm the entry appears.

Key takeaway: Auto Memory works without configuration - Claude Code automatically stores confirmed patterns over the course of sessions.

---

What are the best practices for structuring your memory? (Step 5 - ~5 min)

Apply these principles to maximize the effectiveness of your memory system. A poorly structured CLAUDE.md can degrade Claude Code's performance rather than improve it.

Rule 1: Be concise. Claude Code reads the entire memory at each startup. A 500-line file consumes context unnecessarily. Limit each CLAUDE.md to a maximum of 150 lines.

Rule 2: Use lists, not paragraphs. Instructions in bullet point form are 60% better followed than narrative paragraphs, because Claude Code interprets them as explicit directives.

Rule 3: Separate the "what" from the "why". Write the instruction first, then the justification in parentheses if needed:

- Use named imports (tree-shaking compatibility)
- E2E tests with Playwright (adopted January 2026, replaces Cypress)

Rule 4: Update regularly. An outdated CLAUDE.md creates conflicts. Schedule a monthly review using the /memory command or by directly editing the file.

To master the slash commands that facilitate memory management, check the essential slash commands tutorial.

SFEIR Institute offers a one-day Claude Code training that includes hands-on labs on optimal memory system configuration. You will learn to structure your CLAUDE.md files for enterprise projects with multiple teams.

If Claude Code ignores a rule from your CLAUDE.md, verify that the file does not contain broken Markdown syntax (poorly formatted tables, lists without line breaks).

Key takeaway: an effective CLAUDE.md is short, structured as lists, and updated regularly - conciseness trumps exhaustiveness.

---

How to organize automatic memory with thematic files? (Step 6 - ~5 min)

Beyond the main MEMORY.md file, Claude Code can create thematic files in the memory/ folder. Organize your memory by topics to avoid a monolithic file.

Ask Claude Code to create separate files:

"Create a memory/debugging.md file with solutions to recurring project bugs"

Here is how a thematic structure can be organized:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Main index (200 lines max)
├── debugging.md       # Solutions to recurring problems
├── patterns.md        # Project architectural patterns
└── api-conventions.md # API-specific conventions

The MEMORY.md file serves as an index. Keep in it only references to thematic files and the most critical rules. Secondary files are loaded on demand.

In practice, projects over 50,000 lines of code benefit from 3 to 5 thematic files to cover the different domains of the codebase.

This organization integrates with the Git integration system to version important architectural decisions discovered by Claude Code.

Verification: run ls ~/.claude/projects/*/memory/ and confirm your thematic files appear alongside MEMORY.md.

Key takeaway: create thematic files in the memory/ folder to keep the main MEMORY.md under 200 lines.

---

How to debug memory problems in Claude Code? (Step 7 - ~3 min)

When Claude Code does not follow your instructions despite a configured CLAUDE.md, follow this 4-point diagnostic procedure.

Point 1: verify loading. Ask Claude Code: "What are your current instructions?". It should cite the content of your CLAUDE.md.

Point 2: check for conflicts. If you have both a user CLAUDE.md AND a project CLAUDE.md with contradictory instructions, the project file takes priority. Remove duplicates.

# Display both files side by side
diff ~/.claude/CLAUDE.md ./CLAUDE.md

Point 3: check the size. A CLAUDE.md over 200 lines may be truncated. Count the lines:

wc -l CLAUDE.md
wc -l ~/.claude/CLAUDE.md

Point 4: check the globs. For modular rules, a malformed glob prevents loading. Test your glob:

# List files matching the glob
ls **/*.test.tsx

The complete CLAUDE.md memory system guide covers advanced troubleshooting cases including multi-user conflicts.

To automate these checks in a CI/CD pipeline, check the headless mode tutorial which explains how to validate the consistency of your memory files.

If you see inconsistent behaviors between sessions, verify that you do not have multiple ~/.claude/projects/ folders for the same project (different absolute path).

Key takeaway: a memory diagnostic follows 4 steps - loading, conflicts, size, globs - and resolves 95% of encountered problems.

---

How to integrate the memory system into a team workflow? (Step 8 - ~5 min)

Version your project CLAUDE.md and modular rules in Git to share context with the entire team. Specifically, every developer automatically benefits from the same Claude Code instructions as soon as they clone the repository.

Add these files to your .gitignore to protect personal preferences:

# .gitignore - personal memory files
.claude/memory/

Keep shared files in the repository:

git add CLAUDE.md
git add .claude/rules/
git commit -m "chore: add Claude Code memory configuration"

In practice, teams that version their CLAUDE.md see a 45% reduction in style inconsistencies between contributions from different developers.

Establish a review process for CLAUDE.md modifications, just as you would for any critical configuration file. Use dedicated pull requests.

For teams using Claude Code in CI, the MCP (Model Context Protocol) tutorial explains how to extend Claude Code's capabilities with external context servers.

If you want to go deeper into AI-assisted development beyond Claude Code, the AI-Augmented Developer training from SFEIR Institute covers over 2 days the complete methodologies for integrating AI agents into the development cycle. For profiles already familiar with these practices, the advanced training over one day deepens multi-agent orchestration patterns and advanced prompt engineering strategies.

Verification: run git log --oneline -- CLAUDE.md .claude/rules/ and confirm your memory files appear in the commit history.

Key takeaway: version the project CLAUDE.md and modular rules in Git - keep Auto Memory local via .gitignore.

---

How to go further with the memory system?

You now master the fundamentals of Claude Code's memory system. Here is how to deepen each aspect.

Explore the slash commands related to memory. The /memory command opens the MEMORY.md file directly for quick editing. The slash commands tutorial details all available commands.

Combine memory and context. The memory system works in synergy with Claude Code's context management. Optimize both systems together to maximize response relevance.

In 2026, the memory system continues to evolve with features like team collaborative memory and CLAUDE.md templates by project type. Watch Anthropic's release notes to stay up to date.

Key takeaway: the CLAUDE.md memory system is the foundation of professional Claude Code usage - investing 30 minutes in its configuration saves you hours every week.