How do I set up Claude Code memory so project notes persist across sessions?

Each Claude Code session starts with a fresh context window. Two systems carry knowledge across sessions: you-written CLAUDE.md / rules (and optionally AGENTS.md), plus auto memory notes Claude saves under ~/.claude/projects/<project>/memory/. Start with a project CLAUDE.md (/init helps), leave auto memory on, and confirm with /context / /memory. Sharing AGENTS.md with CLAUDE.md is a companion Spec — not this page.

TL;DR: (1) Add project ./CLAUDE.md or ./.claude/CLAUDE.md — /init bootstraps. (2) Put personal prefs in ~/.claude/CLAUDE.md or gitignored CLAUDE.local.md. (3) Leave auto memory on (default) so MEMORY.md reloads (first 200 lines or 25KB). Audit with /memory. Checked memory docs dateModified 2026-09-26. Primary Labs seed: claude code memory (1300 / KD 17).

Two memory systems

	CLAUDE.md / rules	Auto memory
Who writes	You (team / user / org)	Claude
What	Instructions and rules	Learnings and patterns
Scope	Project, user, or org	Per repository (shared across worktrees)
Loaded into	Every session	Every session (first 200 lines or 25KB of MEMORY.md)
Use for	Standards, workflows, architecture	Preferences, corrections, context Claude can’t derive from code

Both load as context, not hard enforcement. For a hard block, use PreToolUse hooks or permissions ask/deny — soft CLAUDE.md lines won’t guarantee it.

Naming trap: auto memory (this Spec) ≠ auto mode (permission mode that reduces prompts). Don’t mix leave-auto steps into memory setup.

Deep dual-file / /config Project instructions recipes live only on the AGENTS ↔ CLAUDE share Spec.

Set up CLAUDE.md so instructions persist

Pick a scope (docs load order: broad → specific):

Scope	Location	Shared with
Managed policy	macOS /Library/Application Support/ClaudeCode/CLAUDE.md · Linux/WSL /etc/claude-code/CLAUDE.md · Windows C:\Program Files\ClaudeCode\CLAUDE.md	Org
User	~/.claude/CLAUDE.md	You, all projects
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Team via VCS
Local	./CLAUDE.local.md (gitignore)	You, this project

Bootstrap: run /init. Claude analyzes the repo and writes or improves a project CLAUDE.md (build/test commands, conventions it can see). Refine with facts Claude can’t infer — pitfalls, “always do X,” non-obvious layout.

Size / structure: target under ~200 lines per file; markdown headers and concrete bullets (“Use 2-space indentation,” not “format nicely”). For large projects, split into .claude/rules/*.md. Rules without paths frontmatter load at launch like .claude/CLAUDE.md; path-scoped rules load when Claude works on matching files:

---
paths:
  - "src/api/**/*.ts"
---

API rules
- Validate input on every endpoint

@path imports expand at launch (max depth 4). External imports need approval the first time.

Confirm: /context → Memory files list; open/edit via /memory.

Thin AGENTS pointer: by default Claude reads AGENTS.md when no counting project CLAUDE.md / .claude/CLAUDE.md / CLAUDE.local.md sits on the path (direct load needs v2.1.277+). Dual-file / @AGENTS.md / Project instructions → share Spec only.

Turn on (and audit) auto memory

Auto memory is on by default. Toggle in /memory (writes autoMemoryEnabled to ~/.claude/settings.json). Per-project off: "autoMemoryEnabled": false in that project’s settings. Env kill-switch: CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Storage: ~/.claude/projects/<project>/memory/ with MEMORY.md as the index plus topic files. Frontmatter type values Claude may use: user / feedback / project / reference. It skips architecture Claude can derive from code and anything already in CLAUDE.md.

Load cap: first 200 lines or 25KB of MEMORY.md (whichever comes first) at session start. Detail lives in topic files Claude reads on demand.

Auto memory is machine-local; all worktrees of the same git repo share one directory. It is not a substitute for a team-checked-in CLAUDE.md.

Ask Claude to “remember X” → lands in auto memory. Say “add this to CLAUDE.md” when the rule should be team-visible. Browse/edit plain markdown via /memory → open folder / files.

Pitfalls

• Expecting CLAUDE.md to hard-block tools — use permissions/hooks instead.

• Letting CLAUDE.md balloon past ~200 lines / adherence budget; /doctor (v2.1.206+) may propose trims — skill-load diagnosis belongs on the skill-doctor Spec, not here.

• Turning auto memory off as default “setup” advice — leave it on unless you have a reason.

• Cloning the AGENTS share essay or teaching skill-doctor as memory setup.

• Treating community memory tools (e.g. HN Jevmem interest) as Claude Code product behavior — docs above win.

• Mixing auto mode leave steps into this Spec.

• After /compact: project-root CLAUDE.md is re-injected; conversation-only notes vanish unless written to memory or CLAUDE.md.

FAQ

Where do project notes live across sessions?
You-written CLAUDE.md / .claude/rules/ plus Claude-written auto memory at ~/.claude/projects/<project>/memory/ (MEMORY.md index + topic files).

Is auto memory on by default?
Yes. Toggle in /memory, or set autoMemoryEnabled / CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

How is this different from AGENTS.md?
AGENTS is instruction-file interoperability with other coding agents. Setup and dual-file recipes: share Spec.

How do I see what loaded?
/context (Memory files) and /memory (open/edit locations, including auto memory folder).

Does /doctor fix memory?
It may propose CLAUDE.md trims (v2.1.206+). Skill load / doctor body → skill-doctor Spec.

Sources (checked 2026-09-26)

• How Claude remembers your project — dateModified 2026-09-26T00:30:20.503Z (JSON-LD); CLAUDE.md scopes, /init, .claude/rules/, auto memory paths/limits, troubleshooting

• Live bridges: AGENTS ↔ CLAUDE share · skill-doctor · permissions (hooks vs soft instructions)

• Discourse awareness only (not product truth): community project-memory tooling interest (e.g. HN Jevmem) — cite docs for behavior