CLAUDE.md File Explained: Complete Guide to Claude Code Memory

Updated January 2026 | 9 min read

CLAUDE.md is a markdown file that Claude Code reads automatically at the start of every session. It functions as persistent memory—a way to give the AI context about you, your projects, and your preferences without manually explaining everything each time.

This file is the difference between an AI that forgets you exist and one that understands your business from the first prompt.

How CLAUDE.md Works

When you launch Claude Code in a directory containing a CLAUDE.md file, the system automatically loads its contents into context before you type anything. The AI reads the file as foundational information—treating it as established facts about your environment.

The loading happens hierarchically:

1. Global CLAUDE.md: Located in ~/.claude/CLAUDE.md, applies to all projects
2. Project CLAUDE.md: Located in your project root, applies to that specific project
3. Directory CLAUDE.md: Can exist in subdirectories for domain-specific context

These files stack. A project-level file supplements (doesn't replace) your global file. This lets you maintain universal preferences while adding project-specific details.

What to Include in CLAUDE.md

The file structure should match how you want Claude to understand your context. Start broad (who you are), then narrow (specific rules and current state).

Identity Section

Basic facts that shape every interaction:

# Who

Jane Chen
- Product Manager at TechCorp (B2B SaaS)
- Side project: Consulting for early-stage startups
- Based in Austin, TX
- 8 years in product, previously engineering

Current State

What's happening now. Update this section as priorities shift:

# Now

**Active Projects:**
- Q1 roadmap finalization (due Feb 15)
- Customer research synthesis (interviewing 12 users)
- Pricing model revision

**Recent Decisions:**
- Chose Notion over Coda for team wiki
- Delayed mobile app to Q3
- Hired contractor for user research

Tools and Systems

Technical environment the AI should know about:

# Tools

| Tool | Purpose | Notes |
|------|---------|-------|
| Linear | Issue tracking | Workspace: techcorp |
| Notion | Documentation | Team wiki + specs |
| Figma | Design | View-only access |
| Slack | Communication | Async-first culture |
| GitHub | Code | Monorepo structure |

Behavioral Rules

Explicit instructions that prevent repeated issues:

# Rules

1. **Read before edit** — Never modify a file without reading it first
2. **Date format** — Use YYYY.MM.DD (dots, not dashes)
3. **No assumptions** — Ask if unclear, don't guess
4. **Dense output** — No filler phrases, disclaimers, or excessive hedging
5. **Specific numbers** — Always include data when available
6. **Action items** — End planning discussions with clear next steps

Domain Knowledge

Information specific to your work that Claude couldn't know otherwise:

# Domain Context

**Our Product:**
- Enterprise analytics platform
- Main competitors: Amplitude, Mixpanel, Heap
- Key differentiator: Real-time cohort analysis
- Pricing: Usage-based, $0.001 per event

**Our Customers:**
- Mid-market B2B SaaS (50-500 employees)
- Primary users: Product managers, growth teams
- Buying process: 3-6 month sales cycle
- Main objection: Migration complexity from existing tools

Communication Preferences

How you want responses structured:

# Voice

- Direct, no hedging
- Concrete over abstract
- Examples over explanations
- Challenge assumptions when appropriate
- Acknowledge uncertainty rather than guessing

Advanced CLAUDE.md Techniques

Conditional Sections

Use markdown structure to create sections that apply in specific situations:

## When Writing Customer Communications

- Friendly but professional tone
- Always include specific timeline
- End with clear call to action
- Avoid jargon our customers don't use

## When Analyzing Data

- Start with the question we're answering
- Show sample size and confidence
- Include visualization recommendations
- Note any data quality issues

Reference Links

Point to other files in your project that contain detailed context:

# Key Files

| File | Contents |
|------|----------|
| `/docs/architecture.md` | System design overview |
| `/docs/glossary.md` | Company-specific terminology |
| `/specs/roadmap.md` | Current product roadmap |
| `/templates/` | Standard document formats |

Claude Code can read these files when needed, keeping your CLAUDE.md focused on the essentials.

Slash Commands

Define custom commands for frequent tasks:

# Slash Commands

| Command | Action |
|---------|--------|
| `/standup` | Generate daily standup format |
| `/spec` | Create product spec template |
| `/review` | Weekly review checklist |
| `/customer` | Load customer context for research |

Common CLAUDE.md Mistakes

Mistake: Stale content. A CLAUDE.md that describes last quarter's priorities actively misleads the AI. Build a habit of updating it when circumstances change.

Mistake: Vague preferences. "Write well" means nothing. "Short sentences. Active voice. No adverbs." gives Claude concrete constraints.

Mistake: Duplicate information. If something belongs in your global CLAUDE.md, don't repeat it in project files. Use the hierarchy.

CLAUDE.md vs Other Memory Solutions

Getting Started

Create a CLAUDE.md file in your project directory with three sections: who you are, what you're working on, and your key rules. Keep it under 500 words initially. Use it for a week, then expand based on what context you find yourself repeating.

The file evolves with you. What starts as basic preferences grows into a comprehensive knowledge base that makes every AI interaction more effective.

For the full system—including Obsidian integration, multi-file context management, and advanced configurations—see our Claude Code setup guide.