synapse-graph，图记忆skills——给全栈个体户的图拓扑工程记忆系统

一个人维护 5 个项目，AI 是我的"唯一同事"——给全栈个体户的图拓扑工程记忆系统

你不是在管理一个项目的多个模块。你是在管理多个项目，每个项目有十几个模块。你的 AI Agent 是你唯一的"同事"——它忘了，就没人能回答你了。

一、真实的场景：你不是在写一个项目，你是在同时维护好几个

先别急着看技术方案。花 30 秒看看这个场景你熟不熟悉：

上周一：给 SaaS 产品 A 接好支付宝支付回调，写了 200 行后端逻辑 上周二：切到客户项目 B，改 Landing Page 的响应式布局 上周三：客户 B 的服务器崩了，紧急修了一整天 上周四：回到产品 A，准备继续优化支付流程…… 但你和 AI 都忘了——那个回调接口的参数结构是什么来着？ 上周五：外包项目 C 的甲方突然需求变更，要加一个报表导出功能 你打开项目 C 的终端，AI 一脸茫然——上次碰这项目是三个星期前

这不是"模块切换"的问题。这是"项目切换"的问题。

一人公司 / 独立开发者 / 全栈个体户的日常不是在一个项目的 auth 和 payment 之间切来切去——你是在完全不同的代码仓库之间反复横跳。SaaS 产品 A 用 FastAPI + React，外包项目 B 用 Next.js + Prisma，工具项目 C 用 Go + HTMX。每个项目的技术栈完全不同，每个项目的进度完全独立。

而你的 AI Agent——不管是 Claude Code、Cursor 还是 GitHub Copilot——是你唯一的"同事"。

在公司里，你可以扭头问同事：“哎，那个支付回调的参数结构是什么来着？”"改 user 表会影响哪些功能？"但作为一个人，你只能问 AI。当 AI 也忘了的时候——你没有 Plan B。

二、市面上已经有很多"记忆工具"了，为什么它们解决不了你的问题？

你说得对，记忆相关的工具确实很多。但大多数不是为你这种场景设计的：

核心矛盾：现有工具要么为"大型团队"设计（太重），要么为"AI 记住你这个人"设计（场景不匹配），没有为"AI 记住你的多个项目的工程状态"设计的。

更具体地说：

• Mem0 / Letta 等解决的是"对话记忆"——AI 记住你叫张三，喜欢用 TypeScript，偏好函数式风格。但你的问题是"项目 C 的支付模块还差哪些接口没写完？"——这是工程进度记忆，不是用户画像记忆。
• RAG / 向量库解决的是"从大量文档中检索相关信息"。但你的问题不是"从文档中找到支付相关的段落"，而是"精确地知道改mod_user会影响feat_login和feat_subscription两个功能"——这是确定性依赖关系，不是概率性语义相似度。
• CLAUDE.md / Cursor Rules解决的是"给 AI 一段静态背景介绍"。但你的项目在不断变化——每天都有新的接口被接好，新的 bug 被修掉。需要的是一个会随时间更新的活记忆，而不是一份写完之后再也不会改的 README。

三、Synapse Graph Skills 到底做了什么不同的事？

Synapse 是专门为这个场景设计的：

一个全栈开发者 × 多个项目 × AI Agent 是唯一队友 → 需要一种方式让 AI 精确记住每个项目的工程状态，在不同会话之间无缝衔接。

它不是通用记忆，它是工程记忆——专门记住"项目的模块/功能做到什么程度了、模块之间怎么依赖的、改一个会影响哪些"。

如果用一句话说清楚

Synapse 把每个项目变成一张"依赖关系地图"（图拓扑），AI 每次只需要按图索骥加载相关的几个节点，永远不需要把全部记忆塞进 context。

你的其他项目 当前正在操作的项目 │ │ ├── 项目 A (SaaS 产品) ├── meta/feat_payment.md ├── 项目 B (客户 Landing) │ depends_on: [mod_alipay-sdk, mod_user-account] ├── 项目 C (外包后台) │ blocks: [feat_subscription, feat_invoice] ├── 项目 D (开源工具) │ └── 项目 E (实验性项目) │ │ 每个项目独立拥有 AI 只加载项目 A 中与支付 自己的 meta/ 记忆图 相关的 3-5 个节点，不会碰 B/C/D/E 的任何记忆

每个项目的记忆是独立隔离的——你在项目 A 的终端里问"支付做得怎么样了？"，它只查项目 A 的记忆图，项目 B/C/D/E 的记忆文件根本不会被读到。

四、具体怎么运作的？一张图，三层加载

4.1 记忆不是一篇长文，而是一张图

传统的记忆方式是"写一篇 README，把项目信息全部塞进去"。Synapse 的做法完全不同——每个模块/功能是一个独立的 Markdown 节点，节点之间用显式边连接：

---# meta/feat_payment.mddepends_on:[mod_alipay-sdk,mod_user-account,mod_order]auto_linked:[mod_notification,mod_invoice]tags:[支付,支付宝,回调,payment]aliases:[付款,充值,pay,alipay]summary:支付宝 PC 扫码支付 + H5 支付，回调接口已完成，退款接口待接---

三种边构成完整有向图：

"改这个会影响哪些功能？"不再靠猜——图已经算好了。

4.2 三层渐进式加载：永远不"全量读一遍"

AI 面对记忆时的常见行为是"把所有 meta/*.md 读一遍以防遗漏"，这在 30 个模块时直接把 context 撑爆。Synapse 的三层协议强制精确加载：

第 1 层：倒排索引（MEMORY_MAP） ~200-500 tokens └── 查标签/别名 → 找到目标节点名 "支付做得怎么样了？" → 标签匹配"支付" → 锁定 feat_payment 第 2 层：目标节点完整内容 ~500-1500 tokens └── 读了 feat_payment.md，知道回调已接好 → 够了？STOP 第 3 层：受限 BFS 展开（深度≤2，宽度≤5） ~1000-4000 tokens └── "改支付会影响哪些功能？" → 查 blocks：feat_subscription + feat_invoice → 只加载这两个节点的 Connection Points → STOP → token 超过 context 的 15%？硬停止，报告用户

30 个模块的项目，暴力加载读 30 个文件。受限 BFS 读 3-5 个。模块越多，差距越大。

4.3 Hook 强制遵守——规则不是建议，是约束

光写文档说"请按协议加载"是没用的，AI 在长会话中会慢慢偏离协议。Synapse 利用 Claude Code 的 Hook 机制把协议变成运行时强制规则：

每次会话结束时自动执行：

[doctor] Topology Health: ✓ 18 nodes active, 0 dead links, 0 orphans ⚠ 3 nodes flagged for drift: 源码改了但 meta/ 没更新 ⚠ mod_payment.md 218 lines (>200), 建议拆分 [change-summary] 本次会话变更： M feat_payment.md +1 Change Log M mod_alipay-sdk.md 更新 Connection Points M MEMORY_MAP.md 自动重建

你不需要手动维护——会话结束时它自己检查、自己报告。

4.4 连接点是可验证的契约，不是自由文本

传统方式写"需要支付 API"——这对影响分析毫无价值。Synapse 的连接点是带源码锚点的结构化接口描述：

### To mod_alipay-sdk - **调用**: POST /api/v1/payments/callback <!-- @ref: src/payment/routes.ts:45 --> - **入参**: `{ order_id: string, trade_no: string, total_amount: number }` - **返回**: `{ success: boolean, out_trade_no: string }` - **错误码**: `402` 余额不足, `409` 重复通知 - **约束**: 通过 `Idempotency-Key` 实现幂等，支付宝会重复发送通知

@ref锚点让系统能在每次会话结束时检查：源码中的接口还是记忆里记录的样子吗？不是，就报警——不等你踩坑才知道记忆已经过时了。

五、四枚独立 Skill——装几个用几个

Synapse 以 Claude Code Skills 形态发布，四个模块独立可安装：

synapse-graph-memory (66 KB) ← 核心：检索引擎 + 7 步决策树 ├── 什么时候触发？ "XX 做得怎么样了？"、"会影响哪些功能？" └── 包含哪些脚本？ 11 个脚本 + 4 个 hook（完整捆绑，装了就能用） synapse-timeline (5.5 KB) ← 只读查询：时间线 + Open Issues ├── "最近改了啥？"、"有哪些没解决的问题？" └── 单脚本 227 行，bash + 嵌入式 Python synapse-daily-note (26 KB) ← 写入管线：一句话 → 自动更新记忆 ├── "记录一下：接好了 POST /api/v1/auth/login" └── 全管线：NL 解析 → 边检测 → 写入 → 重建索引 → 拓扑校验 synapse-init (43 KB) ← 冷启动向导：给任何项目一键配好记忆 ├── "初始化记忆" └── 自动检测技术栈 → 扫描 src/ → 生成骨架节点 → 注册 hook

去哪里装？

# 从 GitHub 直接复制gitclone https://github.com/LameGz/synapse-graph-skills.gitcp-rsynapse-graph-skills/synapse-graph-memory ~/.claude/skills/cp-rsynapse-graph-skills/synapse-timeline ~/.claude/skills/cp-rsynapse-graph-skills/synapse-daily-note ~/.claude/skills/cp-rsynapse-graph-skills/synapse-init ~/.claude/skills/

六、评估数据：对 AI Agent 的 context 效率有多大提升？

在 8 节点 SaaS 测试项目上使用 deepseek-v4-pro 评估：

不装 Skill 的 AI 行为：MEMORY_MAP.* → 所有 8 个 meta/*.md → README → 2 个 cache 文件 → "以防万一"全读一遍

装 Skill 后的 AI 行为：SKILL.md → MEMORY_MAP.md → feat_login → BFS 展开 2 个直接依赖 → STOP

在 30+ 模块的项目中，这个差距是指数级的——因为不装 Skill 的 AI 会尝试把所有 30 个文件都读一遍，而受限 BFS 停在 3-5 个文件。

七、三段进化：这不是从零开始的点子，它已经打磨了三代

Synapse 解决这个问题走了三代：

V1 (2024) V2 (2025 初) V3 (2025.05) ← 当前 ───────────────── ───────────────── ───────────────────────── 形态：单脚本 形态：单体 Agent 记忆 形态：四枚独立 Skill 存储：Markdown 扁片 存储：Markdown 扁片 存储：图拓扑 + 显式边 检索：grep 全文搜索 检索：关键词 + 摘要 检索：三层渐进式 + 受限 BFS 边关系：无 边关系：隐式（命名约定） 边关系：显式 depends_on/blocks 一致性：靠开发者自律 一致性：靠开发者自律 一致性：Hook 运行时强制 规模上限：~10 节点 规模上限：~15 节点 规模上限：30+ 节点（常数级）

V1→V2 的核心变化：从脚本变成 Agent，自然语言交互替代了命令行。

V2→V3 的核心变化：从扁平文件变成图拓扑——这是质的飞跃。V2 的项目记忆在 ~15 个模块后就开始 context 爆炸；V3 用"显式图 + 受限 BFS"把加载成本和模块数量解耦。

八、适合谁？不适合谁？

适合你，如果你……

• 一个人同时维护 2 个以上的项目
• AI Agent（Claude Code / Cursor / Copilot）是你日常的主要编程搭档
• 经常在不同项目之间切换，切回来已经忘了上次做到哪了
• 项目的模块数在 10 个以上，全量塞进 context 不现实
• 不想折腾向量数据库 / RAG 那一套重型基础设施

不适合你，如果你……

• 你是大厂团队，有专门的文档 / Wiki / oncall —— 你不需要这个
• 你只有一个项目，且只有 3-5 个模块 —— 全量加载就够了
• 你不用 AI Agent 写代码 —— Synapse 是给 AI 读的，不是给你读的
• 你需要的是"对话记忆"（记住用户偏好、习惯）—— 那是 Mem0/Letta 的领域，不是 Synapse 的

九、30 秒快速上手

# 1. 安装cp-rsynapse-graph-skills/synapse-graph-memory ~/.claude/skills/cp-rsynapse-graph-skills/synapse-init ~/.claude/skills/# 2. 在任意项目中初始化# （在 Claude Code 中直接说）用户：初始化记忆# 3. 开始记录用户：记录一下：接好了支付宝 PC 扫码支付，回调通知接口幂等处理完成# 4. 下次打开项目时直接问用户：支付做得怎么样了？ 用户：改 mod_user 的套餐字段会影响哪些功能？

十、总结

一人全栈开发者的核心困境不是"不会写"，而是**“切回来忘了”**。你不是没有 AI 助手——你有，而且它能力很强。但每次打开新会话，它都是"一张白纸"，你花了 20 分钟才让它理解项目的上下文——这就是context 重建成本。

现有记忆工具的对不上这个场景：Mem0 记住"你是什么样的人"，RAG 记住"文档里写了什么"，但没有人记住"你的项目的工程状态"——哪个接口接好了、哪个模块还差什么、模块之间怎么连在一起的。

Synapse 做的就是这件事：

每个项目一张图，AI 按图索骥加载，永远不把所有记忆塞进 context。

你不止一个项目，你的 AI 是你唯一的同事——它不应该每次都从头开始了解你上周做了什么。

• GitHub: https://github.com/LameGz/synapse-graph-skills
• 架构文档: docs/architecture.md
• Skills 总览: docs/skills-overview.md
• 使用指南: USAGE.md

本文由 Synapse Graph Skills 作者撰写。欢迎转载，注明出处即可。