v0.4.2 でプラグインが pip インストール可能になってから 6 週間後、hermes-memory-pgvector v0.5.0 がリリースされました。0.x 系で本当に破壊的な変更を含む最初のリリースであり、その理由は、そもそも最初から採用すべきではなかった名前にあります。
衝突
インポートパッケージ名は pgvector でした。その名前は pgvector-python が所有しています。同じ virtualenv に両方を入れると、最後に入ったほうがトップレベル名を奪い、その時点でこのプラグインの discovery シム はまったく別のモジュールを読み込んでしまう可能性がありました。
この失敗モードこそが、これを少し大きめのバージョンアップに値するものにしています。ローダーは不正な import を「プラグイン不在」とみなし、単一のログ行だけを残して組み込みメモリへフォールバックします。クラッシュはしません。単に全体でメモリ共有が静かに止まり、数週間後に想起結果が空で戻ってきたときにはじめて気づくのです。
そのため、インポートパッケージ名は現在 hermes_pgvector です。変わっていないものは 3 つあります。別々の名前空間であり、移動したのはそのうち 1 つだけだからです。
- ディストリビューション — 依然として
hermes-memory-pgvector - CLI — 依然として
hermes-pgvector - hermes provider — 依然として
pgvector(memory.provider: pgvector)
アップグレード
v0.5.0 では hermes_agent.memory_providers の エントリーポイント を宣言しているため、そのような方法でプラグインを解決できる十分新しいホストでは、通常の pip install だけで足り、シム は不要になりました。とはいえ シム ディレクトリ は エントリーポイント より優先されるため、古いものは削除しなければなりません。
pip install -U hermes-memory-pgvector
# preferred: drop the shim, let the entry point resolve it
hermes-pgvector install --remove
# older host that only scans plugin directories:
hermes-pgvector install --force
hermes memory status # expect: Provider: pgvector; Status: available
離れる前にスケジュール済みジョブを確認してください。 python -m pgvector ... の呼び出しはすべて hermes-pgvector ... に変更する必要があります。古い呼び出しは静かに失敗します。つまり、夜間のバックフィルはただ停止し、埋め込み障害中に書き込まれた行は検索不能のまま残ります。
sudo grep -rl 'python -m pgvector' /etc/systemd/system/ /etc/cron.d/
想定していなかった部分
追跡対象 24 ファイルすべてを対象にしたフルコードベースのレビューで、28 件の確定事項が見つかりました。痛かったのは境界ケースではなく、このリポジトリ内で設定契約が完全に食い違っているものです。どれも正しく設定されているように見せながら、制御を静かに反転させていました。
allowed_themesは文字列として宣言され、リストとして消費されていました。 文字列の allow-list は 1 文字ずつ反復されるため、すべての theme が membership test に失敗し、全体がdefaultにルーティングされていました。アイデンティティのガバナンスは、まったく逆のことをしながら設定済みに見えていました。- Boolean トグルは
falseを無視していました。embed_on_write、sync_turns、hybrid_search、bulk_sync_on_initは schema 上は文字列の"true"/"false"として宣言されているのに、単純な truthiness で読み取られていました。bool("false")はTrueです。 - 埋め込みタイムアウトは 設定 から一切流し込まれていませんでした。 どの呼び出し元もハードコードされた 10秒 を使っていました。6–17秒 で応答する エンドポイント に対しては、多数の 書き込み が タイムアウト し、NULLの埋め込み で着地していました。しかも各試行が必要な 応答時間 より 低く 上限設定されていたため、再試行 は助けになりませんでした。現在は経路ごとに分割されています:
embed_timeout(10秒, エージェントのスレッド) とembed_write_timeout(30秒, バックグラウンド書き込み処理)。 replace()は 0 行しか更新していませんでした。 一括 UPDATE がUNIQUE(agent_identity, target, content)に衝突してUniqueViolationを投げるため、2 件以上に一致する replace は何も行わず、その間に組み込みツールの state だけが先へ進んでいました。- すべての conversation turn が 2 回書き込まれていました。
sync_turnとon_session_endの両方が同じ turn を記録しており、conversationsには unique constraint がありません。 - 死んだ database は無音でした。 worker の failure は
debugにしか記録されず、_healthyは再チェックされなかったため、Postgres の restart により、その session の durable 書き込み はすべて何の合図もなく破棄されました。
これが、このリリースの正直な話です。rename が見出しであり、設定 バグこそが、1.0 ではなく今 rename をやる価値があった理由です。
アイデンティティの バケット分け は、現在は両側で強制されています
新しい external-group、whatsapp-dm、そして _bench は 書き込み-side の sink にしかなっていませんでした。アイデンティティの正規化は identity から PII を取り除いていましたが、message body は依然として content にあり、read 時点では何もフィルタされていませんでした。そのため、どの theme も scope='all' を通じて DM content を context に取り込めたのです。現在は scope='all' がそれらの sink を除外し、明示的に 1 つ名前を挙げることも拒否されます。バケット である agent は自分自身の 行 への完全なアクセスを保持し、通常のテーマ間 recall は変わりません。
慎重に読む価値のある注意点が 1 つあります。ゲート は バケット の 名前 によって除外し、バケット分け は 書き込み 時に行われます。行 は後から遡って書き換えられることはありません。それは意図的です。書き換えると履歴 行 が再想起不能になってしまうからです。キー が バケット 化される前に書かれた 行 は、元の識別情報 を保持します。hermes-pgvector remap --old <raw> --new whatsapp-dm で移行をプレビューでき、実際に実行するには --execute を追加します。
検証
スキップモード で 100 テスト、pgvector 0.8.6 を備え、4 つの マイグレーション をすべて適用した 稼働中のPostgres 16 に対して 145 テスト。今回の リリース では スキーマの変更 も新しい マイグレーション もありません。
更新 — v0.5.1
v0.5.1 は 1 時間後にリリースされました。この系統で、先送りにすべきではない リリース です。たった 1 回の memory remove で、1 つではなくテーマのミラーされたエントリがすべて削除されていました。
組み込みツールの remove op は対象を old_text に持ち、content は空のままにします。ホストはそれを content ではなく metadata 経由で渡します。ところが _worker は old_text=item.content を渡していたため、常に "" になっていました。すると store.remove は content LIKE '%%' を組み立て、それは すべて の row に一致します。1 回の remove で、その (agent_identity, target) ペアのミラー全体が消えていました。組み込み store は一切影響を受けず、影響を受けたのは pgvector mirror だけです。reference deployment の被害を確認したところ、損傷は見つかりませんでした。各 theme の履歴は途切れなく続いており、それは主に、実運用で remove がどれほどまれかを示しています。
これは 2 層で修正されています。無音の 全範囲削除 に対しては 1 層では不十分だからです。_worker は現在 extra["old_text"] を読み、使える対象のない remove を拒否します。さらに store.remove() は空の パターン を明示的に拒否するため、削除はどの呼び出し元からも省略によって到達できません。remove() はまた、組み込み実装に合わせて最大 1 行しか削除しなくなりました。
同じ リリース では、その背後にあった空の content 問題も修正されました。空の add/replace は何も拒否しなかったため、embed() が決して処理できない row が存在し得ました。blank text に対しては EmbeddingError("empty input") が無条件で発生します。夜間の backfill はその row を毎回再試行し、failed を 0 より上に固定し、remaining == 0 を到達不能にしていました。これは operator が実際に見るたった 1 つの signal を壊します。つまり、永久に詰まった row は新たな本物の failure と区別できなくなるのです。空の 書き込み は現在スキップされ(remove は除外)、埋め込み不能の row は sweep から除外され、unembeddable として別個に報告されます。
どちらも見えなかったので、名前を挙げておく価値のある小さな点が 2 つあります。Postgres の trim() は空白だけを取り除くため、改行やタブだけを持つ row はそのまま通過して、やはり永久に失敗していました。現在はすべての site で content ~ '\S' を使っています。そしてそれらの predicate は通常の f-string だったため、\S は無効な escape でした。今日の時点では 4 件の DeprecationWarning、3.12+ では SyntaxWarning、さらに -W error では module の import が完全に失敗します。そうなると hermes-agent の loader は静かに built-in memory にフォールバックしてしまうでしょう。
検証: スキップモード で 118 テスト、pgvector 0.8.6 を備え、4 つの マイグレーション をすべて適用した 稼働中のPostgres 16 に対して 164 テスト。2 回の レビュー作業 があり、1 回目でデータ損失バグが見つかり、2 回目でその修正に含まれていた壊れた escape sequence が見つかりました。
入手する
pip install hermes-memory-pgvector
ソース、アップグレードノート、完全な 設定 reference は GitHub にあります:
