我为 AI 代理构建了一个免费、Git 原生的内存层——原因与实现方法

Source: Dev.to

我一直挥之不去的问题

我经常使用 AI 代理——Windows 上的 Claude、通过 Codex 的 macOS Claude、以及用于二次意见的 GPT‑4o。每一次会话，代理都是陌生人。它不了解我的偏好、我的项目，什么都不知道。

现有的“记忆”方案都有同样的问题：付费 API、数据存放在他们的服务器上、单模型锁定。没有一种感觉是对的。

解决方案：agent‑soul

agent‑soul 是一个 Git 原生的记忆框架，具备以下特性：

• 免费 – 无付费 API 或月费
• 私密 – 所有数据都保存在你自己的 GitHub 仓库中
• 模型无关 – 兼容任何 LLM

每条记忆都是一个追加式的 JSON 事件，存放在私有的 GitHub 仓库中。Python 编译器通过 GitHub Actions 在每次 push 时运行，处理这些事件并输出干净的 Markdown 文件。在每次代理会话开始时，代理通过系统提示读取这些文件。这就是完整的系统。

┌─────────────────────────────────────────────────────────┐
│                    agent-soul repo                      │
│                                                         │
│  sources//YYYY-MM-DD.ndjson   ← 追加式   │
│      事件流（发生了什么）                               │
│                                                         │
│  canonical/                            ← CI 编译产出│
│    profile.md          ← 用户是谁                     │
│    stable-memory.md   ← 持久事实                     │
└─────────────────────────────────────────────────────────┘

添加事件

python scripts/add_event.py \
  --source windows-claude \
  --kind preference \
  --scope stable \
  --summary "User prefers explicit TypeScript types over inferred generics."

推送更改后，GitHub Actions 会自动编译。

与付费记忆 API 的对比

核心概念

• 追加式事件溯源 – 每一次记忆变更都是一次 Git 提交，形成完整的审计日志。你可以回滚、比较或 grep 任意内容。
• Supersedes 字段 – 当事实改变时，写入引用旧事件的新事件。编译器会排除已被取代的事件，同时保留历史。
• 冲突检测 – 编译器使用 Jaccard 相似度标记矛盾的事件。结果写入 canonical/conflicts.md。
• 多代理同步 – Windows 上的 Claude 与 macOS 上的 Claude 共享同一套编译后的记忆。任何能够 git pull 的代理都能保持同步。

入门指南

1. Fork 本仓库。
2. 填写四个角色文件（SOUL.md、IDENTITY.md、USER.md、VOICE.md）。
3. 在你的 fork 中启用 GitHub Actions。
4. 将 JOIN.md 中的会话协议粘贴到你的代理配置文件里。
5. 推送一次 – Actions 将编译记忆。下次会话时，代理就会记住你。

整个设置大约需要 10 分钟。

贡献

欢迎提交 Issue 和 Pull Request。如果你一直想让你的 AI 代理真正记住你是谁——而不必付费或信任别人的服务器——不妨试试 agent‑soul。