Riferimento per la configurazione della memoria

Questa pagina elenca tutte le opzioni di configurazione per la ricerca nella memoria di OpenClaw. Per panoramiche concettuali, consultare:

Tutte le impostazioni della ricerca nella memoria si trovano in agents.defaults.memorySearch all'interno di openclaw.json (o in una sostituzione agents.list[].memorySearch specifica per agente), salvo diversa indicazione.

Selezione del provider

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

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

I provider non locali espliciti adottano un comportamento fail-closed. Se si imposta memorySearch.provider su un provider concreto supportato da 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é usare silenziosamente il recupero solo FTS. Correggere la configurazione del provider o dell'autenticazione, passare a un provider raggiungibile oppure impostare provider: "none" se si desidera intenzionalmente il recupero solo FTS.

ID provider personalizzati

memorySearch.provider può puntare a una voce models.providers.<id> personalizzata 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 api di tale provider per l'adattatore di embedding, mantenendo al contempo l'ID 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 usa 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

Usare 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 inline

Comportamento dell'indicizzazione

Tutti sotto memorySearch.sync, salvo diversa indicazione:

Configurazione della ricerca ibrida

Tutti 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 all'area 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 delle trascrizioni tra agenti con ambito agente, usare agents.list[].memorySearch.qmd.extraCollections invece di memory.qmd.paths. Queste raccolte aggiuntive seguono la stessa struttura { path, name, pattern? }, ma vengono unite per agente e possono mantenere nomi condivisi espliciti quando il percorso punta all'esterno dell'area 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)

Indicizzare 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. Lasciare maxEntries non impostato per una cache senza limiti; impostarlo 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. Il batch di OpenAI è generalmente l'opzione più veloce ed economica per i backfill di grandi dimensioni.

remote.nonBatchConcurrency controlla le chiamate di embedding in linea utilizzate dai provider locali o self-hosted e dai provider ospitati quando le API batch del provider non sono attive. Per l'indicizzazione non batch, Ollama usa come valore predefinito 1 per evitare di sovraccaricare gli host locali più piccoli; impostare un valore maggiore sulle macchine più potenti.

Questa impostazione è separata da sync.embeddingBatchTimeoutSeconds, che controlla il timeout delle chiamate di embedding in linea.

Ricerca nella memoria delle sessioni (sperimentale)

Indicizza le trascrizioni delle sessioni e le rende 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 che ha generato. Per recuperare da una sessione diversa, ad esempio un messaggio diretto, una sessione non correlata dello stesso agente inviata tramite Gateway, ampliare intenzionalmente la visibilità a agent (oppure a all solo quando è richiesto anche il recupero tra agenti e i criteri tra agenti lo consentono).

Gli esempi seguenti inseriscono queste impostazioni sotto agents.defaults. È inoltre possibile applicare impostazioni memorySearch equivalenti in una configurazione specifica dell'agente quando solo un agente deve indicizzare e cercare nelle trascrizioni delle sessioni.

Per il recupero dallo stesso agente dal Gateway a un messaggio diretto:

{  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 si usa QMD, agents.defaults.memorySearch.experimental.sessionMemory e sources: ["sessions"] non esportano autonomamente le trascrizioni in QMD. Impostare anche memory.qmd.sessions.enabled: true.

Accelerazione vettoriale SQLite (sqlite-vec)

Quando sqlite-vec non è disponibile, OpenClaw ripiega automaticamente sulla similarità del coseno calcolata nel processo.

Archiviazione dell'indice

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

Configurazione del backend QMD

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

searchMode: "search" usa esclusivamente la ricerca lessicale/BM25. OpenClaw non esegue verifiche della disponibilità dei vettori semantici né la manutenzione degli embedding QMD per questa modalità, nemmeno 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 versioni successive. In modalità CLI diretta, OpenClaw passa --no-rerank; nella modalità MCP basata su mcporter passa rerank: false allo strumento di query unificato di QMD. Lasciarlo non impostato per usare il comportamento predefinito di QMD per il riordinamento dei risultati delle query.

OpenClaw preferisce le strutture 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 modelli delle raccolte e nomi di strumenti MCP meno recenti. Quando QMD dichiara il supporto per più filtri di raccolta, le raccolte con la stessa origine vengono cercate con un unico processo QMD; le build QMD meno recenti mantengono il percorso di compatibilità per raccolta. Per stessa origine si intende che le raccolte di memoria persistente (i file di memoria predefiniti più i percorsi personalizzati) vengono raggruppate, mentre le raccolte delle trascrizioni delle sessioni restano 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 daemon 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 in PATH, oltre a un server mcporter configurato che esegua qmd mcp. Mantenere l'opzione disabilitata per le configurazioni locali più semplici, in cui il costo di avvio di un processo per ogni query è accettabile.

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

Quando l'inizializzazione QMD all'avvio del Gateway è abilitata, 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 utilizzato 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 persistente affinché possa gestire il watcher e i timer degli intervalli; update.onBoot: false salta 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 è configurato 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/REM come dettaglio implementativo.

Per il comportamento concettuale e i comandi slash, consultare 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