How Claude Code organises persistent context across sessions: a three-layer architecture with progressive disclosure.
Architecture
Loading Timeline
Decision Guide
3
Layers
4
Memory Types
200
Index Line Limit
On-demand
File Loading
Layer 1
Always loaded
CLAUDE.md (Project Instructions)
Loaded into every conversation's system prompt. Contains project conventions, coding standards, search strategies, tool configuration, and operational rules. Think of this as your project's constitution.
CLAUDE.mdproject-scoped
~/.claude/CLAUDE.mdglobal
|
Layer 2
Conditionally loaded
.claude/rules/ (Topic-Specific Context)
Loaded when the conversation topic matches a folder name. Provides deep context for specific domains, projects, or workflows without bloating every session. Each folder has an index.md with pointers and key facts.
{topic}/index.mdper topic
|
Layer 3
Index always loadedFiles on-demand
Auto Memory (Typed Files)
MEMORY.md index loads in every session (truncated at 200 lines). Supporting files are read on-demand via semantic links. Each file has typed frontmatter (user, feedback, project, reference) that helps the agent decide relevance.
MEMORY.mdindexalways loaded
user_profile.mduseron-demand
user_relationships.mduseron-demand
user_routines.mduseron-demand
project_*.mdprojecton-demand
reference_*.mdreferenceon-demand
feedback_*.mdfeedbackon-demand
Always loaded (session start)
Conditionally loaded (topic match)
On-demand (agent reads when needed)
Startup
Load CLAUDE.md
Project instructions injected into the system prompt. Contains conventions, tool configuration, and operational rules. Always present
Startup
Load ~/.claude/CLAUDE.md
Global user instructions that apply across all repositories. Communication preferences, coding workflow, environment configuration.
Startup
Load MEMORY.md (index)
Auto memory index with routing tables and semantic links to supporting files. Truncated at 200 lines; content beyond that is silently invisible to the agent.
Conditional
Load .claude/rules/ (topic match)
When the conversation topic matches a folder name in .claude/rules/, that folder's index.md is loaded. Enables deep context without permanent overhead.
On-demand
Agent reads typed memory files
Triggered by semantic links in MEMORY.md. The link's surrounding prose tells the agent when to follow it. For example: "When acting on the user's behalf, consult user_profile.md for preferences."
On-demand
Progressive disclosure
Each memory file has typed frontmatter (user, feedback, project, reference) so the agent can assess relevance from the description alone, without reading the full content.