22-agent-memory-system.md 9.91 KB

Edit Raw Blame History


22. Agent Memory System — 自动记忆读写架构

版本: v1.1 (已实现 / 生产可用)
日期: 2026-03-25
状态: ✅ 已完成 (Phase 1, 2, 3 全部上线，E2E测试 27/27 通过)
前置: Phase 3.5 FDE 已完成，Phase 4 认知架构的核心部分


一、核心问题与解决方案
当前 Agent 每次新对话都是完全失忆的。
为此，我们设计并实现了一套包含 MVP基础记忆、海马体&小脑检索、自动反思与长期合并 的三阶段进化架构，真实解决：


Agent 自动记住做过什么、学到什么、犯过什么错。
Agent 接到新任务时自动想起相关经验（按关键词计算关联度）。
好的多步方案自动固化到小脑，下次遇到同类任务精准触发复用。


二、目录结构
每个 Agent 的记忆文件严格按以下结构持久化在 data/agents/{agent-id}/memory/ 下：
memory/
├── memory.md              ← 核心记忆（关键事实/已验证模式/失败教训），每次全量注入 prompt
├── hippocampus.md         ← 海马体：情景→方案的映射（Markdown，人类可读）
├── hippocampus-index.json ← 海马体机器索引，用于关键词匹配检索和分值计算
├── cerebellum/            ← 小脑：固化的执行方案（.md 步骤指导）
├── short-term/            ← 短期记忆：近期 session 的纯文本摘要，包含执行数据
├── long-term/             ← 长期记忆：合并过期的短期记忆提取的 keyword 频率与长文归档
├── reflections/           ← 反思日志：每次高复杂度任务自动提取的模式与教训存放处
└── daily/                 ← 日报：汇总当天的对话、反思和新生方案


三、数据流全景
┌─────────────────────────────────────────────────────────┐
│                     新对话开始                            │
│                        │                                 │
│    ┌───────────────────▼──────────────────┐              │
│    │  1. READ: 挂载记忆(buildSystemPrompt) │              │
│    │     ├── memory.md (全量注入 prompt)   │              │
│    │     ├── 海马体精准匹配(用户输入+todo) │              │
│    │     ├── 短期记忆(最近 N 个 session)   │              │
│    │     └── 小脑方案(如果匹配到海马体)    │              │
│    └───────────────────┬──────────────────┘              │
│                        │                                 │
│                        ▼                                 │
│              [ Agent 执行任务 ]                           │
│                        │                                 │
│    ┌───────────────────▼──────────────────┐              │
│    │  2. WRITE: 自动存储记忆(Chat 完成后)  │              │
│    │     ├── 生成 session 摘要 → short-term│              │
│    │     ├── 提取关键事实 → memory.md      │              │
│    │     ├── 高复杂度任务自动触发 Reflection │              │
│    │     └── 好方案自固化 → cerebellum/    │              │
│    └───────────────────┬──────────────────┘              │
│                        │                                 │
│    ┌───────────────────▼──────────────────┐              │
│    │  3. CONSOLIDATE (长期沉淀 API)        │              │
│    │     ├── 短期摘要过期 → 合并 long-term │             │
│    │     ├── 提取高频关键词 → patterns.md  │              │
│    │     ├── daily/ 日报生成               │              │
│    │     └── 遗忘机制及索引整理              │              │
│    └──────────────────────────────────────┘              │
└─────────────────────────────────────────────────────────┘


四、实现复盘 — Todo List 全部点亮
Phase 1: 最小可行记忆 (MVP) 🎯

目标：Agent 不再失忆，每次对话的关键信息自动留存
结果：完美运行，自动提取生成轻量摘要


[x] 1.1 对话结束自动生成 session 摘要


在 agent-chat.js 内捕获对话完毕事件，提取 meta.json 里的基本信息结合对话产出生成 Markdown 概要，存入 short-term/session-{timestamp}.md。

[x] 1.2 短期记忆注入 system prompt


buildSystemPrompt() 会反向加载最新的 5 个 session-*.md 摘要。

[x] 1.3 memory.md 自动追加关键事实


ToolCallCounts > 0 时，自动从任务文本和最终回应抓取一两句话，追加为 [时间] 任务 → 结果 写入 memory.md 的“关键事实”段落。

[x] 1.4 memory.md 大小控制


自带 2000 字符控制，如果超过会安全截断旧记录。


Phase 2: 海马体检索 + 小脑固化 🧠

目标：Agent 能检索相关经验，好方案自动复用
结果：实现基于自研评分机制与语境保护的轻量检索系统


[x] 2.1 海马体索引结构定义


数据结构存储于 hippocampus-index.json，并每次变动都会用 syncHippocampusMd 同步至人类友好版表格 hippocampus.md，追踪使用次数(useCount)与置信度。

[x] 2.2 海马体匹配引擎 (自研提词匹配器)


实现于 memory-service.js:retrieveRelevantPlans。
关键修复：由于历史任务的英文 JSON 记录容易截断最新的中文分词，提词引擎 (extractKeywords) 已升级为“截取前1500字符 + 优先保护中文短词提取 + 容量扩大至 50 词汇”，同时在 prompt 拼接时让新的 userMessage 置顶，精准保证任何海马体历史都能被识别和唤起。

[x] 2.3 小脑方案写入与索引自动更新


实现 saveCerebellumPlan 接口和后端逻辑。存储 MD 方案进入 cerebellum/ 并安全覆盖和递增 hippocampus 表的使用次数。


Phase 3: 反思引擎 + 长期沉淀 🧬

目标：Agent 能自主学习，经验自动沉淀
结果：实现了免唤起 LLM 的“规则型反思引擎”，大幅度降低了 API Cost，但又完美提取并分类总结了信息。


[x] 3.1 反思引擎 (autoReflect)


不做毫无意义的次次反思。仅在：toolCallCount ≥ 3，或 duration ≥ 60s 时自动触发。
成功任务 → 提取到 patterns（模式），5 次及以上 tool calls 更是会触发自动写入小脑执行步骤。
失败任务 (status='failed') → 提取到 lessons（教训）。
所有原始细节封存进 reflections/ 作为 JSON 参考。

[x] 3.2 反思结果自动反馈给当前 Prompt


新学习到的 patterns 和 lessons 会立刻被追加回 memory.md 的对应栏位里，下一次回答时 Agent 即可利用。

[x] 3.3 短期记忆合并到长期记忆 (consolidateMemory)


通过 /api/agent/:agentId/memory/consolidate API 触发。
自动扫除 > 7天以上的 short-term 记录，统合写入 long-term/consolidate-{date}.md 并通过关键词聚合提取模式。

[x] 3.4 日报与统计 (generateDailyReport)


每天生成 daily/YYYY-MM-DD.md 包含对话量、反思数及新知识增幅。


五、关键技术决策（最新版）


#
问题
决策
收益/说明


1
session 摘要生成方式
无 LLM，纯逻辑提取
不增加任何 Token 和耗时开销，完全透明。


2
海马体匹配算法
中英双优 ngram 关键词打分
以 hits / keywords 定比率。免装向量库。通过拦截前排中文字段保证了召回率 (> 0.3 即命中)。


3
memory.md 注入方式
全量 + 最近 5 session
整体记忆控制在最佳窗口容差内，避免爆掉模型的 Attention 机制。


4
反思引擎实现
纯代码规则引擎
旧设计想用 LLM 生成，但考虑到海量废话，现改为通过对话信息解析直接生成结构化数据，速度瞬间出结果并准确反馈。


六、验证标准及结果
以下 E2E 自动化测试用例位于 server/scripts/test-memory-e2e.js 并在 2026-03-25 完成验证。
Phase 1 验收 (✅ Pass)

[x] 与 Agent 对话一次 → short-term/ 出现新 session 文件
[x] 第二次对话 → system prompt 中能看到"近期记忆"段并成功被 Agent 引述
[x] 多次对话后 → memory.md 有新追加的关键事实

Phase 2 验收 (✅ Pass)

[x] 使用 API 保存小脑方案，JSON 索引建立。
[x] 派发强关键词匹配任务 → 海马体引擎拦截命中，Prompt 体积扩大，被方案包围。
[x] 成功命中后，后端日志展现 🐴 海马体命中，海马体 UseCount 累增。

Phase 3 验收 (✅ Pass)

[x] 伪造高工具调用对话 → 触发反思引擎，memory.md 写入已验证模式。
[x] 伪造报错退出对话 → 触发反思引擎，写入失败教训。
[x] POST 触发 /consolidate → 短期记忆消失，清算存入 Long-Term。
[x] POST 触发 /daily-report → 生成包含了当天统计和反思日志指引的日报 Markdown。


🎉 [E2E Suite]: ALL PASSED (27/27) - 核心模块生产就绪！