hermes-memory-pgvector 1.0 : une surface mémoire stable

hermes-memory-pgvector 1.0.0 est sorti. C'est la première version où nous nous engageons à ne pas casser les éléments contre lesquels vous écrivez vos scripts. Cet article couvre ce qu'est le plugin, ce que garantit la 1.0, ce qu'a révélé la revue de pré-version, et comment effectuer la mise à niveau.

Ce que c'est

hermes-memory-pgvector est un fournisseur de mémoire Postgres + pgvector pour hermes-agent. Il s'agit d'une couche de mémoire partagée pour une flotte d'agents coopérants, construite sur une instance Postgres et un point de terminaison d'embedding que vous faites probablement déjà tourner.

Les règles de conception n'ont pas changé depuis le premier article :

Couche de stockage, pas un modèle de mémoire. Les agents continuent à appeler l'outil memory intégré. Le plugin réplique ces écritures dans Postgres et stocke les tours de conversation substantiels pour la recherche sémantique.
Pas de LLM dans le chemin critique de la mémoire. Les embeddings sont des calculs vectoriels. Il n'y a pas de dérivation, pas de boucle dialectique, pas de cycle de rêve.
Thèmes par agent par défaut. Chaque ligne porte un agent_identity. Le rappel reste dans le thème courant sauf si l'agent demande scope='all'.
Dégradation douce. Si le point de terminaison d'embedding est en panne, les écritures se dégradent en texte seul. Si la file d'attente d'écriture est pleine, l'écriture est abandonnée avec un avertissement unique. Si la base de données est en panne, le plugin journalise et saute. Aucune exception n'atteint la boucle de l'agent.
Séparation admin/runtime. Le DDL s'exécute une fois en tant que superutilisateur via hermes-pgvector migrate. Le rôle runtime n'obtient que le DML.

Ce que signifie la 1.0

À partir de la 1.0.0, le projet suit la gestion sémantique de versions sur sa surface publique :

clés de configuration plugins.pgvector.*
noms et paramètres d'outils (recall_memory, recall_conversation)
commandes CLI, drapeaux et codes de sortie
noms de tables et de colonnes de la base de données
le nom du fournisseur pgvector et le point d'entrée pip

Au sein de la 1.x, cette surface peut s'étendre, mais rien dans la liste n'est renommé ou supprimé, et aucun comportement par défaut ne change, sans une 2.0. MemoryStore et les autres classes et modules Python sont internes et non couverts. Un fichier de migration publié n'est jamais modifié en place ; les changements de schéma sont livrés sous forme de nouvelle migration numérotée.

La matrice de support est testée en CI à chaque push : Python 3.11, 3.12 et 3.13 contre PostgreSQL 16, 17 et 18 avec pgvector 0.5.0 ou plus récent. Une suite de conformité hermes-agent en amont s'exécute contre une ref épinglée, avec une vérification hebdomadaire non bloquante de la dérive par rapport à la branche main en amont.

Ce que la revue a trouvé

La 1.0.0 n'est pas un re-taguage de la release candidate, qui n'a jamais été publiée sur PyPI. Avant la sortie, nous avons mené une revue multi-passes sur l'ensemble du code : plusieurs passes avec des agents relecteurs IA en parallèle, où une conclusion nécessitait une reproduction concrète ou une vérification indépendante avant que quiconque n'agisse. La 0.6.0 est sortie d'une revue antérieure de préparation à la 1.0.

Elle a trouvé un bug de sévérité Haute, et c'était un bug de perte de données. hermes-pgvector remap --old X --new X --execute supprimait toutes les lignes memory_entries pour le thème X et sortait avec le code 0. Chaque ligne entrait en conflit avec elle-même à l'insertion, puis la suppression retirait les originaux. remap refuse désormais les --old et --new vides ou identiques avec le code de sortie 1, y compris en dry-run.

Les conclusions de sévérité Moyenne et Faible méritent un coup d'œil si vous l'utilisez en production :

identity_signature() lisait la configuration figée au démarrage, donc les modifications de allowed_themes ou identity_aliases n'atteignaient pas les agents passerelle mis en cache avant un redémarrage. Il relit désormais config.yaml à chaque modification.
Le filet de sécurité on_session_end pouvait écrire deux fois les tours utilisateur multimodaux et pouvait stocker un scaffolding /skill volumineux.
replace() avec un old_text vide écrasait une ligne arbitraire.
Le client d'embedding acceptait des vecteurs contenant NaN, Infinity ou null. La base de données les rejetait et la ligne durable était perdue. Ils se dégradent désormais en ligne texte seul comme toute autre défaillance d'embedding.
backfill réessayait indéfiniment les lignes vides composées d'espaces non-ASCII, et échouait sur toutes les lignes des bases de données SQL_ASCII.
Un --config explicite qui ne pouvait pas être lu se contentait auparavant d'avertir et retombait silencieusement sur le DSN par défaut. C'est désormais une erreur.
Les chats de forum Telegram (topic), les rooms LINE et les sessions webhook n'étaient pas reconnus comme des sessions multi-parties, donc leurs clés de session brutes, incluant un identifiant de participant, devenaient des thèmes à part entière. Ils atterrissent désormais dans le bucket partagé external-group comme les autres trafic de groupe.

La suite de tests est passée de 442 à plus de 500 tests, dont environ 80 tests de régression pour ces corrections. La CI les exécute contre des Postgres 16, 17 et 18 en live, et échoue désormais sur tout test sauté, donc un environnement cassé ne peut plus passer au vert.

Installation et mise à niveau

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

Si vous venez de la 0.6.0, il n'y a pas de changements de schéma ni de nouvelles migrations. Mettez à niveau le package, redémarrez, et lisez les notes de mise à niveau 1.0.0 dans le CHANGELOG. Voici les changements de comportement :

remap refuse les --old/--new vides ou identiques.
Un --config explicite qui ne peut pas être lu ou analysé est désormais une erreur au lieu d'un repli silencieux sur le DSN par défaut.
Les clés de configuration booléennes n'acceptent que 1/true/yes/on et 0/false/no/off. Les valeurs vides ou non reconnues signifient désormais la valeur par défaut de la clé.
prefetch_budget, prefetch_limit et min_similarity sont bornés à leurs plages documentées.
Les nouvelles écritures provenant des sessions forum Telegram, room LINE et webhook vont vers le thème external-group ; les lignes déjà écrites sous leurs clés brutes restent où elles sont.
Les sauvegardes d'installation vont désormais dans un répertoire caché plugins/.pgvector.bak-<ts>. Supprimez tout ancien répertoire visible pgvector.bak* pour que hermes-agent ne le découvre pas comme un second fournisseur.

Si vous venez d'une version antérieure à 0.6.0, lisez d'abord les notes 0.6.0, et suivez la règle d'ordonnancement qui s'y trouve : mettez à niveau le package sur chaque hôte qui écrit dans la base de données avant d'exécuter migrate. docs/upgrading.md contient la procédure complète.

Liens

Le projet est sous licence BSD-3-Clause, copyright Green Yoga Inc. Les rapports de bugs et les PR ciblées sont les bienvenus.