hermes-memory-pgvector 1.0: una superficie di memoria stabile

hermes-memory-pgvector 1.0.0 è disponibile. È la prima versione in cui promettiamo di non rompere le parti contro cui scrivi script. Questo articolo copre cos'è il plugin, cosa garantisce la 1.0, cosa ha evidenziato la revisione pre-rilascio e come effettuare l'aggiornamento.

Cos'è

hermes-memory-pgvector è un provider di memoria Postgres + pgvector per hermes-agent. È uno strato di memoria condivisa per una flotta di agenti cooperanti, costruito su un'istanza Postgres e un endpoint di embedding che probabilmente esegui già.

Le regole di progettazione non sono cambiate rispetto a il primo write-up:

Strato di archiviazione, non un modello di memoria. Gli agenti continuano a chiamare il tool memory integrato. Il plugin rispecchia quelle scritture in Postgres e memorizza i turni di chat sostanziali per la ricerca semantica.
Nessun LLM nel percorso critico della memoria. Gli embedding sono matematica vettoriale. Non c'è nessun deriver, nessun ciclo dialettico, nessun ciclo di dream.
Temi per agente per impostazione predefinita. Ogni riga trasporta un agent_identity. Il richiamo resta all'interno del tema corrente a meno che l'agente non richieda scope='all'.
Fail-soft. Se l'endpoint di embedding è giù, le scritture degradano a solo testo. Se la coda di scrittura è piena, la scrittura viene scartata con un avviso una tantum. Se il database è giù, il plugin registra e salta. Nessuna eccezione raggiunge il ciclo dell'agente.
Separazione admin/runtime. Il DDL viene eseguito una volta come superutente tramite hermes-pgvector migrate. Il ruolo di runtime ottiene solo il DML.

Cosa significa 1.0

Dalla 1.0.0 il progetto segue il semantic versioning sulla sua superficie pubblica:

chiavi di configurazione plugins.pgvector.*
nomi e parametri dei tool (recall_memory, recall_conversation)
comandi CLI, flag e codici di uscita
nomi di tabelle e colonne del database
il nome del provider pgvector e l'entry point pip

All'interno di 1.x quella superficie può crescere, ma nulla nella lista viene rinominato o rimosso, e nessun default cambia comportamento, senza una 2.0. MemoryStore e le altre classi e moduli Python sono interni e non sono coperti. Un file di migrazione rilasciato non viene mai modificato in loco; le modifiche allo schema vengono distribuite come una nuova migrazione numerata.

La matrice di supporto è testata in CI su ogni push: Python 3.11, 3.12 e 3.13 contro PostgreSQL 16, 17 e 18 con pgvector 0.5.0 o più recente. Una suite di conformità hermes-agent upstream viene eseguita contro un ref pinnato, con un controllo di drift settimanale non bloccante contro l'upstream main.

Cosa ha trovato la revisione

La 1.0.0 non è un nuovo tag della release candidate, che non è mai stata pubblicata su PyPI. Prima del rilascio abbiamo eseguito una revisione multi-pass sull'intero codebase: diversi passaggi con agenti revisori AI paralleli, dove un riscontro necessitava di una riproduzione concreta o di una verifica indipendente prima che qualcuno agisse su di esso. La 0.6.0 è uscita da una precedente revisione di preparazione alla 1.0.

Ha trovato un bug di gravità Alta, ed era un bug di perdita di dati. hermes-pgvector remap --old X --new X --execute eliminava ogni riga di memory_entries per il tema X e usciva con 0. Ogni riga era in conflitto con sé stessa sull'inserimento, poi l'eliminazione rimuoveva gli originali. remap ora rifiuta --old e --new vuoti o identici con exit 1, anche in dry-run.

I riscontri di gravità Media e Bassa meritano una scorsa se lo gestisci in produzione:

identity_signature() leggeva la configurazione congelata all'avvio, quindi le modifiche a allowed_themes o identity_aliases non raggiungevano gli agenti gateway in cache fino a un riavvio. Ora rilegge config.yaml ad ogni modifica.
Il backstop on_session_end poteva scrivere i turni utente multimodali due volte e poteva memorizzare scaffolding /skill di grandi dimensioni.
replace() con un old_text vuoto sovrascriveva una riga arbitraria.
Il client di embedding accettava vettori contenenti NaN, Infinity o null. Il database li rifiutava e la riga durabile andava persa. Ora degradano a una riga solo testo come qualsiasi altro errore di embedding.
backfill riprovava per sempre righe vuote composte da whitespace non ASCII, e falliva ogni riga su database SQL_ASCII.
Un --config esplicito che non poteva essere letto prima avvertiva e ricadeva silenziosamente sul DSN predefinito. Ora è un errore.
Le chat del forum Telegram (topic), le room LINE e le sessioni webhook non venivano riconosciute come sessioni multi-parte, quindi le loro chiavi di sessione grezze, incluso un id partecipante, diventavano temi a sé stanti. Ora finiscono nel bucket condiviso external-group come altro traffico di gruppo.

La suite di test è cresciuta da 442 a più di 500 test, inclusi circa 80 test di regressione per queste correzioni. La CI li esegue contro Postgres 16, 17 e 18 live, e ora fallisce su qualsiasi test skippato, quindi un ambiente rotto non può più passare verde.

Installazione e aggiornamento

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

Se arrivi dalla 0.6.0, non ci sono modifiche allo schema e nessuna nuova migrazione. Aggiorna il pacchetto, riavvia e leggi le note di aggiornamento 1.0.0 nel CHANGELOG. Questi cambiamenti modificano il comportamento:

remap rifiuta --old/--new vuoti o identici.
Un --config esplicito che non può essere letto o parsato ora è un errore invece di un fallback silenzioso al DSN predefinito.
Le chiavi di configurazione booleane accettano solo 1/true/yes/on e 0/false/no/off. Valori vuoti o non riconosciuti ora significano il default della chiave.
prefetch_budget, prefetch_limit e min_similarity vengono clampati ai loro intervalli documentati.
Le nuove scritture da sessioni del forum Telegram, room LINE e webhook vanno al tema external-group; le righe già scritte sotto le loro chiavi grezze restano dove sono.
I backup di installazione ora si spostano in una directory nascosta plugins/.pgvector.bak-<ts>. Rimuovi qualsiasi vecchia directory visibile pgvector.bak* così hermes-agent non la scopra come secondo provider.

Arrivando da qualsiasi versione più vecchia della 0.6.0, leggi prima le note della 0.6.0 e segui la regola di ordinamento lì: aggiorna il pacchetto su ogni host che scrive sul database prima di eseguire migrate. docs/upgrading.md ha la procedura completa.

Link

Il progetto è BSD-3-Clause, copyright Green Yoga Inc. Bug report e PR mirati sono i benvenuti.