记录一次记忆服务的升级（2026-08-03）

跨大版本升级，先想清楚怎么退回去，比升级本身更重要

OpenViking 从 0.3.24 升到 0.4.12，跨度不小。这天没有新功能，只有一次升级和围绕它的几件收尾——因为记忆服务是对所有「上面」的项目都生效的那一层，不能升一半。

一次跨大版本的升级

从 0.3.24 → 0.4.12，升级成功。

跨度大，意味着大概率有破坏性变更。这一版确实有。

最直接的一条：升级后，root key 不能再访问 tenant 数据 API。

之前用 root key 一把梭的方式失效了。处理办法是按新规则签发一个 default/wu 的 admin user key，并更新 hermes 的 .env，让它改用这把新 key 访问数据。

这条不处理，「记忆写不进去」这类问题会以很奇怪的形式冒出来——所以它排在升级清单的第一项。

第二件事是把 agent_evolution 显式开启。

新版里它的默认行为可能变了，为了保持原来的行为，选择把它明确写进配置，而不是依赖默认值。

显式声明和依赖默认值，差别不在功能，在于以后升级时会不会再踩一次。

升级前准备好了回滚，路径在 C:/openviking/upgrade_backup/，里面包含三样：

wheel 是程序本体、data 是数据、conf 是配置——三样都在，才能退回到一个能跑起来的状态。这也是我给「升级」定的标准动作：先想好怎么退，再动手升。

最后一件事：插件里针对错误文案的 retry 匹配，补上了 0.3.24+ 的版本。

0.4.12 的错误文案和之前不一样，原来的匹配匹配不到了，retry 逻辑会失效。把新版本的文案补进去之后，重试才恢复正常。

升级这件事，也分三层。

最表面的是那行版本号：0.3.24 到 0.4.12。

中间一层是那条破坏性变更——root key 不能再访问 tenant 数据。它提醒我：大版本之间的「能用」，往往换了一套前提。旧的前提（root key 一把梭）没了，就得去找新的前提（default/wu admin user key），而不是把报错当成偶发故障反复重试。

最里面一层，是 C:/openviking/upgrade_backup/ 那个目录。 升级成功的时候，它一点用都没有；但它的存在，决定了你敢不敢升。记忆服务这种东西，一旦升坏，影响的是所有依赖它的项目——所以升级前先留好退路，不是谨慎，是必要。