<picture>
  <source media="(prefers-color-scheme: dark)" srcset="../../resources/logos/claude-howto-logo-dark.svg">
  <img alt="Claude How To" src="../../resources/logos/claude-howto-logo.svg">
</picture>

# Memory 指南

## 概览

Memory 让 Claude Code 在不同会话之间保留上下文。你可以把团队规范、项目规则、个人偏好和目录级约束写进 `CLAUDE.md`，让 Claude 在合适的时候自动加载。

## Memory 命令速查

| 命令 | 作用 |
|------|------|
| `/init` | 初始化项目级 `CLAUDE.md` |
| `/memory` | 打开并编辑记忆文件 |
| `#` | 快速把当前规则写入 memory |

## 快速上手：初始化 Memory

### 使用 `/init`

在项目目录中运行：

```bash
/init
```

Claude 会根据当前项目生成一个 `CLAUDE.md`，通常包含类似如下结构：

```md
# 项目配置
## 项目概览
## 开发规范
```

### 使用 `#` 快速更新记忆

当你想把一句规则写入 memory 时，可以直接在输入前加 `#`：

```text
# 这个项目始终使用 TypeScript 严格模式
# 优先使用 async/await，而不是 promise 链
# 每次提交前都运行 npm test
# 文件名统一使用 kebab-case
```

这会把规则加入当前会话能感知到的记忆中。

### 使用 `/memory`

`/memory` 会打开记忆编辑器，让你在不同范围之间切换：

1. 受管策略记忆
2. 项目记忆（`./CLAUDE.md`）
3. 用户记忆（`~/.claude/CLAUDE.md`）
4. 本地项目记忆

适合你把长期规则、项目规范和个人偏好分层管理。

## Memory 架构

Claude Code 的记忆系统通常有以下层级：

| 层级 | 作用范围 | 典型内容 |
|------|----------|----------|
| 受管策略 | 组织级 | 合规、安全、统一流程 |
| 项目记忆 | 单个项目 | 架构、编码标准、工作流 |
| 目录记忆 | 子目录 | 模块约束、局部规范 |
| 用户记忆 | 单个用户 | 个人偏好、默认设置 |

## 记忆层级

Claude 会按更接近当前上下文的规则优先使用更具体的 memory。一般来说：

- 组织级规则优先于普通偏好
- 项目规则优先于个人偏好
- 目录级规则优先于项目级通用规则

## 排除规则

如果某些 `CLAUDE.md` 不应该被自动加载，可以通过 `claudeMdExcludes` 之类的设置排除。

## 配置文件层级

项目设置、用户设置和企业托管设置会共同影响 memory 的加载方式。你可以把它理解为：

1. 组织策略
2. 项目设置
3. 本地设置
4. 临时会话输入

## 模块化规则系统

Memory 不一定要写成一个巨大文件。你可以把规则拆成多个目录文件，再按路径组织。

### 通过 YAML frontmatter 设置路径规则

```md
---
description: API development rules
---

# API Development Rules
```

### 子目录与符号链接

你可以用子目录和 symlink 把局部规则复用到多个项目区域。

## Memory 位置表

常见位置包括：

- 项目根目录的 `CLAUDE.md`
- 用户目录的 `~/.claude/CLAUDE.md`
- 子目录的 `CLAUDE.md`

## Memory 更新生命周期

一般流程是：

1. 创建或编辑 `CLAUDE.md`
2. Claude 重新加载
3. 新规则在后续会话中生效

## Auto Memory

Auto memory 让 Claude 根据当前目录自动寻找并加载合适的记忆文件。

### 工作方式

Claude 会根据当前工作目录、父目录和已配置路径，逐层查找相关 memory。

### 目录结构

```text
project/
├── CLAUDE.md
├── src/
│   ├── CLAUDE.md
│   └── api/
│       └── CLAUDE.md
```

### 版本要求

某些 auto memory 行为依赖较新的 Claude Code 版本。

### 自定义 auto memory 目录

如果默认目录不适合你的项目，可以在设置中指定新的 memory 路径。

### worktree 和仓库共享

在 worktree、monorepo 或多人协作场景中，auto memory 可以帮助保持规则一致。

### Subagent 记忆

Subagents 也可以拥有自己的记忆范围，用于在各自职责内保持一致性。

### 控制 auto memory

```bash
# 当前会话禁用 auto memory

# 显式开启 auto memory
```

## 通过 `--add-dir` 添加额外目录

你可以用 `--add-dir` 把额外目录也加入 Claude 的可见范围，适合多目录协作。

## 实战示例

### 示例 1：项目记忆结构

```md
# 项目配置
## 项目概览
## 架构
## 开发规范
### 代码风格
### 命名约定
### Git 工作流
### 测试要求
### API 规范
### 数据库
### 部署
## 常用命令
## 团队联系人
## 已知问题与解决办法
## 相关项目
```

### 示例 2：目录级记忆

```md
# API 模块规范
## API 专属规范
### 请求校验
### 身份验证
### 响应格式
### 分页
### 限流
### 缓存
```

### 示例 3：个人记忆

```md
# 我的开发偏好
## 关于我
## 代码偏好
### 错误处理
### 注释
### 测试
### 架构
## 调试偏好
## 沟通方式
## 项目组织
## 工具链
```

### 示例 4：会话中更新记忆

两种常见方式：

1. 直接提要求，让 Claude 把规则写进 memory
2. 使用 `# new rule into memory` 这种模式追加规则

## 最佳实践

### 应该做的

- 用项目记忆保存团队标准
- 用目录记忆保存局部差异
- 先写简洁规则，再逐步补充
- 把可重复内容写进 `CLAUDE.md`

### 不应该做的

- 不要把 README 整份复制进 `CLAUDE.md`
- 不要把明显属于代码的实现细节硬塞进 memory
- 不要让 memory 变成垃圾桶

### 记忆管理建议

- 优先引用已有文档，而不是重复粘贴
- 只保留真正影响 Claude 行为的信息
- 定期整理过期或冲突的规则

## 安装说明

### 设置项目记忆

#### 方法 1：使用 `/init`（推荐）

```bash
/init
```

#### 方法 2：手动创建

```bash
cp project-CLAUDE.md CLAUDE.md
```

#### 方法 3：快速更新

```text
# Use semantic versioning for all releases
# Always run tests before committing
# Prefer composition over inheritance
```

### 设置个人记忆

```bash
cp personal-CLAUDE.md ~/.claude/CLAUDE.md
```

### 设置目录记忆

```bash
cp directory-api-CLAUDE.md src/api/CLAUDE.md
```

### 验证安装

- 重新打开 Claude Code 会话
- 检查 `CLAUDE.md` 是否被自动加载
- 用一条明显会受 memory 影响的提示词测试

## 官方文档

如果你想看更详细的行为定义、兼容性和最新限制，建议参考 Claude Code 官方 memory 文档。

## 相关概念

- [Slash Commands 中文参考](../01-slash-commands/README.md)
- [Skills 中文指南](../03-skills/README.md)
- [Subagents 中文参考](../04-subagents/README.md)
- [Advanced Features 中文指南](../09-advanced-features/README.md)
