hermes-memory-pgvector 1.0：稳定的内存接口

hermes-memory-pgvector 1.0.0 已发布。这是我们承诺不会破坏您编写脚本所依赖部分的第一个版本。本文将介绍该插件是什么、1.0 版本所提供的保证、预发布审查发现了哪些问题，以及如何进行升级。

它是什么

hermes-memory-pgvector 是一个面向 hermes-agent 的 Postgres + pgvector 内存提供程序。它为一批相互协作的智能体构建了一个共享内存层，底层依赖一个 Postgres 实例以及您很可能已经在运行的某个 embedding 端点。

自第一篇介绍文章以来，其设计原则一直未曾改变：

存储层，而非内存模型。 智能体继续调用内置的 memory 工具。该插件将这些写入操作镜像到 Postgres 中，并存储具有实质内容的对话轮次以供语义检索。
内存热路径中不调用 LLM。 Embedding 只是向量计算。这里没有派生器、没有辩证循环、没有“梦境”周期。
默认按智能体划分主题。 每一行都带有 agent_identity。除非智能体明确指定 scope='all'，否则召回范围仅限于当前主题之内。
优雅降级。 如果 embedding 端点不可用，写入会降级为仅文本。如果写入队列已满，则丢弃该次写入并发出一次性警告。如果数据库不可用，插件将记录日志并跳过。不会有异常传递到智能体循环。
管理 / 运行时分离。 DDL 由超级用户通过 hermes-pgvector migrate 执行一次。运行时角色仅获得 DML 权限。

1.0 版本的含义

从 1.0.0 开始，项目在其公共接口上遵循语义化版本控制：

plugins.pgvector.* 配置项
工具名称及参数（recall_memory、recall_conversation）
CLI 命令、标志及退出码
数据库表与字段名称
pgvector 提供程序名称及 pip 入口点

在 1.x 范围内，该接口可以扩展，但除非发布 2.0 版本，否则上述列表中的任何项都不会被重命名或移除，默认行为也不会被更改。MemoryStore 及其他 Python 类与模块属于内部实现，不在保证范围内。已发布的迁移文件绝不会就地修改；架构变更以新的编号迁移文件形式发布。

支持矩阵在每次提交时都会通过 CI 进行测试：Python 3.11、3.12 和 3.13 搭配 PostgreSQL 16、17 和 18，以及 pgvector 0.5.0 或更高版本。还会针对固定引用运行上游 hermes-agent 一致性套件，并对上游 main 分支进行非阻塞的每周漂移检查。

审查发现

1.0.0 并非对发布候选版本的重新标记，因为发布候选版本从未发布到 PyPI。在正式发布之前，我们进行了多轮、全代码库的审查：由多个并行 AI 审查智能体进行的多轮审查，其中任何发现都需要具体的复现步骤或独立验证后才会被采纳。早先的 1.0 就绪审查催生了 0.6.0 版本。

审查发现了一个高严重性 Bug，并且是一个会导致数据丢失的 Bug。hermes-pgvector remap --old X --new X --execute 会删除主题 X 的所有 memory_entries 行，并以退出码 0 结束。每行在插入时都与其自身发生冲突，随后 delete 操作删除了原始数据。remap 现在会拒绝空白或相同的 --old 与 --new，并以退出码 1 退出，包括在 dry-run 模式下也是如此。

如果您在生产环境中运行该插件，以下中等和低严重性的发现也值得一读：

identity_signature() 在启动时读取的是冻结的配置，因此对 allowed_themes 或 identity_aliases 的修改，在重启之前不会反映到已缓存的网关智能体中。现在该函数会在配置变更时重新读取 config.yaml。
on_session_end 兜底逻辑可能会将多模态用户轮次写入两次，并可能存储大量的 /skill 脚手架内容。
使用空 old_text 调用 replace() 会覆盖任意一行。
Embedding 客户端曾接受包含 NaN、Infinity 或 null 的向量。数据库拒绝这些向量，导致持久化行丢失。现在它们与其他 embedding 失败一样，降级为仅文本行。
backfill 曾对由非 ASCII 空白组成的空行无限重试，并在 SQL_ASCII 数据库上使每一行都失败。
当显式指定的 --config 无法读取时，过去只会发出警告并静默回退到默认 DSN。现在这会作为错误处理。
Telegram 论坛（话题）聊天、LINE 房间和 webhook 会话未被识别为多方会话，因此它们的原始会话密钥（包括参与者 ID）会各自成为独立的主题。现在它们与其他群组流量一样，统一归入共享的 external-group 桶中。

测试套件从 442 个测试增加到 500 多个，其中包括约 80 个针对上述修复的回归测试。CI 会在真实的 Postgres 16、17 和 18 上运行这些测试，并且现在在任何测试被跳过时都会失败，因此环境异常再也无法通过绿灯。

安装与升级

pip install hermes-memory-pgvector
hermes-pgvector migrate --admin-dsn \
    "dbname=<your-memory-db> user=postgres host=/var/run/postgresql"
hermes config set memory.provider pgvector
hermes memory status

如果您从 0.6.0 升级而来，没有架构变更，也没有新的迁移。升级包、重启进程，并阅读 CHANGELOG 中的 1.0.0 升级说明。以下行为发生了变化：

remap 拒绝空白或相同的 --old/--new。
当显式指定的 --config 无法读取或解析时，现在会作为错误抛出，而不再静默回退到默认 DSN。
布尔型配置项仅接受 1/true/yes/on 与 0/false/no/off。空白或无法识别的值现在视为该配置项的默认值。
prefetch_budget、prefetch_limit 与 min_similarity 会被限制在各自文档规定范围内。
来自 Telegram 论坛、LINE 房间和 webhook 会话的新写入将归入 external-group 主题；已以其原始键写入的行将保持原样。
安装备份现在移至隐藏的 plugins/.pgvector.bak-<ts> 目录。请移除任何旧的可见 pgvector.bak* 目录，以免 hermes-agent 将其识别为第二个提供程序。

如果您来自低于 0.6.0 的版本，请先阅读 0.6.0 的升级说明，并遵循其中的顺序规则：在运行 migrate 之前，先在所有向数据库写入的主机上升级包。完整的操作步骤请参阅 docs/upgrading.md。