Spiegazione della memoria OpenClaw: architettura, configurazione e perché si dimentica

L'architettura di memoria OpenClaw completa (spiegazione di 3 livelli)

La memoria OpenClaw opera su tre livelli distinti, ciascuno con caratteristiche di persistenza e modalità di guasto diverse.

Ciclo di vita completo della memoria:

Write → Embed/Index → Search → Compact → Recover
  ↓          ↓           ↓         ↓         ↓
.md file   sqlite-vec  semantic  summary   MEMORY.md
created    indexes it  query     replaces  re-read at
           on save     returns   context   session start
                       chunks    window

Ogni fase di questa catena può fallire in modo indipendente. La maggior parte dei problemi di dimenticanza si riconducono esattamente a una fase interrotta.

Layer 1: la finestra del contesto attivo

Questa è la memoria di lavoro del modello: tutto ciò che è attualmente caricato nella finestra di contesto per la conversazione attiva. Include il prompt del sistema, la cronologia delle conversazioni e qualsiasi blocco di memoria recuperato dallo strumento di ricerca.

Cosa lo riempie:

• Prompt del sistema (spesso di grandi dimensioni)
• Estratti di memoria recuperati
• Cronologia delle chiamate dello strumento
• La conversazione si trasforma

Limite pratico: supponiamo di avere circa il 60-70% della finestra di contesto pubblicizzata del modello disponibile per la conversazione effettiva dopo il prompt del sistema e il sovraccarico della memoria.

Layer 2 — Note giornaliere (la finestra mobile di due giorni)

Le note giornaliere sono file Markdown di sola aggiunta denominati nel formato YYYY-MM-DD archiviati nella directory memory/. OpenClaw carica quello di oggi e quello di ieri file automaticamente all'inizio di ogni sessione.

• I fatti relativi al lavoro di oggi, alle decisioni prese e alle attività attive vengono aggiunti qui
• Non sono destinati a essere modificati: trattali come un registro
• Dopo due giorni, non rientrano nella finestra di caricamento automatico e diventano ricercabili solo tramite ricerca semantica

Layer 3 — Memoria durevole (MEMORY.md e memory-wiki)

I fatti a lungo termine che dovrebbero sopravvivere attraverso le sessioni (il tuo nome, il contesto del progetto, le preferenze di codifica, le decisioni sull'architettura) appartengono a MEMORY.md o al vault strutturato del plugin memory-wiki.

Il problema della compattazione: perché le tue istruzioni svaniscono a metà attività

La compattazione è la modalità di errore meno documentata in OpenClaw. La maggior parte degli articoli tratta dell’oblio post-sessione. Quasi nessun indirizzo compattazione a metà attività in flussi di lavoro autonomi di lunga durata — quando l'agente sta eseguendo un'attività in più passaggi, la compattazione si attiva silenziosamente al passaggio 7 di 12 e le istruzioni comportamentali del passaggio 1 scompaiono.

Cosa fa la compattazione:

1. Rileva che la finestra di contesto si sta avvicinando alla capacità massima
2. Riassume la conversazione corrente in un blocco condensato
3. Sostituisce il contesto originale con il riepilogo
4. Continua l'esecuzione

Quando si attiva: Non esiste una soglia configurabile nel plugin memory-core predefinito. Si attiva in base al conteggio dei token, non alla fase dell'attività. In una corsa autonoma di 2 ore, puoi aspettarti 3-5 cicli di compattazione.

Come costruire un'architettura di file resistente alla compattazione

Inserisci le istruzioni comportamentali in MEMORY.md, non nella conversazione. Tutto ciò che deve sopravvivere a più cicli di compattazione deve trovarsi in un file durevole che viene riletto dopo ogni compattazione.

Schema di blocco consigliato:

## Agent Behavioral Rules (always active)
- Never overwrite files without showing a diff first
- Write tests before implementation (TDD mode: on)
- Use TypeScript strict mode in all new files

## Project Context
- Stack: Node.js 22, Fastify, PostgreSQL 16
- Repo root: /home/user/project
- Active sprint goal: migrate auth to Clerk

Convenzioni di denominazione che sopravvivono alla compattazione:

• Prefisso le sezioni critiche con ## [PINNED]: il riepilogo considera le intestazioni maiuscole come ad alta priorità
• Mantieni ogni fatto su una riga, ove possibile: i paragrafi densi vengono riepilogati, i fatti su una sola riga tendono a sopravvivere alla lettera
• Ripeti le 3-5 regole comportamentali più critiche sia in MEMORY.md che nella nota quotidiana di oggi: la ridondanza è la tua copertura di compattazione

Configurazione da zero a memoria in 10 minuti (impalcatura file completa)

Questa è la guida all'installazione che non esiste da nessun'altra parte. Copia questa struttura, inserisci il contesto e sei pronto.

Albero delle directory:

memory/
├── MEMORY.md
├── 2026-04-27.md          ← today's daily note (create manually)
└── wiki/                  ← only if using memory-wiki plugin
    ├── index.md
    ├── project-context.md
    └── decisions.md

Avviatore MEMORY.md:

# Persistent Memory

## Identity & Preferences
- Name: [your name]
- Role: [your role]
- Preferred response style: concise, no preamble

## Project: [Project Name]
- Stack: [your stack]
- Key constraints: [e.g., no external APIs, TypeScript only]
- Current focus: [active task or sprint goal]

## Behavioral Rules
- [Rule 1]
- [Rule 2]

## Decisions Made
- [YYYY-MM-DD] Decided to use X because Y

Nota giornaliera iniziale (2026-04-27.md):

# 2026-04-27

## Session Goals
- [ ] Task 1
- [ ] Task 2

## Notes

Configurazione slot plug-in (sintassi 2026):

Per disabilitare completamente la memoria:

{
  "plugins": {
    "slots": {
      "memory": false
    }
  }
}

Passaggi di verifica:

1. Esegui una sessione e chiedi all'agente di ricordare qualcosa che gli hai detto in una sessione precedente
2. Controlla che sia stato scritto memory/YYYY-MM-DD.md (dovrebbe avere nuovi contenuti)
3. Chiedi direttamente all'agente: "Cosa sai di me?" - dovrebbe estrarre da MEMORY.md

Configuring memory-wiki per una knowledge base di produzione

Abilitalo scambiando lo slot del plugin:

{
  "plugins": {
    "slots": {
      "memory": "memory-wiki"
    }
  }
}

memory-wiki genera un deposito strutturato in memory/wiki/. Ogni argomento ha la propria pagina. Il plugin compila un digest.md che aggrega fatti altamente affidabili e non contraddittori affinché l'agente possa caricarli all'avvio della sessione.

Struttura pratica del caveau per un agente di produzione:

Semantic Search and Embeddings: SQLite, sqlite-vec e JS Fallback

OpenClaw indicizza i file di memoria utilizzando SQLite with the sqlite-vec extension per la ricerca di somiglianza vettoriale. Quando tu o l'agente effettuate una ricerca in memoria, incorpora la query e recupera i blocchi più semanticamente rilevanti.

Verifica che il tuo archivio vettoriale sia integro:

Se sqlite-vec non è disponibile (comune su ARM Linux e alcune configurazioni Windows), OpenClaw ricorre a un'estensione vettoriale puramente JS. Forza il fallback in modo esplicito:

{
  "memory": {
    "vectorBackend": "js"
  }
}

Segment-Specific Memory Strategies

Solo Developer: spese generali minime, richiamo massimo

Configurazione consigliata: plugin memory-core, MEMORY.md + solo note giornaliere, nessun deposito wiki.

• Mantieni MEMORY.md sotto le 200 righe: i file più lunghi rallentano l'avvio della sessione
• Aggiungi alle note giornaliere in modo aggressivo; non cercare di mantenerli puliti
• Rivedi e elimina MEMORY.md settimanalmente: i fatti obsoleti peggiorano la qualità della ricerca

Pipeline multi-agente: memoria condivisa tra agenti

Quando più agenti leggono e scrivono nella stessa directory memory/, sono necessarie regole di proprietà esplicite.

• One agent owns writes to each file — le scritture simultanee sullo stesso file .md produrranno conflitti
• Utilizza sottodirectory per agente: memory/agent-a/, memory/agent-b/, con un memory/shared/MEMORY.md condiviso
• Utilizza memory-wiki per il vault condiviso: la sua compilazione digest gestisce l'aggiornamento su più autori meglio dei file non elaborati

Long-Running Autonomous Tasks — Sopravvivere alle ore di esecuzione

Per gli agenti che eseguono attività misurate in ore:

• Force memory writes at checkpoints — dopo ciascuna fase dell'attività principale, chiedere all'agente di aggiungere il suo stato attuale alla nota giornaliera di oggi
• Pre-load compaction-resistant context — inserisci la specifica completa dell'attività in MEMORY.md prima dell'inizio dell'esecuzione, non solo nel messaggio iniziale
• Set explicit continuation markers nelle note giornaliere: <!-- RESUME POINT: completed steps 1-4, next: step 5 --> in modo che l'agente possa auto-orientarsi dopo un ciclo di compattazione

Troubleshooting OpenClaw Memory: diagnostica eventuali problemi di dimenticanza in 2 minuti

Segui questi passaggi in ordine:

Frequently Asked Questions

Verdetto finale: l'impostazione della memoria che funziona davvero

Recommended baseline per la maggior parte degli utenti: Plugin memory-core, directory memory/ creata prima della prima sessione, MEMORY.md con regole comportamentali in una sezione fissata chiaramente etichettata, note giornaliere aggiunte durante ogni sessione.

La tua lista di controllo delle azioni:

• Crea la directory memory/ nella root del tuo progetto
• Copia il modello MEMORY.md iniziale sopra e inserisci il contesto
• Verifica che plugins.slots.memory sia impostato su "memory-core" (o il plugin scelto)
• Aggiungi le tue 3-5 regole comportamentali più critiche in ## [PINNED] in MEMORY.md
• Dopo la prima sessione, conferma che è stata scritta una nota giornaliera con data
• Se la ricerca semantica sembra inadeguata, esegui openclaw reindex per ricostruire l'indice del vettore

L'architettura è solida una volta che la capisci. La maggior parte dei problemi di dimenticanza si risolvono entro 10 minuti dopo aver seguito questa lista di controllo.