hermes-memory-pgvector 1.0: 安定したメモリインターフェース

hermes-memory-pgvector 1.0.0 がリリースされました。これは、スクリプトで利用する部分に対して互換性を壊さないことを初めて約束するリリースです。この記事では、プラグインの概要、1.0 で保証される内容、リリース前のレビューで判明した事項、そしてアップグレード方法について説明します。

概要

hermes-memory-pgvector は、hermes-agent 向けの Postgres + pgvector メモリプロバイダです。協調動作するエージェント群のための共有メモリレイヤーで、おそらくすでに稼働している Postgres インスタンスと、ひとつの埋め込みエンドポイント上に構築されています。

設計方針は、最初の記事以降変わっていません:

記憶モデルではなくストレージ層。 エージェントは組み込みの memory ツールを使い続けます。本プラグインはそれらの書き込みを Postgres にミラーし、セマンティック検索のために実質的なチャットターンを保存します。
メモリ処理のホットパスに LLM は介在しない。 埋め込みはベクトル演算です。派生処理も弁証法的ループもドリームサイクルも存在しません。
デフォルトでエージェントごとのテーマ。 すべての行に agent_identity が付与されます。想起は、エージェントが scope='all' を要求しない限り、現在のテーマ内に留まります。
フェイルソフト。 埋め込みエンドポイントが落ちている場合、書き込みはテキストのみに縮退します。書き込みキューが満杯の場合、書き込みは一度だけ警告を出して破棄されます。データベースが停止している場合は、プラグインがログを記録してスキップします。例外がエージェントループに到達することはありません。
管理/ランタイムの分離。 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 でテストされています: pgvector 0.5.0 以上と組み合わせた Python 3.11、3.12、3.13 と PostgreSQL 16、17、18。アップストリームの hermes-agent 準拠テストスイートはピン留めされた ref に対して実行され、アップストリームの main に対しては非ブロッキングの週次ドリフトチェックが実施されます。

レビューで判明した事項

1.0.0 はリリース候補の再タグ付けではありません(リリース候補は PyPI に公開されていません)。リリース前に複数パスにわたるコードベース全体のレビューを実施しました: 並列の AI レビュアーエージェントによる複数パスのレビューで、指摘事項は、誰かが対応する前に具体的な再現手順または独立した検証を必要としました。0.6.0 は前回の 1.0 準備レビューから生まれたものです。

その結果、重大度 High のバグがひとつ見つかりました。それはデータロスのバグです。hermes-pgvector remap --old X --new X --execute は、テーマ X のすべての memory_entries 行を削除して終了コード 0 を返しました。各行がインサートで自分自身と競合し、その後削除によって元の行が取り除かれていました。現在では remap は、ドライランを含め、--old と --new が空または同一の場合に終了コード 1 で拒否します。

Medium および Low の指摘事項は、本番環境で運用する場合に一読の価値があります:

identity_signature() が起動時に凍結された設定を読み取るため、allowed_themes や identity_aliases の変更は、エージェントを再起動するまでキャッシュされたゲートウェイエージェントに届きませんでした。現在は config.yaml の変更を検知して再読み込みします。
on_session_end のバックストップがマルチモーダルなユーザーターンを二重に書き込み、大規模な /skill のスキャフォールドを保存する可能性がありました。
空の old_text を指定した replace() が任意の上書きを行っていました。
埋め込みクライアントが NaN、Infinity、null を含むベクトルを受け付けていました。データベースはこれらを拒否し、永続化された行が失われていました。現在は他の埋め込み失敗と同様に、テキストのみの行に縮退します。
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> ディレクトリへ移動するようになりました。hermes-agent が第二のプロバイダとして検出しないよう、以前の可視状態の pgvector.bak* ディレクトリがあれば削除してください。

0.6.0 より前からアップグレードする場合は、まず 0.6.0 のノートを読み、そこに記載された順序ルールに従ってください: migrate を実行する前に、データベースに書き込むすべてのホストでパッケージをアップグレードします。docs/upgrading.md に完全な手順があります。

リンク

本プロジェクトは BSD-3-Clause で、copyright Green Yoga Inc です。バグレポートと的を絞った PR を歓迎します。