hermes-memory-pgvector は、hermes-agent のエージェント群に PostgreSQL と pgvector 上で共有される永続的なメモリを与えるオープンソースのプラグインです。バージョン 0.5.3 が PyPI で公開され、プラグイン内の最後のハードコードされた前提、つまりどの埋め込みモデルがあなたのメモリを検索可能なベクトルに変換するか、が取り除かれました。
このリリースが存在する理由
これまで、埋め込みモデルは事実上固定されていました。プラグインは各ベクトルをリテラルな 768 次元、つまりデフォルトの nomic-embed-text モデルのサイズと照合し、API キーを送る方法もなかったため、ホスト型の埋め込みサービスは利用できませんでした。
それが、私たち自身のデプロイメントにおいて実際の制約になりました。メモリデータベースを OpenAI の text-embedding-3-small に移し、OpenRouter 経由で提供するようにしました。ホストされたエンドポイントは常に起動状態ですが、自前ホストのモデルは起動に数秒かかることがあるからです。データベースのカラムは 1536 次元に変更されましたが、プラグイン側にはそれに追従できる設定がありませんでした。v0.5.3 ではそれらの設定が追加されます。
3 つの新しい設定
embed_dimは、あなたのモデルが返すベクトルの長さです。デフォルトは768なので、既存のセットアップには影響しません。すべての埋め込みは引き続きこの値に対してチェックされるため、不一致はデータベースに到達する前に即座に失敗します。embed_api_key_envは、OPENROUTER_API_KEYのようなベアラートークンを保持する環境変数の名前です。キーは設定ファイルには決して入らず、呼び出し時に読み込まれ、ログにも残りません。embed_protocolはopenai、ollama、またはautoです。デフォルトのautoは OpenAI 互換の経路を試し、Ollama のネイティブ API にフォールバックします。ホスト型サービスに対してopenaiを選ぶと、認証エラーやモデルエラーはそのまま報告され、フォールバック先からの 404 の背後に隠されることはありません。
OpenRouter 経由でプラグインを text-embedding-3-small に向ける設定は、次のようになります。
plugins:
pgvector:
embed_url: "https://openrouter.ai/api"
embed_model: "openai/text-embedding-3-small"
embed_dim: 1536
embed_api_key_env: "OPENROUTER_API_KEY"
embed_protocol: "openai"
何も変更しなくても重要な 2 つの修正
- hermes-agent プラグインローダー配下での埋め込み。 プラグインを読み込んだ後、ホスト側のローダーは
embedという名前のものを含め、すべてのサブモジュールをパッケージに再アタッチします。それがプラグインが呼び出していた関数を置き換えてしまい、埋め込みはTypeError: 'module' object is not callableで失敗し、メモリ書き込みはテキストとして保存される代わりに破棄されていました。現在、プラグインはローダーが触れない private alias を呼び出します。 - 遅いエンドポイント。 接続は受け付けたものの、タイムアウト後に応答したサーバーは bare な
TimeoutErrorを発生させ、それがプラグインのエラーハンドリングをすり抜けていました。フォールバックも再試行もなく、書き込みは失われていました。現在は、他のすべてのエンドポイント障害と同じように処理されます。
アップグレード
デフォルトは変更されていません。768 次元、認証ヘッダーなし、auto プロトコル、そして新しいデータベース移行もありません。アップグレードするには、次を実行します。
pip install -U hermes-memory-pgvector
異なるベクトルサイズのモデルへ切り替えるのは、単なる設定編集ではなくデータベース移行です。2 つの異なるモデルのベクトルは比較できないからです。README ではその手順を説明しています。カラム型を変更し、hermes-pgvector backfill で既存行を再埋め込みし、その後 HNSW インデックスを再構築します。
ソースコードと完全な設定リファレンスは GitHub にあります。