Manage Claude’s memory

Learn how to manage Claude Code’s memory across sessions with different memory locations and best practices.

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:

Memory Type	Location	Purpose	Use Case Examples	Shared With
Enterprise policy	• macOS: /Library/Application Support/ClaudeCode/CLAUDE.md • Linux: /etc/claude-code/CLAUDE.md • Windows: C:\Program Files\ClaudeCode\CLAUDE.md	Organization-wide instructions managed by IT/DevOps	Company coding standards, security policies, compliance requirements	All users in organization
Project memory	./CLAUDE.md or ./.claude/CLAUDE.md	Team-shared instructions for the project	Project architecture, coding standards, common workflows	Team members via source control
Project rules	./.claude/rules/*.md	Modular, topic-specific project instructions	Language-specific guidelines, testing conventions, API standards	Team members via source control
User memory	~/.claude/CLAUDE.md	Personal preferences for all projects	Code styling preferences, personal tooling shortcuts	Just you (all projects)
Project memory (local)	./CLAUDE.local.md	Personal project-specific preferences	Your sandbox URLs, preferred test data	Just you (current project)

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.local.md files are automatically added to .gitignore, making them ideal for private project-specific preferences that shouldn't be checked into version control.

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:

> /init

Tips:

• Include frequently used commands (build, test, lint) to avoid repeated searches
• Document code style preferences and naming conventions
• Add important architectural patterns specific to your project
• CLAUDE.md memories can be used for both instructions shared with your team and for your individual preferences.

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:

Pattern	Matches
**/*.ts	All TypeScript files in any directory
src/**/*	All files under src/ directory
*.md	Markdown files in the project root
src/components/*.tsx	React components in a specific directory

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.

Best practices for `.claude/rules/`:

• Keep rules focused: Each file should cover one topic (e.g., testing.md, api-design.md)
• Use descriptive filenames: The filename should indicate what the rules cover
• Use conditional rules sparingly: Only add paths frontmatter when rules truly apply to specific file types
• Organize with subdirectories: Group related rules (e.g., frontend/, backend/)

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.

---

To find navigation and other pages in this documentation, fetch the llms.txt file at: https://code.claude.com/docs/llms.txt