# 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 |¶
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |¶
| **EnterpriseManaged policy** | • macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br />• Linux: `/etc/claude-code/CLAUDE.md`<br />• 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.¶
¶
<Note>¶
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.¶
</Note>¶
¶
## 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` 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¶
```¶
¶
<Tip>¶
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.¶
</Tip>¶
¶
## 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.¶
¶
```markdown theme={null}¶
---¶
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 specify multiple patterns:¶
¶
```markdown theme={null}¶
---¶
paths:¶
- "src/**/*.ts"¶
- "lib/**/*.ts"¶
- "tests/**/*.test.ts"¶
---¶
```¶
¶
Brace expansion is supported for matching multiple extensions or directories:¶
¶
```markdown theme={null}¶
---¶
paths:¶
- "src/**/*.{ts,tsx}"¶
- "{src,lib}/**/*.ts"¶
---¶
¶
# TypeScript/React Rules¶
```¶
¶
This expands `src/**/*.{ts,tsx}` to match both `.ts` and `.tsx` files.¶
¶
### 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:¶
¶
```bash theme={null}¶
# 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.¶
¶
<Tip>¶
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/`)¶
</Tip>¶
¶
## Organization-level memory management¶
¶
Organizations can deploy centrally managed CLAUDE.md files that apply to all users.¶
¶
To set up organization-level memory management:¶
¶
1. Create the managed memory file at the **Managed policy** location shown in the [memory types table above](#determine-memory-type).¶
¶
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