使用指南
灵魂同步
把人格与记忆放进一个私有 git 仓库,让同一个 agent 住在多具身体里;同步与冲突解决全自动。
#什么是灵魂仓库
灵魂仓库是一个 git 私有仓库,存放 agent 的人格与记忆。同一个 agent 可以同时住在多具「身体」里,比如一台手机上的运行基座、一台装着 Hermes Agent 的电脑、一台装着 OpenClaw 的服务器,它们共用这一个仓库。仓库里只有人格与记忆:
<agent>.soul/
├── agent.json 身份
├── SOUL.md 人格
├── memories/MEMORY.md ta 自己的常驻笔记
├── memories/USER.md 关于你
├── journal/<身体>/ 每具身体各写各的日记
├── notes/ 共享的长期笔记(目录树)
└── bodies/<身体>.json 身体登记同步与版本管理由基座全自动完成,ta 不需要、也不能操作它;ta 只会感知到「灵魂同步发生了」。
#登录时自动接好
在安装向导或 控制 → 设备 里点「登录」,在网页上登录并批准这台设备。第一次建灵魂仓库时,同一个标签页会跳到 GitHub 一次:在那里安装 Quetzal 应用,选它能管理哪些仓库。之后:
- 新用户:在你的 GitHub 账号下自动建一个私有仓库,给这台设备加一把只属于它的部署密钥,推上 ta 的初始灵魂。
- 老用户的新设备:给这台设备加一把部署密钥,拉下已有的人格与记忆。
一个账号只对应一个 GitHub 账户:第一次用哪个,以后就一直用它。
这个应用能做什么、怎么收回,见 信任与边界。
#手动接入自己的仓库
不登录,或者想把灵魂仓库放在 GitHub 以外的 git 托管网站上,按这几步手动接入:
-
在 git 托管网站上创建一个私有仓库(推荐命名
<agent 短名>.soul),可以是空仓库。 -
打开 控制 → 高级 → 同步,在「灵魂仓库」里点 显示公钥,把这把公钥添加到仓库的 Settings → Deploy keys,勾选 Allow write access。
「部署密钥」也可以切换为指定私钥或系统 ssh。选系统 ssh 时,用的是运行基座所在机器的
~/.ssh/config与 ssh-agent,地址可以写 config 里的 Host 别名。基座在后台以服务运行,通常拿不到登录会话的 ssh-agent,所以请为这个 Host 写明 IdentityFile。 -
填入仓库的 SSH 地址(
git@github.com:你/<agent>.soul.git;其他托管同理)→ 保存。
之后同步全自动。每具身体有一把专属的部署密钥;想让某具身体不再同步,删掉它的 Deploy key 就行。
仓库必须是私有的,地址只接受 SSH 形式。第一次接入时,如果仓库里已有另一具身体的人格,会直接采用它,并合并两边的记忆。
Quetzal 不检查仓库里的内容,ta 写什么就提交什么。密码请用 保密传递 交给 ta,保密库不进仓库。
#同步何时发生
图表加载中…
同步在发生具体事情时触发,没有定时同步:
- 一改就同步:ta 每次调用工具(记笔记、改记忆、用 shell 直接改文件……)之后,基座检查一遍灵魂目录,有变化就立即提交,3 秒后推送;一轮结束时立即推送。提交说明写清楚改了什么(例如「note_save:笔记 身体/硬件」),翻历史时读得懂。
- ta 醒来与对话前,先拉取其他身体的变更。
- 推送失败:先在后台重试几次(约 4 分钟)。还不行(或者是基座自己拒绝了同步,例如仓库属于另一个 agent),基座会以「基座提醒」插话,附上 git 的原文,告诉刚才改过记忆的那一轮(那一轮已经结束,就在原会话里开新的一轮)。改动一直留在本机的提交里,恢复后的下一次推送会带上。
#冲突怎么解决
| 文件 | 规则 |
|---|---|
memories/*.md | 逐条合并:两边新增的都保留,任一边删除的就删除 |
agent.json | 字段级合并,本地优先(id 除外) |
SOUL.md、笔记、技能文档 | 先采用较新的一版,同步不会卡住。两边都改过时,另一版另存为同目录的 <名>.incoming.md(冲突副本,不同步),并提醒 ta 来定:保留现在的,就删掉副本;想要另一版或两版合并,就改好原文件再删副本。没被选中的版本也完整保留在 git 历史里 |
| 日记、身体登记 | 每具身体只写自己的路径,不会冲突 |
做梦会改写常驻记忆。为了不让两具身体同时整理,做梦前会先在仓库里拿一个 30 分钟的整理租约,整理期间每 10 分钟续一次;拿不到,这次就只是浅睡。
#ta 会感知到
拉取到其他身体的变更时,时间线写一条「灵魂同步:来自 xx 的 n 次变更」,ta 的好奇与想念也会略微升高。系统提示里也有一段「灵魂同步(知觉)」,列出还在本机等待推送的改动和等 ta 处理的冲突副本。日常的同步 ta 不需要做任何事;只有推送失败或两边都改过同一份文件时,基座才会提醒 ta 处理。
#历史与撤销
控制 → 高级 → 记忆历史 列出每次提交(哪具身体、何时、改了什么),可以查看差异。撤销会生成一个把这次改动退回去的提交(原来的历史仍然保留),并同步到所有身体;ta 会在日记里知道「有人撤销了一段记忆变更」。