# Memory (CLAUDE.md)

> 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.

## Memory Types

Claude Code offers four memory locations in a hierarchical structure:

| Memory Type            | Location                                                                                             | Purpose                                             | Use Case Examples                                                    | Shared With                     |
| :--------------------- | :--------------------------------------------------------------------------------------------------- | :-------------------------------------------------- | :------------------------------------------------------------------- | :------------------------------ |
| **Managed 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 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.

**Note**: `CLAUDE.local.md` files are automatically added to `.gitignore`, making them ideal for private project-specific preferences.

## CLAUDE.md Imports

CLAUDE.md files can import additional files using `@path/to/import` syntax:

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

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

Both relative and absolute paths are allowed. Importing files from the user's home directory allows team members to provide individual instructions not checked into the repository:

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

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

```markdown
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.

## How Claude Looks Up Memories

Claude Code reads memories recursively: starting in the cwd, it recurses up to (but not including) the root directory `/` and reads any `CLAUDE.md` or `CLAUDE.local.md` files it finds.

This is convenient for 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.

## Setting Up Project Memory

Bootstrap a CLAUDE.md for your codebase:
```
> /init
```

Or directly edit with:
```
> /memory
```

### Tips for Project Memory
- 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
- Can be used for both instructions shared with your team and individual preferences

## Modular Rules with .claude/rules/

For larger projects, organize instructions into multiple files using the `.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:

```markdown
---
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.

### 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 |

Multiple patterns:
```markdown
---
paths:
  - "src/**/*.ts"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---
```

Brace expansion:
```markdown
---
paths:
  - "src/**/*.{ts,tsx}"
  - "{src,lib}/**/*.ts"
---
```

### Subdirectories

Rules can be organized into subdirectories:
```
.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 for sharing common rules across 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
```

### User-Level Rules

Create personal rules 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/`)

### General Memory Best Practices
- **Be specific**: "Use 2-space indentation" is better than "Format code properly"
- **Use structure**: Format each individual memory as a bullet point and group related memories under descriptive markdown headings
- **Review periodically**: Update memories as your project evolves

## Organization-Level Memory Management

Organizations can deploy centrally managed CLAUDE.md files:

1. Create the managed memory file at the **Managed policy** location
2. Deploy via your configuration management system (MDM, Group Policy, Ansible, etc.)

## Grid Integration Opportunities

<!-- Placeholder for Grid-specific integration notes -->