Référence de configuration de la mémoire
Cette page répertorie tous les réglages de configuration pour la recherche mémoire 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
| Clé | Type | Valeur par défaut | Description |
|---|
provider | string | auto-détecté | ID de l’adaptateur d’embeddings : openai, gemini, voyage, mistral, ollama, local |
model | string | valeur par défaut du fournisseur | Nom du modèle d’embeddings |
fallback | string | "none" | ID de l’adaptateur de repli lorsque le principal échoue |
enabled | boolean | true | Activer ou désactiver la recherche mémoire |
Ordre d’auto-détection
Lorsque provider n’est pas défini, OpenClaw sélectionne le premier disponible :
local — si memorySearch.local.modelPath est configuré et que le fichier existe.openai — si une clé OpenAI peut être résolue.gemini — si une clé Gemini peut être résolue.voyage — si une clé Voyage peut être résolue.mistral — si une clé Mistral peut être résolue.
ollama est pris en charge mais n’est pas auto-détecté (définissez-le explicitement).
Résolution des clés API
Les embeddings distants nécessitent une clé API. OpenClaw les résout depuis :
les profils d’authentification, models.providers.*.apiKey, ou les variables d’environnement.
| Fournisseur | Variable env | Clé de configuration |
|---|
| OpenAI | OPENAI_API_KEY | models.providers.openai.apiKey |
| Gemini | GEMINI_API_KEY | models.providers.google.apiKey |
| Voyage | VOYAGE_API_KEY | models.providers.voyage.apiKey |
| Mistral | MISTRAL_API_KEY | models.providers.mistral.apiKey |
| Ollama | OLLAMA_API_KEY (placeholder) | — |
Configuration du point de terminaison distant
Pour des points de terminaison personnalisés compatibles OpenAI ou pour remplacer les valeurs par défaut du fournisseur :
| Clé | Type | Description |
|---|
remote.baseUrl | string | URL de base API personnalisée |
remote.apiKey | string | Remplacer la clé API |
remote.headers | object | En-têtes HTTP supplémentaires (fusionnés avec les valeurs par défaut du fournisseur) |
{
agents: {
defaults: {
memorySearch: {
provider: "openai",
model: "text-embedding-3-small",
remote: {
baseUrl: "https://api.example.com/v1/",
apiKey: "YOUR_KEY",
},
},
},
},
}
Configuration spécifique à 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 |
Modifier le modèle ou outputDimensionality déclenche une réindexation complète automatique.
Configuration des embeddings locaux
| Clé | Type | Valeur par défaut | Description |
|---|
local.modelPath | string | téléchargé automatiquement | Chemin vers le fichier modèle GGUF |
local.modelCacheDir | string | valeur par défaut de node-llama-cpp | Répertoire cache pour les modèles téléchargés |
embeddinggemma-300m-qat-Q8_0.gguf (~0.6 GB, téléchargement automatique).
Nécessite une construction native : pnpm approve-builds puis pnpm rebuild node-llama-cpp.
Configuration de la recherche hybride
Tout se trouve sous memorySearch.query.hybrid :
| Clé | Type | Valeur par défaut | Description |
|---|
enabled | boolean | true | Activer la recherche hybride BM25 + vecteur |
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é)
| Clé | Type | Valeur par défaut | Description |
|---|
mmr.enabled | boolean | false | Activer le reclassement MMR |
mmr.lambda | number | 0.7 | 0 = diversité maximale, 1 = pertinence maximale |
Décroissance temporelle (récence)
| Clé | Type | Valeur par défaut | Description |
|---|
temporalDecay.enabled | boolean | false | Activer le boost de récence |
temporalDecay.halfLifeDays | number | 30 | Le score est divisé par deux tous les N jours |
MEMORY.md, fichiers non datés dans memory/) ne subissent jamais de décroissance.
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
| Clé | Type | Description |
|---|
extraPaths | string[] | Répertoires ou fichiers supplémentaires à indexer |
{
agents: {
defaults: {
memorySearch: {
extraPaths: ["../team-docs", "/srv/shared-notes"],
},
},
},
}
.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 une recherche de transcriptions inter-agents à portée d’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 courant.
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 l’audio aux côtés du Markdown avec Gemini Embedding 2 :
| Clé | Type | Valeur 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 |
extraPaths. Les racines mémoire par défaut restent limitées au Markdown.
Nécessite gemini-embedding-2-preview. fallback doit être "none".
Formats pris en charge : .jpg, .jpeg, .png, .webp, .gif, .heic, .heif
(images) ; .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).
Cache d’embeddings
| Clé | Type | Valeur par défaut | Description |
|---|
cache.enabled | boolean | false | Mettre en cache les embeddings de blocs dans SQLite |
cache.maxEntries | number | 50000 | Nombre maximal d’embeddings en cache |
Indexation par lots
| Clé | Type | Valeur par défaut | Description |
|---|
remote.batch.enabled | boolean | false | Activer l’API d’embeddings par lots |
remote.batch.concurrency | number | 2 | Tâches parallèles par lots |
remote.batch.wait | boolean | true | Attendre la fin du lot |
remote.batch.pollIntervalMs | number | — | Intervalle de sondage |
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 gros remplissages initiaux.
Recherche mémoire de session (expérimental)
Indexez les transcriptions de session et exposez-les via memory_search :
| Clé | Type | Valeur 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 d’octets pour la réindexation |
sync.sessions.deltaMessages | number | 50 | Seuil de messages pour la réindexation |
Accélération vectorielle SQLite (sqlite-vec)
| Clé | Type | Valeur par défaut | Description |
|---|
store.vector.enabled | boolean | true | Utiliser sqlite-vec pour les requêtes vectorielles |
store.vector.extensionPath | string | groupé | Remplacer le chemin de sqlite-vec |
Stockage de l’index
| Clé | Type | Valeur 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 | Tokenizer FTS5 (unicode61 ou trigram) |
Configuration du backend QMD
Définissez memory.backend = "qmd" pour l’activer. Tous les paramètres QMD se trouvent sous
memory.qmd :
| Clé | Type | Valeur par défaut | Description |
|---|
command | string | qmd | Chemin de l’exécutable QMD |
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 | — | Rétention des transcriptions |
sessions.exportDir | string | — | Répertoire d’export |
Planification des mises à jour
| Clé | Type | Valeur par défaut | Description |
|---|
update.interval | string | 5m | Intervalle de rafraîchissement |
update.debounceMs | number | 15000 | Antirebond des changements de fichiers |
update.onBoot | boolean | true | Rafraîchir au démarrage |
update.waitForBootSync | boolean | false | Bloquer le démarrage jusqu’à la fin du rafraîchissement |
update.embedInterval | string | — | Cadence séparée pour les embeddings |
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’embeddings QMD |
Limites
| Clé | Type | Valeur par défaut | Description |
|---|
limits.maxResults | number | 6 | Nombre maximal de résultats de recherche |
limits.maxSnippetChars | number | — | Limiter la longueur des extraits |
limits.maxInjectedChars | number | — | Limiter le total de caractères injectés |
limits.timeoutMs | number | 4000 | Délai d’expiration de la recherche |
Portée
Contrôle quelles sessions peuvent recevoir des résultats de recherche QMD. Même schéma que
session.sendPolicy :
{
memory: {
qmd: {
scope: {
default: "deny",
rules: [{ action: "allow", match: { chatType: "direct" } }],
},
},
},
}
match.keyPrefix correspond à la clé de session normalisée ;
match.rawKeyPrefix correspond à la clé brute incluant agent:<id>:.
Citations
memory.citations s’applique à tous les backends :
| Valeur | Comportement |
|---|
auto (par défaut) | Inclure un 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 toujours transmis à l’agent en interne) |
Exemple complet QMD
{
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 (expérimental)
Dreaming est configuré sous plugins.entries.memory-core.config.dreaming,
et non sous agents.defaults.memorySearch. Pour les détails conceptuels et les
commandes de chat, consultez Dreaming.
| Clé | Type | Valeur par défaut | Description |
|---|
mode | string | "off" | Préréglage : off, core, rem, ou deep |
cron | string | valeur prédéfinie du preset | Remplacement de l’expression cron du planning |
timezone | string | fuseau horaire utilisateur | Fuseau horaire pour l’évaluation du planning |
limit | number | valeur prédéfinie du preset | Nombre maximal de candidats à promouvoir par cycle |
minScore | number | valeur prédéfinie du preset | Score pondéré minimal pour la promotion |
minRecallCount | number | valeur prédéfinie du preset | Seuil minimal du nombre de rappels |
minUniqueQueries | number | valeur prédéfinie du preset | Seuil minimal du nombre de requêtes distinctes |
Valeurs par défaut des presets
| Mode | Cadence | minScore | minRecallCount | minUniqueQueries |
|---|
off | Désactivé | — | — | — |
core | Quotidien 3 h | 0.75 | 3 | 2 |
rem | Toutes les 6 heures | 0.85 | 4 | 3 |
deep | Toutes les 12 heures | 0.80 | 3 | 3 |
Exemple
{
plugins: {
entries: {
"memory-core": {
config: {
dreaming: {
mode: "core",
timezone: "America/New_York",
},
},
},
},
},
}
