Claude Code Memory, CLAUDE.md, Persistent Instructions, and Project Context: How Anthropic’s Coding Agent Actually Stores, Loads, and Uses Long-Term Guidance

Claude Code does not treat memory as a single feature.

It uses a layered context system built from human-written instruction files, Claude-written auto memory, path-scoped rules, and on-demand retrieval from the repository during the session.

That distinction is the key to understanding how persistent behavior works in practice.

A team can give Claude Code durable guidance through CLAUDE.md, Claude can preserve learned patterns in auto memory, and the agent can still discover additional context dynamically as it reads files and traverses the codebase.

The result is not a rigid configuration model.

It is a context-engineering model in which some instructions are injected at startup, some rules activate only when relevant files are touched, and some knowledge is retrieved only when the task demands it.

·····

CLAUDE.md is the persistent instruction layer rather than a general memory dump.

Anthropic documents CLAUDE.md as the place for instructions and rules that should persist across sessions.

The intended use is practical and operational: project architecture notes, coding conventions, standard commands, workflow rules, and recurring preferences that Claude should see at the start of a session.

That makes CLAUDE.md different from ordinary chat history.

If a user tells Claude something once in conversation, the instruction may influence the current exchange, but it only becomes durable project guidance when it is written into CLAUDE.md or otherwise saved in memory.

Anthropic separates this file from auto memory for a reason.

CLAUDE.md is the curated layer written by humans, while auto memory is the adaptive layer that Claude writes itself from observed corrections, preferences, and learned patterns.

·····

Claude Code loads CLAUDE.md from multiple scopes rather than from a single file.

Anthropic supports several instruction scopes for CLAUDE.md, including managed, project, user, and local files.

Those scopes let organizations, teams, and individuals contribute different layers of guidance without collapsing everything into one document.

A project can define shared conventions in ./CLAUDE.md or ./.claude/CLAUDE.md.

A user can keep cross-project preferences in ~/.claude/CLAUDE.md.

A local personal file such as ./CLAUDE.local.md can store project-specific notes that should not be committed for everyone else.

Claude Code also traverses the directory tree upward from the working directory.

That means a session started in a nested folder can inherit multiple instruction files from the surrounding path hierarchy, all of which are concatenated into the startup context rather than treated as simple overrides.

........

Instruction File Scopes in Claude Code

Scope	Typical Location	Purpose
Managed	OS-level managed paths set by IT or DevOps	Organization-wide policy and standardized guidance
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Shared repository instructions and conventions
User	~/.claude/CLAUDE.md	Personal defaults across projects
Local	./CLAUDE.local.md	Personal notes for one project that usually stay uncommitted

·····

The most important limitation is that persistent instructions are context, not hard enforcement.

Anthropic is explicit that CLAUDE.md is injected as a user message after the system prompt.

That means Claude is expected to follow the file, but the file is not equivalent to a locked system-level policy.

This matters because many users assume that writing something in CLAUDE.md guarantees compliance.

In practice, reliability depends on instruction quality, clarity, specificity, and the absence of conflicts with other context.

A vague line such as “format code nicely” gives Claude a broad preference.

A precise line such as “use 2-space indentation and run npm test before committing” gives Claude an actionable and verifiable instruction.

Anthropic recommends --append-system-prompt when stronger control is required for automation.

That option pushes guidance into the system prompt layer for that invocation, which is better suited to scripts and tightly controlled workflows than to ordinary interactive editing sessions.

The editorial consequence is simple.

CLAUDE.md should be understood as a high-priority context file, not as a policy engine.

·····

The quality of CLAUDE.md determines how useful persistent instructions become.

Anthropic recommends keeping each file under roughly 200 lines and writing instructions in a concise, structured format.

Headers, compact sections, and concrete wording improve adherence because they reduce ambiguity and make the file easier for Claude to scan and apply.

This recommendation is not cosmetic.

Long files consume context window space, weaken signal strength, and make it harder for the agent to distinguish the truly important rules from the merely informative ones.

A strong CLAUDE.md is therefore less like a handbook and more like a compact operational brief.

It should define commands, defaults, constraints, architecture hints, and recurring project decisions that repeatedly matter during implementation work.

The most effective files usually avoid abstract principles unless they can be operationalized.

Claude follows “run pnpm test after modifying components in src/ui” more reliably than “be careful with frontend quality.”

·····

Imports turn CLAUDE.md into a modular instruction system.

Anthropic allows CLAUDE.md to import other files with @path/to/file syntax.

Those imported files are expanded into context at launch, relative paths are resolved from the importing file, and recursive imports are supported up to a documented depth limit.

This design solves a common scaling problem.

Teams do not need to pack architecture notes, workflow details, tool conventions, and environment instructions into one oversized root file.

Instead, they can keep a compact root CLAUDE.md and pull in narrowly focused references.

Anthropic even notes that Claude Code can interoperate with repositories built around AGENTS.md by creating a CLAUDE.md that imports that file, which helps multi-agent environments share one source of truth.

The practical advantage is not only cleanliness.

It is better context prioritization.

A smaller root file keeps the main signal strong while still allowing deeper project knowledge to be included deliberately when needed.

·····

Path-scoped rules make project context conditional and local to the code being touched.

Anthropic’s .claude/rules/ system extends the memory model beyond a single startup file.

Rules can be unconditional, meaning they load at launch, or conditional, meaning they activate only when Claude works with files that match specified path patterns.

This is one of the most important architectural moves in Claude Code.

It means a monorepo does not need to force every database rule, frontend standard, and infrastructure convention into the same initial context payload.

Instead, path-aware rules allow the relevant instructions to appear only when the session actually reaches that part of the tree.

Anthropic documents glob-style matching for extensions, directories, and grouped patterns, which makes the rule system useful for language-specific or subsystem-specific guidance.

The effect is a more efficient definition of project context.

Rather than treating the project as one undifferentiated prompt, Claude Code can assemble context progressively as the task narrows toward specific files and domains.

........

How Claude Code Loads Different Context Layers

Context Layer	Who Writes It	When It Loads	Best Use
CLAUDE.md	Human	At session start from the relevant path hierarchy	Shared instructions, rules, commands, architecture
CLAUDE.local.md	Human	At session start after CLAUDE.md in the same directory	Personal project-only notes
.claude/rules/unconditional rules	Human	At launch	Global project conventions
.claude/rules/conditional rules	Human	When matching files are read	Path-specific guidance
Auto memory	Claude	Startup summary plus topic files on demand	Learned preferences and recurring patterns
Repository retrieval	Claude via tools	During the task	Source files, docs, and live project evidence

·····

Auto memory stores learned patterns, but it is not the same thing as project instructions.

Anthropic stores auto memory per working tree under the Claude directory for the project.

The top-level MEMORY.md acts as an index, while more detailed topic files can hold deeper notes about debugging lessons, API behavior, or conventions learned over time.

Startup loading is intentionally limited.

Claude only injects the first 200 lines or 25 KB of MEMORY.md at session start, while deeper topic files remain available for on-demand reading later in the session.

That limit matters.

Anthropic is signaling that auto memory should stay concise at the top level and should not grow into a giant uncontrolled repository of everything Claude has ever observed.

Auto memory is also machine-local.

Worktrees in the same repository can share it on the same machine, but it is not inherently a synchronized team knowledge base across environments.

This makes auto memory useful for continuity in repeated personal workflows.

It is less appropriate as the canonical place for team-wide rules, because those belong in versioned, human-auditable instruction files such as CLAUDE.md and .claude/rules/.

·····

Project context is a hybrid of startup memory and runtime retrieval.

Anthropic’s engineering writing on context engineering describes agentic systems as hybrids.

Some context is loaded eagerly for speed, while other context is discovered dynamically through tools such as file reads, search, globbing, and targeted inspection during the session.

Claude Code follows that model closely.

CLAUDE.md provides immediate direction, rules files add conditional guidance, and runtime tools fill the gaps by retrieving actual code and documentation when the task reaches them.

This is why project context in Claude Code should not be reduced to one markdown file.

The agent’s real operating context is assembled from several layers, with repository evidence still playing a central role in actual implementation decisions.

The practical implication is that a well-written CLAUDE.md does not eliminate the need for Claude to inspect the codebase.

It gives Claude a better starting map for exploring the codebase correctly.

·····

Nested instruction files and directory traversal make context increasingly specific as Claude moves deeper.

Anthropic documents that Claude Code can discover nested CLAUDE.md files in subdirectories.

Those files are not necessarily loaded at startup, but they are brought into context when Claude reads files in those areas of the repository.

That behavior creates a form of contextual narrowing.

A broad root file can define global repository standards, while deeper subdirectory files can introduce localized rules that only matter for a package, service, or subsystem.

This matters in large codebases where different domains follow different conventions.

A data pipeline directory may need one set of instructions, while a React application or infrastructure module may need another.

Claude Code’s loading model supports that kind of specialization without forcing every session to carry every rule from the start.

The project context becomes more precise as the agent traverses into the relevant parts of the tree.

·····

Observability tools reveal what memory Claude has actually loaded.

Anthropic includes a /memory command for inspection and management.

That interface allows users to see which instruction files and rules are currently active, inspect auto memory, and control whether auto memory is enabled.

This is essential because memory problems are often visibility problems.

If a file is not loaded, Claude cannot follow it, no matter how carefully it was written.

Anthropic also documents an InstructionsLoaded hook.

The hook fires whenever a CLAUDE.md or rule file is loaded, including session start, nested traversal, path-based rule activation, includes, and compaction-related reloads.

That gives advanced users and teams a way to audit when and why contextual instructions entered the session.

In complex repositories, that observability is often the difference between guessing and actually debugging the memory system.

........

Why a Claude Code Instruction May Fail in Practice

Failure Pattern	Typical Cause	Better Fix
Claude ignores a rule	The rule is vague or conflicts with other context	Rewrite it as a specific, verifiable instruction
Claude never sees the rule	The file was not loaded from the current path or rule scope	Verify with /memory or InstructionsLoaded
Claude behaves inconsistently across machines	Auto memory is machine-local	Move shared guidance into versioned CLAUDE.md files
Startup context feels bloated	Too much content is packed into root instructions	Split instructions with imports and scoped rules
Local preferences leak into team workflow	Personal notes are stored in shared files	Move them into CLAUDE.local.md or user scope

·····

Compaction and additional directories reveal the boundaries of persistence.

Anthropic notes that CLAUDE.md survives session compaction.

After /compact, Claude re-reads the file from disk, which means instructions that are properly written into persistent files remain available even when conversational context is compressed.

That creates a clean distinction between remembered conversation and remembered configuration.

If something disappears after compaction, it was likely never stored in the persistent instruction layer in the first place.

Anthropic also supports additional working directories through --add-dir.

By default, CLAUDE.md files from those extra directories are not automatically loaded, and a dedicated environment variable is required to include them.

This is a subtle but important design decision.

Claude Code can be given access to extra directories for retrieval without automatically importing all of their instruction files into the session context.

In other words, access and instruction loading are related but not identical.

Project context remains a controlled assembly process rather than a side effect of filesystem reach.

·····

The best operational model is a compact root file plus modular and path-aware extensions.

Anthropic’s own documentation points toward a consistent pattern.

Keep the root CLAUDE.md small, use it for the project’s highest-value defaults, and move specialized details into imported references or scoped rules.

That pattern preserves clarity at the top while still allowing depth where the repository needs it.

It also mirrors the underlying architecture of Claude Code itself, which balances startup context with progressive retrieval.

A team that treats CLAUDE.md as a giant wiki usually weakens the file.

A team that treats it as a concise operational brief usually makes Claude more predictable.

The same is true for memory more broadly.

Human-authored persistent instructions work best when they define stable rules, while Claude-authored auto memory works best when it records learned tendencies and recurring implementation patterns.

The most accurate summary is therefore not that Claude Code has memory.

It is that Claude Code has a layered project-context system in which memory, instructions, rules, and retrieval continuously interact.

·····

FOLLOW US FOR MORE.

·····

DATA STUDIOS

·····

[datastudios.org]

·····