Skip to content
eWiki The practical AI reference

AI Basics

What Is Claude Code Memory? CLAUDE.md and Auto Memory Explained

Stacks of blank white paper and cards beside a dark folder, a blue geometric object, and a long gray strip on a light surface.

Claude Code memory combines user-written instructions in CLAUDE.md with notes Claude creates through auto memory. Together, they preserve useful project context, but they serve different roles and consume context before work begins.

What Claude Code Memory Includes

Claude Code is an agentic coding tool that can read a codebase, edit files, run commands, and connect with development tools through terminal, IDE, desktop, and browser interfaces.

Its project context includes two complementary memory mechanisms. CLAUDE.md holds persistent instructions written by users, such as repository conventions and required commands. Auto memory contains notes Claude writes based on corrections and preferences. Before the first prompt, the context can already include both mechanisms, along with MCP tool names and skill descriptions.

The practical distinction is ownership: developers deliberately define shared instructions in CLAUDE.md, while Claude creates auto-memory notes from prior guidance. Because both occupy context, they should contain information that remains useful rather than temporary task details.

Layered translucent sketches clipped together above five small architectural drawings, with a pen and metal ruler on a desk.

How CLAUDE.md Loads Project Instructions

At session start, Claude Code reads CLAUDE.md files in the working directory and directories above it. A project-root file is therefore suitable for shared architecture notes, conventions, and commands. A nested CLAUDE.md is loaded later when Claude reads files in that subdirectory, making it useful for module-specific guidance.

More narrowly targeted instructions can live under .claude/rules/. These path-scoped rules can load only when Claude works with matching files, instead of occupying context for unrelated work. Claude Code can also read repository AGENTS.md files instead of CLAUDE.md under its documented loading conditions; user-level and managed instructions and .claude/rules/ can continue loading alongside AGENTS.md.

CLAUDE.md can import other files to make instructions easier to organize. Imports do not save context, however, because the imported material loads with the file that references it. Organization can improve maintainability, but it does not make the loaded content smaller.

A seated person placing a gray card among rows of blue, gray, and black cards on a wall-mounted board.

How to Keep Project Context Useful

Write instructions that describe an observable action. Anthropic’s examples include “Use 2-space indentation” and “Run npm test before committing”; these are clearer than broad requests to follow good practices. Repeated corrections are candidates for persistent instructions when they represent stable project rules.

Keep each CLAUDE.md focused. Anthropic recommends fewer than 200 lines because longer files consume more context and may weaken instruction adherence. Move guidance that applies only to particular files into path-scoped rules. Periodically remove obsolete or contradictory directions: when CLAUDE.md files, nested instructions, and rules conflict, Claude may select among them arbitrarily.

An edit made during an active session is not ordinarily reloaded on every turn. The updated instructions become available after /compact, when the file is opened through /memory, or in the next session. /compact replaces the conversation with a structured summary and then reloads most startup context automatically. When changing to unrelated work, clearing old conversation context can also prevent earlier material from continuing to consume tokens and crowd out relevant files.

Conclusion

Use the project-root CLAUDE.md for concise, stable instructions shared across the repository. Put module-specific guidance in nested files and narrowly applicable directions in path-scoped rules. Auto memory complements this structure by recording notes from corrections and preferences, but it does not replace deliberate project instructions.

Review your project-root CLAUDE.md now, remove conflicting or outdated guidance, and move file-specific rules into .claude/rules/. If you change instructions during an active session, open them through /memory, run /compact, or begin a new session so Claude Code loads the revised context.

Disclosures and limitations

  • This article was drafted with AI assistance using the cited Anthropic product documentation and Help Center materials.

Sources

Improve this guide

Report a problem or suggest the next question

Submissions enter a private editorial queue. They are reviewed and deduplicated before any public update or new page is created.