Memory Guide

Memory enables Claude to retain context across sessions and conversations. It exists in two forms: automatic synthesis in claude.ai, and filesystem-based CLAUDE.md in Claude Code.

Overview

Memory in Claude Code provides persistent context that carries across multiple sessions and conversations. Unlike temporary context windows, memory files allow you to:

• Share project standards across your team
• Store personal development preferences
• Maintain directory-specific rules and configurations
• Import external documentation
• Version control memory as part of your project

The memory system operates at multiple levels, from global personal preferences down to specific subdirectories, allowing for fine-grained control over what Claude remembers and how it applies that knowledge.

Memory Commands Quick Reference

Quick Start: Initializing Memory

The /init Command

The /init command is the fastest way to set up project memory in Claude Code. It initializes a CLAUDE.md file with foundational project documentation.

Usage:

What it does:

• Creates a new CLAUDE.md file in your project (typically at ./CLAUDE.md or ./.claude/CLAUDE.md)
• Establishes project conventions and guidelines
• Sets up the foundation for context persistence across sessions
• Provides a template structure for documenting your project standards

Enhanced interactive mode: Set CLAUDE_CODE_NEW_INIT=1 to enable a multi-phase interactive flow that walks you through project setup step by step:

When to use /init:

• Starting a new project with Claude Code
• Establishing team coding standards and conventions
• Creating documentation about your codebase structure
• Setting up memory hierarchy for collaborative development

Example workflow:

Quick Memory Updates

Note: The # shortcut for inline memory was discontinued. Use /memory to edit memory files directly, or ask Claude conversationally to remember something (e.g., "remember that we always use TypeScript strict mode").

The recommended ways to add information to memory are:

Option 1: Use /memory command

Opens your memory files in your system editor for direct editing.

Option 2: Ask conversationally

Asking Claude to remember something saves it to auto memory. To change CLAUDE.md instead, say "add this to CLAUDE.md", or edit the file yourself with /memory.

Historical reference (no longer functional):

The # prefix shortcut previously allowed adding rules inline:

If you relied on this pattern, switch to the /memory command or conversational requests.

The /memory Command

The /memory command provides direct access to edit your CLAUDE.md memory files within Claude Code sessions. It opens your memory files in your system editor for comprehensive editing. When the file opens in a GUI editor, the session no longer blocks while the file stays open, so you can keep working in parallel (v2.1.216); terminal editors like Vim still take over the terminal until you exit.

Usage:

What it does:

• Opens your memory files in your system's default editor
• Allows you to make extensive additions, modifications, and reorganizations
• Provides direct access to all memory files in the hierarchy
• Enables you to manage persistent context across sessions

When to use /memory:

• Reviewing existing memory content
• Making extensive updates to project standards
• Reorganizing memory structure
• Adding detailed documentation or guidelines
• Maintaining and updating memory as your project evolves

Comparison: /memory vs /init

Example workflow:

Using Memory Imports:

CLAUDE.md files support the @path/to/file syntax to include external content:

Import features:

• Both relative and absolute paths are supported (e.g., @docs/api.md or @~/.claude/my-project-instructions.md)
• Recursive imports are supported with a maximum depth of 4 hops
• First-time imports from external locations trigger an approval dialog for security
• Import directives are not evaluated inside markdown code spans or code blocks (so documenting them in examples is safe)
• Helps avoid duplication by referencing existing documentation
• Automatically includes referenced content in Claude's context

Memory Architecture

Memory in Claude Code follows a hierarchical system where different scopes serve different purposes. Unlike Claude Web/Desktop's 24-hour synthesis cycle (see Memory in Claude Web/Desktop below), Claude Code has two memory systems that both load at the start of every session and update continuously, not on a timer:

Memory Hierarchy in Claude Code

Claude Code has two complementary memory systems, both loaded at the start of every conversation: CLAUDE.md files (instructions you write) and auto memory (notes Claude writes itself). CLAUDE.md files are concatenated into context rather than overriding each other - this is not a strict precedence chain where a higher tier replaces a lower one. .claude/rules/*.md files are a separate, related mechanism for topic- or path-scoped instructions.

CLAUDE.md file locations, in load order (broadest scope to most specific):

Within the directory tree, Claude Code walks up from your working directory: foo/CLAUDE.md loads before foo/bar/CLAUDE.md if you launch from foo/bar/, so instructions closer to where you launched are read last - not "highest priority" in an override sense, just most recent in context. Within each directory, CLAUDE.local.md is appended after CLAUDE.md. CLAUDE.md and CLAUDE.local.md files in subdirectories under your working directory load on demand, when Claude reads files in those subdirectories, rather than at launch.

Organizations can also put managed CLAUDE.md content directly inside managed-settings.json via the claudeMd key, instead of deploying a separate file. This is honored only in managed/policy settings - setting claudeMd in user or project settings has no effect.

**.claude/rules/*.md** - modular, topic-specific instructions, optionally scoped to file paths via paths frontmatter. Rules without a paths field load unconditionally with the same priority as .claude/CLAUDE.md; path-scoped rules load on demand when Claude reads, writes, or edits a matching file - including viewing it with a single-file Bash read such as cat, head, tail, sed -n, or grep (Write/Edit since v2.1.288, Bash reads since v2.1.293). User-level rules (~/.claude/rules/) load before project rules.

Auto memory (~/.claude/projects/<project>/memory/) is a separate system: Claude's own notes, not CLAUDE.md content, and not part of the concatenation order above. See Auto Memory below.

Note: CLAUDE.local.md is fully supported and documented in the official documentation. It provides personal project-specific preferences that are not committed to version control. Add CLAUDE.local.md to your .gitignore.

Memory Discovery Behavior:

All files shown are concatenated into one context, not selected by override - later boxes appear later in context, not "instead of" earlier ones.

AGENTS.md

AGENTS.md is a cross-tool project-context file: the same category of document as CLAUDE.md, written so that several coding agents can share one set of project conventions. Since v2.1.277, Claude Code reads it directly as project instructions rather than requiring you to import it.

Default behavior (claude-md-or-agents-md):

Which files suppress AGENTS.md. Claude Code checks the working directory and every directory above it for CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md. If it finds any of them, AGENTS.md is not read. ~/.claude/CLAUDE.md, managed CLAUDE.md, and .claude/rules/ do not count for this check and keep loading alongside whichever project file wins.

Warning: adding a CLAUDE.local.md silently stops AGENTS.md being read. If your project instructions seem to vanish after you create a local override, this is usually why.

What gets read. Every AGENTS.md and .claude/AGENTS.md at and above the working directory loads at session start; files in subdirectories load on demand, when Claude reads files there. @path imports expand the same way they do in CLAUDE.md, and claudeMdExcludes applies.

What is never read: AGENTS.local.md, AGENTS.override.md, and anything under .agents/.

Choosing the behavior. The Project instructions setting takes four values:

Set it through /config, or in settings:

This key is honored in user and managed settings only - setting it in project or local settings has no effect.

Where direct reading is unavailable. On versions before v2.1.277 (or before v2.1.281 on Bedrock/Vertex/Foundry, behind LLM gateways, or with telemetry disabled), during the first session after upgrading, or with the built-in agents-md plugin disabled, Claude Code will not pick up AGENTS.md on its own. In those cases, import it from CLAUDE.md:

Excluding CLAUDE.md Files with claudeMdExcludes

In large monorepos, some CLAUDE.md files may be irrelevant to your current work. The claudeMdExcludes setting lets you skip specific CLAUDE.md files so they are not loaded into context:

Patterns are matched against absolute file paths using glob syntax, so start repo-relative patterns with **/. This is particularly useful for:

• Monorepos with many sub-projects, where only some are relevant
• Repositories that contain vendored or third-party CLAUDE.md files
• Reducing noise in Claude's context window by excluding stale or unrelated instructions

Settings File Hierarchy

Claude Code settings (including autoMemoryDirectory, claudeMdExcludes, and other configuration) resolve by precedence - unlike CLAUDE.md files above, settings genuinely override rather than concatenate. When the same setting appears in multiple scopes, the higher level wins:

Managed settings also support a drop-in directory, managed-settings.d/, alongside managed-settings.json: the base file merges first, then *.json files in the drop-in directory merge on top in alphabetical order (scalars override, arrays concatenate and de-duplicate, objects deep-merge). This lets separate teams deploy independent policy fragments without editing a shared file. Note this is a settings.json mechanism, not a CLAUDE.md one - it doesn't apply to the CLAUDE.md file locations described above.

Permission rules (allow/ask/deny) behave differently from other settings: they merge across scopes instead of the higher level replacing the lower one.

Platform-specific configuration (v2.1.51+):

Settings can also be configured via:

• macOS: Property list (plist) files
• Windows: Windows Registry

These platform-native mechanisms are read alongside JSON settings files and follow the same precedence rules.

Note (v2.1.119): /config changes now persist to ~/.claude/settings.json. Values written via /config participate in the normal policy/local/project precedence chain described above - they are no longer session-only. Use /config for interactive edits and edit settings.json files directly for scripted or managed configuration.

Retention and Cleanup Settings

Attribution, Voice, and PR URL Settings

An empty string ("") hides that attribution; "attribution": false hides all of it (v2.1.281+).

Deprecated setting names

The following legacy setting keys still work but are deprecated. Prefer the replacements above.

Modular Rules System

Create organized, path-specific rules using the .claude/rules/ directory structure. Rules can be defined at both the project level and user level:

Rules are discovered recursively within the rules/ directory, including any subdirectories. User-level rules at ~/.claude/rules/ are loaded before project-level rules, allowing personal defaults that projects can override.

Path-Specific Rules with YAML Frontmatter

Define rules that apply only to specific file paths:

Glob Pattern Examples:

• **/*.ts - All TypeScript files
• src/**/* - All files under src/
• src/**/*.{ts,tsx} - Multiple extensions
• {src,lib}/**/*.ts, tests/**/*.test.ts - Multiple patterns

Subdirectories and Symlinks

Rules in .claude/rules/ support two organizational features:

• Subdirectories: Rules are discovered recursively, so you can organize them into topic-based folders (e.g., rules/api/, rules/testing/, rules/security/)
• Symlinks: Symlinks are supported for sharing rules across multiple projects. For example, you can symlink a shared rule file from a central location into each project's .claude/rules/ directory. Since v2.1.284, a rule symlinked from outside the project - or a .claude directory symlinked from outside - shows the same external-imports approval prompt as an @path import

Memory Locations Table

CLAUDE.md files and rules are concatenated into context, not selected by strict override - "Load order" below means where in context it appears, not which one wins. Auto memory is a separate mechanism with its own storage location.

Memory Update Lifecycle

Here's how memory updates flow through your Claude Code sessions:

Auto Memory

Auto memory is a persistent directory where Claude automatically saves typed notes (user, feedback, project, reference) as it works with your project. It skips anything it can derive from the codebase, such as architecture, file paths, or debugging fixes. Unlike CLAUDE.md files which you write and maintain manually, auto memory is written by Claude itself during sessions.

How Auto Memory Works

• Location: ~/.claude/projects/<project>/memory/
• Entrypoint: MEMORY.md serves as the main file in the auto memory directory
• Topic files: Optional additional files, one per memory (e.g., prefers-pnpm.md, release-checklist.md)
• Loading behavior: The first 200 lines of MEMORY.md (or first 25KB, whichever comes first) are loaded into context at session start. Topic files are loaded on demand, not at startup.
• Read/write: Claude reads and writes memory files during sessions as it learns your preferences, feedback, and project context
• Frontmatter: Files that begin with YAML frontmatter get a modified field - an ISO 8601 timestamp Claude Code records each time it writes the file (v2.1.214)

Auto Memory Architecture

Auto Memory Directory Structure

Version Requirement

Auto memory requires Claude Code v2.1.59 or later. If you are on an older version, upgrade first:

Turning Auto Memory On or Off

Auto memory is on by default. The autoMemoryEnabled setting (default true) controls it; when false, Claude neither reads from nor writes to the auto memory directory. You can also toggle it with /memory during a session.

To disable it via environment instead, set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Setting it to 0 forces auto memory on even when --bare mode or autoMemoryEnabled: false would otherwise disable it.

Custom Auto Memory Directory

By default, auto memory is stored in ~/.claude/projects/<project>/memory/. You can change this location using the autoMemoryDirectory setting (available since v2.1.74):

Note: autoMemoryDirectory is read from any settings scope: user, project, local, managed policy, or --settings. The value must be an absolute path or start with ~/.

This is useful when you want to:

• Store auto memory in a shared or synced location
• Separate auto memory from the default Claude configuration directory
• Use a project-specific path outside the default hierarchy

Worktree and Repository Sharing

All worktrees and subdirectories within the same git repository share a single auto memory directory. This means switching between worktrees or working in different subdirectories of the same repo will read and write to the same memory files.

Subagent Memory

Subagents (spawned via the Agent tool) can keep their own persistent memory. The memory frontmatter field in the subagent definition picks where that memory directory lives:

The subagent reads the first 200 lines / 25KB of that directory's MEMORY.md at startup and gets Read/Write/Edit to maintain it. It has no effect when auto memory is disabled.

Note: Subagents can also maintain their own auto memory. See the official subagent memory documentation for details.

Controlling Auto Memory

Auto memory can be controlled via the CLAUDE_CODE_DISABLE_AUTO_MEMORY environment variable:

Additional Directories with --add-dir

The --add-dir flag allows Claude Code to load CLAUDE.md files from additional directories beyond the current working directory. This is useful for monorepos or multi-project setups where context from other directories is relevant.

To enable this feature, set the environment variable:

Then launch Claude Code with the flag:

Claude will load CLAUDE.md from the specified additional directory alongside the memory files from your current working directory.

Practical Examples

Example 1: Project Memory Structure

File: ./CLAUDE.md

Example 2: Directory-Specific Memory

File: ./src/api/CLAUDE.md

Example 3: Personal Memory

File: ~/.claude/CLAUDE.md

_My Test_

Ask Claude to save a new rule

Claude has not save the rule because I did not have any Claude.md file anywhere. Then asked Claude to confirm the location.

Example 4: Memory Update During Session

You can add new rules to CLAUDE.md during an active Claude Code session by asking Claude directly (asking it to remember something saves to auto memory instead):

Or use /memory to edit memory files directly for extensive updates or reorganization.

Tips for Adding Memory

• Be specific and actionable in your rules
• Group related rules together under a section header
• Update existing sections instead of duplicating content
• Choose the appropriate memory scope (project vs. personal)

Memory Features Comparison

Memory in Claude Web/Desktop

Memory Synthesis Timeline

Example Memory Summary:

Best Practices

Do's - What To Include

• Be specific and detailed: Use clear, detailed instructions rather than vague guidance
• ✅ Good: "Use 2-space indentation for all JavaScript files"
• ❌ Avoid: "Follow best practices"

• Keep organized: Structure memory files with clear markdown sections and headings

• Use appropriate hierarchy levels:
• Managed policy: Company-wide policies, security standards, compliance requirements
• Project memory: Team standards, architecture, coding conventions (commit to git)
• User memory: Personal preferences, communication style, tooling choices
• Directory memory: Module-specific rules and overrides

• Leverage imports: Use @path/to/file syntax to reference existing documentation
• Supports a maximum depth of 4 hops for recursive imports
• Avoids duplication across memory files
• Example: See @README.md for project overview

• Document frequent commands: Include commands you use repeatedly to save time

• Version control project memory: Commit project-level CLAUDE.md files to git for team benefit

• Review periodically: Update memory regularly as projects evolve and requirements change

• Provide concrete examples: Include code snippets and specific scenarios

Don'ts - What To Avoid

• Don't store secrets: Never include API keys, passwords, tokens, or credentials

• Don't include sensitive data: No PII, private information, or proprietary secrets

• Don't duplicate content: Use imports (@path) to reference existing documentation instead

• Don't be vague: Avoid generic statements like "follow best practices" or "write good code"

• Don't make it too long: Target under 200 lines per CLAUDE.md. Longer files still load in full, but adherence drops - see Keeping CLAUDE.md small below

• Don't over-organize: Use hierarchy strategically; don't create excessive subdirectory overrides

• Don't forget to update: Stale memory can cause confusion and outdated practices

• Don't exceed nesting limits: Memory imports support a maximum depth of 4 hops

Keeping CLAUDE.md Small

Anthropic's current guidance is the opposite of "put everything in CLAUDE.md". The file loads into every session, so every line you add is a line that competes for attention on tasks it has nothing to do with.

Rule of thumb: keep CLAUDE.md under 200 lines. Longer files still load in full, but instruction adherence degrades as the file grows.

When it starts growing, move content out rather than trimming prose:

Note: @path imports organize a large CLAUDE.md but do not save context - imported files are pulled in at load time just the same. Splitting into path-scoped rules is what actually reduces what loads.

/doctor (v2.1.206+) inspects your configuration and proposes trims when CLAUDE.md has grown past the point of usefulness.

Don't Write Verification Reminders

Older guidance encouraged lines like "always run the tests before saying you're done" or "double-check your work". On Claude Opus 5 and Fable 5 these now cause over-verification - Claude re-checks work that was already correct, burning turns and tokens.

Anthropic removed more than 80% of Claude Code's own system prompt for the Claude 5 generation with no measured regression. The same principle applies to your CLAUDE.md: prefer stating the goal and letting Claude exercise judgment over enumerating the checks it should perform.

Delete verification reminders from existing CLAUDE.md files targeting Opus 5 or Fable 5. Keep genuinely non-obvious project requirements - "integration tests need Docker running" is information, not a reminder.

Memory Management Tips

Choose the right memory level:

Quick update workflow:

1. For single rules: Use /memory to open editor, or ask conversationally
2. For multiple changes: Use /memory to open editor
3. For initial setup: Use /init to create template

Import best practices:

Installation Instructions

Setup Project Memory

Method 1: Using /init Command (Recommended)

The fastest way to set up project memory:

1. Navigate to your project directory:

2. Run the init command in Claude Code:

3. Claude will create and populate CLAUDE.md with a template structure

4. Customize the generated file to match your project needs

5. Commit to git:

Method 2: Manual Creation

If you prefer manual setup:

1. Create a CLAUDE.md in your project root:

2. Add project standards:

3. Commit to git:

Setup Personal Memory

1. Create ~/.claude directory:

2. Create personal CLAUDE.md:

3. Add your preferences:

Setup Directory-Specific Memory

1. Create memory for specific directories:

2. Add directory-specific rules:

3. Commit to version control:

Verify Setup

1. Check memory locations:

2. Claude Code will automatically load these files when starting a session

3. Test with Claude Code by starting a new session in your project

Official Documentation

For the most up-to-date information, refer to the official Claude Code documentation:

• Memory Documentation - Complete memory system reference
• Slash Commands Reference - All built-in commands including /init and /memory
• CLI Reference - Command-line interface documentation

Key Technical Details from Official Docs

Memory Loading:

• All memory files are automatically loaded when Claude Code launches
• Claude traverses upward from the current working directory to discover CLAUDE.md files
• Subtree files are discovered and loaded contextually when accessing those directories

Import Syntax:

• Use @path/to/file to include external content (e.g., @~/.claude/my-project-instructions.md)
• Supports both relative and absolute paths (relative paths resolve relative to the file containing the import, not the working directory)
• Recursive imports supported with a maximum depth of 4 hops
• First-time external imports trigger an approval dialog
• Not evaluated inside markdown code spans or code blocks
• Automatically includes referenced content in Claude's context

CLAUDE.md Load Order (concatenated into context, not strict override - see Memory Hierarchy in Claude Code above):

1. Managed Policy (loads first)
2. User-Level Rules (~/.claude/rules/)
3. User Memory
4. Project Rules (.claude/rules/)
5. Project Memory
6. Local Project Memory (loads last)

Auto Memory is a separate mechanism (~/.claude/projects/<project>/memory/), not part of this concatenation order.

Related Concepts Links

Integration Points

• MCP Protocol - Live data access alongside memory
• Slash Commands - Session-specific shortcuts
• Skills - Automated workflows with memory context

Related Claude Features

• Claude Web Memory - Automatic synthesis
• Official Memory Docs - Anthropic documentation

Last Updated: October 18, 2026

Claude Code Version: 2.1.302

Sources:

• https://code.claude.com/docs/en/memory
• https://code.claude.com/docs/en/memory#agents-md
• https://code.claude.com/docs/en/memory#when-agents-md-support-is-unavailable
• https://github.com/anthropics/claude-code/releases/tag/v2.1.284
• https://github.com/anthropics/claude-code/releases/tag/v2.1.288
• https://github.com/anthropics/claude-code/releases/tag/v2.1.293
• https://code.claude.com/docs/en/sub-agents#enable-persistent-memory
• https://code.claude.com/docs/en/settings-reference
• https://code.claude.com/docs/en/claude-directory

Compatible Models: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5