TLDR: La maggior parte degli agenti si resetta e dimentica. Ecco l'esatta architettura di memoria che ho costruito in modo che i miei agenti condividano il contesto tra riavvii, coordinino senza pestarsi i piedi e conservino le decisioni per mesi.
Il problema che nessuno risolve
Ecco la configurazione tipica della memoria di un agente AI. Infilare le cose importanti nel prompt di sistema. Sperare che la finestra di contesto non si esaurisca. Riavviare e perdere tutto.
Ho gestito due agenti coordinati (Ella su OpenClaw, Lyra su Hermes) attraverso centinaia di sessioni in 6 mesi. La cosa più importante che li rende utili non sono i modelli o gli strumenti. È l'architettura della memoria.
Quando Lyra rilascia una correzione alle 2 di notte, Ella lo sa al mattino. Quando a gennaio ho deciso come dovrebbero essere memorizzati i segreti, entrambi gli agenti seguono ancora quella decisione a luglio. Quando una sessione si blocca a metà di un'attività, quella successiva riprende esattamente da dove si era interrotta.
Ecco il sistema esatto a 4 livelli.
Livello 1: Contesto in-sessione
Ogni sessione inizia leggendo due file. Il file di identità è l'identità permanente dell'agente. Non un prompt di sistema sepolto nella configurazione. Un vero file markdown che posso modificare. Contiene come l'agente dovrebbe comportarsi, cosa prioritizza, cosa non fa mai senza chiedere e la sua relazione con gli altri agenti.
Il file dell'indice di memoria è l'indice di tutto ciò che vale la pena ricordare tra le sessioni. Non un database vettoriale. Non embedding. Un semplice sommario che punta a singoli file di memoria. Ogni file di memoria è una breve nota con un nome, una descrizione, un tipo e un breve corpo. L'indice viene sempre caricato. I singoli file vengono letti su richiesta quando pertinenti.
Perché markdown? Perché posso leggerlo, modificarlo e fare debug. Quando un agente inizia a comportarsi male, apro l'indice e trovo l'istruzione sbagliata. Quando voglio cambiare un comportamento, modifico il file. Nessuna API. Nessun pannello di controllo. Nessun riaddestramento.
Livello 2: Conservazione post-sessione (Hindsight)
Il problema della memoria solo markdown: cattura solo ciò che qualcuno scrive esplicitamente. La maggior parte del contesto prezioso è implicito. Decisioni prese durante un'esecuzione. Fatti dedotti da un compito. Cose che si sono rivelate importanti.
Hindsight è un backend di conservazione dei fatti locale che gira su localhost. Alla fine di ogni sessione significativa, l'agente invia automaticamente un insieme curato di fatti conservati in un archivio nominato. Ogni agente ha il proprio archivio.
Cosa viene conservato: decisioni prese durante la sessione, fatti non ovvi sull'utente o sul progetto, schemi di fallimento e le correzioni adottate, e preferenze che l'utente ha confermato o corretto.
Quando inizia una nuova sessione, Hindsight viene interrogato per il contesto pertinente prima che l'agente risponda. Non è una ricerca full-text sulle trascrizioni. Sono fatti curati, etichettati per tipo, che l'agente ha imparato essere degni di essere portati avanti.
Il percorso promosso: fatto Hindsight, revisione umana, voce nell'indice di memoria. Conservazione automatica con un gate di approvazione umana.
Livello 3: Stato condiviso a lungo termine (Nexus)
La memoria di un singolo agente si rompe quando aggiungi un secondo agente. Divergono. Uno pensa che X sia lo stato attuale del progetto. L'altro pensa Y. Entro una settimana si contraddicono a vicenda.
La soluzione è un file di stato condiviso e ispezionabile che entrambi gli agenti leggono e scrivono. Usiamo un vault Obsidian che chiamo Nexus. Contiene un log del contesto in tempo reale a cui entrambi gli agenti aggiungono dopo ogni turno significativo, un file dello stato del progetto, un log delle decisioni e un checkpoint del contesto di lavoro per agente aggiornato ogni poche chiamate di strumenti durante attività lunghe.
Il file del contesto in tempo reale è la stretta di mano in tempo reale. L'invariante: prima di ogni risposta, leggilo. Dopo ogni turno significativo, aggiungi.
Quando Lyra finisce una PR alle 2 di notte ed Ella risponde alla mia domanda del mattino, Ella lo sa già. Ha letto il log. Nessun passaggio di messaggi. Nessuna API tra agenti. Nessun polling. Un file condiviso, due agenti, log solo append.
Livello 4: Conoscenza ricercabile (gbrain)
I primi tre livelli gestiscono la memoria episodica. Cosa è successo, cosa è stato deciso, cosa è importante portare avanti. gbrain è il livello semantico. È un wiki compilato che gira come server MCP sul vault Nexus. Ricerca full-text e semantica su tutto ciò che è stato scritto.
Quando un agente deve rispondere a una domanda di ricerca, trovare una sintesi precedente o cercare come abbiamo gestito una classe di problemi in passato, interroga gbrain invece di rileggere ogni file. L'output è un elenco classificato di pagine pertinenti con provenienza. L'agente legge ciò che è pertinente. Non scarica l'intero vault nel contesto.
Questa è la differenza tra memoria e richiamo. I livelli da 1 a 3 gestiscono ciò che l'agente porta con sé. Il livello 4 gestisce ciò che l'agente può cercare.
L'invariante di sincronizzazione tra agenti
Due agenti, un file di contesto in tempo reale. Il rischio: si sovrascrivono a vicenda o perdono le voci dell'altro. L'invariante che eseguiamo: ogni voce è firmata con il nome dell'agente, il canale, il tipo e un riepilogo di una riga. Solo append. Non modificare mai la voce di qualcun altro. Se Lyra ha registrato qualcosa di pertinente, Ella lo riconosce esplicitamente nella risposta successiva. Per decisioni significative, entrambi gli agenti scrivono anche nel log delle decisioni con timestamp e motivazione.
Questo ha funzionato per centinaia di sessioni. Abbiamo avuto un conflitto: una race condition in cui entrambi gli agenti hanno aggiunto entro lo stesso minuto durante un passaggio di consegne. Risoluzione: leggere entrambe le voci, riconciliare nel turno successivo. Nessun merge automatico necessario.
Cosa sostituisce questo
Prima di questa architettura: cinque sessioni di chat disconnesse, ognuna con il proprio contesto obsoleto. Agenti che si contraddicevano a vicenda perché nessuno dei due poteva vedere cosa sapeva l'altro. Istruzioni che ho dato tre settimane fa, dimenticate. Decisioni che vivevano nella mia testa invece che in un file.
Dopo: due agenti che si informano prima di ogni risposta. Un log di stato condiviso che nessuno dei due può negare. Decisioni conservate che sopravvivono a mesi di reset del contesto. Ogni preferenza di comportamento in un file che posso modificare e verificare.
Il compromesso onesto: questo sistema richiede disciplina. Devi scrivere le cose. Devi mantenere i file. Devi rivedere ciò che viene conservato prima che diventi permanente. Non è un sistema magico sempre attivo. È disciplina manuale strutturata più automazione alle giunture.
Come iniziare
Non hai bisogno di due agenti o di un vault completo per eseguire la versione uno di questo.
Passo 1: Un file di identità più un indice di memoria. Creali. Leggili all'inizio della sessione. Scrivi ogni preferenza di comportamento nell'indice la seconda volta che correggi l'agente per la stessa cosa.
Passo 2: Un file di stato condiviso. Se esegui più di un agente o usi Claude in più finestre, crea un file di contesto in tempo reale. Ogni sessione vi aggiunge alla fine e lo legge all'inizio.
Passo 3: Una regola di conservazione. Quando una sessione produce una decisione che dovrebbe sopravvivere, scrivila manualmente nell'indice. Fallo a mano finché non ti fidi del modello. Poi automatizza la segnalazione.
Passo 4: Un file per fatto, non un unico grande documento. L'indice punta a singoli file. Questo rende facile eliminare un ricordo obsoleto senza toccare gli altri.
L'intero stack a 4 livelli ha impiegato circa 6 mesi per stabilizzarsi. I livelli 1 e 3 hanno richiesto un fine settimana. Inizia da lì.
Conclusione
La maggior parte delle configurazioni di memoria degli agenti sono gestione della finestra di contesto con passaggi extra. Funzionano finché la finestra non si resetta o aggiungi un secondo agente.
La memoria duratura dell'agente è un problema infrastrutturale, non un problema di prompting. La risposta sono più livelli con diversi orizzonti temporali: contesto in-sessione, fatti tra sessioni, stato condiviso, conoscenza ricercabile.
Tutto il nostro è markdown semplice. Nessun database vettoriale. Nessun embedding. Nessun riaddestramento. Solo file che posso aprire, modificare e fare debug.
Gli agenti che sono veramente utili non sono quelli con la finestra di contesto più grande. Sono quelli che ricordano ciò che conta e dimenticano ciò che non conta.
Se stai costruendo agenti di cui vuoi fidarti per lavori reali, inizia con l'architettura della memoria prima di aggiungere più strumenti.
Strumenti di riferimento
Hindsight (conservazione della memoria locale): https://github.com/vectorize-io/hindsight
gbrain (wiki compilato / ricerca semantica): https://github.com/garrytan/gbrain
OpenClaw (runtime agente): https://openclaw.ai
Hermes (runtime agente): hermes-agent.nousresearch.com
