La memoria di OpenClaw: come funziona, perché è importante e come controllarla

L’ascesa degli agenti IA autonomi ha introdotto un nuovo paradigma nei sistemi software: la cognizione artificiale persistente. A differenza dei chatbot tradizionali che operano senza stato, i moderni framework di agenti come OpenClaw consentono flussi di lavoro IA continui e consapevoli del contesto. Al centro di questa capacità c’è il sistema di memoria di OpenClaw, che permette all’agente di memorizzare, recuperare ed evolvere la conoscenza tra le sessioni.

La memoria persistente trasforma gli assistenti IA da strumenti conversazionali effimeri in sistemi con stato capaci di ricordare decisioni, apprendere preferenze e mantenere conoscenze a livello di progetto nel tempo. In pratica, questo significa che gli sviluppatori non devono più spiegare ripetutamente il contesto o reinizializzare i workflow a ogni interazione con l’agente ( Se ti stai ancora chiedendo come iniziare e configurare OpenClaw, ecco il tutorial di cinque minuti sulla configurazione di OpenClaw con CometAPI).

Tuttavia, questo cambiamento architetturale introduce anche complesse sfide ingegneristiche:

• Come vengono memorizzati e recuperati i dati di memoria?
• Come possono gli sviluppatori controllare il comportamento della memoria?
• Quali sono le implicazioni di sicurezza della memoria persistente dell’agente?
• Come può la memoria scalare senza sovraccaricare la finestra di contesto dell’LLM?

Questo articolo fornisce un’analisi tecnica approfondita del sistema di memoria di OpenClaw, inclusi architettura, modello di archiviazione, pipeline di recupero, meccanismi di controllo e considerazioni di sicurezza.

Che cos’è OpenClaw?

OpenClaw è un assistente IA personale open-source, workspace-first, che esegui sui tuoi dispositivi. Si connette a piattaforme di chat (WhatsApp, Telegram, Slack, Discord, ecc.), espone un piano di controllo Gateway e—cruciale per questo articolo—conserva ciò che “ricorda” come file in chiaro all’interno di una directory di workspace. Questo design rende la memoria al contempo trasparente e direttamente controllabile: la memoria non è un database nascosto dentro il modello; i file nel workspace dell’agente sono la fonte di verità.

Sistemi IA senza stato vs con stato

I sistemi conversazionali IA tradizionali operano in modalità senza stato. Ogni interazione è elaborata in modo indipendente, senza consapevolezza delle sessioni precedenti se non fornita esplicitamente nel prompt.

Questo crea diversi limiti:

• Il contesto si azzera tra le sessioni
• Gli utenti devono ripetere le informazioni
• L’apprendimento a lungo termine è impossibile
• I workflow non possono persistere

OpenClaw affronta questo limite introducendo memoria persistente archiviata direttamente nel workspace dell’agente.

Invece di fare affidamento solo sulla finestra di contesto del modello linguistico, OpenClaw mantiene un livello di memoria locale memorizzato come file strutturati che l’agente può leggere e aggiornare.

Questo abilita:

• Continuità del contesto tra sessioni
• Archiviazione della conoscenza a lungo termine
• Assistenti IA personalizzati
• Automazione dei workflow su orizzonti temporali estesi

Di conseguenza, OpenClaw trasforma gli assistenti IA da risponditori senza stato ad agenti portatori di conoscenza.

Architettura della memoria — i quattro livelli che contano

Il runtime di OpenClaw organizza le informazioni in livelli. Comprendere questi livelli è la chiave per controllare cosa l’agente ricorda e a cosa può accedere.

1) File di bootstrap del workspace — il nucleo durevole

File come SOUL.md, AGENTS.md, IDENTITY.md, TOOLS.md e MEMORY.md risiedono alla radice del workspace e sono trattati come materiale di bootstrap. Sono ricaricati da disco all’avvio della sessione e rappresentano la memoria più durevole: sopravvivono alla compattazione dei token e vengono reintrodotti in ogni assemblaggio del prompt da disco anziché dalla cronologia di sessione transitoria. Usa questi file per fatti di lunga durata (preferenze utente, vincoli legali, decisioni di progetto).

2) File giornalieri/di sessione — contesto di breve/medio termine

OpenClaw raccoglie le trascrizioni delle conversazioni e salva file di sessione (ad esempio note giornaliere sotto una cartella memory/). Sono utili per il contesto recente e la continuità di sessione, ma possono essere potati o compattati quando la finestra di contesto del tuo agente diventa troppo grande. Molti utenti si affidano a file di note giornaliere come memory/2026-03-10.md per catturare fatti ad hoc.

3) Finestra di contesto dell’LLM — effimera ma decisiva

Il prompt di ogni turno è costruito da una combinazione di file di bootstrap, cronologia recente di sessione e risultati di memoria recuperati. Questo contesto “nel prompt” è ciò che l’LLM effettivamente “vede” quando produce una risposta; è effimero (limitato dai budget di token) e ricostruito a ogni turno. Se vuoi che l’agente agisca in modo coerente, assicurati che le direttive essenziali siano nei file di bootstrap—non solo in messaggi effimeri.

4) Indice semantico / plugin di memoria — recupero rapido

Per consentire all’agente di trovare note passate rilevanti, OpenClaw usa un plugin di memoria (predefinito: memory-core) che fornisce ricerca semantica sui file Markdown e opzionali archivi vettoriali esterni (sqlite-vec, LanceDB, QMD, ecc.). L’indice è separato dai file: i file sono la fonte di verità; l’indice accelera il recupero. Puoi cambiare plugin per modificare il comportamento del backend (provider di embedding, algoritmo di retrieval, persistenza).

Come funziona la memoria di OpenClaw?

Architettura dell’agente basata su Gateway

OpenClaw utilizza un’architettura incentrata sul gateway che orchestra la comunicazione tra diversi componenti di sistema.

Componenti principali:

All’interno di questa architettura, la memoria funge da livello di archiviazione a lungo termine per la conoscenza dell’agente.

Memoria come file (la verità canonica)

OpenClaw pone i file Markdown in chiaro nel workspace dell’agente al centro del proprio modello di memoria. L’agente scrive su e legge da questi file; essi sono l’archivio persistente, modificabile dall’uomo. L’LLM “ricorda” solo ciò che è stato scritto su disco — il contesto di sessione volatile è separato. File tipici e convenzioni includono:

• MEMORY.md — elementi di memoria curati e durevoli (decisioni, dati del profilo utente, preferenze persistenti).
• memory/YYYY-MM-DD.md — log giornalieri append-only usati come memoria giornaliera/effimera.
• USER.md, SOUL.md, AGENTS.md — altri file del workspace che influenzano la personalità o il comportamento dell’agente.
  Questi file vivono nel workspace dell’agente (predefinito ~/.openclaw/workspace) e possono essere letti o modificati da te in qualsiasi momento.

Due percorsi di accesso: basati su file + basati su indice

Poiché i file in chiaro sono inefficienti per ricerche semantiche su larga scala, OpenClaw abbina la sorgente Markdown a un indice (uno store vettoriale più un indice testuale opzionale BM25). L’indice è usato dal tool orientato all’agente memory_search; le letture mirate usano memory_get, che legge direttamente un intervallo di righe di un file. L’approccio di indicizzazione ibrido — embedding (vettoriali) + BM25 (keyword) — fornisce sia richiamo semantico sia affidabilità per corrispondenze esatte. L’archiviazione tipica dell’indice è un file SQLite locale potenziato per la ricerca vettoriale (ad es. ~/.openclaw/agents/<agentId>/index.sqlite).

• memory_search(query, topK) — restituisce un elenco classificato di snippet corrispondenti con metadati (percorso, righe, punteggio). Usalo quando vuoi che l’agente “cerchi prima” la memoria pertinente prima di rispondere.
• memory_get(path, startLine, endLine) — restituisce una porzione grezza di un file Markdown; usalo quando sai già dove si trova la memoria.
  Questi sono strumenti integrati dell’agente; skill e codice personalizzato possono chiamarli secondo necessità.

Ciclo di vita: scrittura, indicizzazione, richiamo, flush, compattazione

OpenClaw implementa un esplicito ciclo di vita della memoria:

1. Scrittura — l’agente scrive la memoria nei file Markdown quando si verifica un evento degno di memoria (richiesta esplicita, decisione registrata o un flush di memoria automatico).
2. Indicizzazione — un watcher di file e un job batch indicizzano in modo incrementale i file nuovi/modificati nello store vettoriale + BM25.
3. Richiamo — l’agente invoca memory_search (semantico) o memory_get (mirato) durante una sessione.
4. Flush della memoria (pre-compattazione) — quando il contesto della sessione si avvicina al limite della finestra del modello, OpenClaw attiva un turno silenzioso dell’agente per scrivere su disco tutto ciò che l’agente ritiene debba essere preservato prima della compattazione (è configurabile).
5. Compattazione — il sistema comprime o riassume il contesto per mantenere piccola la sessione attiva; i file di memoria sono la base durevole di fallback.

Pipeline di chunking ed embedding (dettaglio tecnico)

Quando i file vengono indicizzati, sono suddivisi in chunk (euristiche comuni: ~300–500 token per chunk con overlap), poi ogni chunk viene convertito in un embedding usando un provider scelto da te (OpenAI, Gemini, embedding locali GGUF, ecc.). I vettori risultanti sono archiviati insieme ai metadati di origine (percorso file, riga iniziale/finale, timestamp) per il recupero. Il recupero avviene calcolando l’embedding della query, effettuando una ricerca dei vicini più prossimi nello spazio vettoriale e poi combinando opzionalmente con punteggi BM25 e un reranker. Questo approccio ibrido migliora la precisione per query fattuali preservando il richiamo semantico per contenuti parafrasati.

Concreto: come controllare la memoria (comandi, file, configurazione)

Di seguito sono riportate azioni pratiche passo-passo che operatori e sviluppatori dovrebbero usare per ispezionare, modificare e controllare la memoria di OpenClaw. Gli esempi assumono un’installazione locale standard in cui il workspace predefinito è ~/.openclaw/workspace (puoi sovrascriverlo tramite agents.defaults.workspace).

Ispezionare ed eseguire il backup dei file di memoria grezzi

La memoria è Markdown. Esegui il backup del workspace o, almeno, copia MEMORY.md e la cartella memory/.

Esempio shell:

# show workspace location (recommended)openclaw config get agents.defaults.workspace# copy memory files to a timestamped backupcp -r ~/.openclaw/workspace ~/.openclaw/workspace-backup-$(date +%F-%H%M)# or only memory files:cp ~/.openclaw/workspace/MEMORY.md ~/backups/opencaw-MEMORY-$(date +%F).mdcp -r ~/.openclaw/workspace/memory ~/backups/opencaw-memory-$(date +%F)/

La documentazione e le guide della community raccomandano esplicitamente di copiare MEMORY.md + memory/ per esportazione/backup.

Modificare MEMORY.md — il modo consigliato per codificare fatti di lungo termine

Inserisci preferenze e fatti stabili in MEMORY.md. Questo file viene letto all’avvio della sessione per iniezione diretta nel contesto.

Esempio di snippet MEMORY.md:

# MEMORY.md## User preferences- timezone: Asia/Tokyo- prefers_brief_responses: true- default_calendar: personal@gmail.com## Projects- acme-internal: deploy target Cloudflare Workers, main repo: github.com/org/acme

Dopo la modifica, non è richiesto alcun riavvio per la lettura dei file nelle nuove sessioni; tuttavia, per gli indici dei plugin potrebbe essere necessario reindicizzare (vedi sotto).

Scrittura programmatica della memoria (esempio Node.js)

Poiché la memoria è costituita da file, semplici script possono aggiungere o creare elementi di memoria. Questo è utile quando un sistema esterno vuole registrare fatti nel workspace dell’agente.

// append-memory.js (Node.js)import {writeFileSync, appendFileSync} from 'fs';import {homedir} from 'os';import path from 'path';const ws = path.join(homedir(), '.openclaw', 'workspace');const mdPath = path.join(ws, 'memory', `${new Date().toISOString().slice(0,10)}.md`);// ensure folder exists and append a factappendFileSync(mdPath, `\n- ${new Date().toISOString()}: Completed deployment for project X\n`);console.log(`Wrote to ${mdPath}`);

Suggerimento: usa openclaw config get agents.defaults.workspace per confermare il percorso del workspace prima di scrivere.

Reindicizzazione e controllo del plugin

Se modifichi i file di memoria e dipendi dalla ricerca semantica, è necessaria la reindicizzazione (o l’attesa dell’indicizzatore automatico del plugin).

• Verifica quale plugin è attivo: openclaw config get plugins.slots.memory
• Reindicizza (dipende dal plugin—molti plugin espongono una CLI come openclaw memory reindex o richiedono il riavvio del Gateway).

Esempio di snippet di configurazione per disattivare i plugin di memoria (forza il comportamento solo-file):

// ~/.openclaw/openclaw.json (partial){  "plugins": {    "slots": {      "memory": "none"    }  }}

Dopo aver modificato le impostazioni del plugin, riavvia il Gateway per rendere effettiva la configurazione:

openclaw gateway restart

Documentazione e riferimenti di configurazione mostrano specificamente plugins.slots.memory e plugins.installs come controlli per la gestione dei plugin di memoria.

Sostituire i backend di memoria — esempio: aggiungere un plugin LanceDB

Esistono plugin della community per sostituire il backend di memoria predefinito con store vettoriali di maggiore scala. Schema di esempio (da un plugin community ampiamente usato):

# from your workspace rootcd ~/.openclaw/workspacegit clone https://github.com/win4r/memory-lancedb-pro.git plugins/memory-lancedb-procd plugins/memory-lancedb-pronpm install# then update openclaw.json to activate the 'memory-lancedb-pro' plugin# and restart gateway:openclaw gateway restart

Il README del plugin e gli autori raccomandano percorsi assoluti in plugins.load.paths e variabili d’ambiente esplicite per le chiavi API di embedding.

Ricerca della memoria via CLI e troubleshooting

OpenClaw espone helper CLI come openclaw memory per cercare o gestire l’indice semantico. Tieni d’occhio problemi specifici del plugin (ad esempio, gli utenti del backend QMD hanno segnalato incongruenze tra indice/ricerca che hanno richiesto una riconfigurazione). Quando i risultati mancano, reindicizza e controlla i log del plugin.

Memoria come file (la verità canonica)

OpenClaw pone i file Markdown in chiaro nel workspace dell’agente al centro del proprio modello di memoria. L’agente scrive su e legge da questi file; essi sono l’archivio persistente, modificabile dall’uomo. L’LLM “ricorda” solo ciò che è stato scritto su disco — il contesto di sessione volatile è separato. File tipici e convenzioni includono:

• MEMORY.md — elementi di memoria curati e durevoli (decisioni, dati del profilo utente, preferenze persistenti).
• memory/YYYY-MM-DD.md — log giornalieri append-only usati come memoria giornaliera/effimera.
• USER.md, SOUL.md, AGENTS.md — altri file del workspace che influenzano la personalità o il comportamento dell’agente.
  Questi file vivono nel workspace dell’agente (predefinito ~/.openclaw/workspace) e possono essere letti o modificati da te in qualsiasi momento.

Conclusione

Il sistema di memoria di OpenClaw rappresenta un cambiamento fondamentale nell’architettura dell’IA.

Invece di conversazioni effimere, la piattaforma introduce livelli di memoria persistenti e controllati dagli sviluppatori che consentono agli agenti IA di accumulare conoscenza nel tempo.

Il suo design enfatizza:

• trasparenza tramite archiviazione basata su file
• scalabilità tramite recupero basato su embedding
• controllo per gli sviluppatori tramite configurazione
• estensibilità tramite plugin

Tuttavia, la memoria persistente introduce anche nuove sfide ingegneristiche e di sicurezza che gli sviluppatori devono gestire con attenzione.

Man mano che gli agenti autonomi diventano più potenti e ampiamente distribuiti, sistemi di memoria come quello di OpenClaw diventeranno probabilmente un componente centrale della prossima generazione di sistemi software intelligenti.

CometAPI ora si integra con openclaw. Se stai cercando API che supportano Claude, Gemini e GPT-5 Series, CometAPI è la scelta migliore per usare openclaw, e il prezzo della sua API è continuamente scontato.). OpenClaw ha aggiornato di recente la sua compatibilità con GPT-5.4 e ha ottimizzato il suo workflow. Ora puoi anche configurare OpenClaw tramite GPT-5.4 di CometAPI.

Pronti a partire?→ Iscriviti a openclaw oggi !

Se vuoi conoscere altri suggerimenti, guide e novità sull’IA seguici su VK, X e Discord!