Référence de configuration de la mémoire

Cette page liste chaque réglage de configuration pour la recherche mémoire d’OpenClaw. Pour des vues d’ensemble conceptuelles, consultez :

Tous les paramètres de recherche mémoire se trouvent sous agents.defaults.memorySearch dans openclaw.json, sauf indication contraire.

Sélection du fournisseur

Lorsque provider n’est pas défini, OpenClaw utilise les embeddings OpenAI. Définissez provider explicitement pour utiliser Gemini, Voyage, Mistral, DeepInfra, Bedrock, GitHub Copilot, Ollama, un modèle GGUF local ou un endpoint /v1/embeddings compatible avec OpenAI. Les anciennes configurations qui indiquent encore provider: "auto" se résolvent en openai.

Lorsque provider n’est pas défini, que l’ancien provider: "auto" est présent, ou que provider: "none" sélectionne intentionnellement le mode FTS uniquement, le rappel mémoire peut tout de même utiliser le classement lexical FTS lorsque les embeddings sont indisponibles.

Les fournisseurs non locaux explicites échouent en mode fermé. Si vous définissez memorySearch.provider sur un fournisseur concret adossé à un service distant tel qu’OpenAI, Gemini, Voyage, Mistral, Bedrock, GitHub Copilot, DeepInfra, Ollama, LM Studio ou un fournisseur personnalisé compatible avec OpenAI, et que ce fournisseur est indisponible à l’exécution, memory_search renvoie un résultat d’indisponibilité au lieu d’utiliser silencieusement le rappel FTS uniquement. Corrigez la configuration du fournisseur/de l’authentification, passez à un fournisseur joignable ou définissez provider: "none" si vous voulez un rappel FTS uniquement délibéré.

Identifiants de fournisseur personnalisés

memorySearch.provider peut pointer vers une entrée personnalisée models.providers.<id> pour des adaptateurs de fournisseur propres à la mémoire comme ollama, ou pour des API de modèle compatibles avec OpenAI comme openai-responses / openai-completions. OpenClaw résout le propriétaire api de ce fournisseur pour l’adaptateur d’embeddings tout en préservant l’identifiant de fournisseur personnalisé pour la gestion de l’endpoint, de l’authentification et des préfixes de modèle. Cela permet aux configurations multi-GPU ou multi-hôtes de dédier les embeddings mémoire à un endpoint local spécifique :

{  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",      },    },  },}

Résolution de la clé API

Les embeddings distants nécessitent une clé API. Bedrock utilise plutôt la chaîne d’identifiants par défaut de l’AWS SDK (rôles d’instance, SSO, clés d’accès).

Configuration d’endpoint distant

Utilisez provider: "openai-compatible" pour un serveur générique /v1/embeddings compatible avec OpenAI qui ne doit pas hériter des identifiants globaux de chat OpenAI.

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

Configuration propre au fournisseur

{  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

Délai d’expiration des embeddings en ligne

Configuration de la recherche hybride

Tout se trouve sous memorySearch.query.hybrid :

Exemple complet

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

Chemins mémoire supplémentaires

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

Les chemins peuvent être absolus ou relatifs à l’espace de travail. Les répertoires sont analysés récursivement pour les fichiers .md. La gestion des liens symboliques dépend du backend actif : le moteur intégré ignore les liens symboliques, tandis que QMD suit le comportement du scanner QMD sous-jacent.

Pour la recherche de transcriptions inter-agents limitée à un agent, utilisez agents.list[].memorySearch.qmd.extraCollections au lieu de memory.qmd.paths. Ces collections supplémentaires suivent la même forme { path, name, pattern? }, mais elles sont fusionnées par agent et peuvent conserver des noms partagés explicites lorsque le chemin pointe hors de l’espace de travail actuel. Si le même chemin résolu apparaît à la fois dans memory.qmd.paths et dans memorySearch.qmd.extraCollections, QMD conserve la première entrée et ignore le doublon.

Mémoire multimodale (Gemini)

Indexez les images et l’audio avec Markdown à l’aide de Gemini Embedding 2 :

Formats pris en charge : .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (images) ; .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).

Cache des embeddings

Évite de recalculer les embeddings du texte inchangé lors d’une réindexation ou de mises à jour de transcriptions.

Indexation par lots

Disponible pour openai, gemini et voyage. Les lots OpenAI sont généralement les plus rapides et les moins coûteux pour les grands remplissages rétrospectifs.

remote.nonBatchConcurrency contrôle les appels d’embeddings en ligne utilisés par les fournisseurs locaux/auto-hébergés et par les fournisseurs hébergés lorsque les API de lots du fournisseur ne sont pas actives. Ollama utilise par défaut 1 pour l’indexation hors lots afin d’éviter de surcharger les petits hôtes locaux ; définissez une valeur plus élevée sur les machines plus puissantes.

Cela est distinct de sync.embeddingBatchTimeoutSeconds, qui contrôle le délai d’expiration des appels d’embeddings en ligne.

Recherche dans la mémoire de session (expérimental)

Indexez les transcriptions de session et exposez-les via memory_search :

Les résultats de transcription de session respectent également tools.sessions.visibility. La visibilité tree par défaut n’expose que la session actuelle et les sessions qu’elle a lancées. Pour rappeler, depuis une autre session comme un DM, une session non liée distribuée par le Gateway pour le même agent, élargissez volontairement la visibilité à agent (ou à all uniquement lorsque le rappel entre agents est également requis et que la politique agent-à-agent l’autorise).

Les exemples ci-dessous placent ces paramètres sous agents.defaults. Vous pouvez aussi appliquer des paramètres memorySearch équivalents dans une surcharge par agent lorsque seul un agent doit indexer et rechercher les transcriptions de session.

Pour le rappel Gateway-vers-DM pour le même agent :

{  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" },  },}

Avec QMD, agents.defaults.memorySearch.experimental.sessionMemory et sources: ["sessions"] n’exportent pas à eux seuls les transcriptions dans QMD. Définissez également memory.qmd.sessions.enabled: true.

Accélération vectorielle SQLite (sqlite-vec)

Lorsque sqlite-vec n’est pas disponible, OpenClaw revient automatiquement à la similarité cosinus en cours de processus.

Stockage des index

Les index mémoire intégrés résident dans la base de données SQLite OpenClaw de chaque agent à agents/<agentId>/agent/openclaw-agent.sqlite.

Configuration du backend QMD

Définissez memory.backend = "qmd" pour l’activer. Tous les paramètres QMD résident sous memory.qmd :

searchMode: "search" est uniquement lexical/BM25. OpenClaw n’exécute pas de sondes de préparation vectorielle sémantique ni de maintenance des embeddings QMD pour ce mode, y compris pendant memory status --deep ; vsearch et query continuent d’exiger la préparation vectorielle et les embeddings QMD.

rerank: false ne modifie que le mode query de QMD et nécessite QMD 2.1 ou plus récent. En mode CLI direct, OpenClaw transmet --no-rerank ; en mode MCP basé sur mcporter, il transmet rerank: false à l’outil de requête unifié de QMD. Laissez-le non défini pour utiliser le comportement de reranking de requête par défaut de QMD.

OpenClaw privilégie les formes actuelles de collections QMD et de requêtes MCP, mais maintient la compatibilité avec les anciennes versions de QMD en essayant, si nécessaire, des indicateurs de modèles de collection compatibles et d’anciens noms d’outils MCP. Lorsque QMD annonce la prise en charge de plusieurs filtres de collection, les collections de même source sont recherchées avec un seul processus QMD ; les anciennes versions de QMD conservent le chemin de compatibilité par collection. Même source signifie que les collections de mémoire durable sont regroupées, tandis que les collections de transcriptions de session restent un groupe séparé afin que la diversification des sources conserve les deux entrées.

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

Lorsque l’initialisation QMD au démarrage du Gateway est activée, OpenClaw démarre QMD uniquement pour les agents éligibles. Si update.onBoot vaut true et qu’aucune maintenance d’intervalle ou d’intégration n’est configurée, le démarrage utilise un gestionnaire à exécution unique pour l’actualisation au démarrage, puis le ferme. Si un intervalle de mise à jour ou d’intégration est configuré, le démarrage ouvre le gestionnaire QMD longue durée afin qu’il puisse posséder l’observateur et les minuteurs d’intervalle ; update.onBoot: false ignore uniquement l’actualisation immédiate au démarrage.

Exemple QMD complet

{  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 se configure sous plugins.entries.memory-core.config.dreaming, et non sous agents.defaults.memorySearch.

Dreaming s’exécute comme un balayage planifié unique et utilise des phases internes légères/profondes/REM comme détail d’implémentation.

Pour le comportement conceptuel et les commandes slash, consultez Dreaming.

Paramètres utilisateur

Exemple

{  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",          },        },      },    },  },}

Connexe

• Référence de configuration
• Vue d’ensemble de la mémoire
• Recherche dans la mémoire