Tutorial 20: Memoria Persistente — Memoria a Lungo Termine

Questa parte fa parte della serie di tutorial ufficiali di Hermes Agent. Vedi tutti i tutorial

Pensa a questa funzione come a un post-it sulla tua scrivania: Hermes Agent scrive le cose importanti su di te e sui tuoi progetti, così non le dimentica tra una conversazione e l’altra. Niente più ripetizioni ogni volta che inizi una nuova chat.

Cosa Fa la Memoria Persistente?

Normalmente, un agente AI riparte da zero a ogni sessione — dimentica tutto quando la conversazione finisce. La Memoria Persistente cambia tutto questo. Hermes Agent tiene due piccoli file di testo sul tuo computer. Li legge all’inizio di ogni sessione, così ricorda immediatamente le tue preferenze, i dettagli dei tuoi progetti e qualsiasi altra cosa gli hai insegnato.

Passo 1: Conosci i Due File di Memoria

La memoria dell’agente vive in due file, salvati in ~/.hermes/memories/:

File	Cosa Contiene	Limite di Dimensione
MEMORY.md	Note personali dell’agente — fatti sull’ambiente, convenzioni, cose che ha imparato	2.200 caratteri (~800 token)
USER.md	Il tuo profilo — preferenze, stile di comunicazione, aspettative	1.375 caratteri (~500 token)

I limiti sono voluti. Costringono l’agente a tenere solo ciò che è importante, come un quaderno ben organizzato piuttosto che un cassetto in disordine.

Passo 2: Vedi Come la Memoria Appare nel Prompt

All’inizio di ogni sessione, l’agente carica entrambi i file e li mostra come un’istantanea congelata nel suo prompt di sistema. Ecco un esempio di ciò che l’agente “vede”:

══════════════════════════════════════════════
MEMORIA (le tue note personali) [67% — 1.474/2.200 caratteri]
══════════════════════════════════════════════
Il progetto dell'utente è un servizio web Rust in ~/code/myapi che usa Axum + SQLx
§
Questa macchina gira su Ubuntu 22.04, ha Docker e Podman installati
§
L'utente preferisce risposte concise, non ama spiegazioni prolisse

Nota i dettagli:

Un’intestazione che mostra quale archivio è (MEMORIA o PROFILO UTENTE)
Percentuale di utilizzo e conteggio dei caratteri — così l’agente sa quanto spazio è rimasto
Voci separate da § (simbolo di sezione)
Le voci possono essere su più righe

Importante: Questa istantanea viene catturata una volta all’inizio della sessione e non cambia mai a metà sessione. Se l’agente aggiorna la sua memoria durante la chat, le modifiche vengono salvate su disco immediatamente ma non appariranno nel prompt fino alla prossima sessione. Questo mantiene tutto veloce preservando la cache del modello.

Passo 3: L’Agente Gestisce la Propria Memoria

L’agente usa uno strumento chiamato memory con tre azioni:

add — Aggiunge una nuova voce di memoria
replace — Sostituisce una voce esistente (usa la corrispondenza di sottostringhe con old_text)
remove — Elimina una voce che non è più rilevante (usa anche old_text)

Non c’è un’azione read perché la memoria è già iniettata nel prompt — l’agente la vede sempre.

Ecco un semplice esempio di come l’agente potrebbe usare lo strumento:

memory action=add content="L'utente preferisce elenchi puntati ai paragrafi"

O sostituire una vecchia preferenza:

memory action=replace old_text="L'utente preferisce risposte concise" new_text="L'utente preferisce risposte di una riga con emoji"

Passo 4: Cosa Succede Quando la Memoria è Piena?

La memoria non si compatta automaticamente. Quando una scrittura supererebbe il limite, lo strumento memory restituisce un errore invece di eliminare silenziosamente le voci. L’agente quindi fa spazio da solo — consolidando o rimuovendo voci nello stesso turno prima di riprovare.

Nota anche: replace è soggetto allo stesso limite. Sostituire una voce con una più lunga può comunque causare un overflow, quindi il nuovo contenuto deve essere accorciato (o un’altra voce rimossa) per rientrare nei limiti.

Passo 5: Un Agente per Home di Hermes (Importante!)

Non puntare due processi agente alla stessa directory home di Hermes. Le scritture di memoria sono automatiche e vengono ricaricate nel prompt di sistema all’inizio della sessione, quindi due scrittori che condividono una home combineranno le rispettive voci in un pasticcio che nessuno dei due ha scritto. La memoria è limitata per profilo di progettazione — dai a un secondo agente il suo profilo. Se hanno bisogno di memoria condivisa, usa invece un provider di memoria esterno.

Riepilogo

La Memoria Persistente dà a Hermes Agent un modo semplice e limitato per ricordarti tra le sessioni. Due piccoli file — MEMORY.md e USER.md — contengono note curate, iniettate come un’istantanea congelata all’inizio della sessione. L’agente gestisce questi file da solo usando lo strumento memory, e i limiti di caratteri mantengono tutto concentrato. Ricorda solo: un agente per directory home, e l’istantanea si aggiorna solo all’inizio della sessione.

Prossimo: Tutorial 21 — Attività Pianificate: impostare automazioni che si eseguono da sole con un timer.