CLAUDE.md Structure and Purpose

CLAUDE.md is the primary mechanism for persistent agent memory in Claude Code. Unlike conversation history that accumulates and eventually compacts, CLAUDE.md loads at the start of every session, providing consistent instructions regardless of how many times the agent resets.

Claude Code reads CLAUDE.md contents and injects them into the system context before processing any user requests. The agent treats these instructions as immutable system rules with higher precedence than user-provided guidance during the conversation.

File locations and hierarchy

Claude Code implements a four-level hierarchical memory system. Files higher in the hierarchy take precedence over those below.

Priority	Type	Location	Purpose
1 (Highest)	Enterprise policy	System paths	Organization-wide instructions
2	Project memory	`./CLAUDE.md`	Team-shared project instructions
3	Project rules	`./.claude/rules/*.md`	Modular topic-specific rules
4 (Lowest)	User memory	`~/.claude/CLAUDE.md`	Personal preferences

Enterprise CLAUDE.md files live in system-protected locations:

macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
Linux/WSL: /etc/claude-code/CLAUDE.md
Windows: C:\Program Files\ClaudeCode\CLAUDE.md

Project files sit in the repository root or the .claude/ directory. Local personal overrides use CLAUDE.local.md, which Claude Code automatically adds to .gitignore.

How files load

Claude Code discovers memory files by traversing upward from the current working directory toward the filesystem root. CLAUDE.md files nested in child directories load on-demand when the agent reads files in those subtrees:

project/
├── CLAUDE.md                    # Loads at startup
├── packages/
│   ├── api/
│   │   └── CLAUDE.md            # Loads when working in api/
│   └── web/
│       └── CLAUDE.md            # Loads when working in web/

This hierarchical loading prevents overwhelming sessions with irrelevant context.

The instruction limit problem

Agents cannot follow unlimited instructions. Research shows that frontier models exhibit performance degradation as instruction density increases, with most showing a "cognitive saturation zone" around 150-200 instructions.

Different model types degrade differently:

Reasoning models maintain near-perfect performance until a critical threshold, then show rising variance
Standard models exhibit linear decay each additional instruction slightly reduces adherence to all instructions
Older models collapse exponentially, dropping from reasonable accuracy to near-random behavior

Claude Code's system prompt already contains approximately 50 instructions. This leaves roughly 100-150 instructions of reliable capacity for CLAUDE.md content.

Instruction limits apply to instruction count, not token count. A 500-token file with 200 bullet-point rules will perform worse than a 1000-token file with 50 well-crafted paragraphs.

Token budget awareness

Every token in CLAUDE.md consumes context budget on every interaction:

Component	Approximate tokens	Percentage of 200k window
System prompt	~3,200	1.6%
System tools	~11,600	5.8%
Memory files (CLAUDE.md)	~750	0.4%
Total baseline	~15,500	7.8%

When context approaches capacity and Claude Code triggers auto-compaction, CLAUDE.md content survives while conversation history gets summarized. Bloated CLAUDE.md files continue consuming capacity even after compaction reduces everything else.

Practitioners recommend keeping CLAUDE.md under 300 lines, with 60 lines or fewer as an optimal target. Boris Cherny maintains a team CLAUDE.md of approximately 2,500 tokens brief enough to stay effective while comprehensive enough to encode team conventions.

The import mechanism

CLAUDE.md files can import additional content using @path/to/file syntax:

# Project overview
See @README.md for full project description.

# API documentation
See @docs/api-reference.md for endpoint specifications.

# Code standards
@~/.claude/code-standards.md

Imports support relative paths, absolute paths, and home directory expansion with ~. The system follows imports recursively with a maximum depth of five hops.

Import syntax is not evaluated inside code blocks. A reference like @path/to/file within triple backticks remains literal text.

Enterprise configuration

Organizations deploying Claude Code across teams can enforce policies through managed settings in protected system locations:

{
  "permissions": {
    "deny": ["Read(**/.env)", "Read(**/secrets/*)"]
  },
  "allowedTools": ["Bash", "Read", "Write", "Edit"],
  "allowUserMcpServers": false
}

Where managed-settings.json enforces hard security boundaries, enterprise CLAUDE.md provides organizational guidance: coding standards, documentation requirements, review processes.

Checking what loaded

Two commands help verify memory configuration:

/memory displays all loaded memory files and allows editing them directly
/context shows current token usage breakdown, including how much CLAUDE.md content contributes

When instructions appear to be ignored, these commands reveal common issues: a file in an unexpected location not loading, imports failing silently, or memory content consuming more tokens than expected.