claude/for
Search
Subscribe
Claude CodeUpdated

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

Arthur Teboul
Arthur TeboulEditor, claude/for
UPDATED SEP 26 · 5 MIN

Set up Claude Code memory with project CLAUDE.md instructions and auto memory, then verify what loads with /context and /memory.

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 covered in a companion guide, 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.

Two memory systems

CLAUDE.md / rulesAuto memory
Who writesYou (team / user / org)Claude
WhatInstructions and rulesLearnings and patterns
ScopeProject, user, or orgPer repository (shared across worktrees)
Loaded intoEvery sessionEvery session (first 200 lines or 25KB of MEMORY.md)
Use forStandards, workflows, architecturePreferences, 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 page) ≠ auto mode (permission mode that reduces prompts). They are separate features with separate settings.

Transcripts are not memory either. The raw session files you resume from are deleted after 30 days by default; keep Claude Code conversations longer than 30 days covers the cleanupPeriodDays setting.

Deep dual-file / /config Project instructions recipes live in the AGENTS ↔ CLAUDE share guide.

Set up CLAUDE.md so instructions persist

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

ScopeLocationShared with
Managed policymacOS /Library/Application Support/ClaudeCode/CLAUDE.md · Linux/WSL /etc/claude-code/CLAUDE.md · Windows C:\Program Files\ClaudeCode\CLAUDE.mdOrg
User~/.claude/CLAUDE.mdYou, all projects
Project./CLAUDE.md or ./.claude/CLAUDE.mdTeam 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 guide only.

The Claude moves worth stealing, by email

Workflows tested on real jobs, sent only when they are worth it. Free.

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 is covered in the skill-doctor guide, not here.

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

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

  • 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 guide.

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 details → skill-doctor guide.

Sources (checked 2026-09-26)

The Claude moves worth stealing, by email

Workflows tested on real jobs, sent only when they are worth it. Free.