Cette page répertorie chaque paramètre de configuration de la recherche de mémoire OpenClaw. Pour des présentations conceptuelles, consultez :Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Memory overview
Fonctionnement de la mémoire.
Builtin engine
Backend SQLite par défaut.
QMD engine
Sidecar local-first.
Memory search
Pipeline de recherche et réglages.
Active memory
Sous-agent de mémoire pour les sessions interactives.
agents.defaults.memorySearch dans openclaw.json, sauf indication contraire.
Si vous cherchez l’interrupteur de la fonctionnalité active memory et la configuration du sous-agent, ils se trouvent sous
plugins.entries.active-memory plutôt que sous memorySearch.Active memory utilise un modèle à deux barrières :- le plugin doit être activé et cibler l’ID de l’agent actuel
- la requête doit être une session de chat persistante interactive éligible
Sélection du fournisseur
| Clé | Type | Valeur par défaut | Description |
|---|---|---|---|
provider | string | auto-détecté | ID d’adaptateur d’embedding tel que bedrock, deepinfra, gemini, github-copilot, local, mistral, ollama, openai ou voyage ; peut aussi être un models.providers.<id> configuré dont api pointe vers l’un de ces adaptateurs |
model | string | valeur par défaut du fournisseur | Nom du modèle d’embedding |
fallback | string | "none" | ID de l’adaptateur de secours lorsque le principal échoue |
enabled | boolean | true | Activer ou désactiver la recherche de mémoire |
Ordre d’auto-détection
Lorsqueprovider n’est pas défini, OpenClaw sélectionne le premier disponible :
github-copilot
Sélectionné si un jeton GitHub Copilot peut être résolu (variable d’environnement ou profil d’authentification).
ollama est pris en charge mais n’est pas auto-détecté (définissez-le explicitement).
ID de fournisseurs personnalisés
memorySearch.provider peut pointer vers une entrée models.providers.<id> personnalisée. OpenClaw résout le propriétaire api de ce fournisseur pour l’adaptateur d’embedding tout en préservant l’ID de fournisseur personnalisé pour la gestion du point de terminaison, de l’authentification et du préfixe de modèle. Cela permet aux configurations multi-GPU ou multi-hôtes de dédier les embeddings de mémoire à un point de terminaison local précis :
Résolution de la clé API
Les embeddings distants nécessitent une clé API. Bedrock utilise à la place la chaîne d’identifiants par défaut AWS SDK (rôles d’instance, SSO, clés d’accès).| Fournisseur | Variable d’environnement | Clé de configuration |
|---|---|---|
| Bedrock | Chaîne d’identifiants AWS | Aucune clé API nécessaire |
| DeepInfra | DEEPINFRA_API_KEY | models.providers.deepinfra.apiKey |
| Gemini | GEMINI_API_KEY | models.providers.google.apiKey |
| GitHub Copilot | COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN | Profil d’authentification via connexion d’appareil |
| Mistral | MISTRAL_API_KEY | models.providers.mistral.apiKey |
| Ollama | OLLAMA_API_KEY (placeholder) | — |
| OpenAI | OPENAI_API_KEY | models.providers.openai.apiKey |
| Voyage | VOYAGE_API_KEY | models.providers.voyage.apiKey |
Codex OAuth couvre uniquement le chat et les complétions, et ne satisfait pas les requêtes d’embedding.
Configuration du point de terminaison distant
Pour les points de terminaison personnalisés compatibles OpenAI ou pour remplacer les valeurs par défaut du fournisseur :URL de base API personnalisée.
Remplacer la clé API.
En-têtes HTTP supplémentaires (fusionnés avec les valeurs par défaut du fournisseur).
Configuration propre au fournisseur
Gemini
Gemini
| Clé | Type | Valeur par défaut | Description |
|---|---|---|---|
model | string | gemini-embedding-001 | Prend aussi en charge gemini-embedding-2-preview |
outputDimensionality | number | 3072 | Pour Embedding 2 : 768, 1536 ou 3072 |
OpenAI-compatible input types
OpenAI-compatible input types
Les points de terminaison d’embedding compatibles OpenAI peuvent choisir d’utiliser des champs de requête
Modifier ces valeurs affecte l’identité du cache d’embedding pour l’indexation par lots du fournisseur et doit être suivi d’une réindexation de la mémoire lorsque le modèle amont traite les libellés différemment.
input_type propres au fournisseur. C’est utile pour les modèles d’embedding asymétriques qui nécessitent des libellés différents pour les embeddings de requête et de document.| Clé | Type | Valeur par défaut | Description |
|---|---|---|---|
inputType | string | non défini | input_type partagé pour les embeddings de requête et de document |
queryInputType | string | non défini | input_type au moment de la requête ; remplace inputType |
documentInputType | string | non défini | input_type d’index/document ; remplace inputType |
Bedrock
Bedrock
Configuration d’embedding Bedrock
Bedrock utilise la chaîne d’identifiants par défaut AWS SDK ; aucune clé API n’est nécessaire. Si OpenClaw s’exécute sur EC2 avec un rôle d’instance activé pour Bedrock, définissez simplement le fournisseur et le modèle :| Clé | Type | Valeur par défaut | Description |
|---|---|---|---|
model | string | amazon.titan-embed-text-v2:0 | Tout ID de modèle d’embedding Bedrock |
outputDimensionality | number | valeur par défaut du modèle | Pour Titan V2 : 256, 512 ou 1024 |
| ID du modèle | Fournisseur | Dimensions par défaut | Dimensions configurables |
|---|---|---|---|
amazon.titan-embed-text-v2:0 | Amazon | 1024 | 256, 512, 1024 |
amazon.titan-embed-text-v1 | Amazon | 1536 | — |
amazon.titan-embed-g1-text-02 | Amazon | 1536 | — |
amazon.titan-embed-image-v1 | Amazon | 1024 | — |
amazon.nova-2-multimodal-embeddings-v1:0 | Amazon | 1024 | 256, 384, 1024, 3072 |
cohere.embed-english-v3 | Cohere | 1024 | — |
cohere.embed-multilingual-v3 | Cohere | 1024 | — |
cohere.embed-v4:0 | Cohere | 1536 | 256-1536 |
twelvelabs.marengo-embed-3-0-v1:0 | TwelveLabs | 512 | — |
twelvelabs.marengo-embed-2-7-v1:0 | TwelveLabs | 1024 | — |
amazon.titan-embed-text-v1:2:8k) héritent de la configuration du modèle de base.Authentification : l’authentification Bedrock utilise l’ordre standard de résolution des identifiants AWS SDK :- Variables d’environnement (
AWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY) - Cache de jetons SSO
- Identifiants de jeton d’identité web
- Fichiers d’identifiants et de configuration partagés
- Identifiants de métadonnées ECS ou EC2
AWS_REGION, AWS_DEFAULT_REGION, du baseUrl du fournisseur amazon-bedrock, ou prend par défaut la valeur us-east-1.Autorisations IAM : le rôle ou l’utilisateur IAM a besoin de :InvokeModel au modèle précis :Local (GGUF + node-llama-cpp)
Local (GGUF + node-llama-cpp)
| Clé | Type | Par défaut | Description |
|---|---|---|---|
local.modelPath | string | téléchargé automatiquement | Chemin vers le fichier de modèle GGUF |
local.modelCacheDir | string | valeur par défaut de node-llama-cpp | Répertoire de cache pour les modèles téléchargés |
local.contextSize | number | "auto" | 4096 | Taille de la fenêtre de contexte pour le contexte de vectorisation. 4096 couvre les fragments typiques (128 à 512 jetons) tout en limitant la VRAM hors poids. Réduisez à 1024-2048 sur les hôtes contraints. "auto" utilise le maximum d’entraînement du modèle, ce qui n’est pas recommandé pour les modèles 8B+ (Qwen3-Embedding-8B : 40 960 jetons -> ~32 Go de VRAM contre ~8,8 Go à 4096). |
embeddinggemma-300m-qat-Q8_0.gguf (~0,6 Go, téléchargé automatiquement). Les extractions de source nécessitent toujours l’approbation de compilation native : pnpm approve-builds puis pnpm rebuild node-llama-cpp.Utilisez la CLI autonome pour vérifier le même chemin de fournisseur que celui utilisé par le Gateway :provider vaut auto, local n’est sélectionné que lorsque local.modelPath pointe vers un fichier local existant. Les références de modèle hf: et HTTP(S) peuvent toujours être utilisées explicitement avec provider: "local", mais elles ne font pas sélectionner local par auto avant que le modèle soit disponible sur le disque.Délai d’expiration de la vectorisation en ligne
Remplacez le délai d’expiration des lots de vectorisation en ligne pendant l’indexation de la mémoire.Non défini, utilise la valeur par défaut du fournisseur : 600 secondes pour les fournisseurs locaux/auto-hébergés tels que
local, ollama et lmstudio, et 120 secondes pour les fournisseurs hébergés. Augmentez cette valeur lorsque les lots de vectorisation locaux liés au CPU sont sains mais lents.Configuration de la recherche hybride
Tout se trouve sousmemorySearch.query.hybrid :
| Clé | Type | Par défaut | Description |
|---|---|---|---|
enabled | boolean | true | Activer la recherche hybride BM25 + vectorielle |
vectorWeight | number | 0.7 | Poids des scores vectoriels (0-1) |
textWeight | number | 0.3 | Poids des scores BM25 (0-1) |
candidateMultiplier | number | 4 | Multiplicateur de taille du pool de candidats |
- MMR (diversité)
- Décroissance temporelle (récence)
| Clé | Type | Par défaut | Description |
|---|---|---|---|
mmr.enabled | boolean | false | Activer le reclassement MMR |
mmr.lambda | number | 0.7 | 0 = diversité maximale, 1 = pertinence maximale |
Exemple complet
Chemins de mémoire supplémentaires
| Clé | Type | Description |
|---|---|---|
extraPaths | string[] | Répertoires ou fichiers supplémentaires à indexer |
.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 préserver des noms partagés explicites lorsque le chemin pointe en dehors 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 :| Clé | Type | Par défaut | Description |
|---|---|---|---|
multimodal.enabled | boolean | false | Activer l’indexation multimodale |
multimodal.modalities | string[] | — | ["image"], ["audio"] ou ["all"] |
multimodal.maxFileBytes | number | 10000000 | Taille maximale de fichier pour l’indexation |
S’applique uniquement aux fichiers dans
extraPaths. Les racines mémoire par défaut restent limitées au Markdown. Nécessite gemini-embedding-2-preview. fallback doit être "none"..jpg, .jpeg, .png, .webp, .gif, .heic, .heif (images) ; .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).
Cache des représentations vectorielles
| Clé | Type | Par défaut | Description |
|---|---|---|---|
cache.enabled | boolean | false | Mettre en cache les représentations vectorielles des fragments dans SQLite |
cache.maxEntries | number | 50000 | Nombre maximal de représentations vectorielles en cache |
Indexation par lots
| Clé | Type | Par défaut | Description |
|---|---|---|---|
remote.nonBatchConcurrency | number | 4 | Représentations vectorielles intégrées parallèles |
remote.batch.enabled | boolean | false | Activer l’API de représentations vectorielles par lots |
remote.batch.concurrency | number | 2 | Tâches par lots parallèles |
remote.batch.wait | boolean | true | Attendre la fin du lot |
remote.batch.pollIntervalMs | number | — | Intervalle d’interrogation |
remote.batch.timeoutMinutes | number | — | Délai d’expiration du lot |
openai, gemini et voyage. Le traitement par lots OpenAI est généralement le plus rapide et le moins coûteux pour les grands remplissages rétrospectifs.
remote.nonBatchConcurrency contrôle les appels de représentations vectorielles intégrés utilisés par les fournisseurs locaux/auto-hébergés et les fournisseurs hébergés lorsque les API de traitement par lots du fournisseur ne sont pas actives. Ollama utilise par défaut 1 pour l’indexation hors lots afin d’éviter de saturer les hôtes locaux plus petits ; 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 de représentations vectorielles intégrés.
Recherche dans la mémoire de session (expérimental)
Indexez les transcriptions de session et exposez-les viamemory_search :
| Clé | Type | Par défaut | Description |
|---|---|---|---|
experimental.sessionMemory | boolean | false | Activer l’indexation des sessions |
sources | string[] | ["memory"] | Ajouter "sessions" pour inclure les transcriptions |
sync.sessions.deltaBytes | number | 100000 | Seuil en octets pour la réindexation |
sync.sessions.deltaMessages | number | 50 | Seuil en messages pour la réindexation |
Accélération vectorielle SQLite (sqlite-vec)
| Clé | Type | Par défaut | Description |
|---|---|---|---|
store.vector.enabled | boolean | true | Utiliser sqlite-vec pour les requêtes vectorielles |
store.vector.extensionPath | string | bundled | Remplacer le chemin de sqlite-vec |
Stockage de l’index
| Clé | Type | Par défaut | Description |
|---|---|---|---|
store.path | string | ~/.openclaw/memory/{agentId}.sqlite | Emplacement de l’index (prend en charge le jeton {agentId}) |
store.fts.tokenizer | string | unicode61 | Analyseur lexical FTS5 (unicode61 ou trigram) |
Configuration du backend QMD
Définissezmemory.backend = "qmd" pour l’activer. Tous les paramètres QMD se trouvent sous memory.qmd :
| Clé | Type | Par défaut | Description |
|---|---|---|---|
command | string | qmd | Chemin de l’exécutable QMD ; définissez un chemin absolu lorsque le PATH du service diffère de votre shell |
searchMode | string | search | Commande de recherche : search, vsearch, query |
includeDefaultMemory | boolean | true | Indexer automatiquement MEMORY.md + memory/**/*.md |
paths[] | array | — | Chemins supplémentaires : { name, path, pattern? } |
sessions.enabled | boolean | false | Indexer les transcriptions de session |
sessions.retentionDays | number | — | Conservation des transcriptions |
sessions.exportDir | string | — | Répertoire d’exportation |
searchMode: "search" est uniquement lexical/BM25. OpenClaw n’exécute pas de sondes de disponibilité 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 disponibilité vectorielle QMD et les embeddings.
OpenClaw privilégie la collection QMD actuelle et les formes de requête MCP, mais maintient la compatibilité avec les anciennes versions de QMD en essayant, si nécessaire, des indicateurs de motifs de collection compatibles et d’anciens noms d’outils MCP. Quand 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 dans un groupe séparé afin que la diversification des sources conserve toujours les deux entrées.
Les substitutions de modèle QMD restent côté QMD, pas dans la configuration OpenClaw. Si vous devez remplacer les modèles de QMD globalement, définissez des variables d’environnement comme
QMD_EMBED_MODEL, QMD_RERANK_MODEL et QMD_GENERATE_MODEL dans l’environnement d’exécution du Gateway.Calendrier de mise à jour
Calendrier de mise à jour
| Clé | Type | Par défaut | Description |
|---|---|---|---|
update.interval | string | 5m | Intervalle d’actualisation |
update.debounceMs | number | 15000 | Anti-rebond des changements de fichiers |
update.onBoot | boolean | true | Actualiser lorsque le gestionnaire QMD longue durée s’ouvre; contrôle aussi l’actualisation au démarrage avec opt-in |
update.startup | string | off | Actualisation facultative au démarrage du Gateway: off, idle ou immediate |
update.startupDelayMs | number | 120000 | Délai avant l’exécution de l’actualisation startup: "idle" |
update.waitForBootSync | boolean | false | Bloquer l’ouverture du gestionnaire jusqu’à la fin de son actualisation initiale |
update.embedInterval | string | — | Cadence d’embedding séparée |
update.commandTimeoutMs | number | — | Délai d’expiration pour les commandes QMD |
update.updateTimeoutMs | number | — | Délai d’expiration pour les opérations de mise à jour QMD |
update.embedTimeoutMs | number | — | Délai d’expiration pour les opérations d’embedding QMD |
Limites
Limites
| Clé | Type | Par défaut | Description |
|---|---|---|---|
limits.maxResults | number | 6 | Nombre maximal de résultats de recherche |
limits.maxSnippetChars | number | — | Limiter la longueur de l’extrait |
limits.maxInjectedChars | number | — | Limiter le nombre total de caractères injectés |
limits.timeoutMs | number | 4000 | Délai d’expiration de la recherche |
Portée
Portée
Contrôle quelles sessions peuvent recevoir des résultats de recherche QMD. Même schéma que La valeur par défaut livrée autorise les sessions directes et de canal, tout en continuant à refuser les groupes.Par défaut, seuls les DM sont autorisés.
session.sendPolicy:match.keyPrefix correspond à la clé de session normalisée; match.rawKeyPrefix correspond à la clé brute incluant agent:<id>:.Citations
Citations
memory.citations s’applique à tous les backends:| Valeur | Comportement |
|---|---|
auto (par défaut) | Inclure le pied de page Source: <path#line> dans les extraits |
on | Toujours inclure le pied de page |
off | Omettre le pied de page (le chemin est quand même transmis à l’agent en interne) |
Exemple QMD complet
Dreaming
Dreaming est configuré sousplugins.entries.memory-core.config.dreaming, pas sous agents.defaults.memorySearch.
Dreaming s’exécute comme un balayage planifié unique et utilise des phases internes light/deep/REM comme détail d’implémentation.
Pour le comportement conceptuel et les commandes slash, consultez Dreaming.
Paramètres utilisateur
| Clé | Type | Par défaut | Description |
|---|---|---|---|
enabled | boolean | false | Activer ou désactiver entièrement Dreaming |
frequency | string | 0 3 * * * | Cadence cron facultative pour le balayage Dreaming complet |
model | string | modèle par défaut | Remplacement facultatif du modèle de sous-agent Dream Diary |
Exemple
- Dreaming écrit l’état machine dans
memory/.dreams/. - Dreaming écrit la sortie narrative lisible par l’humain dans
DREAMS.md(ou le fichierdreams.mdexistant). dreaming.modelutilise la barrière de confiance de sous-agent du Plugin existant; définissezplugins.entries.memory-core.subagent.allowModelOverride: trueavant de l’activer.- Dream Diary réessaie une fois avec le modèle par défaut de la session lorsque le modèle configuré n’est pas disponible. Les échecs de confiance ou de liste d’autorisation sont journalisés et ne sont pas réessayés silencieusement.
- La politique et les seuils des phases light/deep/REM sont un comportement interne, pas une configuration destinée à l’utilisateur.