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

Cette page répertorie tous les paramètres de configuration de la recherche en mémoire d’OpenClaw. Pour des présentations conceptuelles, consultez :

Tous les paramètres de recherche en mémoire se trouvent sous agents.defaults.memorySearch dans openclaw.json (ou dans une substitution propre à un agent sous agents.list[].memorySearch), sauf indication contraire.

Sélection du fournisseur

Lorsque provider n’est pas défini, OpenClaw utilise les incorporations OpenAI. Définissez explicitement provider pour utiliser Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, un modèle GGUF local ou un point de terminaison /v1/embeddings compatible avec OpenAI. Les anciennes configurations qui indiquent encore provider: "auto" sont résolues 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 en mémoire peut toujours utiliser le classement lexical FTS lorsque les incorporations ne sont pas disponibles.

Les fournisseurs non locaux explicitement sélectionnés échouent de manière restrictive. Si vous définissez memorySearch.provider sur un fournisseur distant concret tel que Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage 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 ou de l’authentification, choisissez un fournisseur accessible ou définissez provider: "none" si vous souhaitez délibérément utiliser le rappel FTS uniquement.

Identifiants de fournisseurs personnalisés

memorySearch.provider peut pointer vers une entrée personnalisée models.providers.<id> pour des adaptateurs propres à la mémoire tels que ollama, ou pour des API de modèles compatibles avec OpenAI telles que openai-responses / openai-completions. OpenClaw résout le propriétaire api de ce fournisseur pour l’adaptateur d’incorporation tout en conservant l’identifiant du fournisseur personnalisé pour la gestion du point de terminaison, de l’authentification et du préfixe de modèle. Cela permet aux configurations à plusieurs GPU ou plusieurs hôtes de réserver les incorporations de mémoire à un point de terminaison local spécifique :

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

Résolution de la clé API

Les incorporations distantes nécessitent une clé API. Bedrock utilise à la place la chaîne d’identifiants par défaut du SDK AWS (rôles d’instance, SSO, clés d’accès ou clé API Bedrock).

Configuration du point de terminaison distant

Utilisez provider: "openai-compatible" pour un serveur /v1/embeddings générique compatible avec OpenAI qui ne doit pas hériter des identifiants globaux de discussion 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 de la vectorisation en ligne

Comportement de l’indexation

Tous les paramètres se trouvent sous memorySearch.sync, sauf indication contraire :

Configuration de la recherche hybride

Tous les paramètres sous memorySearch.query :

Et sous memorySearch.query.hybrid :

Exemple complet

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

Chemins de 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 rechercher les fichiers .md. La gestion des liens symboliques dépend du moteur actif : le moteur intégré ignore les liens symboliques, tandis que QMD suit le comportement de son analyseur sous-jacent.

Pour une recherche dans les transcriptions d’autres agents limitée à un agent donné, utilisez agents.list[].memorySearch.qmd.extraCollections plutôt que memory.qmd.paths. Ces collections supplémentaires suivent la même structure { path, name, pattern? }, mais elles sont fusionnées pour chaque 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 memorySearch.qmd.extraCollections, QMD conserve la première entrée et ignore le doublon.

Mémoire multimodale (Gemini)

Indexez les images et les fichiers audio avec les fichiers 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 des transcriptions. Laissez maxEntries non défini pour un cache sans limite ; définissez-le lorsque la croissance de l’espace disque importe davantage que la vitesse maximale de réindexation. Lorsqu’il est défini, les entrées les plus anciennes (selon leur date de dernière mise à jour) sont supprimées en premier dès que le cache dépasse la limite.

Indexation par lots

Disponible pour gemini, openai et voyage. Le traitement par lots d’OpenAI est généralement le plus rapide et le moins coûteux pour les remplissages rétroactifs volumineux.

remote.nonBatchConcurrency contrôle les appels directs d’embedding utilisés par les fournisseurs locaux ou auto-hébergés, ainsi que par les fournisseurs hébergés lorsque leurs API de traitement par lots ne sont pas actives. Pour l’indexation sans traitement par lots, Ollama utilise par défaut la valeur 1 afin d’éviter de surcharger les petites machines locales ; définissez une valeur plus élevée sur les machines plus puissantes.

Ce paramètre est distinct de sync.embeddingBatchTimeoutSeconds, qui contrôle le délai d’expiration des appels directs d’embedding.

Recherche dans la mémoire des sessions (expérimental)

Indexez les transcriptions de sessions et rendez-les accessibles via memory_search :

Les résultats issus des transcriptions de sessions respectent également tools.sessions.visibility. La visibilité tree par défaut n’expose que la session actuelle et les sessions qu’elle a créées. Pour retrouver, depuis une autre session telle qu’un message privé, une session sans lien distribuée par le Gateway au même agent, élargissez intentionnellement la visibilité à agent (ou à all uniquement lorsque le rappel entre agents est également nécessaire et que la politique entre agents l’autorise).

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

Pour le rappel du Gateway vers les messages privés d’un 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 vers QMD. Définissez également memory.qmd.sessions.enabled: true.

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

Lorsque sqlite-vec est indisponible, OpenClaw utilise automatiquement en remplacement la similarité cosinus calculée dans le processus.

Stockage des index

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

Configuration du backend QMD

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

searchMode: "search" utilise uniquement la recherche lexicale/BM25. OpenClaw n’exécute pas de vérifications de disponibilité des vecteurs sémantiques ni de maintenance des plongements QMD pour ce mode, y compris pendant memory status --deep ; vsearch et query continuent d’exiger que les vecteurs et les plongements QMD soient prêts.

rerank: false modifie uniquement le mode query de QMD et nécessite QMD 2.1 ou une version plus récente. En mode CLI direct, OpenClaw transmet --no-rerank ; en mode MCP reposant sur mcporter, il transmet rerank: false à l’outil de requête unifié de QMD. Ne le définissez pas pour utiliser le comportement de reclassement par défaut des requêtes QMD.

OpenClaw privilégie les formats actuels des collections QMD et des requêtes MCP, mais maintient la compatibilité avec les anciennes versions de QMD en essayant, si nécessaire, des options compatibles pour les motifs de collections et d’anciens noms d’outils MCP. Lorsque QMD annonce la prise en charge de plusieurs filtres de collections, les collections de même source sont interrogées par un seul processus QMD ; les anciennes versions de QMD conservent le chemin de compatibilité par collection. « De même source » signifie que les collections de mémoire persistante — fichiers de mémoire par défaut et chemins personnalisés — sont regroupées, tandis que les collections de transcriptions de sessions restent dans un groupe distinct afin que la diversification des sources conserve les deux entrées.

Intégration de mcporter

Tous les paramètres se trouvent sous memory.qmd.mcporter. Cette configuration achemine les recherches QMD par l’intermédiaire d’un démon MCP mcporter de longue durée au lieu de lancer qmd pour chaque requête, ce qui réduit le coût des démarrages à froid pour les modèles plus volumineux.

Nécessite que mcporter soit installé et accessible dans PATH, ainsi qu’un serveur mcporter configuré pour exécuter qmd mcp. Laissez cette option désactivée pour les configurations locales plus simples, lorsque le coût de lancement d’un processus pour chaque requête est acceptable.

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

Lorsque l’initialisation de 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 par intervalle ou d’intégration n’est configurée, le démarrage utilise un gestionnaire ponctuel pour l’actualisation initiale, 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 de vie afin qu’il puisse gérer 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: 4, 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 sous la forme d’un balayage planifié unique et utilise en interne des phases légère, profonde et 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",          },        },      },    },  },}

Pages associées

• Référence de configuration
• Présentation de la mémoire
• Recherche dans la mémoire