diff --git a/docs/memory/01-usage-guide.md b/docs/memory/01-usage-guide.md index 92e2349c..225f7dbe 100644 --- a/docs/memory/01-usage-guide.md +++ b/docs/memory/01-usage-guide.md @@ -237,8 +237,23 @@ Claude：[本次对话中不使用任何记忆内容] 记忆变旧？验证后再使用 ↓ 过时？更新或删除 + ↓ + （24h + 5个会话后） + ↓ + AutoDream 后台整合记忆 ``` +### AutoDream —— "做梦"整理记忆 + +Claude Code 有一个隐藏的 **AutoDream** 功能，类比人类睡眠时大脑整理记忆的过程。当满足以下条件时，Claude 会在后台静默启动一个"做梦"子智能体： + +- 距上次整合 **>= 24 小时** +- 期间积累了 **>= 5 个会话** + +做梦过程分四阶段：定向 → 收集 → 整合 → 修剪。底部状态栏会显示 **"dreaming"**，你可以按 `Shift+Down` 查看进度，按 `x` 终止。 + +详细技术分析见 [AutoDream 记忆整合](./03-autodream.md)。 + ### 新鲜度管理 - **今天/昨天的记忆**：直接使用 @@ -257,4 +272,6 @@ Claude：[本次对话中不使用任何记忆内容] | 审查和整理 | `/remember` 命令 | | 忽略记忆 | "忽略记忆" / "不要用记忆" | | 禁用自动记忆 | `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` | +| 禁用 AutoDream | `settings.json` 中 `"autoDreamEnabled": false` | +| 手动整合记忆 | `/dream` 命令 | | 查看记忆目录 | `~/.claude/projects/{hash}/memory/` | diff --git a/docs/memory/02-implementation.md b/docs/memory/02-implementation.md index af5e23c5..c6e1c542 100644 --- a/docs/memory/02-implementation.md +++ b/docs/memory/02-implementation.md @@ -26,6 +26,7 @@ | 模块 | 源码位置 | 职责 | |------|----------|------| +| **AutoDream** | `src/services/autoDream/` | 后台记忆整合（"做梦"），详见 [03-autodream.md](./03-autodream.md) | | **类型定义** | `src/memdir/memoryTypes.ts` | 四种记忆类型的分类法和提示词模板 | | **新鲜度** | `src/memdir/memoryAge.ts` | 计算记忆年龄、生成陈旧警告 | | **文件检测** | `src/utils/memoryFileDetection.ts` | 判断路径是否属于记忆系统 | @@ -453,5 +454,19 @@ maxTurns = 5 // 分叉代理最多 5 个 turn │ → runForkedAgent() [共享缓存, 限制工具, 5 turns] │ │ → 写入新记忆文件 + 更新 MEMORY.md │ │ → 通知用户 │ +└────────────────────────┬────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────┐ +│ 后台记忆整合（AutoDream） │ +│ │ +│ executeAutoDream() [每 24h + 5个会话触发] │ +│ → 五重门控检查（开关/时间/节流/会话/锁） │ +│ → buildConsolidationPrompt() │ +│ → runForkedAgent() [只读 Bash, 仅记忆目录写入] │ +│ → 四阶段：定向 → 收集 → 整合 → 修剪 │ +│ → 合并重复 / 修正过时 / 压缩索引 │ +│ → 通知用户："Improved N memories" │ +│ │ +│ 详见 03-autodream.md │ └─────────────────────────────────────────────────────┘ ``` diff --git a/docs/memory/03-autodream.md b/docs/memory/03-autodream.md new file mode 100644 index 00000000..c58f817b --- /dev/null +++ b/docs/memory/03-autodream.md @@ -0,0 +1,316 @@ +# Claude Code 记忆系统 — AutoDream 记忆整合 + +> Claude 会"做梦"——在后台静默回顾近期会话，整合、更新、修剪记忆，就像人类睡眠中整理白天的记忆一样。 + +

+AutoDream · 触发条件 · 整合流程 · 安全限制 · UI 展示 · 配置开关 · 对比 · 源码导航 +

+ +![AutoDream 概览](./images/11-autodream-overview.png) + +--- + +## 一、什么是 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 触发流程](./images/12-autodream-trigger.png) + +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 四阶段流程](./images/13-autodream-phases.png) + +一旦所有门控通过，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` | 梦境失败 | — | diff --git a/docs/memory/README.md b/docs/memory/README.md index 91a6a1ef..4bf9b812 100644 --- a/docs/memory/README.md +++ b/docs/memory/README.md @@ -37,6 +37,22 @@ --- +### [03-autodream.md](./03-autodream.md) — AutoDream 记忆整合 + +Claude 的"做梦"机制——后台静默整合记忆的深度解析，涵盖： + +- **核心概念**：像人类睡眠整理记忆一样，定期回顾多个会话整合知识 +- **五重门控**：功能开关 → 时间门控(24h) → 扫描节流(10min) → 会话门控(5个) → 锁门控 +- **四阶段流程**：Orient（定向）→ Gather（收集）→ Consolidate（整合）→ Prune（修剪） +- **安全限制**：Bash 只读、写操作仅限记忆目录、PID 锁文件互斥 +- **UI 展示**：底部 "dreaming" 标签、Shift+Down 详情对话框、完成通知 +- **配置控制**：settings.json 本地开关 + GrowthBook 远程 feature flag +- **与 extractMemories 对比**：白天记笔记 vs 睡觉整理笔记本 + +**适合人群**：贡献者、架构师、对 Claude 自动化记忆管理感兴趣的开发者 + +--- + ## 🖼️ 配图说明 所有配图采用深色背景（#1a1a2e）+ Anthropic 品牌橙铜色（#D97757）风格，与 Claude Code 官方文档一致。 @@ -53,6 +69,9 @@ | `08-auto-extraction.png` | 自动提取流程 — 分叉代理完整流程 | 1.2 MB | | `09-memory-retrieval.png` | 智能检索流程 — Sonnet 选择 + 新鲜度管理 | 816 KB | | `10-agent-memory.png` | 代理记忆作用域 — 三级嵌套结构 | 523 KB | +| `11-autodream-overview.png` | AutoDream 概览 — 做梦机制的核心架构与人类睡眠类比 | 777 KB | +| `12-autodream-trigger.png` | AutoDream 触发流程 — 五重门控检查链 | 493 KB | +| `13-autodream-phases.png` | AutoDream 四阶段 — Orient/Gather/Consolidate/Prune | 602 KB | --- @@ -84,6 +103,7 @@ | **MEMORY.md** | 索引文件，始终加载到上下文（最多 200 行 / 25KB） | | **主题文件** | `*.md` 文件，包含 frontmatter + 内容 | | **自动提取** | 每次回复后后台运行，分叉代理分析对话 | +| **AutoDream** | 每 24h + 5 个会话后，后台整合/去重/修剪全部记忆 | | **智能检索** | Sonnet 模型从所有记忆中选择最多 5 个相关的 | | **新鲜度** | ≤1 天无警告，>1 天附带陈旧警告 | | **分叉代理** | 共享提示词缓存，限制工具权限，最多 5 turns | @@ -96,4 +116,6 @@ - [Claude Code 主文档](../) - [记忆系统源码](../../src/memdir/) - [自动提取服务](../../src/services/extractMemories/) +- [AutoDream 服务](../../src/services/autoDream/) +- [DreamTask 任务](../../src/tasks/DreamTask/) - [GitHub Issues](https://github.com/anthropics/claude-code/issues) diff --git a/docs/memory/images/11-autodream-overview.png b/docs/memory/images/11-autodream-overview.png new file mode 100644 index 00000000..aa0c805e Binary files /dev/null and b/docs/memory/images/11-autodream-overview.png differ diff --git a/docs/memory/images/12-autodream-trigger.png b/docs/memory/images/12-autodream-trigger.png new file mode 100644 index 00000000..76ec8486 Binary files /dev/null and b/docs/memory/images/12-autodream-trigger.png differ diff --git a/docs/memory/images/13-autodream-phases.png b/docs/memory/images/13-autodream-phases.png new file mode 100644 index 00000000..5ed41bdd Binary files /dev/null and b/docs/memory/images/13-autodream-phases.png differ