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 une présentation conceptuelle, consultez :

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

Sélection du fournisseur

Lorsque provider n’est pas défini, OpenClaw utilise les embeddings 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 paramètre 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 embeddings sont indisponibles.

Les fournisseurs non locaux explicitement définis échouent de manière restrictive. Si vous définissez memorySearch.provider sur un fournisseur distant précis tel que Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage ou un fournisseur personnalisé compatible avec OpenAI, et que celui-ci est indisponible lors de l’exécution, memory_search renvoie un résultat d’indisponibilité au lieu d’utiliser silencieusement un rappel FTS uniquement. Corrigez la configuration du fournisseur ou de l’authentification, choisissez un fournisseur accessible ou définissez provider: "none" si vous souhaitez utiliser délibérément un rappel FTS uniquement.

Identifiants de fournisseurs personnalisés

memorySearch.provider peut pointer vers une entrée models.providers.<id> personnalisée pour des adaptateurs propres aux fournisseurs de 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’embeddings, tout en conservant l’identifiant du fournisseur personnalisé pour la gestion du point de terminaison, de l’authentification et du préfixe du modèle. Les configurations à plusieurs GPU ou plusieurs hôtes peuvent ainsi réserver les embeddings de mémoire à un point de terminaison local précis :

{  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é d’API

Les embeddings distants nécessitent une clé d’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é d’API Bedrock).

Configuration du point de terminaison 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 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 à chaque 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

Comportement d'indexation

Toutes les options se trouvent sous memorySearch.sync, sauf indication contraire :

Configuration de la recherche hybride

Toutes les options se trouvent 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 à la recherche de 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 de l'analyseur QMD sous-jacent.

Pour effectuer une recherche inter-agents dans les transcriptions à l'échelle d'un agent, utilisez agents.list[].memorySearch.qmd.extraCollections au lieu de memory.qmd.paths. Ces collections supplémentaires suivent la même structure { 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 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 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 la mise à jour d’une transcription. 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 dernière date de 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étrospectifs volumineux.

remote.nonBatchConcurrency contrôle les appels d’embedding en ligne utilisés par les fournisseurs locaux/autohébergés et par les fournisseurs hébergés lorsque leurs API de traitement par lots ne sont pas actives. Ollama utilise par défaut 1 pour l’indexation hors lot afin d’éviter de surcharger les petits hôtes locaux ; définissez une valeur supérieure sur les machines plus puissantes.

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

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

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

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

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

Pour le rappel d’un Gateway vers un message privé au sein 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" },  },}

Lors de l’utilisation de 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 se rabat automatiquement sur la similarité cosinus calculée dans le processus.

Stockage de l’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 ni sondes de disponibilité vectorielle sémantique ni maintenance des embeddings QMD pour ce mode, y compris pendant memory status --deep ; vsearch et query continuent de nécessiter la disponibilité vectorielle et les embeddings de QMD.

rerank: false ne modifie que le mode query de QMD et nécessite QMD 2.1 ou une version ultérieure. 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. Laissez-le non défini pour utiliser le comportement de reclassement des requêtes par défaut de 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 indicateurs compatibles de motif de collection et les anciens noms d’outils MCP. Lorsque QMD annonce la prise en charge de plusieurs filtres de collection, 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. « Même source » signifie que les collections de mémoire durable (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 bien les deux entrées.

Intégration de mcporter

Tous les paramètres se trouvent sous memory.qmd.mcporter. 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 surcoût du démarrage à froid pour les modèles plus volumineux.

Nécessite que mcporter soit installé et présent dans PATH, ainsi qu’un serveur mcporter configuré qui exécute qmd mcp. Laissez cette option désactivée pour les configurations locales simples où le coût du lancement d’un processus par 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 admissibles. Si update.onBoot vaut true et qu’aucune maintenance par intervalle ou 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 de longue durée 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 est configuré 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 des phases internes légère/profonde/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",          },        },      },    },  },}

Voir aussi

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