When you use Claude Code in a repository, a new session starts with a fresh context window. Files named CLAUDE.md and Claude Code’s automatic memory help carry useful information between sessions. A CLAUDE.md file contains instructions you write; automatic memory contains notes Claude Code creates about a project.
Use CLAUDE.md for stable guidance, such as coding conventions and test commands. Let automatic memory capture useful project details that change over time. Both provide context for Claude Code, so neither guarantees that Claude will follow an instruction or remember every detail. The Claude Code memory documentation describes how these sources fit into a session.
Put instructions in the right CLAUDE.md file
A project-level CLAUDE.md shares instructions with people who work in the repository. Place it at the repository root, or use .claude/CLAUDE.md. For personal preferences that should not be shared, use ~/.claude/CLAUDE.md. An organization can also provide instructions through enterprise settings.
Claude Code also supports CLAUDE.local.md for personal project settings. It is automatically added to .gitignore, which makes it useful for local preferences or notes that should stay on your machine. Claude Code can read AGENTS.md files as well, so check for those instructions when you join a repository.
For larger projects, put guidance near the code it concerns. A nested CLAUDE.md can provide instructions for a particular part of the repository. You can also import another file with @path/to/file; Claude Code loads the imported content with the file that references it. Imports can be nested up to four levels.
Keep each CLAUDE.md under 200 lines, as the official guidance recommends. A concise, specific instruction is easier to apply than a broad one. For example, “Use 2-space indentation” gives Claude Code a clear rule to follow; “Format code properly” leaves the meaning open to interpretation.
Use automatic memory for changing project details
Automatic memory stores project notes separately from your repository’s instruction files. Claude Code keeps the notes under ~/.claude/projects/, with a project-specific memory directory and a MEMORY.md file that acts as its index. The memory file layout can help you locate and inspect those notes.
Put lasting rules in CLAUDE.md and changing facts in memory. A coding convention belongs in the instruction file. A recent migration decision or a note about where a feature lives is more likely to belong in memory. Keep the index short and point to details rather than filling it with long explanations. Claude Code loads the first 200 lines of MEMORY.md at session start, so important notes should appear near the top.
Review memory from time to time. Notes can become outdated. One reported auto-memory corruption issue describes incorrect or partial information that carried into later sessions. Check remembered claims against the current code and documentation before relying on them. The /memory command lets you view and manage memory files.
Treat instructions as guidance, not access controls
Claude Code reads CLAUDE.md and memory as context. Claude Code follows concise, relevant instructions more consistently, but these files cannot block an action. If a command or tool call must be blocked regardless of what Claude decides, use a PreToolUse hook rather than relying on Markdown instructions.
Conflicting instructions also make behavior less predictable. When Claude Code gives an unexpected answer, check the project and personal CLAUDE.md files, nested instruction files, and rules under .claude/rules/. Remove or update instructions that no longer match the repository.
Start small and keep the files current
Run /init to create a starting CLAUDE.md based on the repository. If one already exists, Claude Code suggests improvements rather than replacing it. Then edit the file so it contains the commands and conventions that actually apply. Use /memory to review automatic notes, and remove details that are stale or no longer useful.
Write down information Claude Code needs repeatedly and keep it near the code or task it applies to. Verify details that might have changed. Avoid building a large custom memory setup before you know what the built-in files fail to preserve.