Memory

Claude Code can remember information across sessions — learn how the memory system works and how to manage it.

Claude Code has a persistent memory system that survives between sessions. Rather than starting fresh every time, Claude can carry forward what it has learned about you, your project, and your preferences.

Types of memory

Session context

The current conversation history. Claude has access to everything said in the active session, but this context is not automatically saved when the session ends.

Persistent memory

Facts, preferences, and project context saved to disk at ~/.claude/projects/<project>/memory/. These are loaded into every future session for the same project.

Memory categories

Persistent memories are organized into four types. Claude uses these categories to decide what to save and when to recall it.

user

Information about your role, goals, and knowledge. For example: your experience level, the languages you know, or the parts of the codebase you own. Claude uses this to tailor explanations and suggestions to you specifically.

feedback

Guidance you have given Claude about how to work — both corrections (“don’t mock the database”) and confirmations of approaches that worked well. Claude saves these so it doesn’t need to be corrected for the same thing twice.

project

Context about ongoing work that isn’t visible in the code or git history — deadlines, incidents, decisions and their rationale, who is working on what. Claude uses this to make better-informed suggestions about the work you bring it.

reference

Pointers to external systems: dashboards, issue trackers, Slack channels, runbooks. Claude recalls these when you reference an external resource during a session.

Code patterns, architecture, git history, and file structure are not saved to memory — Claude can derive these by reading your project. Memory is reserved for context that cannot be reconstructed from the codebase.

How Claude saves memories automatically

At the end of each completed query, Claude runs a background extraction process that reviews the conversation and identifies anything worth saving. This runs as a forked agent using the same session context, and writes memory files to your project’s memory directory.

If Claude already wrote to a memory file during the conversation itself, the background extraction skips that range — avoiding duplicates.

Each memory is stored as an individual Markdown file with frontmatter:

---
name: prefer-bundled-prs
description: User prefers bundled PRs for refactors over many small ones
type: feedback
---

For refactors in this area, prefer one bundled PR over many small ones.

**Why:** User confirmed this after I chose this approach — splitting would've been churn.

**How to apply:** When planning a refactor, default to a single PR unless the user asks to split.

An index file (MEMORY.md) is maintained alongside the topic files. Claude loads this index at the start of every session to orient itself before reading individual topic files on demand.

Managing memory with /memory

Run /memory to open the memory file selector. From there you can browse, open, and edit any memory file in your $EDITOR (or $VISUAL). Changes take effect immediately in the current session.

/memory

To instruct Claude to remember or forget something directly in conversation:

Remember that we always run integration tests against a real database, not mocks.

Forget what you saved about the auth middleware rewrite — that project is cancelled.

Claude will save or remove the relevant memory file and confirm what it did.

CLAUDE.md: project-level instructions

In addition to the memory system, you can place a CLAUDE.md file at the root of your project. Claude reads this file at startup for every session in that directory.

Use CLAUDE.md for instructions that apply to the whole project and should be version-controlled:

# CLAUDE.md

## Development setup
Run `bun install` to install dependencies. Use `bun test` to run the test suite.

## Conventions
- All API handlers go in `src/handlers/`
- Use `zod` for input validation on every new endpoint
- Integration tests must hit a real database — do not mock

## Deployment
Production deploys go through the `deploy` workflow in GitHub Actions.

CLAUDE.md is the right place for project-wide conventions and setup instructions. Use the memory system for context that changes over time or is specific to an individual user.

Team memory

When team memory is enabled, Claude maintains two memory directories:

• Private memory — stored locally, visible only to you
• Team memory — stored in a shared location, visible to everyone on the project

Feedback about personal communication preferences stays private. Project-wide conventions (testing policies, build rules, architectural decisions) are saved to team memory so the whole team benefits.

Team memory requires configuration by your organization. Contact your administrator if you want to enable shared memory for your project.

Disabling memory

To disable the memory system for a session, set the environment variable before starting Claude Code:

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

To disable it permanently for a project, add the following to your project’s settings.json:

{
  "autoMemoryEnabled": false
}

Privacy

Memory files are stored on your local filesystem at ~/.claude/projects/<sanitized-project-path>/memory/. They are plain Markdown files — you can read, edit, or delete them at any time. Nothing is sent to Anthropic as part of the memory system; memories are included in your conversation context when you start a session, and that context is sent to the Anthropic API as part of normal operation.