Claude Code Memory System

Quick Answer

Claude Code memory is a set of markdown files loaded into every session. The hierarchy is global CLAUDE.md, project CLAUDE.md, and any files imported with the at-sign prefix. Auto-memory writes short notes to disk so they persist across sessions. TLDR: memory is file-based, stateless at the model level, and entirely under your control. Edit the files to shape what Claude remembers.

Summary of the 6 memory layers

1. Global CLAUDE.md at home config folder
2. Project CLAUDE.md at repo root
3. Subfolder CLAUDE.md files walked up the tree
4. Imported docs via at-sign prefix references
5. Auto-memory notes written to disk
6. Session context (cleared by /compact or /clear)

How memory actually works

Claude the model is stateless. Every turn sends the full context to the API and gets a response, with no hidden server-side memory of your past sessions or conversations. Claude Code fakes durable memory by loading files into the context at the start of each session: a global config file, a project config file, any subfolder config files on the path, and an index of auto-memory notes. Those files are yours to edit. The agent reads them as part of its system prompt and treats them as permanent context. This design has 2 consequences. First, your memory is portable: copy the files and Claude remembers the same things on another machine. Second, there is no magic: everything Claude knows between sessions is written down somewhere you can read, audit, and modify.

The memory hierarchy

When you run the agent in a project folder, Claude Code walks from the working directory up to the home folder and loads every CLAUDE.md it finds along the way. The files are concatenated into the system prompt in order, with the global file first and the most specific (working directory) file last.

Later files override earlier ones when rules conflict, because the model weighs later content more heavily. In practice conflicts are rare because files at different levels serve different purposes.

Global CLAUDE.md holds personal preferences (how you like explanations, your commit message style). Project CLAUDE.md holds team rules (language version, test commands, folder layout). Subfolder CLAUDE.md holds component-specific rules (this service uses a different database, this package has a custom lint config).

What loads automatically

4 things load on every session without you doing anything.

1. Global CLAUDE.md from the home config folder
2. Project CLAUDE.md from the working directory walk
3. Any files referenced with the at-sign import prefix
4. The MEMORY.md index from the project auto-memory folder

The MEMORY.md index is short (usually under 200 lines) and points to individual memory files. Claude reads the index first and loads specific memories on demand when relevant.

Auto-memory

Claude Code has an auto-memory feature that writes short notes to disk during a session. Notes live at ~/.claude/projects//memory/ as individual markdown files.

You can trigger auto-memory by saying things like "remember this" or "save this decision." Claude also writes memories when it infers something you will want to remember (a user preference, a workaround, a project-specific fact you corrected).

Each memory file is tagged with a type: user profile, feedback, project context, reference. The MEMORY.md index lists all of them with a one-line summary per entry.

On the next session, Claude reads the index and has instant access to everything you remembered. No re-explaining yourself.

Memory types

Auto-memory distinguishes 4 kinds of content.

User profile: facts about you. Your email, your github handle, your preferred commit format.

Feedback: corrections you gave Claude. "Do not use em-dashes." "Always run tests before proposing a commit." "Prefer pnpm over npm."

Project context: facts about the project that are hard to infer. "The payments module has no integration tests." "The deploy script runs only on the main branch." "The Postgres database uses schema name app."

References: pointers to docs or specs. "See docs/architecture.md for the overall design." "The API spec is at specs/openapi.yaml."

Each kind serves a different purpose. Keeping them separate makes the index easier to scan.

MEMORY.md as an index

The MEMORY.md file is a one-liner-per-entry index. It caps at 200 lines to keep the token cost low. Entries look like this.

1. User profile: Email is me@example.com
2. Feedback: Prefer pnpm over npm
3. Project: Payments module has no integration tests
4. Reference: See docs/architecture.md for design

Claude reads the index on session start. When an entry is relevant, Claude can load the full memory file (if one exists) for more detail.

This structure balances cost and detail. The index is small and loads every session. Detailed files load only when needed.

When to manually save memory

Auto-memory does not catch everything. 3 situations call for a manual save.

Important decisions. "We chose Postgres over MySQL because of JSONB support." This is hard to infer from code and painful to re-derive. Save it.

Preferences you want to persist. "Do not suggest Redux, we use Zustand." Auto-memory will catch this after a few repetitions, but saving it early prevents the first 3 mistakes.

Non-obvious facts. "The deploy script takes 8 minutes and must run from the CI runner, not locally." Knowing this avoids a lot of debugging.

Ask Claude to save by phrasing like "remember that we prefer X" or "save this as a project fact."

How memories persist across sessions

Memory files live on disk. They survive restarts, machine reboots, and Claude Code updates. They do not sync across machines unless you sync the folder yourself (via dotfile management or a shared drive).

This is intentional. Memory is per-machine by default because personal preferences and debugging facts are not always safe to share.

If you want to share memory across machines, sync ~/.claude/projects//memory/ via your usual dotfile sync. Or commit the project CLAUDE.md files to git so the team shares them.

Memory vs session context

2 different things that sometimes get confused.

Session context is the active conversation. It includes the files Claude read this session, the tool calls it made, and the outputs it produced. Session context is cleared by /clear or compacted by /compact.

Memory is persistent. It survives session end. It is stored in files. Clearing the session does not clear memory.

A practical rule: if you want to remember something across sessions, save it to memory. If you want to forget something at the end of the session, let it stay in session context.

Managing stale memories

Memory files age. A fact saved 6 months ago may no longer be true. 3 strategies for keeping memory fresh.

Review quarterly. Open the MEMORY.md index, skim every entry, delete or update anything that is outdated.

Version-tag sensitive entries. If a fact depends on library version ("Zustand v4 behaves this way"), include the version in the entry so you know when to revisit.

Ask Claude to audit. Every few months, run a session and ask "review my MEMORY.md for stale entries." Claude will flag ones that look outdated based on the current code.

Team memory

Teams share memory through the project CLAUDE.md file, not through individual memory folders. The CLAUDE.md file is committed to git and loaded by every team member session.

This means team rules, test commands, and project conventions live in CLAUDE.md. Personal preferences and debugging notes stay in individual auto-memory.

A subtle consequence: do not rely on individual memory for team-critical rules. If a rule matters for every team member, put it in CLAUDE.md so it is enforced consistently.

Memory vs AGENTS.md

AGENTS.md is a shared convention for subagent context. CLAUDE.md targets the main Claude Code session.

Most teams reference AGENTS.md from CLAUDE.md with the at-sign import syntax. This avoids duplicating content between the 2 files. The convention reads CLAUDE.md first, imports AGENTS.md, and gets consistent context for both the main session and any subagents dispatched from it.

Using memory to avoid repetition

The highest-value use of memory is avoiding the same correction twice. Every time you tell Claude "actually, we prefer X," either phrase it as a memory save or add it to CLAUDE.md.

Over time the memory files become a mirror of your team conventions. New developers joining the project read CLAUDE.md and pick up the same rules Claude uses. The memory is not just for the agent; it is for the humans too.

Agents that have good memory feel dramatically more capable than agents without. Not because the model is smarter, but because the memory system means Claude starts every session with the context a teammate would have after a year on the project.