# 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，旧文件清理