mirror of
https://github.com/NanmiCoder/cc-haha
synced 2026-07-17 13:13:35 +08:00
d306fd39aa
Add comprehensive documentation for the AutoDream ("dreaming") feature - Claude Code's
background memory consolidation mechanism that periodically reviews session history and
reorganizes memory files. Includes 3 architecture diagrams and updates to existing docs.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
317 lines
10 KiB
Markdown
317 lines
10 KiB
Markdown
# Claude Code 记忆系统 — AutoDream 记忆整合
|
||
|
||
> Claude 会"做梦"——在后台静默回顾近期会话，整合、更新、修剪记忆，就像人类睡眠中整理白天的记忆一样。
|
||
|
||
<p align="center">
|
||
<a href="#一什么是-autodream">AutoDream</a> · <a href="#二触发条件">触发条件</a> · <a href="#三四阶段整合流程">整合流程</a> · <a href="#四安全限制">安全限制</a> · <a href="#五ui-展示">UI 展示</a> · <a href="#六配置与开关">配置开关</a> · <a href="#七与-extractmemories-的关系">对比</a> · <a href="#八源码导航">源码导航</a>
|
||
</p>
|
||
|
||
|
||
|
||
---
|
||
|
||
## 一、什么是 AutoDream？
|
||
|
||
AutoDream 是 Claude Code 的 **后台记忆整合机制**，内部代号 **"Dream: Memory Consolidation"**。
|
||
|
||
核心隐喻：
|
||
|
||
| 人类 | Claude Code |
|
||
|------|-------------|
|
||
| 白天随手记笔记 | `extractMemories` — 每次对话后提取新记忆 |
|
||
| 晚上睡觉时整理笔记本 | `autoDream` — 定期回顾多个会话，整合全部记忆 |
|
||
|
||
当你不活跃时（默认间隔 24 小时、积累 5 个会话后），Claude 会在后台静默启动一个 **"做梦"子智能体**（forked subagent），回顾所有近期会话记录，将零散的记忆整合为结构化的、去重的、去过时的持久化知识。
|
||
|
||
**关键源码**：`src/services/autoDream/autoDream.ts`
|
||
|
||
```typescript
|
||
// Background memory consolidation. Fires the /dream prompt as a forked
|
||
// subagent when time-gate passes AND enough sessions have accumulated.
|
||
```
|
||
|
||
---
|
||
|
||
## 二、触发条件
|
||
|
||
|
||
|
||
AutoDream 采用 **五重门控** 机制，按开销从低到高逐级检查：
|
||
|
||
### 门控链
|
||
|
||
| 序号 | 门控 | 说明 | 开销 |
|
||
|------|------|------|------|
|
||
| 1 | **功能开关** | `isAutoDreamEnabled()` + 非 KAIROS + 非远程模式 + autoMemory 已启用 | 内存读取 |
|
||
| 2 | **时间门控** | 距上次整合 >= `minHours`（默认 24h） | 1 次 stat |
|
||
| 3 | **扫描节流** | 上次扫描后至少等 10 分钟再重新扫描 | 时间戳比较 |
|
||
| 4 | **会话门控** | 自上次整合后至少 `minSessions` 个新会话（默认 5 个，排除当前） | 目录扫描 |
|
||
| 5 | **锁门控** | 没有其他进程正在做梦（PID 锁文件） | stat + read |
|
||
|
||
**关键源码** `src/services/autoDream/autoDream.ts:63-66`：
|
||
|
||
```typescript
|
||
const DEFAULTS: AutoDreamConfig = {
|
||
minHours: 24, // 距离上次整合至少 24 小时
|
||
minSessions: 5, // 期间至少积累了 5 个会话
|
||
}
|
||
```
|
||
|
||
### 扫描节流
|
||
|
||
当时间门控通过但会话门控未通过时，锁文件的 mtime 不会更新，导致时间门控在后续每个 turn 都会通过。为避免频繁的目录扫描，设有 **10 分钟的扫描节流**：
|
||
|
||
```typescript
|
||
const SESSION_SCAN_INTERVAL_MS = 10 * 60 * 1000
|
||
```
|
||
|
||
### 执行入口
|
||
|
||
AutoDream 在每次 AI 回复完成后的 stop hook 阶段被触发（fire-and-forget，不阻塞主线程）：
|
||
|
||
**关键源码** `src/query/stopHooks.ts:154-156`：
|
||
|
||
```typescript
|
||
if (!toolUseContext.agentId) {
|
||
void executeAutoDream(stopHookContext, toolUseContext.appendSystemMessage)
|
||
}
|
||
```
|
||
|
||
### 阻止条件
|
||
|
||
以下情况不会触发 AutoDream：
|
||
|
||
- **KAIROS 模式**：使用独立的 disk-skill dream
|
||
- **远程模式**：`getIsRemoteMode() === true`
|
||
- **autoMemory 未启用**
|
||
- **`--bare` / SIMPLE 模式**
|
||
- **子代理内**：只有主代理才触发
|
||
|
||
---
|
||
|
||
## 三、四阶段整合流程
|
||
|
||
|
||
|
||
一旦所有门控通过，AutoDream 启动一个 **分叉子智能体**，按照 `consolidationPrompt.ts` 定义的 4 阶段提示词工作：
|
||
|
||
### Phase 1 — Orient（定向）
|
||
|
||
```
|
||
- ls 记忆目录，查看已有文件
|
||
- 读取 MEMORY.md 索引，理解当前知识结构
|
||
- 浏览现有主题文件，避免创建重复
|
||
- 如存在 logs/ 或 sessions/ 子目录，检查最近条目
|
||
```
|
||
|
||
### Phase 2 — Gather recent signal（收集近期信号）
|
||
|
||
按优先级从高到低搜集信息：
|
||
|
||
1. **Daily logs** — `logs/YYYY/MM/YYYY-MM-DD.md`（追加流日志）
|
||
2. **漂移的记忆** — 与代码库现状矛盾的旧事实
|
||
3. **会话记录搜索** — 用 `grep` 在 JSONL 转录文件中窄范围检索
|
||
|
||
```
|
||
不要穷尽读取转录文件。只查找你已经怀疑重要的内容。
|
||
```
|
||
|
||
### Phase 3 — Consolidate（整合）
|
||
|
||
- **合并**新信号到已有主题文件（而非创建新的近似文件）
|
||
- **转换**相对日期为绝对日期（"昨天" → "2026-04-03"）
|
||
- **删除**被推翻的旧事实
|
||
|
||
### Phase 4 — Prune and index（修剪与索引）
|
||
|
||
- 更新 `MEMORY.md`，保持 ≤ 规定行数且 ≤ 25KB
|
||
- 删除指向过时记忆的指针
|
||
- 压缩冗长条目（>200 字符的索引行，将内容移入主题文件）
|
||
- 新增指向重要记忆的指针
|
||
- 解决矛盾（两个文件意见不一致时，修复错误的那个）
|
||
|
||
**关键源码** `src/services/autoDream/consolidationPrompt.ts:10-64`
|
||
|
||
---
|
||
|
||
## 四、安全限制
|
||
|
||
AutoDream 子智能体受到严格的工具权限限制：
|
||
|
||
### Bash 仅限只读
|
||
|
||
```
|
||
允许：ls, find, grep, cat, stat, wc, head, tail
|
||
拒绝：所有写入、重定向、修改状态的命令
|
||
```
|
||
|
||
### 文件操作仅限记忆目录
|
||
|
||
`createAutoMemCanUseTool()` 是 `extractMemories` 和 `autoDream` 共享的权限函数：
|
||
|
||
```
|
||
允许 Read / Grep / Glob — 无限制
|
||
允许 Edit / Write — 仅 auto-memory 目录内
|
||
拒绝 MCP / Agent / 非只读 Bash / 其他写操作
|
||
```
|
||
|
||
**关键源码** `src/services/extractMemories/extractMemories.ts:167-171`
|
||
|
||
### 锁文件机制
|
||
|
||
使用 `.consolidate-lock` 文件实现进程级互斥：
|
||
|
||
| 机制 | 说明 |
|
||
|------|------|
|
||
| **锁内容** | 持有者 PID |
|
||
| **时间戳** | 锁文件 mtime = 上次整合时间 |
|
||
| **过期** | 持有超过 1 小时视为过期（防 PID 复用） |
|
||
| **竞争** | 两个进程同时写入 → 最后写入者获胜，失败者在 re-read 时退出 |
|
||
| **回滚** | 失败时回退 mtime 到获取前的值，让下次尝试不受影响 |
|
||
| **崩溃恢复** | mtime 卡住 + 死 PID → 下个进程回收锁 |
|
||
|
||
**关键源码** `src/services/autoDream/consolidationLock.ts`
|
||
|
||
---
|
||
|
||
## 五、UI 展示
|
||
|
||
### 底部状态栏
|
||
|
||
当 AutoDream 运行时，底部状态栏会显示 **"dreaming"** 标签：
|
||
|
||
```typescript
|
||
// src/tasks/pillLabel.ts:61-62
|
||
case 'dream':
|
||
return 'dreaming'
|
||
```
|
||
|
||
### 任务详情对话框
|
||
|
||
用户按 `Shift+Down` 可打开后台任务对话框，查看梦境的实时进度：
|
||
|
||
- **DreamDetailDialog** 组件展示：
|
||
- 正在回顾的会话数量
|
||
- 当前阶段：`starting`（正在分析）→ `updating`（正在修改记忆文件）
|
||
- 最近的助手文本响应和工具调用次数
|
||
- 已触碰的文件路径列表
|
||
|
||
- **用户可按 `x` 键终止**正在进行的梦境（触发 abort + 锁回滚）
|
||
|
||
### 完成通知
|
||
|
||
梦境完成后，如果有文件被修改，会在主会话中显示内联通知：
|
||
|
||
```typescript
|
||
appendSystemMessage({
|
||
...createMemorySavedMessage(dreamState.filesTouched),
|
||
verb: 'Improved',
|
||
})
|
||
```
|
||
|
||
**关键源码**：
|
||
- `src/tasks/DreamTask/DreamTask.ts` — 任务状态管理
|
||
- `src/components/tasks/DreamDetailDialog.tsx` — UI 组件
|
||
|
||
---
|
||
|
||
## 六、配置与开关
|
||
|
||
### settings.json
|
||
|
||
```json
|
||
{
|
||
"autoDreamEnabled": true
|
||
}
|
||
```
|
||
|
||
- **显式设置时**：直接使用用户的值
|
||
- **未设置时**：由远程 GrowthBook feature flag `tengu_onyx_plover` 控制
|
||
|
||
**关键源码** `src/services/autoDream/config.ts:13-21`：
|
||
|
||
```typescript
|
||
export function isAutoDreamEnabled(): boolean {
|
||
const setting = getInitialSettings().autoDreamEnabled
|
||
if (setting !== undefined) return setting
|
||
const gb = getFeatureValue_CACHED_MAY_BE_STALE<{ enabled?: unknown } | null>(
|
||
'tengu_onyx_plover', null,
|
||
)
|
||
return gb?.enabled === true
|
||
}
|
||
```
|
||
|
||
### 远程配置参数
|
||
|
||
`tengu_onyx_plover` feature flag 可配置：
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `enabled` | boolean | — | 功能总开关 |
|
||
| `minHours` | number | 24 | 最小间隔（小时） |
|
||
| `minSessions` | number | 5 | 最小会话数 |
|
||
|
||
### 手动触发 `/dream`
|
||
|
||
除了自动触发，用户可以通过 `/dream` 命令手动触发记忆整合。手动触发会调用 `recordConsolidation()` 更新锁文件时间戳。
|
||
|
||
---
|
||
|
||
## 七、与 extractMemories 的关系
|
||
|
||
| 维度 | extractMemories | autoDream |
|
||
|------|----------------|-----------|
|
||
| **触发频率** | 每次对话回合结束 | 每 24h + 5 个会话 |
|
||
| **触发位置** | `stopHooks.ts` L149 | `stopHooks.ts` L155 |
|
||
| **处理范围** | 当前对话最近的消息 | 多个会话的历史记录 |
|
||
| **目标** | 提取新记忆 | 整合/去重/修剪已有记忆 |
|
||
| **人类类比** | 白天随手记笔记 | 睡觉时整理笔记本 |
|
||
| **共享组件** | `createAutoMemCanUseTool` | `createAutoMemCanUseTool` |
|
||
| **分叉代理** | 最多 5 turns | 无 turn 限制 |
|
||
| **转录** | 不记录（`skipTranscript`） | 不记录（`skipTranscript`） |
|
||
|
||
### 协作流
|
||
|
||
```
|
||
每次对话结束
|
||
↓
|
||
extractMemories → 提取新记忆片段 → 写入 *.md + MEMORY.md
|
||
↓
|
||
（积累 24h + 5个会话后）
|
||
↓
|
||
autoDream → 回顾所有记忆 + 会话记录
|
||
↓
|
||
合并重复 / 修正过时 / 删除矛盾 / 压缩索引
|
||
↓
|
||
MEMORY.md 和主题文件焕然一新
|
||
```
|
||
|
||
---
|
||
|
||
## 八、源码导航
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `src/services/autoDream/autoDream.ts` | 主逻辑：门控检查、启动分叉代理、进度监控 |
|
||
| `src/services/autoDream/config.ts` | 开关控制：settings.json 或 GrowthBook |
|
||
| `src/services/autoDream/consolidationPrompt.ts` | 梦境提示词：4 阶段整合工作流 |
|
||
| `src/services/autoDream/consolidationLock.ts` | 锁文件机制：防并发、时间戳、回滚 |
|
||
| `src/tasks/DreamTask/DreamTask.ts` | UI 任务注册：状态管理、终止、回滚 |
|
||
| `src/tasks/pillLabel.ts` | 底部状态栏标签："dreaming" |
|
||
| `src/components/tasks/DreamDetailDialog.tsx` | 梦境详情对话框 UI |
|
||
| `src/query/stopHooks.ts` | 执行入口：每次回复后触发 |
|
||
| `src/utils/backgroundHousekeeping.ts` | 初始化入口：`initAutoDream()` |
|
||
| `src/services/extractMemories/extractMemories.ts` | 共享的 `createAutoMemCanUseTool` |
|
||
|
||
---
|
||
|
||
## 九、分析事件
|
||
|
||
AutoDream 通过以下事件记录运行状态：
|
||
|
||
| 事件 | 时机 | 附带数据 |
|
||
|------|------|----------|
|
||
| `tengu_auto_dream_fired` | 梦境启动 | `hours_since`, `sessions_since` |
|
||
| `tengu_auto_dream_completed` | 梦境完成 | `cache_read`, `cache_created`, `output`, `sessions_reviewed` |
|
||
| `tengu_auto_dream_failed` | 梦境失败 | — |
|