Riferimento alla configurazione della memoria

Questa pagina elenca ogni opzione di configurazione per la ricerca nella memoria di OpenClaw. Per panoramiche concettuali, consulta:

Tutte le impostazioni di ricerca nella memoria si trovano in agents.defaults.memorySearch in openclaw.json, salvo diversa indicazione.

Selezione del provider

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

Quando provider non è impostato, è presente il legacy provider: "auto" oppure provider: "none" seleziona intenzionalmente la modalità solo FTS, il richiamo della memoria può comunque usare il ranking lessicale FTS quando gli embedding non sono disponibili.

I provider espliciti non locali falliscono in modo chiuso. Se imposti memorySearch.provider su un provider concreto basato su remoto come OpenAI, Gemini, Voyage, Mistral, Bedrock, GitHub Copilot, DeepInfra, Ollama, LM Studio o un provider personalizzato compatibile con OpenAI, e quel provider non è disponibile a runtime, memory_search restituisce un risultato non disponibile invece di usare silenziosamente il richiamo solo FTS. Correggi la configurazione del provider/autenticazione, passa a un provider raggiungibile oppure imposta provider: "none" se vuoi un richiamo intenzionalmente solo FTS.

ID provider personalizzati

memorySearch.provider può puntare a una voce personalizzata models.providers.<id> per adattatori provider specifici della memoria come ollama, oppure per API di modelli compatibili con OpenAI come openai-responses / openai-completions. OpenClaw risolve il proprietario api di quel provider per l'adattatore di embedding preservando l'ID provider personalizzato per endpoint, autenticazione e gestione del prefisso del modello. Questo consente a configurazioni multi-GPU o multi-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" }],      },    },  },  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 istanza, SSO, chiavi di accesso).

Configurazione dell'endpoint remoto

Usa provider: "openai-compatible" per un server generico /v1/embeddings 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

Configurazione della ricerca ibrida

Tutto sotto memorySearch.query.hybrid:

Esempio completo

{  agents: {    defaults: {      memorySearch: {        query: {          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 al workspace. Le directory vengono analizzate ricorsivamente alla ricerca di file .md. La gestione dei symlink dipende dal backend attivo: il motore integrato ignora i symlink, mentre QMD segue il comportamento dello scanner QMD sottostante.

Per la ricerca delle trascrizioni tra agenti con ambito dell'agente, usa agents.list[].memorySearch.qmd.extraCollections invece di memory.qmd.paths. Queste raccolte aggiuntive seguono la stessa forma { path, name, pattern? }, ma vengono unite per agente e possono preservare nomi condivisi espliciti quando il percorso punta all'esterno del workspace corrente. Se lo stesso percorso risolto appare sia in memory.qmd.paths sia in memorySearch.qmd.extraCollections, QMD mantiene la prima voce e salta 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 rigenerare gli embedding per testo invariato durante la reindicizzazione o gli aggiornamenti delle trascrizioni.

Indicizzazione batch

Disponibile per openai, gemini e voyage. Il batch OpenAI è in genere il più veloce ed economico per grandi backfill.

remote.nonBatchConcurrency controlla le chiamate di embedding inline usate dai provider locali/autogestiti e dai provider ospitati quando le API batch del provider non sono attive. Ollama usa per impostazione predefinita 1 per l'indicizzazione non batch, per evitare di sovraccaricare host locali più piccoli; imposta un valore più alto su macchine più grandi.

Questo è separato da sync.embeddingBatchTimeoutSeconds, che controlla il timeout per le chiamate di embedding inline.

Ricerca nella memoria di sessione (sperimentale)

Indicizza le trascrizioni delle sessioni e le espone tramite memory_search:

Anche le corrispondenze nelle trascrizioni delle sessioni rispettano tools.sessions.visibility. La visibilità predefinita tree espone solo la sessione corrente e le sessioni che ha generato. Per richiamare da una sessione diversa, come un DM, una sessione non correlata dello stesso agente inviata tramite Gateway, estendi intenzionalmente la visibilità a agent (o a all solo quando è richiesto anche il richiamo tra agenti e la policy da agente ad agente lo consente).

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

Per il richiamo dallo stesso agente da Gateway a DM:

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

Accelerazione vettoriale SQLite (sqlite-vec)

Quando sqlite-vec non è disponibile, OpenClaw torna automaticamente alla similarità coseno in-process.

Archiviazione degli indici

Gli indici di memoria integrati si trovano nel database SQLite 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" è solo lessicale/BM25. OpenClaw non esegue probe di prontezza vettoriale semantica né manutenzione degli embedding QMD per quella modalità, anche durante memory status --deep; vsearch e query continuano a richiedere la prontezza vettoriale e gli embedding QMD.

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

OpenClaw preferisce le forme correnti di collection QMD e query MCP, ma mantiene funzionanti le versioni QMD precedenti provando, quando necessario, flag di pattern di collection compatibili e nomi di strumenti MCP più vecchi. Quando QMD dichiara il supporto per più filtri di collection, le collection della stessa sorgente vengono cercate con un unico processo QMD; le build QMD più vecchie mantengono il percorso di compatibilità per collection. Stessa sorgente significa che le collection di memoria durevole vengono raggruppate insieme, mentre le collection delle trascrizioni delle sessioni rimangono un gruppo separato affinché la diversificazione delle sorgenti abbia comunque entrambi gli input.

{  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 di intervallo/embed, l'avvio usa un gestore monouso per l'aggiornamento di boot e lo chiude. Se è configurato un intervallo di aggiornamento o embed, l'avvio apre il gestore QMD di lunga durata, così può gestire il watcher e i timer di intervallo; update.onBoot: false salta solo l'aggiornamento immediato di boot.

Esempio QMD completo

{  memory: {    backend: "qmd",    citations: "auto",    qmd: {      includeDefaultMemory: true,      update: { interval: "5m", debounceMs: 15000 },      limits: { maxResults: 6, 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 una singola scansione pianificata e usa fasi interne light/deep/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 alla configurazione
• Panoramica della memoria
• Ricerca nella memoria