278 lines
8.5 KiB
Markdown
278 lines
8.5 KiB
Markdown
# Claude Code 记忆系统 — 使用指南
|
||
|
||
> 让 Claude Code 跨会话记住你是谁、你偏好什么、项目正在发生什么。
|
||
|
||
<p align="center">
|
||
<a href="#一什么是记忆系统">记忆系统</a> · <a href="#二四种记忆类型">四种记忆类型</a> · <a href="#三如何触发记忆保存">触发保存</a> · <a href="#四记忆存储在哪里">存储位置</a> · <a href="#五如何管理记忆">管理记忆</a> · <a href="#六记忆的生命周期">生命周期</a> · <a href="#七快速参考">快速参考</a>
|
||
</p>
|
||
|
||
|
||
|
||
---
|
||
|
||
## 一、什么是记忆系统？
|
||
|
||
Claude Code 的记忆系统是一套**基于文件的持久化知识库**，让 Claude 能够跨越多次对话，持续积累对你和你的项目的理解。
|
||
|
||
核心理念：**只记住无法从代码中推断出来的东西。**
|
||
|
||
| 记住 | 不记住 |
|
||
|------|--------|
|
||
| 你是数据科学家，关注日志系统 | 代码架构、文件结构 |
|
||
| "不要 mock 数据库" | Git 历史、谁改了什么 |
|
||
| 周四后冻结非关键合并 | 已有的 CLAUDE.md 内容 |
|
||
| Bug 跟踪在 Linear 的 INGEST 项目 | 调试方案（修复已在代码里） |
|
||
|
||
---
|
||
|
||
## 二、四种记忆类型
|
||
|
||
|
||
|
||
Claude Code 将记忆严格分为四类：
|
||
|
||
### 1. User（用户画像）
|
||
|
||
记录你的角色、目标、技能水平和偏好，帮助 Claude 调整协作方式。
|
||
|
||
```
|
||
用户说：我写了十年 Go，但这是第一次碰这个仓库的 React 部分
|
||
Claude 保存：深厚 Go 经验，React 新手 — 用后端类比解释前端概念
|
||
```
|
||
|
||
### 2. Feedback（行为反馈）
|
||
|
||
你对 Claude 工作方式的纠正或肯定。这类记忆让 Claude 不会犯同样的错。
|
||
|
||
```
|
||
用户说：别在回复末尾总结你做了什么，我能看 diff
|
||
Claude 保存：用户要求简洁回复，不要尾部摘要
|
||
```
|
||
|
||
**重要**：不只记录纠正，也记录肯定。如果 Claude 做了一个非显而易见的选择而你认可了，也会被记住。
|
||
|
||
### 3. Project（项目动态）
|
||
|
||
无法从代码或 Git 历史中推导出的项目上下文：谁在做什么、为什么、截止日期。
|
||
|
||
```
|
||
用户说：我们周四后冻结所有非关键合并，移动团队要切发布分支
|
||
Claude 保存：2026-03-05 起合并冻结，标记该日期后的非关键 PR 工作
|
||
```
|
||
|
||
**注意**：Claude 会将相对日期（"周四"）转换为绝对日期（"2026-03-05"），确保记忆不会过时失效。
|
||
|
||
### 4. Reference（外部引用）
|
||
|
||
指向外部系统中信息的指针：仪表板、工单系统、Slack 频道。
|
||
|
||
```
|
||
用户说：oncall 看的是 grafana.internal/d/api-latency 这个面板
|
||
Claude 保存：grafana.internal/d/api-latency 是 oncall 延迟仪表板 — 编辑请求路径代码时检查
|
||
```
|
||
|
||
---
|
||
|
||
## 三、如何触发记忆保存
|
||
|
||
|
||
|
||
### 方式一：自动提取（最常用）
|
||
|
||
这是最主要的方式。**你不需要做任何事情**，Claude 会在每次对话结束时自动分析对话内容，提取值得记住的信息。
|
||
|
||
工作流程：
|
||
1. 你和 Claude 正常对话
|
||
2. Claude 完成回复（没有工具调用时）
|
||
3. 后台启动一个**记忆提取子代理**
|
||
4. 子代理分析最近的对话内容
|
||
5. 识别出值得保存的记忆
|
||
6. 写入记忆文件 + 更新 MEMORY.md 索引
|
||
|
||
终端会显示通知：
|
||
```
|
||
Memory updated in ~/.claude/projects/.../memory/feedback_testing.md · /memory to edit
|
||
```
|
||
|
||
### 方式二：显式要求
|
||
|
||
直接告诉 Claude "记住这个"：
|
||
|
||
```
|
||
用户：记住，这个项目部署前必须运行 bun test
|
||
Claude：[立即保存为 feedback 类型记忆]
|
||
```
|
||
|
||
### 方式三：/memory 命令
|
||
|
||
在终端输入 `/memory` 命令，会打开一个文件选择器，让你在编辑器中直接编辑记忆文件。
|
||
|
||
```
|
||
> /memory
|
||
```
|
||
|
||
这会列出所有可编辑的记忆文件（CLAUDE.md、CLAUDE.local.md、auto-memory 等），选择后用你的 `$EDITOR` 或 `$VISUAL` 打开。
|
||
|
||
### 方式四：/remember 命令
|
||
|
||
输入 `/remember` 触发记忆审查技能，它会：
|
||
- 审查所有自动记忆条目
|
||
- 提议将合适的条目提升到 CLAUDE.md 或 CLAUDE.local.md
|
||
- 检测重复、过时和冲突的记忆
|
||
- **不会直接修改**，所有变更需要你批准
|
||
|
||
---
|
||
|
||
## 四、记忆存储在哪里？
|
||
|
||
### 目录结构
|
||
|
||
```
|
||
~/.claude/
|
||
└── projects/
|
||
└── {项目路径哈希}/
|
||
└── memory/ ← 自动记忆目录
|
||
├── MEMORY.md ← 索引文件（始终加载到上下文）
|
||
├── user_role.md ← 用户画像记忆
|
||
├── feedback_testing.md ← 行为反馈记忆
|
||
├── project_freeze.md ← 项目动态记忆
|
||
├── reference_linear.md ← 外部引用记忆
|
||
└── team/ ← 团队共享记忆（如启用）
|
||
├── MEMORY.md
|
||
└── ...
|
||
```
|
||
|
||
### 记忆文件格式
|
||
|
||
每个记忆文件使用 YAML frontmatter + Markdown 内容：
|
||
|
||
```markdown
|
||
---
|
||
name: 测试策略偏好
|
||
description: 集成测试必须使用真实数据库，不要 mock
|
||
type: feedback
|
||
---
|
||
|
||
集成测试必须使用真实数据库，不要 mock。
|
||
|
||
**Why:** 上季度 mock 测试通过但生产环境迁移失败，mock/生产差异掩盖了问题。
|
||
|
||
**How to apply:** 编写或审查测试时，确保数据库操作使用真实连接。
|
||
```
|
||
|
||
### MEMORY.md 索引文件
|
||
|
||
MEMORY.md 是索引而不是内容。它**始终加载到上下文**中，每行一个条目：
|
||
|
||
```markdown
|
||
- [用户角色](user_role.md) — 数据科学家，关注可观测性/日志
|
||
- [测试策略](feedback_testing.md) — 集成测试用真实数据库，不 mock
|
||
- [合并冻结](project_freeze.md) — 2026-03-05 起冻结非关键合并
|
||
- [Bug 追踪](reference_linear.md) — 流水线 bug 在 Linear INGEST 项目
|
||
```
|
||
|
||
**限制**：最多 200 行或 25KB，超出会被截断。
|
||
|
||
---
|
||
|
||
## 五、如何管理记忆
|
||
|
||
### 让 Claude 遗忘
|
||
|
||
```
|
||
用户：忘记关于合并冻结的记忆
|
||
Claude：[找到并删除相关记忆文件和索引条目]
|
||
```
|
||
|
||
### 让 Claude 忽略记忆
|
||
|
||
```
|
||
用户：忽略记忆，从零开始
|
||
Claude：[本次对话中不使用任何记忆内容]
|
||
```
|
||
|
||
### 手动编辑
|
||
|
||
直接编辑 `~/.claude/projects/{hash}/memory/` 下的文件，或使用 `/memory` 命令。
|
||
|
||
### 禁用自动记忆
|
||
|
||
| 方法 | 做法 |
|
||
|------|------|
|
||
| 环境变量 | `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` |
|
||
| 设置文件 | `settings.json` 中 `"autoMemoryEnabled": false` |
|
||
| 精简模式 | `--bare` 启动 / `CLAUDE_CODE_SIMPLE=1` |
|
||
|
||
### 自定义记忆目录
|
||
|
||
在 `~/.claude/settings.json` 中设置：
|
||
|
||
```json
|
||
{
|
||
"autoMemoryDirectory": "~/my-claude-memories"
|
||
}
|
||
```
|
||
|
||
支持 `~/` 展开。出于安全考虑，项目级 `.claude/settings.json` **不允许**设置此项。
|
||
|
||
---
|
||
|
||
## 六、记忆的生命周期
|
||
|
||
|
||
|
||
```
|
||
对话中学到新信息
|
||
↓
|
||
自动提取 / 显式保存
|
||
↓
|
||
写入记忆文件 + 索引
|
||
↓
|
||
下次对话加载 MEMORY.md
|
||
↓
|
||
智能选择相关记忆（Sonnet）
|
||
↓
|
||
注入到对话上下文
|
||
↓
|
||
记忆变旧？验证后再使用
|
||
↓
|
||
过时？更新或删除
|
||
↓
|
||
（24h + 5个会话后）
|
||
↓
|
||
AutoDream 后台整合记忆
|
||
```
|
||
|
||
### AutoDream —— "做梦"整理记忆
|
||
|
||
Claude Code 有一个隐藏的 **AutoDream** 功能，类比人类睡眠时大脑整理记忆的过程。当满足以下条件时，Claude 会在后台静默启动一个"做梦"子智能体：
|
||
|
||
- 距上次整合 **>= 24 小时**
|
||
- 期间积累了 **>= 5 个会话**
|
||
|
||
做梦过程分四阶段：定向 → 收集 → 整合 → 修剪。底部状态栏会显示 **"dreaming"**，你可以按 `Shift+Down` 查看进度，按 `x` 终止。
|
||
|
||
详细技术分析见 [AutoDream 记忆整合](./03-autodream.md)。
|
||
|
||
### 新鲜度管理
|
||
|
||
- **今天/昨天的记忆**：直接使用
|
||
- **超过 1 天的记忆**：附带陈旧警告，提醒 Claude 验证后再引用
|
||
- **引用文件路径/函数名的记忆**：使用前先 grep 确认还存在
|
||
|
||
---
|
||
|
||
## 七、快速参考
|
||
|
||
| 操作 | 方法 |
|
||
|------|------|
|
||
| 让 Claude 记住 | "记住：这个项目用 bun 不用 npm" |
|
||
| 让 Claude 忘记 | "忘记关于 XXX 的记忆" |
|
||
| 编辑记忆 | `/memory` 命令 |
|
||
| 审查和整理 | `/remember` 命令 |
|
||
| 忽略记忆 | "忽略记忆" / "不要用记忆" |
|
||
| 禁用自动记忆 | `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` |
|
||
| 禁用 AutoDream | `settings.json` 中 `"autoDreamEnabled": false` |
|
||
| 手动整合记忆 | `/dream` 命令 |
|
||
| 查看记忆目录 | `~/.claude/projects/{hash}/memory/` |
|