Riferimento alla configurazione della memoria

Questa pagina elenca ogni parametro di configurazione per la ricerca in memoria di OpenClaw. Per panoramiche concettuali, vedi:

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

# Selezione del provider

# Ordine di rilevamento automatico

Quando provider non è impostato, OpenClaw seleziona il primo disponibile:

ollama è supportato ma non viene rilevato automaticamente (impostalo esplicitamente).

# ID di provider personalizzati

memorySearch.provider può puntare a una voce personalizzata models.providers.<id>. OpenClaw risolve il proprietario api di quel provider per l'adapter di embedding, preservando al tempo stesso l'id del provider personalizzato per la gestione di endpoint, autenticazione e prefissi dei modelli. 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'SDK AWS (ruoli dell'istanza, SSO, chiavi di accesso).

# Configurazione dell'endpoint remoto

Per endpoint personalizzati compatibili con OpenAI o per sovrascrivere i valori predefiniti del provider:

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

# Configurazione specifica del provider

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env: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 main
openclaw memory index --force --agent main

# Timeout dell'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 memoria aggiuntivi

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

I percorsi possono essere assoluti o relativi al workspace. Le directory vengono scansionate 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 nei transcript tra agenti con ambito agente, usa agents.list[].memorySearch.qmd.extraCollections invece di memory.qmd.paths. Quelle collezioni extra seguono la stessa forma { path, name, pattern? }, ma vengono unite per agente e possono preservare nomi condivisi espliciti quando il percorso punta fuori dal 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 al 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 del 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ù rapido ed economico per backfill di grandi dimensioni.

remote.nonBatchConcurrency controlla le chiamate di embedding inline usate dai provider locali/self-hosted 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 delle sessioni (sperimentale)

Indicizza le trascrizioni delle sessioni e rendile disponibili tramite memory_search:

# Accelerazione vettoriale SQLite (sqlite-vec)

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

# Archiviazione dell'indice

# Configurazione del backend QMD

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

searchMode: "search" è solo lessicale/BM25. OpenClaw non esegue sonde 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 QMD e gli embedding.

OpenClaw preferisce la raccolta QMD corrente e le forme di query MCP, ma mantiene funzionanti le versioni QMD precedenti provando flag compatibili per i pattern di raccolta e nomi di strumenti MCP più vecchi quando necessario. Quando QMD dichiara il supporto per più filtri di raccolta, le raccolte della stessa origine vengono cercate con un solo processo QMD; le build QMD più vecchie mantengono il percorso di compatibilità per raccolta. Stessa origine significa che le raccolte di memoria duratura sono raggruppate insieme, mentre le raccolte delle trascrizioni di sessione restano un gruppo separato, così la diversificazione delle fonti mantiene comunque entrambi gli input.

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

Gli aggiornamenti all'avvio QMD usano un percorso subprocess monouso durante l'avvio del gateway. Il gestore QMD a lunga durata possiede comunque il file watcher regolare e i timer a intervallo quando la ricerca in memoria viene aperta per l'uso interattivo.

# 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 di implementazione.

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 in memoria