hermes-memory-pgvector 1.0: Eine stabile Speicher-Schnittstelle

hermes-memory-pgvector 1.0.0 ist veröffentlicht. Es ist die erste Version, bei der wir versprechen, die Teile nicht zu brechen, gegen die Sie Skripte schreiben. Dieser Beitrag behandelt, was das Plugin ist, was 1.0 garantiert, was die Vorabversionsprüfung ergeben hat und wie Sie aktualisieren.

Was es ist

hermes-memory-pgvector ist ein Postgres- und pgvector-Speicheranbieter für hermes-agent. Es ist eine gemeinsame Speicherebene für eine Flotte kooperierender Agenten, die auf einer Postgres-Instanz und einem Embedding-Endpunkt aufbaut, den Sie wahrscheinlich bereits betreiben.

Die Designregeln haben sich seit dem ersten Beitrag nicht geändert:

Speicherebene, kein Speichermodell. Agenten rufen weiterhin das eingebaute memory-Tool auf. Das Plugin spiegelt diese Schreibvorgänge in Postgres und speichert substanzielle Chat-Beiträge für die semantische Suche.
Kein LLM im heißen Speicherpfad. Embeddings sind Vektorrechnung. Es gibt keinen Deriver, keinen dialektischen Loop, keinen Traumzyklus.
Pro-Agent-Themen standardmäßig. Jede Zeile trägt eine agent_identity. Der Abruf bleibt innerhalb des aktuellen Themas, sofern der Agent nicht scope='all' anfordert.
Fehlertolerant. Wenn der Embed-Endpunkt ausfällt, werden Schreibvorgänge auf reinen Text reduziert. Wenn die Schreibwarteschlange voll ist, wird der Schreibvorgang mit einer einmaligen Warnung verworfen. Wenn die Datenbank ausfällt, protokolliert das Plugin und überspringt. Keine Ausnahme erreicht den Agenten-Loop.
Trennung von Administration und Laufzeit. DDL wird einmal als Superuser über hermes-pgvector migrate ausgeführt. Die Laufzeitrolle erhält nur DML.

Was 1.0 bedeutet

Ab 1.0.0 folgt das Projekt Semantic Versioning für seine öffentliche Schnittstelle:

plugins.pgvector.* Konfigurationsschlüssel
Tool-Namen und Parameter (recall_memory, recall_conversation)
CLI-Befehle, Flags und Exit-Codes
Datenbank-Tabellen- und Spaltennamen
der pgvector-Anbietername und der pip-Einstiegspunkt

Innerhalb von 1.x darf diese Schnittstelle wachsen, aber nichts auf der Liste wird umbenannt oder entfernt, und kein Standard ändert das Verhalten, ohne dass eine 2.0 erscheint. MemoryStore und die anderen Python-Klassen und -Module sind intern und nicht abgedeckt. Eine veröffentlichte Migrationsdatei wird nie an Ort und Stelle bearbeitet; Schemaänderungen werden als neue nummerierte Migration ausgeliefert.

Die Support-Matrix wird in CI bei jedem Push getestet: Python 3.11, 3.12 und 3.13 gegen PostgreSQL 16, 17 und 18 mit pgvector 0.5.0 oder neuer. Eine hermes-agent-Konformitäts-Suite von Upstream läuft gegen einen festgepinnten Ref, mit einer nicht blockierenden wöchentlichen Drift-Prüfung gegen Upstream main.

Was die Prüfung ergeben hat

1.0.0 ist kein Re-Tag des Release-Kandidaten, der nie auf PyPI veröffentlicht wurde. Vor der Veröffentlichung haben wir eine mehrstufige, codebasenweite Prüfung durchgeführt: mehrere Durchläufe mit parallelen KI-Prüfer-Agenten, wobei ein Befund eine konkrete Reproduktion oder eine unabhängige Überprüfung erforderte, bevor jemand handelte. 0.6.0 entstand aus einer früheren 1.0-Bereitschaftsprüfung.

Dabei wurde ein Bug mit hoher Schwere gefunden, und es war ein Datenverlust-Bug. hermes-pgvector remap --old X --new X --execute löschte jede memory_entries-Zeile für Theme X und beendete sich mit Exit 0. Jede Zeile stand beim Insert mit sich selbst in Konflikt, dann entfernte das Delete die Originale. remap verweigert nun leere oder identische --old und --new mit Exit 1, auch im Dry-Run.

Die Befunde mit mittlerer und niedriger Schwere lohnen einen Blick, wenn Sie dies in der Produktion betreiben:

identity_signature() las die beim Start eingefrorene Konfiguration, sodass Änderungen an allowed_themes oder identity_aliases zwischengespeicherte Gateway-Agenten erst nach einem Neustart erreichten. Es liest nun config.yaml bei Änderung erneut.
Die on_session_end-Rückfallebene konnte multimodale Benutzerbeiträge doppelt schreiben und große /skill-Gerüste speichern.
replace() mit einem leeren old_text überschrieb eine beliebige Zeile.
Der Embed-Client akzeptierte Vektoren mit NaN, Infinity oder null. Die Datenbank wies sie zurück und die dauerhafte Zeile ging verloren. Sie werden nun wie jeder andere Embed-Fehler zu einer reinen Textzeile herabgestuft.
backfill wiederholte leere Zeilen aus Nicht-ASCII-Leerzeichen für immer und schlug auf SQL_ASCII-Datenbanken für jede Zeile fehl.
Eine explizite --config, die nicht gelesen werden konnte, warnte zuvor und fiel stillschweigend auf die Standard-DSN zurück. Es ist nun ein Fehler.
Telegram-Forum-(Topic-)Chats, LINE-Räume und Webhook-Sitzungen wurden nicht als Mehrparteiensitzungen erkannt, sodass ihre rohen Sitzungsschlüssel, einschließlich einer Teilnehmer-ID, zu eigenen Themen wurden. Sie landen nun wie anderer Gruppenverkehr im gemeinsamen external-group-Bucket.

Die Test-Suite wuchs von 442 auf über 500 Tests, einschließlich etwa 80 Regressionstests für diese Korrekturen. CI führt sie gegen laufende Postgres 16, 17 und 18 aus und schlägt nun bei jedem übersprungenen Test fehl, sodass eine defekte Umgebung nicht mehr grün bestehen kann.

Installation und Upgrade

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

Wenn Sie von 0.6.0 kommen, gibt es keine Schemaänderungen und keine neuen Migrationen. Aktualisieren Sie das Paket, starten Sie neu und lesen Sie die 1.0.0-Upgrade-Hinweise im CHANGELOG. Diese ändern das Verhalten:

remap verweigert leere oder identische --old/--new.
Eine explizite --config, die nicht gelesen oder geparst werden kann, ist nun ein Fehler statt eines stillschweigenden Falls auf die Standard-DSN.
Boolesche Konfigurationsschlüssel akzeptieren nur 1/true/yes/on und 0/false/no/off. Leere oder nicht erkannte Werte bedeuten nun den Standard des Schlüssels.
prefetch_budget, prefetch_limit und min_similarity werden auf ihre dokumentierten Bereiche begrenzt.
Neue Schreibvorgänge aus Telegram-Forum-, LINE-Raum- und Webhook-Sitzungen gehen in das external-group-Thema; bereits unter ihren rohen Schlüsseln geschriebene Zeilen bleiben, wo sie sind.
Installations-Backups werden nun in ein verstecktes plugins/.pgvector.bak-<ts>-Verzeichnis verschoben. Entfernen Sie jedes alte sichtbare pgvector.bak*-Verzeichnis, damit hermes-agent es nicht als zweiten Anbieter entdeckt.

Wenn Sie von einer älteren Version als 0.6.0 kommen, lesen Sie zuerst die 0.6.0-Hinweise und befolgen Sie die dortige Reihenfolgeregel: Aktualisieren Sie das Paket auf jedem Host, der in die Datenbank schreibt, bevor Sie migrate ausführen. docs/upgrading.md enthält die vollständige Vorgehensweise.

Links

Das Projekt ist BSD-3-Clause lizenziert, Copyright Green Yoga Inc. Fehlerberichte und fokussierte PRs sind willkommen.