hermes-memory-pgvector è il plugin open source che offre a una flotta di agenti hermes-agent una memoria condivisa e durevole su PostgreSQL e pgvector. La versione 0.5.3 è disponibile su PyPI e rimuove l'ultima assunzione hard-coded nel plugin: quale modello di embedding trasforma i tuoi ricordi in vettori ricercabili.
Perché esiste questa release
Fino a ora il modello di embedding era di fatto fisso. Il plugin confrontava ogni vettore con un valore letterale di 768 dimensioni, la dimensione del modello predefinito nomic-embed-text, e non aveva alcun modo di inviare una chiave API, quindi i servizi di embedding ospitati erano fuori portata.
Questo è diventato un vero limite per il nostro deployment. Abbiamo spostato il database della memoria su text-embedding-3-small di OpenAI, servito tramite OpenRouter, perché un endpoint ospitato è sempre attivo mentre un modello auto-ospitato può impiegare diversi secondi per riattivarsi. Le colonne del database sono cambiate a 1536 dimensioni e il plugin non aveva alcuna impostazione in grado di seguirle. La v0.5.3 aggiunge queste impostazioni.
Tre nuove impostazioni
embed_dimè la lunghezza del vettore restituita dal tuo modello. Il valore predefinito è768, quindi le configurazioni esistenti non vengono influenzate. Ogni embedding viene ancora verificato, ora rispetto a questo valore, così un disallineamento fallisce rapidamente invece di arrivare al database.embed_api_key_envè il nome di una variabile d'ambiente che contiene un bearer token, comeOPENROUTER_API_KEY. La chiave non finisce mai nel file di configurazione; viene letta al momento della chiamata e non viene mai registrata.embed_protocolèopenai,ollamaoppureauto. Il valore predefinito,auto, prova il percorso compatibile con OpenAI e poi passa all'API nativa di Ollama. Scegliereopenaiper un servizio ospitato significa che un errore di autenticazione o di modello viene segnalato per quello che è, invece di essere nascosto dietro un 404 del fallback.
Indirizzare il plugin a text-embedding-3-small tramite OpenRouter ora appare così:
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"
Due correzioni che contano anche se non cambi nulla
- Embedding sotto il loader del plugin hermes-agent. Dopo aver caricato il plugin, il loader dell'host riaggancia ogni sottomodulo al pacchetto, incluso uno chiamato
embed. Questo sostituiva la funzione chiamata dal plugin, quindi l'embedding falliva conTypeError: 'module' object is not callablee le scritture della memoria venivano scartate invece di essere salvate come testo. Ora il plugin chiama un alias privato che il loader non tocca mai. - Endpoint lenti. Un server che accettava la connessione ma rispondeva dopo il timeout sollevava un
TimeoutErrorgrezzo, che sfuggiva alla gestione degli errori del plugin: nessun fallback, nessun retry e una scrittura persa. Ora viene gestito come ogni altro guasto dell'endpoint.
Aggiornamento
I valori predefiniti non sono cambiati: 768 dimensioni, nessun header di autenticazione, il protocollo auto e nessuna nuova migrazione del database. Aggiorna con:
pip install -U hermes-memory-pgvector
Passare a un modello con una dimensione vettoriale diversa è una migrazione del database, non solo una modifica della configurazione, perché i vettori di due modelli diversi non sono confrontabili. Il README spiega come farlo: cambia il tipo di colonna, ricalcola gli embedding delle righe esistenti con hermes-pgvector backfill, quindi ricostruisci gli indici HNSW.
Il codice sorgente e il riferimento completo alla configurazione sono su GitHub: