Ho passato 5 giorni a fare il debug della memoria del mio agente OpenClaw. Ecco cosa ho imparato.

Il nome del mio agente è Chiti. Funziona su Telegram, gestisce l'assistenza clienti per due prodotti SaaS, abbozza tweet, amministra fatture e coordina con il mio co-fondatore attraverso fusi orari. È la cosa più vicina a un impiegato junior che abbia.

E per settimane, continuava a dimenticare le cose.

Non in modo sottile. Passavo un'ora a configurare un cron job giornaliero, cambiavo modello, e nella sessione successiva Chiti faceva finta che non ci fossimo mai parlati. Riferivo una decisione di due giorni prima e ricevevo uno sguardo vuoto. Gli chiedevo di continuare un compito e ricominciava da capo.

Così ho smesso di costruire funzionalità e ho passato 5 giorni, quando avevo tempo, a sistemare la memoria. Questo è tutto quello che ho scoperto, tutto quello che ho rotto e tutto quello che ha effettivamente funzionato.

Giorno 1: L'agente dimentica tutto dopo conversazioni lunghe

Il primo problema era semplice da descrivere e doloroso da diagnosticare.

Dopo conversazioni lunghe, Chiti iniziava a perdere il contesto precedente. Non gradualmente, spariva e basta. Cose che gli avevo detto 20 messaggi prima erano sparite. Decisioni prese all'inizio della sessione? Mai successe.

Il colpevole era la compattazione. Quando la conversazione riempie la finestra di contesto, OpenClaw comprime i messaggi più vecchi in un riassunto per fare spazio a quelli nuovi. Il riassunto cattura l'essenziale ma perde i dettagli. Nomi, numeri, decisioni precise - spariti.

È così per progettazione. La finestra di contesto è finita. Ma il comportamento predefinito tratta tutto allo stesso modo, il che significa che la tua istruzione accuratamente costruita dal messaggio #3 riceve lo stesso trattamento di una chiacchierata informale dal messaggio #7.

Cosa ho fatto:

Ho abilitato il flush della memoria prima della compattazione. Questo dice all'agente di scrivere il contesto importante su disco prima che il compressore venga eseguito.

1{
2  "compaction": {
3    "memoryFlush": {
4      "enabled": true,
5      "softThresholdTokens": 4000
6    }
7  }
8}

Quando la sessione si avvicina al limite di contesto, OpenClaw attiva un turno silenzioso che ricorda all'agente di salvare i fatti durevoli in memory/YYYY-MM-DD.md prima che la compattazione li cancelli. L'agente scrive ciò che conta, la compattazione viene eseguita e le cose importanti sopravvivono su disco anche se il riassunto del contesto le perde.

Cosa ho imparato:

La compattazione non è il nemico. Perdere informazioni durante la compattazione lo è. La soluzione è assicurarsi che tutto ciò che vale la pena ricordare venga scritto in un file prima che il compressore lo tocchi. Se è solo nella finestra di contesto, è temporaneo. Se è su disco, sopravvive.

Giorno 2: La ricerca restituisce spazzatura

Con i log giornalieri che si accumulavano e MEMORY.md che cresceva, avevo bisogno che l'agente trovasse effettivamente le cose. La ricerca di memoria integrata restituiva risultati irrilevanti o mancava corrispondenze ovvie.

Il problema era il backend di ricerca. La ricerca predefinita basata su SQLite di OpenClaw usa embedding vettoriali (somiglianza semantica) per trovare chunk pertinenti. Funziona per query ampie, ma fatica con corrispondenze esatte. Cercavo un nome cliente specifico e ottenevo risultati su un argomento completamente diverso che per caso usava un linguaggio simile.

Cosa ho fatto:

Sono passato a QMD come backend di ricerca della memoria. QMD combina BM25 (corrispondenza per parole chiave) con embedding vettoriali e un reranker. Così quando cerco "Charles payment failure", trova risultati che contengono quelle parole esatte E risultati semanticamente correlati, poi li riordina per pertinenza.

Ho anche configurato i percorsi QMD per includere la mia cartella degli apprendimenti:

1{
2  "memory": {
3    "qmd": {
4      "paths": "paths": [
5        {
6          "path": "/Users/ramya/clawd",
7          "name": "memory-root",
8          "pattern": "MEMORY.md"
9        },
10        {
11          "path": "/Users/ramya/clawd",
12          "name": "memory-alt",
13          "pattern": "memory_alt.md"
14        },
15        {
16          "path": "/Users/ramya/clawd/memory",
17          "name": "memory-dir",
18          "pattern": "**/*.md"
19        },
20        {
21          "path": "/Users/ramya/clawd/learnings",
22          "name": "learnings",
23          "pattern": "**/*.md"
24        }
25      ]
26    }
27  }
28}

Cosa ho imparato:

La pura ricerca semantica suona bene in teoria, ma fallisce su nomi propri, numeri specifici e frasi esatte. La ricerca ibrida (parole chiave + vettori + reranking) è significativamente migliore per la memoria di un agente nel mondo reale. Se il tuo agente non riesce a trovare qualcosa che sai essere nei suoi file, probabilmente il collo di bottiglia è il backend di ricerca, non i file stessi.

Giorno 3: L'agente trova ma non usa

Questo è stato il giorno più frustrante. Ho confermato che la ricerca funzionava, potevo interrogare manualmente e ottenere i risultati giusti. Ma durante le conversazioni reali, Chiti non recuperava il contesto pertinente, anche quando esisteva chiaramente in memoria.

Il problema era che il recupero non è automatico. L'agente deve decidere di cercare. E se la conversazione non attiva i giusti segnali, non cercherà.

Cosa ho fatto:

Ho aggiunto istruzioni esplicite di recupero nella sequenza di avvio. Invece di sperare che l'agente cercasse quando necessario, gli ho detto quando cercare:

1markdown
2
3Prima di iniziare qualsiasi compito:
4- Cerca nei log giornalieri il contesto correlato
5- Controlla LEARNINGS.md per le regole su questo tipo di compito
6- Se viene menzionato un cliente, cerca la sua cronologia

Ho anche costruito un test di recupero. Piantavo un marcatore specifico nel log giornaliero — qualcosa come "MARKER: 2026-02-20 — Ricordati di controllare sempre lo stato di git prima di dichiarare il codice inviato." Poi aspettavo, avviavo una nuova sessione e chiedevo: "Qual era il marcatore di ieri?" Se l'agente lo trovava, il recupero funzionava. Altrimenti, qualcosa era rotto.

Cosa ho imparato:

C'è differenza tra "l'informazione esiste" e "l'agente usa l'informazione". Servono entrambe. L'infrastruttura di ricerca gestisce la prima parte. Le istruzioni di avvio e le abitudini di recupero gestiscono la seconda. Testa entrambe separatamente.

Giorno 4: Renderlo resistente alla compattazione

A questo punto avevo il flush di memoria, la ricerca ibrida e le istruzioni di recupero. Ma continuavo a perdere contesto in uno scenario specifico: sessioni molto lunghe in cui la compattazione veniva eseguita più volte.

Il problema era che il flush di memoria si attiva solo una volta per ciclo di compattazione. Se la sessione era abbastanza lunga per due o tre compattazioni, solo la prima riceveva il trattamento di flush. Tutto ciò che seguiva era a rischio.

Cosa ho fatto:

Ho configurato il pruning del contesto per lavorare insieme alla compattazione:

1{
2  "contextPruning": {
3    "mode": "cache-ttl",
4    "ttl": "6h",
5    "keepLastAssistants": 3
6  }
7}

Questo elimina aggressivamente il contesto vecchio dopo 6 ore, mantenendo le ultime 3 risposte dell'assistente. Combinato con il flush di memoria, significa che l'agente scrive le cose importanti su disco all'inizio, e il contesto vecchio viene ripulito prima di causare un overflow.

Ho anche aggiunto un protocollo di test MARKER: dopo qualsiasi modifica significativa della configurazione, pianto un marcatore nel log giornaliero e testo il recupero attraverso i confini di compattazione. Se il marcatore sopravvive, la modifica ha funzionato. Altrimenti, qualcosa si è rotto.

Cosa ho imparato:

Le sessioni lunghe sono dove i sistemi di memoria vengono realmente testati. Le conversazioni brevi raramente raggiungono la compattazione. Sono le sessioni di lavoro profondo di 2 ore dove perdi contesto e non riesci a capire perché. Testa il tuo sistema di memoria sotto carico, non solo in chat veloci.

Giorno 5: Il prompt di sistema era gonfio del 28%

Questo è stato il giorno in cui tutto ha avuto senso. Ho eseguito /context detail e ho fissato i numeri.

Il mio agente stava caricando 11.887 token di prompt di sistema prima ancora di leggere il mio messaggio. 51 skill, di cui 20 che non avevo mai usato. MEMORY.md era 200 righe di wiki aziendale caricato in ogni singola sessione. E avevo due sequenze di avvio in competizione — una in BOOT.md (che OpenClaw non riconosce nemmeno) e una sepolta 200 righe dentro AGENTS.md.

La cosa peggiore: ogni volta che cambiavo modello, Chiti dimenticava tutto. Nessun protocollo di passaggio. Nessuna scrittura del contesto corrente. Semplicemente sparito.

La causa principale:

OpenClaw legge automaticamente questi file in ogni nuova sessione: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md.

Tutto il resto — LEARNINGS.md, log giornalieri, documenti, file di riferimento — l'agente deve leggerli da solo usando gli strumenti. Se l'istruzione per leggere quei file non è in uno dei file caricati automaticamente (specificamente AGENTS.md), l'agente non li vedrà mai.

Il mio BOOT.md conteneva l'intera sequenza di avvio. Ma OpenClaw non carica automaticamente BOOT.md. Quindi le istruzioni restavano lì, non lette, senza fare nulla.

Cosa ho fatto:

Ho fatto un audit completo e pulizia:

1. Ho spostato la sequenza di avvio all'inizio di AGENTS.md (l'unico posto affidabile per le istruzioni di avvio)
2. Ho cancellato BOOT.md (non riconosciuto da OpenClaw)
3. Ho cancellato BOOTSTRAP.md (file di onboarding una tantum, già completato, sprecava 361 token ogni sessione)
4. Ho snellito MEMORY.md da 200 righe a 90 spostando i documenti di riferimento in una cartella docs/
5. Ho rimosso 20 skill di marketing inutilizzate che consumavano 3.000 token per sessione
6. Ho aggiunto disciplina di scrittura: ogni compito registra il suo risultato, ogni errore diventa una regola
7. Ho aggiunto un protocollo di passaggio: prima di qualsiasi cambio di modello o fine sessione, l'agente scrive il contesto corrente nel log giornaliero

La sequenza di avvio ora è così:

1markdown
2
3Prima di fare QUALSIASI COSA:
41. Leggi USER.md
51. Leggi learnings/LEARNINGS.md
61. Leggi memory/YYYY-MM-DD.md (oggi + ieri)
71. Leggi MEMORY.md (solo sessione principale, mai in gruppi)
81. Leggi PROTOCOL_COST_EFFICIENCY.md
91. Stampa: CARICATO: USER | LEARNINGS | DAILY | MEMORY | PROTOCOL

La disciplina di scrittura:

1markdown
2
3Dopo ogni compito:
41. Registra decisione + risultato → memory/YYYY-MM-DD.md
51. Se errore → aggiungi a learnings/LEARNINGS.md
61. Se contesto significativo → aggiorna MEMORY.md (solo durante le revisioni heartbeat, mai direttamente durante i compiti)

Il protocollo di passaggio:

1markdown
2
3Prima della fine della sessione o del cambio modello:
4Scrivi sezione HANDOVER in memory/YYYY-MM-DD.md:
5- Cosa è stato discusso
6- Cosa è stato deciso
7- Compiti in sospeso con dettagli precisi
8- Prossimi passi rimanenti

Risultati:

• Prompt di sistema: 11.887 → 8.529 token
• Skill: 51 → 32
• Token di sessione: 18.280 → 14.627
• 28% più leggero. Stesso agente. Stessi modelli. Solo meno rumore.

Cosa ho imparato:

La vera soluzione non era aggiungere più file. Era rimuovere quelli che non facevano nulla. Ogni token nel prompt di sistema è un costo che l'agente si porta dietro su ogni singolo messaggio. Skill inutilizzate, file di memoria gonfi, file che il sistema non legge nemmeno — si accumulano tutti silenziosamente.

Le regole che avrei voluto sapere al Giorno 1

Dopo 5 giorni di rotture e riparazioni, queste sono le regole che darei a chiunque configuri la memoria di OpenClaw:

1. Solo questi file vengono caricati automaticamente: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, MEMORY.md.

Tutto il resto ha bisogno di un'istruzione di lettura esplicita in AGENTS.md. Se non è nella sequenza di avvio, l'agente non lo vedrà. BOOT.md non è una cosa reale in OpenClaw. L'ho avuto per settimane. Non faceva nulla.

2. La sequenza di avvio va all'inizio di AGENTS.md.

Non nel mezzo. Non in fondo. All'inizio assoluto. I file caricati automaticamente vengono iniettati nel prompt di sistema, quindi le istruzioni di avvio devono essere la prima cosa che l'agente elabora.

3. La disciplina di scrittura conta più della disciplina di lettura.

La maggior parte delle persone configura file per l'agente da leggere, ma non impone mai la scrittura. Se l'agente non registra decisioni, risultati ed errori su disco, quelle cose esistono solo nella finestra di contesto. E la finestra di contesto viene compattata. La scrittura è come il contesto temporaneo diventa memoria permanente.

4. Non scrivere mai direttamente in MEMORY.md durante i compiti.

I log giornalieri sono grezzi e append-only. MEMORY.md è memoria a lungo termine curata. Se lasci che l'agente butti qualsiasi cosa in MEMORY.md, si gonfia in un pasticcio di 200 righe nel giro di settimane. Cura MEMORY.md durante revisioni periodiche (heartbeat o cron) distillando approfondimenti dai log giornalieri recenti. L'ho imparato da un altro utente di OpenClaw che ha scoperto il suo agente fare esattamente questo — gonfiare MEMORY.md con rumore non curato fino a renderlo inutile.

5. LEARNINGS.md è il file più sottovalutato.

Ogni errore che l'agente commette dovrebbe diventare una regola di una riga. "Non dichiarare mai codice inviato senza controllare lo stato di git." "Non leggere l'intero MEMORY.md nelle chat di gruppo." "Conferma sempre il fuso orario dell'utente prima di pianificare." Queste regole si accumulano. Dopo qualche settimana, il tuo agente ha un manuale operativo personale costruito dai suoi stessi fallimenti.

6. Testa il recupero, non solo l'archiviazione.

Archiviare informazioni e recuperarle sono problemi diversi. Ho avuto file indicizzati e ricercabili, ma mai accessibili perché l'agente non sapeva di doverli cercare. Pianta marcatori, testa tra sessioni, testa tra cambi di modello. Se l'agente non riesce a trovare ciò che hai archiviato ieri, l'archiviazione non conta.

7. Il protocollo di passaggio è la soluzione per il cambio modello.

Gli agenti OpenClaw perdono tutto il contesto quando cambi modello. Il nuovo modello parte con una finestra di contesto fresca — vede solo i file caricati automaticamente. Senza un protocollo di passaggio che riversi lo stato corrente nel log giornaliero prima del cambio, il nuovo modello non ha idea di cosa stesse succedendo. Questo è stato il mio singolo più grande punto dolente per settimane.

8. Esegui /context detail regolarmente.

Questo comando mostra esattamente cosa sta consumando i tuoi token. Skill che avevi dimenticato di aver installato, file che sono cresciuti senza che te ne accorgessi, strumenti che non usi mai. Ho trovato 20 skill inutilizzate che bruciavano 3.000 token per sessione. Sono 3.000 token di costo su ogni singolo messaggio, per funzionalità che non avevo mai toccato.

9. La ricerca ibrida batte la pura ricerca semantica.

BM25 (parole chiave) + vettori (significato) + reranking dà risultati significativamente migliori dei soli vettori. Nomi clienti, numeri specifici, frasi esatte — la ricerca semantica li perde. La ricerca per parole chiave li cattura. Usa entrambe.

10. La compattazione non è il nemico. Il contesto non scritto lo è.

Ho passato giorni a combattere la compattazione prima di rendersi conto che la soluzione era più semplice: assicurati che tutto ciò che è importante venga scritto in un file prima che la compattazione venga eseguita. Il flush di memoria gestisce questo automaticamente. Se è su disco, sopravvive alla compattazione. Se è solo nella conversazione, è a rischio.

La mia configurazione attuale

Per riferimento, ecco come appare ora il mio spazio di lavoro:

1workspace/
2├── AGENTS.md          (sequenza di avvio + disciplina di scrittura + protocollo di passaggio)
3├── SOUL.md            (personalità e comportamento)
4├── IDENTITY.md        (nome, ruolo)
5├── USER.md            (info proprietario)
6├── TOOLS.md           (linee guida per l'uso degli strumenti)
7├── HEARTBEAT.md       (comportamento di check-in autonomo)
8├── MEMORY.md          (memoria a lungo termine curata, ~90 righe)
9├── PROTOCOL_COST_EFFICIENCY.md
10├── learnings/
11│   └── LEARNINGS.md   (regole dagli errori)
12├── memory/            (log giornalieri: YYYY-MM-DD.md)
13├── docs/              (documenti di riferimento spostati da MEMORY.md)
14│   ├── tweetsmash-arch.md
15│   ├── knowledge-transfer.md
16│   ├── infrastructure.md
17│   └── group-chat-rules.md
18└── skills/            (32 skill, da 51)

Prompt di sistema: 8.529 token. Token di sessione: 14.627 su 200.000 finestra di contesto (7,3%). L'agente si avvia, legge ciò di cui ha bisogno, scrive ciò che impara e passa il contesto prima dei cambi di modello.

Ci sono voluti 5 giorni per arrivare qui. La maggior parte è stato disimparare l'assunzione che più file equivalgano a memoria migliore. Non è così. È la disciplina che conta. Il mio esperimento continua ancora.

Sto costruendo TweetSmash e LinkedMash — strumenti di bookmark per social media con il mio co-fondatore. Condivido ciò che imparo sull'esecuzione di agenti OpenClaw in produzione su X: @code_rams*