Hermes Agent non ricorda le conversazioni: come risolvere

Il tuo agente doveva ricordare

Lunedì hai raccontato a Hermes Agent del tuo progetto. Mercoledì si presenta come se non vi foste mai visti. La promessa della memoria persistente è il motivo per cui hai scelto un agente self-hosted invece di ChatGPT, e ora sembra lo stesso strumento smemorato ma con più passi di configurazione.

La buona notizia è che il sistema di memoria di Hermes Agent è abbastanza semplice da diagnosticare dall'esterno. MEMORY.md e USER.md sono semplici file markdown su disco. Se l'agente non ricorda, sta succedendo una tra quattro cose, e ognuna ha un fix specifico.

Come funziona davvero la memoria di Hermes Agent

Prima di diagnosticare, aiuta capire la forma di ciò che è rotto.

Hermes Agent scrive due tipi di memoria (persistente) nella directory dati (di solito ~/.hermes/memories/):

• MEMORY.md - note curate dall'agente sui tuoi progetti, preferenze e flussi di lavoro. Limitato a circa 2.200 caratteri, così il modello è costretto a dare priorità.
• USER.md - un profilo stabile di chi sei: ruolo, stack tecnico, stile di comunicazione.

All'inizio di ogni sessione, l'agente legge entrambi i file e li inietta nel system prompt. Durante la sessione, li aggiorna in automatico in base a ciò di cui avete parlato. Quando la sessione finisce, i file restano su disco.

Quest'ultima frase è tutta la promessa. Se i file non sono su disco dopo un riavvio, la memoria non sta persistendo. Se ci sono e l'agente dimentica comunque, sta succedendo qualcos'altro. Sono due bug diversi.

Per una spiegazione più ampia del sistema di memoria in sé, vedi come funzionano memoria e skill di Hermes Agent. Questo articolo tratta solo le modalità di fallimento.

Causa 1: il volume dati non è montato

È di gran lunga la causa più comune. Sintomo: l'agente funziona bene per un'intera conversazione, ricorda tutto quello che gli hai detto cinque minuti fa, poi il container si riavvia e si dimentica che esisti.

Cosa sta succedendo: i file di memoria vengono scritti dentro il livello scrivibile del container invece che in un volume persistente. Con docker stop e docker start, quel livello sopravvive. Con docker rm (o docker compose down, o quando l'host si riavvia e ricrea il container), il livello scrivibile viene distrutto e MEMORY.md muore insieme.

Controlla prima: la directory di memoria esiste davvero sul tuo host?

ls -la ~/.hermes/memories/

Se quella directory è vuota o mancante dopo che l'agente gira da un po', il container non sta scrivendo lì.

Il fix: monta ~/.hermes come volume. In docker run:

docker run -v ~/.hermes:/root/.hermes ...

Nel docker-compose.yml:

services:
  hermes:
    volumes:
      - ~/.hermes:/root/.hermes

Dopo la modifica, ricrea il container (non basta un restart) e verifica che la directory memories si popoli sull'host mentre usi l'agente. La guida Docker di Hermes Agent copre il compose completo.

Causa 2: volume montato ma permessi sbagliati

Hai montato il volume, la directory esiste sull'host, ma i file restano vuoti oppure i log dell'agente riportano "permission denied" quando prova a scrivere.

Container e host condividono lo stesso spazio numerico di UID, e per default niente riconcilia quei numeri. Se il tuo agente gira come UID 1000 dentro il container e la directory sull'host è di root, la scrittura fallisce in silenzio. Su Fedora, RHEL e altre distribuzioni con SELinux, la scrittura viene negata anche quando i permessi Unix standard la consentirebbero, e Docker non ti avviserà.

Controlla il proprietario:

ls -ln ~/.hermes/memories/

Fix, Docker classico: rendi la directory sull'host scrivibile dallo stesso UID usato dal container:

sudo chown -R $(id -u):$(id -g) ~/.hermes

Fix, host con SELinux: aggiungi l'etichetta :Z al mount del volume così Docker lo rietichetta per l'accesso dal container:

volumes:
  - ~/.hermes:/root/.hermes:Z

Fix, Docker rootless: il "root" del container è mappato sul tuo UID host tramite user namespaces, non sullo UID 0 reale. Il chown sopra copre già questo caso, ma il modello mentale inganna chi prova a fare sudo sul file e vede il fallimento continuare.

Causa 3: è pieno il context window, non il file di memoria

Sintomo: MEMORY.md è su disco, contiene le note del tuo progetto, cat mostra il contenuto, e l'agente si comporta comunque come se non ricordasse. Non è un bug di memoria. È un bug di context window travestito da memoria.

Hermes Agent legge MEMORY.md e USER.md nel system prompt all'inizio della sessione, ma si porta dietro anche la cronologia della conversazione in corso nella stessa context window. Se la dimensione combinata supera il limite del modello, i token più vecchi vengono troncati per primi. Anche prima del limite duro entra in gioco l'effetto "lost in the middle": i modelli recuperano informazioni in modo affidabile dall'inizio e dalla fine del contesto, molto meno dal centro.

Quindi il file di memoria può essere presente e corretto, ma al turno 30 di una conversazione lunga al modello è stata servita una versione troncata o sepolta al centro e si comporta come se non l'avesse mai vista.

Diagnostica:

• Confronta le context window dei modelli. Guarda quale modello hai configurato. Un modello con finestra piccola sbatte contro questo limite molto prima di uno da 200k o 1M token.
• Controlla la dimensione di MEMORY.md. Se è vicino al tetto dei 2.200 caratteri, è ok. Se una vecchia versione di Hermes lo ha lasciato crescere a 20k, taglialo.
• Guarda la lunghezza della sessione corrente. Le sessioni singole lunghe sono più esposte a questo delle sessioni corte e frequenti.

Fix:

• Passa a un modello con context window più grande nella tua configurazione.
• Taglia MEMORY.md a mano se ha superato il suo tetto.
• Riavvia la sessione periodicamente. Hermes rilegge la memoria da zero all'inizio della sessione, quindi una nuova sessione carica MEMORY.md e USER.md in un contesto pulito.

Lo stesso modo di fallimento è descritto da un'altra angolazione nella guida al troubleshooting di Telegram, alla sezione "i messaggi arrivano ma l'agente ignora il contenuto". È lo stesso bug di fondo su canali diversi.

Causa 4: confusione tra memoria per chat e memoria globale

Alcuni deployment fanno girare un processo Hermes Agent per ogni chat Telegram, altri condividono la memoria tra le chat. Se hai detto qualcosa all'agente in un DM privato e non lo sa quando passi a un gruppo, sei davanti a un disallineamento di ambito, non a un bug di persistenza.

Diagnostica:

• Rileggi la config. Se c'è un pattern di directory dati per chat, la memoria è per chat per design.
• Se sei su un setup self-hosted con un unico ~/.hermes condiviso tra tutte le chat, la memoria è globale e la causa è altrove.
• Se stai facendo girare più processi Hermes contro la stessa home per servire chat diverse, hai un problema di tutt'altro tipo: due processi che scrivono sullo stesso MEMORY.md si sovrascrivono, e il file finisce in uno stato che nessuno dei due ha scritto. Non farlo.

Fix: decidi quale modello vuoi e configura di conseguenza. La maggior parte degli operatori self-hosted vuole memoria globale (un te, un agente, tutte le chat). I deployment multi-utente o multi-tenant vogliono di solito isolamento per chat. Entrambi sono validi, ma non sono intercambiabili.

Recuperare dopo un riavvio andato male

Se MEMORY.md è corrotto, troncato a zero byte o contiene contenuto illeggibile dopo un crash o uno shutdown brutto, il percorso di recupero è semplice perché è un semplice file markdown.

1. Ferma l'agente prima di toccare il file. Un agente in esecuzione può sovrascrivere il tuo tentativo di recupero.
2. Cerca i backup. Se hai seguito le indicazioni in migrare Hermes Agent su una nuova macchina, hai già snapshot periodici di ~/.hermes. Ripristina lo snapshot buono più recente.
3. Modifica a mano se serve. MEMORY.md è markdown. Aprilo in un editor di testo, rimuovi la sezione corrotta e salva. Non c'è alcuno schema da rispettare.
4. Avvia l'agente e conferma che la memoria recuperata compaia nella sessione successiva.

Se non avevi backup, questo è il momento di impostarli. Un tar czf hermes-backup-$(date +%F).tar.gz ~/.hermes giornaliero in cron impiega pochi secondi e ti compra un percorso di recupero reale per il prossimo incidente.

Quando smettere di debuggare e delegare l'infrastruttura

Ogni fix di questo articolo è una piccola correzione al modo in cui il container è cablato. Nessuna è difficile da sola. Ciò che brucia tempo è scoprirle il giorno in cui l'agente dimentica un progetto di due settimane a metà conversazione, e realizzare che il volume non è mai stato montato, i permessi erano sbagliati e non c'è un backup a cui tornare.

Se preferisci non vedere mai più un "permission denied" in un log di Hermes, Hermify fa girare un Hermes Agent gestito su Telegram con gli stessi MEMORY.md e USER.md, montati come si deve, con backup notturno e ripristinabili in un clic. La tua memoria resta tua (i file sono cifrati a riposo e scaricabili), e il debug dei mount del volume smette di essere un tuo problema.

Per uno sguardo più ampio su come si risolve il trade-off di deployment, vedi hosting di Hermes Agent contro self-hosting.

Inizia con Hermify e salta del tutto la checklist di persistenza della memoria.

Fonti

• Riferimento memoria di Hermes Agent
• Guida Docker di Hermes Agent
• Problemi di permessi con i volumi Docker su container non-root
• Il context window è RAM, non storage (Mem0)
• Context window di LLM e troncamento (Redis)