diff --git a/docs/system-design/22-agent-memory-system.md b/docs/system-design/22-agent-memory-system.md new file mode 100644 index 0000000..0bf3bac --- /dev/null +++ b/docs/system-design/22-agent-memory-system.md @@ -0,0 +1,282 @@ +# 22. Agent Memory System — 自动记忆读写架构 + +> **版本**: v1.0 (设计稿) +> **日期**: 2026-03-25 +> **状态**: 规划中 +> **前置**: Phase 3.5 FDE 已完成，Phase 4 认知架构的核心部分 + +--- + +## 一、核心问题 + +当前 Agent 每次新对话都是**完全失忆**的。 +memory 目录结构已就位，但读写机制全是空壳。 + +**需要解决**： +1. Agent 如何**自动记住**做过什么、学到什么、犯过什么错 +2. Agent 接到新任务时如何**自动想起**相关经验 +3. 好方案如何**自动固化**，下次遇到同类任务直接复用 + +--- + +## 二、目录结构（已就位） + +``` +data/agents/{agent-id}/memory/ +├── memory.md ← 核心记忆索引（注入 prompt，≤2000字） +├── hippocampus.md ← 海马体：情景→方案 映射索引 +├── cerebellum/ ← 小脑：固化的执行方案（.md 步骤 / .js 脚本） +│ ├── handle-okr-task.md +│ └── create-agent.md +├── short-term/ ← 短期记忆：近期 session 摘要 +│ ├── session-2026-03-25-001.md +│ └── session-2026-03-25-002.md +├── long-term/ ← 长期记忆：沉淀的经验 & 事实 +│ ├── patterns.md ← 反复验证的模式 +│ ├── lessons.md ← 失败教训 +│ └── facts.md ← 重要事实 +├── daily/ ← 日报 +│ └── 2026-03-25.md +└── sessions/ ← 按 session 存的原始快照（可选） +``` + +--- + +## 三、数据流全景 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 新对话开始 │ +│ │ │ +│ ┌───────────────────▼──────────────────┐ │ +│ │ 1. READ: 加载记忆 │ │ +│ │ ├── memory.md (全量注入 prompt) │ │ +│ │ ├── 海马体匹配(关键词→方案) │ │ +│ │ ├── 短期记忆(最近 N 个 session) │ │ +│ │ └── 小脑方案(如果匹配到) │ │ +│ └───────────────────┬──────────────────┘ │ +│ │ │ +│ ▼ │ +│ [ Agent 执行任务 ] │ +│ │ │ +│ ┌───────────────────▼──────────────────┐ │ +│ │ 2. WRITE: 自动存储记忆 │ │ +│ │ ├── 生成 session 摘要 → short-term│ │ +│ │ ├── 提取关键事实 → memory.md │ │ +│ │ ├── 好方案 → cerebellum/ + 索引 │ │ +│ │ └── 教训/模式 → memory.md │ │ +│ └───────────────────┬──────────────────┘ │ +│ │ │ +│ ┌───────────────────▼──────────────────┐ │ +│ │ 3. CONSOLIDATE (定时整理) │ │ +│ │ ├── short-term 过期 → 合并 long-term │ │ +│ │ ├── memory.md 超长 → 摘要压缩 │ │ +│ │ ├── daily/ 日报生成 │ │ +│ │ └── hippocampus 索引更新 │ │ +│ └──────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────┘ +``` + +--- + +## 四、实现计划 — Todo List + +### Phase 1: 最小可行记忆 (MVP) 🎯 + +> 目标：Agent 不再失忆，每次对话的关键信息自动留存 + +- [ ] **1.1 对话结束自动生成 session 摘要** + - 位置: `server/routes/agent-chat.js` → `result` 事件处理 + - 触发: 对话 status 变为 `completed` 时 + - 输出: `memory/short-term/session-{timestamp}.md` + - 内容: 任务描述、执行结果、工具调用数、关键产出文件 + - 实现: 从 `messages.log` 提取（无需额外 LLM 调用） + ```javascript + // 伪代码 + function autoSaveSessionSummary(agentId, convId, meta) { + const summary = { + timestamp: new Date().toISOString(), + task: extractTaskFromFirstMessage(convId), + result: meta.lastAssistantMessage?.substring(0, 500), + toolCalls: meta.stats.toolCallCount, + duration: meta.duration, + files: extractCreatedFiles(convId), + }; + writeFile(`memory/short-term/session-${Date.now()}.md`, formatSummary(summary)); + } + ``` + +- [ ] **1.2 短期记忆注入 system prompt** + - 位置: `buildSystemPrompt()` 函数 + - 逻辑: 读取最近 5 个 `short-term/session-*.md`，拼接注入 + - 大小限制: 最近 5 个 session 摘要，每个 ≤300 字 + ``` + # 近期记忆（最近 5 次对话） + + ## 2026-03-25 10:00 — 训练 CEO 技能 + - 结果: 完成 Hunt→Digest→Evolve，最终分数 92/100 + - 产出: workspace/ceo/hunt/, workspace/ceo/digest/, workspace/ceo/evolve/ + + ## 2026-03-25 09:30 — 创建 Poet Agent + - 结果: 成功创建，SKILL.md 已就绪 + - 产出: data/agents/poet/ + ``` + +- [ ] **1.3 memory.md 自动追加关键事实** + - 触发: 对话结束 + toolCallCount > 0 + - 逻辑: 从 session 摘要中提取"关键事实"条目 + - 追加到 memory.md 的对应章节（关键事实/已验证模式/失败教训） + - 大小控制: memory.md 超过 2000 字时触发压缩 + +- [ ] **1.4 memory.md 大小控制** + - 当 memory.md > 2000 字: + - 移除最旧的条目 + - 或合并同类条目 + - 确保 prompt 不会因记忆过多而爆掉 + +--- + +### Phase 2: 海马体检索 + 小脑固化 + +> 目标：Agent 能检索相关经验，好方案自动复用 + +- [ ] **2.1 海马体索引结构定义** + ```markdown + # hippocampus.md + | # | 情景模式 | 匹配关键词 | 方案文件 | 置信度 | 使用次数 | + |---|---------|-----------|---------|--------|---------| + | 1 | 创建新 Agent | agent,create,创建 | cerebellum/create-agent.md | 0.9 | 5 | + | 2 | OKR 任务分解 | okr,goal,分解,plan | cerebellum/okr-decompose.md | 0.8 | 3 | + ``` + +- [ ] **2.2 海马体匹配引擎 (关键词 MVP)** + - 新建: `server/services/memory-service.js` + - 函数: `retrieveRelevantMemory(task, agentDir)` + - 逻辑: + 1. 解析 hippocampus.md 索引 + 2. 从 task 文本提取关键词（分词 + 停用词过滤） + 3. 计算关键词命中率 + 4. 返回命中的小脑方案列表 + - 注入: 在 `buildSystemPrompt()` 中调用，匹配到的方案追加到 prompt + +- [ ] **2.3 小脑方案写入** + - 触发: Agent 在反思中标记"这个方案效果好" + - 或: 管理员手动标记某个 session 为"好方案" + - 格式: + ```markdown + # 方案: 创建新 Agent + + ## 适用条件 + - 需要创建新的 Agent 角色 + - 需要定义 agent.md + soul.md + identity.md + SKILL.md + + ## 执行步骤 + 1. 确认 Agent 角色定义（名称、类型、能力） + 2. 调用 scaffold API 创建目录结构 + 3. 依次填写 agent.md, soul.md, identity.md + 4. 创建 .claude/skills/main_skill/SKILL.md + 5. 验证 config.json 配置 + + ## 注意事项 + - identity.md 必须包含 名称 字段 + - config.json 的 type 要正确设置 + ``` + +- [ ] **2.4 海马体索引自动更新** + - 当小脑新增方案时，自动追加索引行 + - 每次方案被成功使用，更新"使用次数"和"置信度" + +--- + +### Phase 3: 反思引擎 + 长期记忆 + +> 目标：Agent 能自主学习，经验自动沉淀 + +- [ ] **3.1 反思引擎实现** + - 位置: `Agent.js` 的 `reflect()` 方法 + - 触发条件（不是每次都反思）: + - toolCallCount ≥ 3 (有实质操作) + - 或 duration > 60s (较长时间的任务) + - 或 task 包含"训练/调试/修复"等关键词 + - 反思 prompt: + ``` + 请反思这次任务执行： + 1. 做得好的是什么？有什么可复用的模式？ + 2. 做得不好的是什么？有什么教训？ + 3. 这类任务的情景特征是什么？下次遇到类似任务应该怎么做？ + + 输出格式： + - pattern: (可复用的模式) + - lesson: (教训) + - scenario_keywords: (情景关键词列表) + - plan_summary: (如果方案好，写出步骤摘要) + ``` + +- [ ] **3.2 反思结果自动写入** + - pattern → memory.md "已验证的模式" + - lesson → memory.md "失败教训" + - plan_summary → cerebellum/ 新方案文件 + - scenario_keywords → hippocampus.md 新索引行 + +- [ ] **3.3 短期记忆合并到长期记忆** + - 触发: CronCreate 每天凌晨 2 点 + - 逻辑: + 1. 扫描 short-term/ 中超过 7 天的 session 摘要 + 2. 提取反复出现的模式 → long-term/patterns.md + 3. 提取重要事实 → long-term/facts.md + 4. 删除已合并的 short-term 文件 + - 输出: 更新 long-term/ 目录 + +- [ ] **3.4 日报自动化** + - 触发: CronCreate 每天 23:00 + - 内容: 当天的 session 数、任务完成数、关键成果 + - 输出: `memory/daily/YYYY-MM-DD.md` + +- [ ] **3.5 记忆遗忘机制** + - long-term 中连续 30 天未被引用的条目，降低权重 + - hippocampus 中置信度 < 0.3 且使用次数 = 0 的条目，标记为"已遗忘" + - 防止记忆无限膨胀 + +--- + +## 五、关键技术决策 + +| # | 问题 | 决策 | 说明 | +|---|------|------|------| +| 1 | session 摘要生成方式 | **无 LLM，纯提取** (MVP) | 从 meta.json + messages.log 提取，不消耗 API 配额 | +| 2 | 海马体匹配算法 | **关键词匹配** (MVP) | 后续按需升级向量检索 | +| 3 | memory.md 注入方式 | **全量 + 最近 5 session** | memory.md ≤2000字 + 5 个 session 摘要 ≤1500字 | +| 4 | 反思触发条件 | **有实质操作的对话才反思** | toolCallCount ≥ 3 或 duration > 60s | +| 5 | 反思执行者 | **Agent 自己** | 通过追加一条 prompt 让 Agent 反思并输出 JSON | +| 6 | 长期合并频率 | **每天凌晨** | cron 触发，不影响白天使用 | + +--- + +## 六、代码改动点 + +| 文件 | 改动 | Phase | +|------|------|-------| +| `server/routes/agent-chat.js` | `result` 事件中调用 MemoryWriter | 1 | +| `server/routes/agent-chat.js` | `buildSystemPrompt()` 加载 short-term | 1 | +| `server/services/memory-service.js` | **新建**: session摘要、记忆检索、索引更新 | 1+2 | +| `packages/agent-core/Agent.js` | `reflect()` 实现 | 3 | +| `packages/agent-core/base/common/capabilities.md` | 增加记忆使用说明 | 1 | + +--- + +## 七、验证标准 + +### Phase 1 验收 +- [ ] 与 CEO Agent 对话一次 → `short-term/` 出现新 session 文件 +- [ ] 第二次对话 → system prompt 中能看到"近期记忆"段 +- [ ] 多次对话后 → memory.md 有新追加的关键事实 + +### Phase 2 验收 +- [ ] 手动添加一条 hippocampus 索引 +- [ ] 给 Agent 分配匹配的任务 → prompt 中出现小脑方案内容 +- [ ] Agent 使用方案完成任务 → 索引的使用次数 +1 + +### Phase 3 验收 +- [ ] Agent 完成复杂任务 → 自动触发反思 +- [ ] 反思结果写入 memory.md 和 cerebellum/ +- [ ] 7 天后 → short-term 合并到 long-term，旧文件清理