For a long time, coding assistants had a very human problem: they forgot everything when the session ended. Build commands, test conventions, architecture notes, that one “we use pnpm, not npm” preference—you had to repeat it over and over.
Claude Code tackles this with persistent memory that spans sessions. The system is intentionally split into two parts: automatic memory (Claude writes it) and CLAUDE.md files (you and your team write them). The goal isn’t to store everything—it’s to store the right context, in the right place, with clear precedence.
Two kinds of memory that persist across sessions
Claude Code uses two mechanisms that load into context at the start of each session:
- Auto memory: Claude automatically saves useful learnings (project patterns, debugging notes, your preferences).
- CLAUDE.md files: Markdown instructions you maintain (rules, standards, architecture decisions, workflows).
A key detail: auto memory only loads the first 200 lines of its main file (MEMORY.md) at startup. Longer notes are meant to live in separate topic files that Claude reads only when needed.
There isn’t just one CLAUDE.md: memory is hierarchical
Claude Code organizes memory in a hierarchy. More specific instructions override broader ones, and CLAUDE.md files are discovered by walking up the directory tree from your current working directory.
Here’s the map at a glance:
| Memory type | Location | What it’s for | Shared with |
|---|---|---|---|
| Managed policy (org-wide) | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md · Linux: /etc/claude-code/CLAUDE.md · Windows: C:\Program Files\ClaudeCode\CLAUDE.md | IT/DevOps-managed rules (security, compliance, standards) | Everyone in the org |
| Project memory | ./CLAUDE.md or ./.claude/CLAUDE.md | Team instructions for a repo | Team (via source control) |
| Project rules (modular) | ./.claude/rules/*.md | Topic-specific rules (testing, API, style) | Team (via source control) |
| User memory | ~/.claude/CLAUDE.md | Personal preferences across projects | Just you |
| Project memory (local) | ./CLAUDE.local.md | Your private project-specific prefs | Just you |
| Auto memory | ~/.claude/projects/<project>/memory/ | Claude’s own notes per project | Just you |
Auto memory: what Claude writes down for later
Auto memory is a per-project directory where Claude records patterns and learnings as it works. It lives here:
~/.claude/projects/<project>/memory/
Typical structure:
MEMORY.md(entrypoint/index, first 200 lines loaded at startup)- optional topic files like
debugging.md,api-conventions.md, etc.
Claude updates these files during sessions. The design intent is “keep the index concise, move details into topic files.”
How to disable auto memory (globally or per project)
Global setting:
// ~/.claude/settings.json
{ "autoMemoryEnabled": false }
Project setting:
// .claude/settings.json
{ "autoMemoryEnabled": false }
Or force it via environment variable (useful for CI):
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 # Force off
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 # Force on
CLAUDE.md: your project “brief” (with imports so it stays sane)
CLAUDE.md is where you put explicit instructions you want Claude to follow: common commands, conventions, architectural choices, workflow rules, and do/don’t lists. Claude Code supports imports using @path/to/file so you can keep a top-level CLAUDE.md short and fan out into modular docs. Imports can be relative or absolute and can chain up to a maximum depth.
Example:
# Project Overview
- Commands: see @package.json
- Architecture: @docs/architecture.md# Rules
- Testing: @docs/testing.md
- API: @docs/api.md
- Security: @docs/security.md
Modular rules with .claude/rules/ (and path-scoped enforcement)
For larger repos, Claude Code can load all Markdown files under ./.claude/rules/ automatically. You can also scope rules to only apply to certain files using YAML frontmatter with paths: and glob patterns.
---
paths:
- "src/api/**/*.ts"
---# API Rules
- Validate inputs on every endpoint
- Use the standard error format
- Include OpenAPI doc comments
Practical best practices (the “don’t regret this later” list)
- Don’t store secrets in any memory file (tokens, credentials, private URLs). Treat them like documentation.
- Keep the main project CLAUDE.md short: commands, conventions, and pointers to deeper docs.
- Put team-wide rules in
.claude/…and your personal stuff inCLAUDE.local.md. - In CI, consider forcing
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1to avoid writing memories on ephemeral runners. - Review auto memory occasionally—if Claude “learns” the wrong thing, you’ll keep tripping over it.
Source: Claude Memory