Riferimento per la configurazione della memoria

Questa pagina elenca tutte le opzioni di configurazione per la ricerca nella memoria di OpenClaw. Per una panoramica concettuale, consulta:

Tutte le impostazioni di ricerca nella memoria si trovano in agents.defaults.memorySearch nel file openclaw.json (oppure in una sostituzione specifica per agente agents.list[].memorySearch), salvo diversa indicazione.

Selezione del provider

Quando provider non è impostato, OpenClaw utilizza gli embedding di OpenAI. Imposta esplicitamente provider per utilizzare Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, un modello GGUF locale o un endpoint /v1/embeddings compatibile con OpenAI. Le configurazioni precedenti che contengono ancora provider: "auto" vengono risolte in openai.

Quando provider non è impostato, è presente il valore precedente provider: "auto" oppure provider: "none" seleziona intenzionalmente la modalità basata solo su FTS, il recupero dalla memoria può comunque utilizzare l'ordinamento lessicale FTS quando gli embedding non sono disponibili.

I provider espliciti non locali adottano una strategia di chiusura in caso di errore. Se imposti memorySearch.provider su un provider concreto basato su un servizio remoto, come Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage o un provider personalizzato compatibile con OpenAI, e tale provider non è disponibile durante l'esecuzione, memory_search restituisce un risultato di indisponibilità anziché utilizzare silenziosamente il recupero basato solo su FTS. Correggi la configurazione del provider o dell'autenticazione, passa a un provider raggiungibile oppure imposta provider: "none" se desideri intenzionalmente un recupero basato solo su FTS.

ID di provider personalizzati

memorySearch.provider può puntare a una voce personalizzata models.providers.<id> per adattatori di provider specifici per la memoria, come ollama, oppure per API di modelli compatibili con OpenAI, come openai-responses / openai-completions. OpenClaw risolve il proprietario di api di tale provider per l'adattatore di embedding, mantenendo al contempo l'ID del provider personalizzato per la gestione dell'endpoint, dell'autenticazione e del prefisso del modello. Ciò consente alle configurazioni con più GPU o più host di dedicare gli embedding della memoria a uno specifico endpoint locale:

{  models: {    providers: {      "ollama-5080": {        api: "ollama",        baseUrl: "http://gpu-box.local:11435",        apiKey: "ollama-local",        models: [{ id: "qwen3-embedding:0.6b", name: "Qwen3 Embedding 0.6B" }],      },    },  },  agents: {    defaults: {      memorySearch: {        provider: "ollama-5080",        model: "qwen3-embedding:0.6b",      },    },  },}

Risoluzione della chiave API

Gli embedding remoti richiedono una chiave API. Bedrock utilizza invece la catena di credenziali predefinita dell'AWS SDK (ruoli dell'istanza, SSO, chiavi di accesso o una chiave API Bedrock).

Configurazione dell'endpoint remoto

Utilizza provider: "openai-compatible" per un server /v1/embeddings generico compatibile con OpenAI che non deve ereditare le credenziali globali della chat OpenAI.

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        model: "text-embedding-3-small",        remote: {          baseUrl: "https://api.example.com/v1/",          apiKey: "YOUR_KEY",        },      },    },  },}

Configurazione specifica del provider

{  agents: {    defaults: {      memorySearch: {        provider: "openai-compatible",        remote: {          baseUrl: "https://embeddings.example/v1",          apiKey: "${EMBEDDINGS_API_KEY}",        },        model: "asymmetric-embedder",        queryInputType: "query",        documentInputType: "passage",      },    },  },}

{  agents: {    defaults: {      memorySearch: {        provider: "bedrock",        model: "amazon.titan-embed-text-v2:0",      },    },  },}

{  "Effect": "Allow",  "Action": "bedrock:InvokeModel",  "Resource": "*"}

arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

openclaw memory status --deep --agent mainopenclaw memory index --force --agent main

Timeout degli embedding in linea

Comportamento dell'indicizzazione

Tutte le opzioni si trovano sotto memorySearch.sync, salvo diversa indicazione:

Configurazione della ricerca ibrida

Tutte le opzioni sotto memorySearch.query:

E sotto memorySearch.query.hybrid:

Esempio completo

{  agents: {    defaults: {      memorySearch: {        query: {          maxResults: 6,          minScore: 0.35,          hybrid: {            vectorWeight: 0.7,            textWeight: 0.3,            mmr: { enabled: true, lambda: 0.7 },            temporalDecay: { enabled: true, halfLifeDays: 30 },          },        },      },    },  },}

Percorsi di memoria aggiuntivi

{  agents: {    defaults: {      memorySearch: {        extraPaths: ["../team-docs", "/srv/shared-notes"],      },    },  },}

I percorsi possono essere assoluti o relativi allo spazio di lavoro. Le directory vengono analizzate ricorsivamente alla ricerca di file .md. La gestione dei collegamenti simbolici dipende dal backend attivo: il motore integrato ignora i collegamenti simbolici, mentre QMD segue il comportamento dello scanner QMD sottostante.

Per la ricerca nelle trascrizioni tra agenti con ambito limitato all'agente, usare agents.list[].memorySearch.qmd.extraCollections anziché memory.qmd.paths. Queste raccolte aggiuntive seguono la stessa struttura { path, name, pattern? }, ma vengono unite per ogni agente e possono mantenere nomi condivisi espliciti quando il percorso punta all'esterno dello spazio di lavoro corrente. Se lo stesso percorso risolto compare sia in memory.qmd.paths sia in memorySearch.qmd.extraCollections, QMD mantiene la prima voce e ignora il duplicato.

Memoria multimodale (Gemini)

Indicizza immagini e audio insieme a Markdown usando Gemini Embedding 2:

Formati supportati: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (immagini); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).

Cache degli embedding

Evita di generare nuovamente gli embedding del testo invariato durante la reindicizzazione o gli aggiornamenti delle trascrizioni. Lascia maxEntries non impostato per una cache senza limiti; impostalo quando la crescita dello spazio su disco è più importante della velocità massima di reindicizzazione. Quando è impostato, una volta superato il limite vengono eliminate per prime le voci meno recenti, in base all'ora dell'ultimo aggiornamento.

Indicizzazione in batch

Disponibile per gemini, openai e voyage. L'elaborazione in batch di OpenAI è generalmente la soluzione più rapida ed economica per i backfill di grandi dimensioni.

remote.nonBatchConcurrency controlla le chiamate di embedding inline utilizzate dai provider locali o self-hosted e dai provider in hosting quando le API batch del provider non sono attive. Per l'indicizzazione non batch, il valore predefinito di Ollama è 1, per evitare di sovraccaricare gli host locali meno potenti; imposta un valore superiore sui computer più potenti.

Questa impostazione è distinta da sync.embeddingBatchTimeoutSeconds, che controlla il timeout delle chiamate di embedding inline.

Ricerca nella memoria delle sessioni (sperimentale)

Indicizza le trascrizioni delle sessioni e rendile disponibili tramite memory_search:

Anche i risultati delle trascrizioni delle sessioni rispettano tools.sessions.visibility. La visibilità predefinita tree espone solo la sessione corrente e le sessioni da essa avviate. Per recuperare, da una sessione diversa come un messaggio diretto, una sessione non correlata dello stesso agente distribuita dal Gateway, amplia intenzionalmente la visibilità ad agent (oppure ad all solo quando è richiesto anche il recupero tra agenti e i criteri di comunicazione tra agenti lo consentono).

Gli esempi seguenti collocano queste impostazioni sotto agents.defaults. Puoi anche applicare impostazioni memorySearch equivalenti in una sostituzione per singolo agente quando solo un agente deve indicizzare e cercare nelle trascrizioni delle sessioni.

Per il recupero dal Gateway ai messaggi diretti dello stesso agente:

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  tools: {    sessions: { visibility: "agent" },  },}

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  memory: {    backend: "qmd",    qmd: {      sessions: { enabled: true },    },  },  tools: {    sessions: { visibility: "agent" },  },}

Quando utilizzi QMD, agents.defaults.memorySearch.experimental.sessionMemory e sources: ["sessions"] non esportano autonomamente le trascrizioni in QMD. Imposta anche memory.qmd.sessions.enabled: true.

Accelerazione vettoriale SQLite (sqlite-vec)

Quando sqlite-vec non è disponibile, OpenClaw passa automaticamente alla similarità del coseno calcolata all'interno del processo.

Archiviazione degli indici

Gli indici di memoria integrati si trovano nel database SQLite di OpenClaw di ciascun agente, in agents/<agentId>/agent/openclaw-agent.sqlite.

Configurazione del backend QMD

Imposta memory.backend = "qmd" per abilitarlo. Tutte le impostazioni QMD si trovano sotto memory.qmd:

searchMode: "search" usa esclusivamente la ricerca lessicale/BM25. Per questa modalità, OpenClaw non esegue verifiche di disponibilità dei vettori semantici né la manutenzione degli embedding QMD, anche durante memory status --deep; vsearch e query continuano a richiedere la disponibilità dei vettori e degli embedding QMD.

rerank: false modifica solo la modalità query di QMD e richiede QMD 2.1 o una versione successiva. In modalità CLI diretta, OpenClaw passa --no-rerank; nella modalità MCP basata su mcporter, passa rerank: false allo strumento di query unificato di QMD. Lascialo non impostato per usare il comportamento predefinito di riordinamento delle query di QMD.

OpenClaw preferisce i formati correnti delle raccolte QMD e delle query MCP, ma mantiene la compatibilità con le versioni precedenti di QMD provando, quando necessario, flag compatibili per i pattern delle raccolte e i nomi meno recenti degli strumenti MCP. Quando QMD dichiara il supporto per più filtri di raccolta, le raccolte con la stessa origine vengono cercate tramite un unico processo QMD; le build meno recenti di QMD mantengono il percorso di compatibilità per singola raccolta. Per stessa origine si intende che le raccolte di memoria persistente (file di memoria predefiniti e percorsi personalizzati) vengono raggruppate, mentre le raccolte delle trascrizioni delle sessioni rimangono un gruppo separato, affinché la diversificazione delle origini continui a disporre di entrambi gli input.

Integrazione con mcporter

Tutte le impostazioni si trovano sotto memory.qmd.mcporter. Instrada le ricerche QMD attraverso un demone MCP mcporter di lunga durata invece di avviare qmd per ogni query, riducendo il sovraccarico dell'avvio a freddo per i modelli più grandi.

Richiede che mcporter sia installato e disponibile nel PATH, oltre a un server mcporter configurato che esegua qmd mcp. Mantienilo disabilitato per le configurazioni locali più semplici, nelle quali il costo dell'avvio di un processo per ogni query è accettabile.

{  memory: {    qmd: {      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },    },  },}

Quando è abilitata l'inizializzazione di QMD all'avvio del Gateway, OpenClaw avvia QMD solo per gli agenti idonei. Se update.onBoot è true e non è configurata alcuna manutenzione a intervalli o degli embedding, all'avvio viene usato un gestore monouso per l'aggiornamento iniziale, che viene poi chiuso. Se è configurato un intervallo di aggiornamento o degli embedding, all'avvio viene aperto il gestore QMD a lunga durata, affinché possa gestire il watcher e i timer degli intervalli; update.onBoot: false evita solo l'aggiornamento immediato all'avvio.

Esempio QMD completo

{  memory: {    backend: "qmd",    citations: "auto",    qmd: {      includeDefaultMemory: true,      update: { interval: "5m", debounceMs: 15000 },      limits: { maxResults: 4, timeoutMs: 4000 },      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],    },  },}

Dreaming

Dreaming si configura in plugins.entries.memory-core.config.dreaming, non in agents.defaults.memorySearch.

Dreaming viene eseguito come un'unica scansione pianificata e utilizza internamente le fasi leggera, profonda e REM come dettaglio implementativo.

Per il comportamento concettuale e i comandi slash, consulta Dreaming.

Impostazioni utente

Esempio

{  plugins: {    entries: {      "memory-core": {        subagent: {          allowModelOverride: true,          allowedModels: ["anthropic/claude-sonnet-4-6"],        },        config: {          dreaming: {            enabled: true,            frequency: "0 3 * * *",            model: "anthropic/claude-sonnet-4-6",          },        },      },    },  },}

Correlati

• Riferimento della configurazione
• Panoramica della memoria
• Ricerca nella memoria