Module 3: CLAUDE.md and the Memory System

Overview

You've installed Claude Code. You verified it works with /doctor. You configured your preferred model and you understand the difference between Opus 5 and Sonnet 5. Claude Code is ready in your terminal. Now comes the most important step in the entire guide: giving Claude context about your project.

A coding agent is only as good as the context you give it. Without context, Claude Code is a senior developer with amnesia — extraordinary skills, but it knows nothing about your project, your conventions, your stack, or your rules. With good context, it's a senior developer who has been on your team for months and knows every corner of the codebase.

This module teaches you to set up that context professionally. CLAUDE.md is the file that separates mediocre results from production-grade results. It isn't an optional file — it's the foundation everything else is built on.

---

Where you are in the guide

Module 01: What Claude Code is ✅
Module 02: Installation and setup ✅
Module 03: CLAUDE.md and memory ← YOU ARE HERE
Module 04: Agentic workflow
Module 05: Skills and Hooks
Module 06: Subagents
Module 07: Integrations (Git, SDK, Remote Control)
Module 08: Capstone project

In Module 01 you understood what Claude Code is and why it leads the space. In Module 02 you installed and configured it. Now, in Module 03, we move from installing to configuring the agent's intelligence. Everything that comes after — agentic workflow, skills, hooks, subagents — works better when CLAUDE.md is done well.

---

The fundamental mental model

CLAUDE.md is the equivalent of configuring your IDE before you write code.

Think about what happens when you open VS Code on a new project with nothing configured: no formatter, no idea which linter to use, none of your shortcuts, no clue where the tests are. It works, sure — but it works badly. You spend the first hour setting up .eslintrc, prettier.config, tsconfig.json, extensions, settings.

CLAUDE.md is exactly that, but for your coding agent. It's the configuration that tells Claude:

• Which technologies you use
• How the project is structured
• Which conventions to follow
• Which commands to run
• What NOT to do

If you don't set it up well, every interaction with Claude Code is a lottery. Sometimes it lands, sometimes it doesn't. If you set it up well, Claude Code produces consistent code that respects your conventions from the very first prompt.

The precise analogy

Without CLAUDE.md:
→ A senior developer who just joined the company
→ Has the skills but doesn't know your team's rules
→ Every task requires you to explain everything from scratch
→ Produces code that "works" but doesn't fit the rest

With a professional CLAUDE.md:
→ A senior developer who has been on your team for 6 months
→ Knows the stack, the conventions, the architecture
→ You only have to say WHAT to do, not HOW
→ Produces code consistent with the rest of the project

The real impact

The difference isn't theoretical. Look at this example:

Without CLAUDE.md:

You: "Create an endpoint to list products with pagination"

Claude: [uses Express even though your project is FastAPI]
Claude: [uses snake_case even though your project uses camelCase]
Claude: [puts the file in routes/ even though your project uses routers/]
Claude: [uses print() for logging even though you have loguru configured]

With a professional CLAUDE.md:

You: "Create an endpoint to list products with pagination"

Claude: [uses FastAPI because CLAUDE.md says "Stack: FastAPI"]
Claude: [uses snake_case because CLAUDE.md states the convention]
Claude: [puts the file in src/routers/ following the structure]
Claude: [uses loguru because CLAUDE.md says "Logging: loguru"]

Same prompt. Radically different results. The difference is CLAUDE.md.

The most common mistake

Most users do this:

# They install Claude Code
curl -fsSL https://claude.ai/install.sh | bash

# They open their project
cd my-project
claude

# They immediately start asking for tasks
> "Add authentication to my app"

They never create CLAUDE.md. Claude doesn't know which framework they use, which conventions they follow, or what file structure the project has. The result is generic code that takes 5-10 correction messages to fit.

A professional does this:

# They install Claude Code
curl -fsSL https://claude.ai/install.sh | bash

# They create CLAUDE.md BEFORE doing anything else
# (5-10 minutes that save hours)

# They open their project
cd my-project
claude

# Claude reads CLAUDE.md automatically
# Now, the first task
> "Add authentication to my app"

# Claude knows the framework, the conventions, the structure
# Result: code that fits on the first try

The 5-10 minutes you invest creating CLAUDE.md pay for themselves many times over in every session after it.

---

Module objectives

By the end of this module, you'll be able to:

• ✅ Create a well-structured professional CLAUDE.md (<200 lines)
• ✅ Understand and apply the 4 official scopes of CLAUDE.md (Managed / Project / User / Local) and the 6 pedagogical levels of precedence
• ✅ Organize modular rules with .claude/rules/ (with path-specific frontmatter)
• ✅ Use imports with @path to reference external files in CLAUDE.md
• ✅ Use CLAUDE.local.md and ~/.claude/CLAUDE.md (User scope) for personal preferences you don't share
• ✅ Understand how auto memory works and what Claude learns from your corrections
• ✅ Configure settings in the global, project, and local scopes
• ✅ Diagnose where an unexpected Claude Code behavior is coming from
• ✅ Design the right CLAUDE.md hierarchy for your kind of project

---

Why this module is the differentiator

If you look at the Claude Code courses on the market, none of them cover the memory system in full:

• Most mention CLAUDE.md as "a configuration file" and move on to the next topic
• None explain the 4 official scopes (Managed / Project / User / Local) or the 6 pedagogical levels of precedence
• None cover .claude/rules/ with path-specific rules or imports with @path
• None cover CLAUDE.local.md or ~/.claude/CLAUDE.md (User scope) for personal preferences
• None explain the relationship between auto memory, CLAUDE.md, .claude/rules/, and settings

This module goes deep on every one of those. By the end of it, you'll understand Claude Code's memory system better than 99% of users.

The 3 pillars of the memory system

┌─────────────────────────────────────────────────┐
│              MEMORY SYSTEM                      │
│                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌────────┐ │
│  │  CLAUDE.md   │  │ Auto Memory  │  │Settings│ │
│  │  (explicit)  │  │  (implicit)  │  │(config)│ │
│  │              │  │              │  │        │ │
│  │ You write    │  │ Claude       │  │ You    │ │
│  │ the project  │  │ learns from  │  │ define │ │
│  │ rules        │  │ corrections  │  │ scopes │ │
│  └──────────────┘  └──────────────┘  └────────┘ │
│                                                 │
│  6 hierarchy levels determine                   │
│  what takes priority over what                  │
│                                                 │
└─────────────────────────────────────────────────┘

1. CLAUDE.md — What you explicitly tell it about the project (capsule 02)
2. The 6-level hierarchy — How conflicts between context sources get resolved (capsule 03)
3. Auto memory and Settings — What Claude learns on its own + your permissions configuration (capsules 04 and 05)

---

Prerequisites

Required knowledge:

• ✅ Module 02 completed (Claude Code installed and working)
• ✅ Basic familiarity with Markdown (headers, lists, code blocks)
• ✅ Basic familiarity with the terminal

For the practice:

• ✅ An existing project to practice on (any language)
• ✅ Or a new folder with at least a package.json, requirements.txt, or equivalent

Quick check:

Before continuing, verify that Claude Code works by running:

claude

If the interactive interface opens, you're ready. If it doesn't, go back to Module 02.

If you don't have a project:

Create a minimal one to practice on:

mkdir my-practice-project
cd my-practice-project
npm init -y
# or: pip install fastapi && echo "fastapi" > requirements.txt

What matters is having a folder with some structure where Claude can operate.

---

Module roadmap

This module has 5 progressive capsules:

Capsule 01 — Module introduction (this capsule)

Context, mental model, and roadmap. You understand why CLAUDE.md matters and what you're going to learn.

Capsule 02 — Professional CLAUDE.md

The most important file in your project when you use Claude Code. What to include, what to leave out, the ideal structure (<200 lines), 3 comparative examples (beginner, professional, bloated), and the dramatic difference between working with and without CLAUDE.md.

Capsule 03 — The 6-level memory hierarchy

The 6 levels of context Claude Code uses to make decisions: from the model's training data to the current conversation. How they stack, who controls each level, and how to resolve contradictions.

Capsule 04 — Auto memory and settings

How Claude automatically learns from your corrections (auto memory), where it's stored, and how to manage it. The 3 settings scopes (global, project, local) and what to configure in each.

Capsule 05 — CLAUDE.local.md and User CLAUDE.md

The two mechanisms for personal preferences: CLAUDE.local.md (project-local, in .gitignore) and ~/.claude/CLAUDE.md (User scope, applies to all your projects). When to use each, how they interact with the hierarchy, and patterns for worktrees.

Progression map

Capsule 01 (this one)  → Mental model and context
Capsule 02             → CLAUDE.md: the file that changes everything
Capsule 03             → 6 levels: how Claude prioritizes context
Capsule 04             → Auto memory + settings: the implicit layer
Capsule 05             → CLAUDE.local.md: your personal touch

Difficulty: ⭐ ──────────────────────────▶ ⭐⭐⭐

Capsules 02 and 03 are foundational — without CLAUDE.md and without understanding the hierarchy, everything else is built on a weak base. Capsules 04 and 05 are complementary — they optimize your setup for professional use.

---

What you'll build in this module

Across the 5 capsules, you'll produce:

1. A professional CLAUDE.md for your real project (or for the practice project)
2. A subdirectory CLAUDE.md for a specific directory (e.g., /tests/)
3. CLAUDE.local.md with your personal development preferences
4. Settings configuration in the 3 scopes (global, project, local)
5. Auto memories generated through corrections during the exercises

By the end of the module, your project will have a complete, professional memory system that transforms the quality of Claude Code's responses.

---

Connection to the capstone project

In Module 08, you'll build a complete CLI tool using Claude Code. The CLAUDE.md you learn to create in this module is exactly the one you'll use for that project:

1. You define the stack — Python/TypeScript, dependencies, CLI framework
2. You establish conventions — naming, file structure, patterns
3. You configure commands — how to build, test, run
4. You add rules — what not to touch, which patterns to avoid
5. You personalize with CLAUDE.local.md — your preferences during development

A good CLAUDE.md for the capstone project can cut development time significantly, because Claude Code understands the project from the first prompt.

---

A look at before and after

So you can picture the impact of this module, here's what your project looks like before and after you finish the 5 capsules:

Before the module (your project today)

my-project/
├── package.json
├── src/
│   ├── index.ts
│   └── ...
└── tests/
    └── ...

Claude Code: has no context
→ Guesses the stack
→ Guesses the conventions
→ Guesses the structure
→ Doesn't know which commands to use
→ Doesn't know what NOT to do

After the module (your project configured)

my-project/
├── CLAUDE.md                  ← Project rules (shared)
├── CLAUDE.local.md            ← Your preferences (personal)
├── .claude/
│   ├── settings.json          ← Team permissions (shared)
│   └── settings.local.json   ← Your extra permissions (personal)
├── .gitignore                 ← Includes CLAUDE.local.md
├── package.json
├── src/
│   ├── index.ts
│   └── ...
└── tests/
    ├── CLAUDE.md              ← Testing conventions
    └── ...

Claude Code: has full context
→ Knows the stack (CLAUDE.md)
→ Follows the conventions (CLAUDE.md)
→ Respects the structure (CLAUDE.md)
→ Runs commands without asking (settings)
→ Knows what NOT to do (rules in CLAUDE.md)
→ Answers you in your language (CLAUDE.local.md)
→ Learns from your corrections (auto memory)

The difference is tangible from the very first session after you configure it.

---

Key concepts you'll see

CLAUDE.md

The Markdown file at the root of your project that gives Claude Code persistent context. It loads at the start of every session and survives /compact and /clear. It's your #1 tool for controlling output quality.

The 4 CLAUDE.md scopes

The official documentation organizes CLAUDE.md into 4 scopes: Managed policy (organization), Project (./CLAUDE.md or ./.claude/CLAUDE.md), User (~/.claude/CLAUDE.md), and Local (./CLAUDE.local.md). More specific scopes win in conflicts.

The conceptual hierarchy (6 pedagogical levels)

Beyond the 4 scopes, there are conceptually 6 sources that shape every Claude response — from the training data to the current conversation. We keep this pedagogical framing because it helps you understand how Claude prioritizes information.

.claude/rules/ — modular rules

A directory for organizing rules by topic with a YAML paths frontmatter. Rules with paths only load when Claude works with files that match the pattern — you save context.

Imports with @path

CLAUDE.md can import other files with @path/to/file. Useful for referencing a README, package.json, or long docs without duplicating content.

Auto memory

Claude Code learns from your corrections automatically. If you tell it "don't use var, use const", it remembers that for future sessions. It's stored in ~/.claude/projects/<project>/memory/ with a MEMORY.md as the index. Requires Claude Code v2.1.59+.

Settings (3 scopes)

Explicit configuration at 3 levels: global (all your machines), project (shared with the team), and local (just for you). Controls permissions, allowed tools, and behavior.

CLAUDE.local.md and User CLAUDE.md

Two mechanisms for personal preferences: CLAUDE.local.md (project-local, never committed) and ~/.claude/CLAUDE.md (user-wide, applies to all your projects).

---

Versions and compatibility

This module covers:

• Claude Code 2.0+
• Opus 5 (1M token context window)
• Sonnet 5 (1M token context window)

Features covered:

• ✅ CLAUDE.md (project root and subdirectories)
• ✅ CLAUDE.local.md (personal preferences)
• ✅ Auto memory (learning from corrections)
• ✅ Settings (global, project, local scopes)
• ✅ The 6-level memory hierarchy

A note on change:

Claude Code updates frequently (~35 releases in 7 weeks, January-February 2026). The concepts in this module are stable — CLAUDE.md, the memory hierarchy, and the settings system are fundamental to Claude Code's architecture. Implementation details may evolve; the principles won't.

---

The 6 levels at a glance

Before we go deep (capsule 03), here's a preview of the full hierarchy so you have the mental map:

HIGH PRIORITY (wins conflicts)
         ▲
         │
  6. Your current conversation
  5. CLAUDE.md in subdirectories (e.g., /tests/)
  4. CLAUDE.md at the project root
  3. The organization's CLAUDE.md (enterprise)
  2. Anthropic's system prompt
  1. The model's training data
         │
         ▼
LOW PRIORITY (gets overridden)

Level	Who controls it	Example
6. Conversation	You, in every message	"For this file, use camelCase"
5. Subdir CLAUDE.md	You, in each directory	"In tests/, any is acceptable"
4. Project CLAUDE.md	You, at the root	"Stack: FastAPI, snake_case"
3. Enterprise CLAUDE.md	The org admin	"Don't use eval(), JSON logging"
2. System prompt	Anthropic	"Ask for confirmation before rm"
1. Training data	Anthropic (training)	"Python uses snake_case"

The essentials: Higher levels win when there's a conflict. Your conversation always has the last word. CLAUDE.md gives you the most important lever: the project's persistent rules.

Capsule 03 covers each level in depth with practical examples.

---

Summary

This module is the foundation of all your work with Claude Code. The difference between a casual user and a professional comes down to this: the professional configures the context before working.

What you learned in this capsule:

• The agent is only as good as the context you give it
• CLAUDE.md is the equivalent of configuring your IDE — if you don't get it right, everything suffers
• The memory system has 3 pillars: CLAUDE.md, auto memory, and settings
• There are 6 hierarchy levels that determine how Claude prioritizes context
• CLAUDE.local.md lets you keep personal preferences without affecting the team
• This module is the differentiator: no other resource covers this in depth

Next capsule: 02 - Professional CLAUDE.md — how to create the most important file in your project when you use Claude Code.

---

Additional resources

Official documentation

• Claude Code Memory — Memory system, CLAUDE.md, auto memory, the full hierarchy
• Claude Code Settings — Scope configuration: global, project, local
• Claude Code Best Practices — Recommended workflows and context management

Complementary

• Claude Code Overview — General architecture and capabilities
• Claude Code CLI Reference — Command and flag reference
• Claude Code Interactive Mode — Shortcuts and session management