Repository navigation
v0.31.0 — 通道密钥从源码种子确定性派生,密码以加密形态写进项目文档
这一版解决什么问题
用户的诉求(原话要点):不管换什么设备、换什么 AI,只要装了项目、读了项目文档,就该正确畅通地上传和取回记忆;密码要用加密的方式写进项目文档本身,不要明文;而且加密方式必须保证所有主流 AI 和 agent 都读得懂。
旧设计的病根:密钥的源头是通道目录里的一个文件 channel.key。于是「谁有那把钥匙」本身变成了一件需要向人解释的事——新设备装完项目、读完文档,如果没同步到那个文件夹,仍然拿不到密钥。文档写得再清楚也改变不了这一点。
v0.30.3 修的是「本机历史口令盖住通道密钥」,但通道密钥自己仍要靠文件流转。这一版把源头拔掉了。
新设计:密钥从源码种子确定性派生
| v0.30.3 及之前 | v0.31.0 | |
|---|---|---|
| 密钥来源 | os.urandom(32) 随机生成,写进通道目录 channel.key |
由源码常量种子经 PBKDF2-HMAC-SHA256(200000) 确定性派生 |
| 各端如何一致 | 靠同步那个文件 | 各自本地计算,结果逐字节相同 |
| 密码是否明文存在 | 是(云盘里躺着一个 43 字符文件) | 否(通道目录不再存明文口令) |
| AI 能否独立完成 | 否,必须调用程序 | 能:README 公布算法/盐/轮数/自检串,任何语言可复现 |
派生算法(README 逐字公布,纯标准库,零依赖):
import base64, hashlib
SEED = "membridge/mb-639d44f1/jiabaobei"
SALT = "membridge.channel.v1"
dk = hashlib.pbkdf2_hmac("sha256", SEED.encode(), SALT.encode(), 200000, 32)
key = base64.urlsafe_b64encode(dk).decode().rstrip("=") # 43 字符,即通道密钥修掉一个真实缺陷:派生只做在 CLI 层
原先只有在 cli._resolve_passphrase 里才做派生。于是库层直连(自建 agent、脚本、任何绕过 CLI 的调用)拿到 None 就报「需要口令」——「装了项目就通」在最常见的调用路径上其实并不成立。
现在 FolderTransport.publish/fetch 各自回落派生。端到端实测:「需要口令」报错 28 → 0。
顺带补上一个更该早发现的缺口:手动搬运此前完全没有加密
delta / apply 这对命令——把记忆拷到移动硬盘、U 盘、离线归档,或交给未装记忆桥的机器解密时用的正是它们——绕过了整套口令体系,cmd_delta 直接 write_text(payload) 写明文 JSON。
也就是说,最需要手动加密的搬运路径,恰恰是明文。
现补上,并与 publish/fetch 共用同一信封 membridge-delta-enc-v1、同一把口令通用:
delta新增--passphrase(加密)与--plaintext(明文,须显式确认)apply新增--passphrase;旧的明文 JSON 差异包仍能直接并入(向后兼容)- 错口令给出可执行提示,且报错里不回显口令本身
主次关系(勿写反)
自动派生是默认、是主流——日常什么都不用传,AI 读文档即可接手。
手动口令是特定情况下的选择——用于离开通道、把记忆搬到别的储存介质。
--passphrase 优先级最高、任何时候都可用,但不是日常路径。
密钥轮换(一次性,真机执行)
旧随机密钥 → 派生密钥,通道内 29 个包全部重加密,含 531 节点的大包,以及 5 个用已删环境变量 MEMBRIDGE_PASSPHRASE 加密的历史遗留包。
channel.key 改名 channel.key.legacy 留档可回滚。轮换脚本一次性、可重跑、先全解再全写(任一失败即中止,绝不做部分轮换)。
轮换过程本身出过一次事故:脚本第一版漏写
fmt字段,导致 27 个包被判为「未知信封格式」而整体跳过。因为动手前留了完整备份,直接从%TEMP%还原后修正重跑,零丢失。
诚实说明(README 里也写明,不含糊)
种子随源码公开,因此任何拿到这份源码的人都能算出通道密钥。
这是「任何人读完文档就能自己动手」与「密钥保密」之间的逻辑必然,不是实现缺陷——要让 AI 独立完成,派生输入就不能是秘密。
密钥的职责是「让各设备用同一把钥匙、且云盘只见密文」。真正挡住未授权访问的是云盘目录自身的访问权限。
验证
- 独立脚本验证「AI 读得懂」:不 import 项目任何代码,只照 README 抄算法 → 派生出正确密钥 → 通过自检串 → 解开全部 29 个包 / 600 节点。
- 零口令闭环:库层直连
publish→fetch全程无口令通过。 - 测试:151/171 通过,与改动前基线逐条比对,新增回归 0(基线 20 条失败均为沙箱缺
schtasks.exe等环境原因)。新增/改写测试 9 条,覆盖派生确定性、换种子必换密钥、库层零口令收发、默认仍加密、旧密钥优先且报告不一致、CLI 告警。 - 本机自检:
membridge sync干净(跳过 34 个重复包、零警告),membridge channel无轮换告警。
文档
README「跨设备同步」整节重写为八小节:通道是什么 / 密码是什么(种子+盐+轮数+算法+可复现代码+自检密文)/ 加解密规则 / 上传 / 取回 / 新设备三步 / 故障对照表 / 给 AI 的一页速查。
全节不含明文通道密钥,符合"用加密形态写进文档"的要求。
文档中英双语同步(追加)
中文版改完后,英文版 README_EN.md 一开始没有同步 —— 它停在 v0.30.1,
而且不只是漏几句话,是缺整节结构。现已补齐并推送(commit 86b5bc6):
- 新增整节
Cross-device sync八小节,与中文版逐条对应:通道是什么 /
密码是什么(种子 + 固定盐 + 轮数 + 算法 + 可复现代码 + 自检密文)/
加解密规则 / 上传 / 特定情况手动口令 / 取回 / 新设备三步 / 故障对照表 /
给 AI 的一页速查。 - 能力表同步:新增 v0.31 零配置跨设备同步条目;新增「加密钥匙(默认自动,
特殊场景可手动)」条目,主次措辞与中文版一致(自动派生=默认且主流;
手动口令=特定情况)。 - 纠正三处过时表述(中文版已改、英文版还是旧的):v0.17「channel.key
随通道走」标注为已被 v0.31 取代;init不再生成并托管口令;删除「口令也可
来自MEMBRIDGE_PASSPHRASE环境变量」的劝设文字,改为明确警告不要设。 - 补上中文版有、英文版一直缺的
pip install membridge警示。
验证方式是按英文文档独立复现派生(不 import 项目代码):得到 43 字符密钥、
指纹 d1c4、自检串解出 membridge-channel-ok —— 这既验证了英文文档完整可读,
也验证了「AI 读文档就能自己动手」这个承诺对中英两种语言同样成立。
中英两侧的自检串、种子、固定盐、迭代轮数逐项 grep 比对完全一致;两份文档
均不含明文通道密钥。全量测试 20 failed / 165 passed,与基线一致(20 条失败
均为沙箱缺 schtasks.exe),新增回归 0。
版本号描述一致性补正(追加,commit b7b19a6)
复盘本次改版时发现,v0.31.0 自己就漏改了两处版本号描述——正好是「改版必须
同步对齐文档中的版本号描述」这条要求的反面教材:
- 漏改 1:
README.md章节标题仍是「## 当前能力(v0.30)」,而README_EN.md
已是「## Status (v0.31)」,中英两版互相矛盾。改版时改了能力表内的版本号,
漏了章节标题。 - 漏改 2:
docs/roadmap.md的「版本总览(逐版本改版说明)」是改版说明的索引,
但只有 v0.30.1 及更早,v0.31.0 完全没进表(v0.31 此前只在「建议顺序」里
作为计划出现过)。
两处均已补齐。教训:改版本号不是改一处 __version__,而是全仓所有
「版本号常驻位置」遍历一遍——章节标题、能力表、改版说明索引表,都是容易
只改一半的地方;中英双档项目还要两份都对得上。
本次为纯文档改动,无代码变更。验证:中英文档标题版本号一致(均 v0.31);
全量测试 20 failed / 165 passed,与基线逐条一致,新增回归 0。
安装
git clone https://github.com/jiabaobei/memory-bridge.git
cd memory-bridge && pip install -e .
⚠️ 不要用pip install membridge—— PyPI 上的membridge是 ParrotXray 的跨进程共享内存库,不是本项目,会静默装错。