# Claude Code Memory and rules

> How Claude Code reads CLAUDE.md, auto memory, and .claude/rules, with compatibility guidance for AGENTS.md projects.

URL: https://docs.passion8.cc/en/docs/claude-code/memory
Language: en
Publisher: Passion8

Each Claude Code session starts with a new context window. Two mechanisms preserve project knowledge: the `CLAUDE.md` instructions you maintain and the auto memory Claude accumulates.

## CLAUDE.md and auto memory

| Mechanism | Author | Contents | Best for |
| --- | --- | --- | --- |
| `CLAUDE.md` | You or your team | Explicit instructions, directories, commands, conventions | Verifiable long-term rules |
| Auto memory | Claude | Patterns learned from corrections | Recurring preferences and project experience |

Both are context, not enforced permissions. Use [permission rules](https://docs.passion8.cc/en/docs/claude-code/permissions) or [hooks](https://docs.passion8.cc/en/docs/claude-code/hooks) to enforce restrictions.

## File locations

| Scope | Location | Purpose |
| --- | --- | --- |
| Managed policy | macOS `/Library/Application Support/ClaudeCode/CLAUDE.md`, Linux `/etc/claude-code/CLAUDE.md`, Windows `C:\Program Files\ClaudeCode\CLAUDE.md` | Organization instructions |
| User | `~/.claude/CLAUDE.md` | Personal preferences across projects |
| Project | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Shared project rules |
| Local | `./CLAUDE.local.md` | Private project-specific rules; add to gitignore |
| Rules | `./.claude/rules/*.md` | Modular rules, optionally loaded by path |

Claude searches upward from the current directory for `CLAUDE.md` and `CLAUDE.local.md`. Content closer to the working directory enters context later and is more specific. Subdirectory `CLAUDE.md` files load as Claude reads relevant files.

## Recommended structure

```text
your-project/
├── CLAUDE.md
└── .claude/
    ├── settings.json
    └── rules/
        ├── testing.md
        ├── api.md
        └── frontend.md
```

Use `CLAUDE.md` for the overall structure:

```markdown title="CLAUDE.md"
# Project conventions

- Package manager: pnpm
- Run `pnpm lint` after changes, and `pnpm typecheck` for type-related changes
- Do not put .env files, keys, or production configuration in documentation or commits

## Directories

- Pages: `src/app`
- Components: `src/components`
- Documentation: `content/docs`

## Working process

- Propose a plan before large changes
- Check light and dark modes after UI changes
- Include validation commands in the final report
```

## Shorter rules are easier to follow

Aim for fewer than 200 lines. Long files consume context and are more likely to contain contradictions.

Effective rules tend to be:

- Specific: say `pnpm lint`, not “run necessary checks.”
- Verifiable: say “do not commit `.env`,” not “be careful with security.”
- Organized by topic: separate build, testing, directories, and style.




If a rule applies only to certain directories, put it in `.claude/rules/` with `paths` instead of adding it to the root `CLAUDE.md`.




## Import other files

`CLAUDE.md` supports `@path` imports. Relative paths resolve from the containing `CLAUDE.md` directory, with up to four levels of recursive imports.

```markdown title="CLAUDE.md"
@README.md
@docs/development.md

## Claude Code additions

- Prefer existing components
- Avoid unrelated refactoring
```

To display the string literally, wrap it in backticks, such as `` `@README.md` ``.

The first import of a file outside the project requires confirmation. A rejected import does not automatically prompt again; adjust it manually if needed.

## Projects using AGENTS.md

For installations using `CLAUDE.md` rather than native `AGENTS.md` loading, an existing `AGENTS.md` can be imported:

```markdown title="CLAUDE.md"
@AGENTS.md

## Claude Code

- Use plan mode before broad changes
- Check mobile, light, and dark layouts after UI changes
```

A symlink is another option, but the `@AGENTS.md` import is easier on Windows. Check the current official memory documentation for your version's native AGENTS.md support before keeping both mechanisms enabled.

## .claude/rules/

Rule files provide more granular `CLAUDE.md` guidance. Rules without frontmatter load at startup:

```markdown title=".claude/rules/testing.md"
# Testing rules

- Run the relevant unit tests after fixing a bug
- Do not skip failing tests
```

Rules with `paths` load when matching files are accessed:

```markdown title=".claude/rules/api.md"
---
paths:
  - "src/api/**/*.ts"
  - "app/api/**/*.ts"
---

# API rules

- Validate all inputs
- Return a consistent `{ code, message }` error shape
- Never put server secrets in the client bundle
```

This is especially useful in large repositories, reducing irrelevant context and cache invalidation.

## Auto memory

Auto memory records lessons Claude learns from corrections and shares them across sessions for a repository. It is useful for project-specific experience such as build commands, test prerequisites, and recurring failure causes.

Common controls:

| Need | Action |
| --- | --- |
| Temporarily disable auto memory | Set `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` |
| Diagnose why memory did not apply | Inspect loaded content with `/context` |
| Make a class of rules more reliable | Promote it from auto memory to `CLAUDE.md` |

## Troubleshooting

| Symptom | Possible cause | Check |
| --- | --- | --- |
| Current session ignores a CLAUDE.md edit | Root instructions were loaded at startup | `/clear`, `/compact`, or restart |
| Subdirectory rule does not apply | Claude has not read a matching file | Explicitly reference it with `@file` |
| Rules conflict | Multiple instruction files overlap | Inspect load order in `/context` |
| AGENTS.md does not apply | Version or configuration does not load it natively | Use a CLAUDE.md import or check native support |
| Too many rules in a large repository | Instructions fill the context | Split into path-scoped rules |

## Official references

- [How Claude remembers your project](https://code.claude.com/docs/en/memory.md)
- [Explore the .claude directory](https://code.claude.com/docs/en/claude-directory.md)
- [Debug your configuration](https://code.claude.com/docs/en/debug-your-config.md)