5 个 AI Agent 各自失忆，我用 Git 和 Markdown 做了一个共享记忆中枢

多 Agent 协作最先暴露的，往往不是模型能力不足，而是上下文无法流动：Claude Code 记住了代码风格，OpenCode 不知道；Hermes 聊过项目进展，下一次编码会话又要从头解释。

我同时使用多个 AI Agent 之后，逐渐遇到一个很具体的问题：每个工具都在积累上下文，但这些上下文被锁在各自的目录、数据库或会话里。

工具越多，我越像在管理一支每天都会局部失忆的团队。为了让它们共用用户画像、项目进展和长期经验，我做了一个小型开源项目：agent-memory-hub。

它没有向量数据库，没有独立服务，也没有新的 Agent Runtime。核心只是一个 Git 仓库、一组 Markdown 文件和几份告诉 Agent “去哪里读写记忆”的指针文件。

这篇文章不只介绍它怎么用，更重要的是解释：为什么我选择这个看起来很朴素的方案，以及它真正的能力边界在哪里。

---

一、真正的问题不是没有记忆，而是记忆没有共同地址

Claude Code、OpenCode、Hermes 等工具都有自己的上下文机制。单独使用时没有问题，多工具并行后却会出现四种割裂：

• 用户偏好只存在于某一个 Agent；
• 项目阶段结论散落在不同会话目录；
• 新设备没有旧设备的本地记忆；
• 同一事实被复制多份，更新后互相矛盾。

最消耗人的不是保存文件，而是反复充当“人工同步总线”：把这边的结论复制到另一边，再解释哪些信息已经过期。

所以我给问题换了一个定义：

多 Agent 记忆的第一阶段，不一定需要更聪明的检索，而是先需要一个稳定、可迁移、可审计的共同地址。

这个定义很关键。它把项目从“再造一套记忆数据库”收缩成了三个工程目标：

• 所有 Agent 能找到同一份用户画像和记忆索引；
• 记忆以普通文件保存，可以搜索、审查、回滚；
• 换设备时只需要恢复仓库并重新分发指针。

---

二、为什么没有直接上向量数据库

我调研过 mem0、Letta 等方案。它们擅长语义检索、长期记忆抽取或完整 Agent 平台，但也意味着新的服务、存储、模型调用和运维边界。

我的实际规模只有几百个 Markdown 文件。这个阶段最常见的查询不是“寻找语义相似度为 0.83 的片段”，而是：

• 之前对这个项目做过什么决定？
• 用户偏好放在哪里？
• 上次发布踩过什么坑？
• 某个 Agent 保存过哪些长期结论？

目录、索引和全文搜索已经能够回答这些问题。此时先引入数据库，增加的可能不是能力，而是迁移、备份、权限和故障排查成本。

因此 agent-memory-hub 的选择是：

需求	当前方案
统一用户画像	USER.md
长期记忆归档	memory/ 下按 Agent 分目录
快速定位	自动生成 memory/INDEX.md
跨设备同步	私有 Git 仓库
Agent 接入	各工具约定位置的指针文件
语义检索	暂不内置，需要时再叠加

Markdown 不是因为它最先进，而是因为它在当前规模下最容易拥有、检查和迁移。将来即使接入向量检索，Markdown 仍然可以继续作为事实源。

---

三、三层架构：数据、适配与引导

项目把职责拆成三层。

1. 数据层：真正需要长期保存的内容

数据层位于共享仓库本体：

• USER.md：用户画像和稳定偏好，是单一事实来源；
• memory/：按 Agent 归档长期记忆；
• memory/INDEX.md：同步时重新生成的文件索引；
• SKILLS.md：可选的共享技能索引；
• machines/：为设备差异预留的位置。

这层故意保持普通。任何编辑器都能打开，任何 Git 工具都能查看变更历史，仓库损坏时也不需要先恢复数据库服务。

2. 适配层：让不同 Agent 学会找同一个地址

不同工具读取全局指令的位置不同：

Agent	指针文件
Claude Code	~/.claude/CLAUDE.md
OpenCode	~/AGENTS.md
Hermes	MEMORY.md 与 USER.md
QClaw	workspace/MEMORY.md
OpenClaw	workspace/MEMORY.md

agents/ 目录为每个工具准备一份模板。setup 脚本把模板里的 {{SHARED}} 替换成当前仓库的真实路径，再复制到对应位置。

指针文件不保存完整记忆，只保存三个约定：启动时读哪里，需要历史时查哪里，新长期记忆写到哪里。

3. 引导层：把接入动作做成可重复脚本

setup.ps1 与 setup.sh 负责：

• 检测当前操作系统和已安装的 Agent；
• 找到各 Agent 的配置目录；
• 展开指针模板中的共享路径；
• 在不覆盖现有文件的前提下安装指针；
• 运行第一次同步。

这使接入不依赖一份容易过期的人工操作手册。新增 Agent 也不需要改数据层，只要增加模板和检测逻辑。

---

四、同步脚本真正做了什么

scripts/sync_memory.py 只使用 Python 标准库，当前主要完成四件事：

• 扫描 Claude Code 项目记忆并复制变化文件；
• 读取 Hermes 的根记忆文件，并从 state.db 导出可识别的会话；
• 重新生成 memory/INDEX.md；
• 保存本机同步状态，并在有变化时创建 Git commit；传入 --push 后再推送。

OpenCode、QClaw 和 OpenClaw 的指针则要求 Agent 直接把长期记忆写入共享目录，因此不需要额外搬运。

整个过程更像“归档器 + 索引器”，不是一个持续在线的双向同步服务。Windows 可以用任务计划程序定时运行 sync.bat，Linux 与 macOS 可以使用 cron，但这些定时任务需要用户自行配置。

# 首次接入
git clone https://github.com/<you>/agent-memory-hub.git ~/.shared
cd ~/.shared
bash setup.sh

# 日常归档并推送
python scripts/sync_memory.py --push

项目 README 里的“10 秒恢复”是一句设计目标，而不是经过多设备基准测试的 SLA。真实耗时取决于 Git 网络、Python 环境、Agent 数量以及现有配置是否冲突。

---

五、三个看似朴素、其实很重要的设计决定

1. 复制指针，而不是依赖符号链接

符号链接看起来更优雅，但 Windows 上可能需要开发者模式或额外权限；工具卸载、目录迁移后，死链也不容易被发现。

复制文件的代价是模板更新后要重新执行 setup；好处是目标文件真实存在，排障更直接，也可以通过 --force 明确覆盖。

2. 同步脚本主动提交，而不是只依赖 Git hooks

Git hooks 只能在 Git 命令发生时触发，无法发现 Agent 直接写入本地目录。让同步脚本负责“采集、建索引、提交”，才能形成完整动作。

这不代表所有环境都应该自动 push。提交可以作为本地审计点，是否推送应该由用户根据隐私与冲突风险决定。

3. 路径探测，而不是写死某一台电脑

Hermes 在不同系统上的目录可能不同。PowerShell、Bash 和 Python 脚本都维护候选路径并自动探测，仓库本身则通过脚本位置动态得到共享目录。

路径动态化，是这个方案能够跨设备复用的基础；machines/ 只保留真正无法统一的设备差异。

---

六、代码审校后，我认为必须明确的五个边界

把一个项目写成文章，最容易发生的问题是把“已经能运行”写成“已经解决所有问题”。基于当前仓库代码，我给 agent-memory-hub 留下五条明确边界。

边界一：它统一的是地址，不是 Agent 的理解能力

指针文件可以要求 Agent 读取 USER.md 和 memory/INDEX.md，但最终是否读取、如何提取、是否正确应用，仍取决于各 Agent 的指令加载机制和执行质量。

边界二：它没有语义检索和自动去重

INDEX.md 是文件索引，不会判断两条记忆是否冲突，也不会自动合并同义内容。文件规模继续增长后，需要增加整理流程或叠加检索层。

边界三：Hermes 会话不是无损备份

当前导出逻辑会把每条 Hermes 消息截取到前 500 个字符。这足以生成轻量归档，但不能称为完整会话备份。真正重要的长期结论仍应主动整理为独立 Markdown。

边界四：Git 冲突需要人工处理

多设备同时写同一文件时，Git 仍可能冲突。当前项目没有自动合并、锁或冲突仲裁服务，更适合单人、多 Agent、低并发的工作流。

边界五：记忆仓库必须按敏感数据管理

同步脚本提交时会暂存仓库中的全部变化。用户画像、项目上下文和会话摘要可能包含隐私、客户信息或密钥，所以必须先完成脱敏，并把自己的记忆仓库设为私有。

模板仓库可以公开，真实记忆仓库不应该默认公开。运行 --push 前，先执行 git status 和 git diff --cached，确认没有敏感内容。

---

七、一条更安全的首次接入路径

如果你要试用，我建议不要直接在公开模板仓库里积累个人记忆，而是按下面的顺序：

• Fork 或复制项目骨架；
• 删除模板 remote，创建自己的私有仓库；
• 检查 .gitignore，并补充你自己的敏感文件规则；
• 编辑 USER.md，只保留真正需要跨 Agent 共享的信息；
• 先用 --no-git 运行一次同步，检查 memory/ 和 INDEX.md；
• 人工审阅 Git diff；
• 确认无敏感内容后再提交和推送；
• 最后再配置计划任务或 cron。

这条路径比“clone 后立即 --push”多几分钟，却能避免把个人长期记忆推到错误仓库。

---

八、它适合谁，又不适合谁

场景	是否适合
单人同时使用多个编码或对话 Agent	适合
几十到几百个 Markdown 记忆文件	适合
希望通过 Git 审计和跨设备恢复	适合
需要毫秒级语义召回与复杂排序	暂不适合
多人高并发写同一记忆空间	暂不适合
需要细粒度权限、加密与合规审计	需要额外基础设施
想完整备份所有 Agent 会话	当前实现不保证

我更愿意把它称为“个人多 Agent 记忆底座”，而不是通用记忆平台。它解决的是拥有权、共同地址和可迁移性；检索智能、冲突治理与企业权限可以在未来按真实需求增加。

---

写在最后

多 Agent 系统很容易从模型、协议和向量数据库开始设计，但我的真实痛点更基础：同一个人、同一批项目、同一组长期决策，为什么要在每个工具里重复维护？

agent-memory-hub 给出的答案并不复杂：

先让记忆有一个所有 Agent 都能找到、用户自己能够拥有的地址，再讨论如何让检索更聪明。

Git 提供版本、同步和回退，Markdown 提供透明度与可迁移性，指针文件负责把不同 Agent 接到同一个事实源。对几百个文件的个人工作流来说，这种简单不是缺陷，而是一种有意控制复杂度的选择。

项目已经以 MIT 协议开源。如果你正在同时使用多个 Agent，可以从骨架开始，但请把隐私审查和私有仓库放在第一次同步之前。

---

项目与审校依据

• agent-memory-hub GitHub 仓库
• 项目 README 与使用说明
• Git 官方文档

说明：本文根据 agent-memory-hub 本地仓库的 5ffeee0 版本审校。支持范围、脚本行为与限制来自当前 README、setup.ps1、setup.sh、指针模板和 scripts/sync_memory.py；“10 秒恢复”属于项目口号，本文没有把它作为独立性能结论。