Claude Code Memory: How CLAUDE.md, Persistent Instructions, and Project Context Work Across Sessions, Repositories, and Developer Workflows

Claude Code does not treat memory as one single feature, because its behavior is shaped by a combination of persistent instruction files, automatically learned preferences, and live context gathered from the repository during the active session.

That distinction matters because many users describe everything Claude remembers as memory, while Anthropic’s own documentation separates manual instruction layers from automatic memory and from the project context that Claude retrieves as it reads files, searches directories, and uses tools.

The result is a layered system in which some information is loaded at the start of a session, some is learned across sessions, and some is only pulled into context when Claude begins working in the relevant part of the codebase.

·····

CLAUDE.md is the main persistent instruction layer in Claude Code.

Anthropic documents CLAUDE.md as the primary way to give Claude Code persistent instructions that are read at the start of every session, which makes the file the main place to store information that would otherwise need to be repeated each time a developer opens the tool.

In practice, CLAUDE.md functions less like a casual note file and more like an operating manual for the repository, because it is meant to capture recurring rules, preferred workflows, architecture expectations, coding conventions, and other guidance that should remain stable across sessions.

Anthropic explicitly recommends adding information to CLAUDE.md when Claude keeps making the same mistake, when code review reveals a rule it should have followed, when the same correction has to be repeated in later sessions, or when a new teammate would need the same orientation in order to work effectively in the project.

That positioning makes CLAUDE.md the durable instruction surface for recurring expectations rather than a place to store every temporary thought that arises during development.

........

What CLAUDE.md Is Intended to Hold

Content Type	Why It Fits in CLAUDE.md
Coding conventions	They apply repeatedly across sessions
Build and test commands	They are core operating instructions for the repo
Architecture rules	They guide Claude’s decisions during edits and reviews
Repeated corrections	They prevent the same mistake from recurring
Team workflow expectations	They help Claude align with how the project is maintained

·····

Persistent instructions in Claude Code are hierarchical rather than flat.

Anthropic’s documentation describes several scopes for persistent instructions, which means Claude Code does not rely on one universal memory file but instead works with a layered hierarchy that can include organization-managed policies, project-level files, and user-level preferences.

At the project level, Anthropic documents ./CLAUDE.md and ./.claude/CLAUDE.md as standard locations, while user-level preferences live in ~/.claude/CLAUDE.md, allowing developers to carry personal working preferences across repositories without placing those preferences into every project.

Anthropic also documents broader configuration scopes such as managed, user, project, and local, which shows that persistent guidance in Claude Code is designed as a stack of instruction layers rather than as one monolithic prompt file.

This hierarchy matters because it lets organizations define broad policy, repositories define shared project guidance, and individuals define their own cross-project preferences without collapsing all of those concerns into a single instruction surface.

........

How Persistent Instruction Scope Is Structured

Scope	Typical Location or Form	Main Purpose
Managed	Organization-controlled configuration	Defines shared policy and broader guardrails
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Stores repository-level instructions shared with the team
User	~/.claude/CLAUDE.md	Stores personal preferences across projects
Local	Local repository-specific settings	Keeps machine-specific or private behavior out of shared project files

·····

Project context is loaded in stages rather than injected all at once.

Anthropic says that CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded in full at launch, while files in deeper subdirectories are loaded on demand when Claude begins reading or working inside those parts of the repository.

That implementation detail is important because it shows Claude Code does not treat the entire instruction surface of a large repository as one static initial prompt, since some context is present immediately while narrower path-specific guidance only enters context when it becomes relevant to the work being done.

Anthropic also recommends using .claude/rules/ in larger repositories when instructions need to be scoped to certain directories or file types, which reinforces the idea that project context is supposed to become more specific as Claude moves into more specialized parts of the codebase.

This staged loading model makes Claude Code’s context system more selective than a single giant memory block, because broad instructions are available early while fine-grained project rules arrive when the file path or task actually calls for them.

........

How Claude Code Loads Project Context

Context Layer	When It Loads	What It Does
Parent-directory CLAUDE.md files	At session launch	Provides broad instructions immediately
Working-directory project instructions	At session launch	Defines shared local project context
Subdirectory instruction files	On demand	Adds path-specific guidance when relevant
Live repository context	During active work	Comes from files, searches, commands, and tool use

·····

Auto memory is different from CLAUDE.md even though both shape future sessions.

Anthropic explicitly separates CLAUDE.md from auto memory, describing CLAUDE.md as user-written persistent instruction and auto memory as Claude-written learned memory based on corrections, preferences, and repeated patterns observed across work in the same working tree.

That difference matters because CLAUDE.md is intentional and editorial, while auto memory is learned and accumulative, which means one is a place where the developer states what Claude should know and the other is a place where Claude retains what it has been taught repeatedly over time.

Anthropic also notes that both are treated as context rather than enforced configuration, which means they strongly influence behavior but do not operate as hard-coded policy rules in the same way a deterministic enforcement mechanism would.

The documentation further states that only the first 200 lines or 25 KB of auto memory are loaded into each conversation, which makes auto memory a compact learned layer rather than an unlimited archive of everything ever observed in the repository.

........

CLAUDE.md and Auto Memory Serve Different Roles

Dimension	CLAUDE.md	Auto Memory
Who writes it	The user or team	Claude
Main purpose	Stores explicit instructions and stable rules	Stores learned preferences and repeated corrections
Scope	Can exist at organization, project, or user level	Scoped per working tree
Behavior type	Intentional persistent guidance	Learned cross-session context
Loading limit	Instruction-file based	First 200 lines or 25 KB loaded into conversation

·····

Project context in Claude Code extends beyond memory files and includes tools, workflows, and repository exploration.

Anthropic’s Claude Code documentation describes the product as an agentic coding system that reads the codebase, edits files, runs commands, and integrates with development tools, which means project context is not limited to what is stored in CLAUDE.md or auto memory.

Anthropic also distinguishes CLAUDE.md from other reusable mechanisms such as skills, hooks, subagents, and MCP integrations, showing that Claude Code’s broader context model is modular rather than concentrated in one memory feature.

That modular design is important because it prevents CLAUDE.md from becoming a catch-all system for every project behavior, since long reusable procedures may fit better into skills, deterministic automation belongs in hooks, and external system access belongs in MCP-connected tooling.

A repository therefore shapes Claude through several channels at once, including persistent instruction files, learned memory, current file content, directory structure, search results, command output, and any additional tools or integrations enabled in the session.

........

Project Context in Claude Code Comes From More Than Memory Alone

Context Source	Role in the Session
CLAUDE.md	Provides persistent instructions and stable working guidance
Auto memory	Carries learned preferences and prior corrections across sessions
Repository files	Supplies the actual code and documentation being edited
Search and command output	Adds live operational and structural context
Skills, hooks, and subagents	Add reusable procedures, automation, and specialized execution context
MCP integrations	Bring in connected external systems and services

·····

Claude Code memory is best understood as a layered context system rather than a single recall feature.

The most accurate way to describe Claude Code memory is as a system in which CLAUDE.md provides persistent working instructions, auto memory preserves learned preferences and repeated corrections, and project context expands during the session as Claude reads files, searches the repository, runs commands, and engages the tools available in the development environment.

That framing matters because it captures the real structure of the product without collapsing several distinct mechanisms into one vague idea of memory, and it also explains why Claude Code can feel consistent across sessions while still adapting dynamically to the part of the repository it is currently exploring.

Anthropic’s own documentation supports this layered interpretation directly, and even its CLI reference reinforces the same point by noting that --bare mode skips auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md, which shows that these memory and context layers are deliberately loaded components of the normal Claude Code environment rather than invisible background behavior.

In practical terms, CLAUDE.md tells Claude how to work in the repository, auto memory helps Claude carry forward learned preferences, and live project context comes from the files, structure, and tools Claude interacts with while doing the actual development work.

That is the real logic behind Claude Code memory.

·····

FOLLOW US FOR MORE.

·····

DATA STUDIOS

·····

[datastudios.org]

·····