Manage Claude's memory - Claude Code Docs

Claude Code can remember your preferences across sessions, like style guidelines and common commands in your workflow.

Determine memory type

Claude Code offers four memory locations in a hierarchical structure, each serving a different purpose:

All memory files are automatically loaded into Claude Code’s context when launched. Files higher in the hierarchy take precedence and are loaded first, providing a foundation that more specific memories build upon.

CLAUDE.md imports

CLAUDE.md files can import additional files using @path/to/import syntax. The following example imports 3 files:

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

Both relative and absolute paths are allowed. In particular, importing files in user’s home dir is a convenient way for your team members to provide individual instructions that are not checked into the repository. Imports are an alternative to CLAUDE.local.md that work better across multiple git worktrees.

# Individual Preferences
- @~/.claude/my-project-instructions.md

To avoid potential collisions, imports are not evaluated inside markdown code spans and code blocks.

This code span will not be treated as an import: `@anthropic-ai/claude-code`

Imported files can recursively import additional files, with a max-depth of 5 hops. You can see what memory files are loaded by running /memory command.

How Claude looks up memories

Claude Code reads memories recursively: starting in the cwd, Claude Code recurses up to (but not including) the root directory / and reads any CLAUDE.md or CLAUDE.local.md files it finds. This is especially convenient when working in large repositories where you run Claude Code in foo/bar/, and have memories in both foo/CLAUDE.md and foo/bar/CLAUDE.md. Claude will also discover CLAUDE.md nested in subtrees under your current working directory. Instead of loading them at launch, they are only included when Claude reads files in those subtrees.

Directly edit memories with /memory

Use the /memory slash command during a session to open any memory file in your system editor for more extensive additions or organization.

Set up project memory

Suppose you want to set up a CLAUDE.md file to store important project information, conventions, and frequently used commands. Project memory can be stored in either ./CLAUDE.md or ./.claude/CLAUDE.md. Bootstrap a CLAUDE.md for your codebase with the following command:

Modular rules with .claude/rules/

For larger projects, you can organize instructions into multiple files using the .claude/rules/ directory. This allows teams to maintain focused, well-organized rule files instead of one large CLAUDE.md.

Basic structure

Place markdown files in your project’s .claude/rules/ directory:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

All .md files in .claude/rules/ are automatically loaded as project memory, with the same priority as .claude/CLAUDE.md.

Path-specific rules

Rules can be scoped to specific files using YAML frontmatter with the paths field. These conditional rules only apply when Claude is working with files matching the specified patterns.

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

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

Rules without a paths field are loaded unconditionally and apply to all files.

Glob patterns

The paths field supports standard glob patterns:

You can use braces to match multiple patterns efficiently:

---
paths: src/**/*.{ts,tsx}
---

# TypeScript/React Rules

This expands to match both src/**/*.ts and src/**/*.tsx. You can also combine multiple patterns with commas:

---
paths: {src,lib}/**/*.ts, tests/**/*.test.ts
---

Subdirectories

Rules can be organized into subdirectories for better structure:

.claude/rules/
├── frontend/
│   ├── react.md
│   └── styles.md
├── backend/
│   ├── api.md
│   └── database.md
└── general.md

All .md files are discovered recursively.

Symlinks

The .claude/rules/ directory supports symlinks, allowing you to share common rules across multiple projects:

# Symlink a shared rules directory
ln -s ~/shared-claude-rules .claude/rules/shared

# Symlink individual rule files
ln -s ~/company-standards/security.md .claude/rules/security.md

Symlinks are resolved and their contents are loaded normally. Circular symlinks are detected and handled gracefully.

User-level rules

You can create personal rules that apply to all your projects in ~/.claude/rules/:

~/.claude/rules/
├── preferences.md    # Your personal coding preferences
└── workflows.md      # Your preferred workflows

User-level rules are loaded before project rules, giving project rules higher priority.

Organization-level memory management

Enterprise organizations can deploy centrally managed CLAUDE.md files that apply to all users. To set up organization-level memory management:

1. Create the enterprise memory file at the Enterprise policy location shown in the memory types table above.
2. Deploy via your configuration management system (MDM, Group Policy, Ansible, etc.) to ensure consistent distribution across all developer machines.

Memory best practices

• Be specific: “Use 2-space indentation” is better than “Format code properly”.
• Use structure to organize: Format each individual memory as a bullet point and group related memories under descriptive markdown headings.
• Review periodically: Update memories as your project evolves to ensure Claude is always using the most up to date information and context.