mirror of
https://github.com/nicepkg/ai-workflow.git
synced 2026-11-18 18:04:23 +00:00
212 lines
9.0 KiB
Markdown
212 lines
9.0 KiB
Markdown
---
|
||
source: https://code.claude.com/docs/en/memory
|
||
title: Manage Claude's memory
|
||
---
|
||
|
||
Claude Code can remember your preferences across sessions, like style guidelines and common commands in your workflow.
|
||
|
||
## [](#determine-memory-type) 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 imports
|
||
|
||
CLAUDE.md files can import additional files using `@path/to/import` syntax. The following example imports 3 files:
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
# Individual Preferences
|
||
- @~/.claude/my-project-instructions.md
|
||
```
|
||
|
||
To avoid potential collisions, imports are not evaluated inside markdown code spans and code blocks.
|
||
|
||
```bash
|
||
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) 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) 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) 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:
|
||
|
||
```bash
|
||
> /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/) 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) Basic structure
|
||
|
||
Place markdown files in your project’s `.claude/rules/` directory:
|
||
|
||
```bash
|
||
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) 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.
|
||
|
||
```bash
|
||
---
|
||
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) 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:
|
||
|
||
```bash
|
||
---
|
||
paths:
|
||
- "src/**/*.ts"
|
||
- "lib/**/*.ts"
|
||
- "tests/**/*.test.ts"
|
||
---
|
||
```
|
||
|
||
Brace expansion is supported for matching multiple extensions or directories:
|
||
|
||
```bash
|
||
---
|
||
paths:
|
||
- "src/**/*.{ts,tsx}"
|
||
- "{src,lib}/**/*.ts"
|
||
---
|
||
|
||
# TypeScript/React Rules
|
||
```
|
||
|
||
This expands `src/**/*.{ts,tsx}` to match both `.ts` and `.tsx` files.
|
||
|
||
### [](#subdirectories) Subdirectories
|
||
|
||
Rules can be organized into subdirectories for better structure:
|
||
|
||
```bash
|
||
.claude/rules/
|
||
├── frontend/
|
||
│ ├── react.md
|
||
│ └── styles.md
|
||
├── backend/
|
||
│ ├── api.md
|
||
│ └── database.md
|
||
└── general.md
|
||
```
|
||
|
||
All `.md` files are discovered recursively.
|
||
|
||
### [](#symlinks) Symlinks
|
||
|
||
The `.claude/rules/` directory supports symlinks, allowing you to share common rules across multiple projects:
|
||
|
||
```bash
|
||
# 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) User-level rules
|
||
|
||
You can create personal rules that apply to all your projects in `~/.claude/rules/`:
|
||
|
||
```bash
|
||
~/.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) 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) 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. |