AI Agent 记忆系统新思路：用图拓扑替代扁平文件，Token 消耗直降 73%

一句话说清楚：我做了一个叫 Synapse 的开源项目，用「图」来管理 AI Agent 的项目记忆。10 模块真实测试中，每次任务加载的 Token 比传统扁平方案少 73%，跨模块上下文零丢失。

📊 测试条件：10 模块电商项目、7 种典型任务模拟，基线为 RecallLoom 扁平方案（rolling_summary.md）。复现命令见下方「实测」章节。

---

Synapse 核心架构设计图

痛点：Agent 用久了，记忆文件会变成垃圾场

不知道你有没有遇到这种情况——

用 Claude Code 或者 Cursor 写项目，刚开的时候一切丝滑。项目涨到十几个模块（前端、后端、数据库、鉴权、支付……），Agent 越来越「糊涂」：

• 你让它改个按钮颜色，它非要把支付接口的代码也看一遍
• 上下文窗口里塞满了和当前任务无关的东西
• Token 疯狂燃烧，回答质量反而下降

核心原因很简单：传统 Agent 记忆方案是扁平的。（比如 RecallLoom 的 rolling_summary.md）

一切项目记忆堆在一个或几个大文件里。Agent 每次工作，不管改前端还是调后端，都得把全量信息装进脑子。

这就是「扁平记忆的信息密度超载」。

---

解法：把记忆组织成图，按需加载子图

假设你的项目有 10 个模块：

auth（鉴权）──→ db（数据库）←── payment（支付）
  ↑                  ↑               ↑
  │                  │               │
feat_login      feat_cart       feat_checkout

箭头方向 = 依赖方向。feat_login → auth → db 的意思是：登录功能依赖鉴权模块，鉴权模块又依赖数据库。项目和项目之间天然就是这张网。

传统做法：10 个模块的全量信息塞进一个文件 → 每次都全量加载 → ~2600 tokens

Synapse 的做法：每个模块是一个独立节点，节点之间通过 depends_on 声明依赖关系。Agent 收到任务时：

1. 查标索引（MEMORY_MAP，O(1) 查找）
2. 找到目标节点
3. 沿边做有界 BFS 遍历（广度优先搜索——像水波纹往外扩散，读完一个节点后读它直接依赖的节点。限制最多扩散 2 层、每层不超过 5 个，既覆盖了传递依赖链，又防止扩散过头）
4. 只加载相关子图，其他一概不碰

---

实测：10 模块项目中 Token 节省 73%

用 benchmark 脚本模拟了一个电商项目（鉴权、支付、购物车、结账、搜索、用户、路由、组件库、数据库、API 网关 —— 10 个模块，有交叉依赖），跑了 7 种典型任务：

任务	文件数	Token	vs 扁平
修结账页按钮颜色	4	1,167	55% ↓
用户资料加字段	4	597	77% ↓
优化搜索查询	3	483	81% ↓
改 JWT 过期时间	2	403	84% ↓
加支付方式	4	584	77% ↓
调试 401 错误（跨域）	5	1,302	50% ↓
平均	3.6	702	73% ↓

复现命令：bash scripts/benchmark.sh setup && bash scripts/benchmark.sh run

最好的情况（单域修改任务），只加载 2 个节点文件。最坏的情况（跨域调试），也才 5 个节点 —— 有界 BFS 保证了上限。

---

三个工程决策（值得展开说）

1. 不是树，是图

项目的依赖关系天然是图（一个鉴权模块可能同时被支付、登录、管理后台三个功能依赖）。树结构处理不了这种网状关系。

每个节点在 frontmatter 里声明 depends_on 边，脚本自动反推 blocks（入度边）。Agent 只做一次 BFS 就能拿到所有相关上下文。

2. 不是 1-hop，是有界 BFS

单层 1-hop 遍历在浅层依赖里没问题。但真实项目有传递链：结账 → 支付 → 鉴权 → 数据库。刚性 1-hop 只到支付，丢了鉴权和数据库。

Synapse 用的是有界 BFS —— 深度 ≤ 2（覆盖传递链）、宽度 ≤ 5（防止扇出爆炸）。标签过滤+Token 预算双重保底。

3. 不信任 Agent 的自觉，用 Hook 强制执行

Agent 在长会话末尾会偷懒——这是一致的研究观察。如果指望 Agent「记得去更新记忆图」，图一定会慢慢腐化。

Synapse 直接把会话收尾协议写进 Claude Code 的生命周期 hook：

• PostToolUse：每次编辑节点文件后，自动校验 frontmatter 完整性 + 死链检测
• Stop：会话结束时，自动重建索引 + 拓扑校验 + 输出变更摘要

不是「让 Agent 记住去做」，而是「基础设施保证一定会发生」。

---

还能回答「咱们做的咋样了」

模糊查询是扁平方案的优势 —— 一个大文件里什么都有，问一句总览直接翻就行。但 Synapse 用了更聪明的方式：

MEMORY_MAP.md 里有一个自动生成的 ## Status Digest 段落，每个节点一行：

- **mod_auth-api** (stable, updated: 2026-05-01, 0 open issues)
  Last: Added refresh endpoint
- **feat_checkout** (in-progress, updated: 2026-05-01, 0 open issues)
  Last: Wired up payment flow

Agent 读这一个段落就能回答「项目怎么样了」，不需要加载任何完整节点。一次模糊查询 = ~200 tokens。

---

项目结构

Synapse/
├── .claude/
│   ├── settings.json                         ← Hook 注册
│   └── skills/synapse-graph-memory/
│       ├── SKILL.md                          ← 核心协议（267行，Agent 肌肉记忆）
│       ├── template.md                       ← 节点模板
│       └── scripts/generate_memory_map.sh    ← 索引生成 + 拓扑校验
├── scripts/
│   ├── benchmark.sh                          ← A/B 测试脚本
│   ├── parse-session.sh                      ← 会话日志分析
│   └── hooks/post-tool-use.sh, session-end.sh
├── README.md / README.zh-CN.md
├── USAGE.md                                  ← 详细使用指南
└── LICENSE (Apache 2.0)

---

和 Claude-Mem 有什么区别？

关注 Agent 记忆的读者大概率知道 Claude-Mem。两者不是竞品，定位不同：

	Claude-Mem	Synapse
记忆模型	事件流（append-only）	知识图谱（可覆写）
检索方式	向量相似度	确定性图遍历（depends_on 边）
基础设施	SQLite + Chroma + Bun	纯 Markdown + Bash
适用场景	通用项目，零配置	多模块复杂项目，需要结构化
核心优势	自动捕获，零摩擦	精确保真度，按需加载

Claude-Mem 是「什么都记，事后搜索」。Synapse 是「只记关键，事前路由」。两者可以共存 —— Claude-Mem 记事件流，Synapse 管模块状态。

---

适用于谁？

场景	推荐方案
小项目、单领域、快速原型	RecallLoom（扁平）
多领域项目、10+ 模块、长期维护	Synapse（图）
从 RecallLoom 迁移	两者互补，渐进升级

我自己就是在用 RecallLoom 管理项目记忆时遇到「扁平塌陷」问题，才推导出这条演进路径的。

---

链接

• GitHub: https://github.com/LameGz/Synapse
• Skill 文件: .claude/skills/synapse-graph-memory/SKILL.md
• 完整使用指南: USAGE.md
• 设计哲学参考: RecallLoom / Microsoft GraphRAG

---

一句话总结

Synapse 不是一个新的记忆格式，而是一套「用图拓扑做上下文分区加载」的可执行协议。

落地只需要两个东西：一个 267 行的 SKILL.md，加一个自动生成索引的 bash 脚本。

跑起来，看看你的 Agent 少加载了多少无关上下文。

---

欢迎 Star / Issue / PR。如果你也在折腾 Agent 记忆系统，聊聊。