Referentie voor geheugenconfiguratie

Deze pagina bevat alle configuratieopties voor geheugenzoekopdrachten van OpenClaw. Zie voor conceptuele overzichten:

Alle instellingen voor geheugenzoekopdrachten bevinden zich onder agents.defaults.memorySearch in openclaw.json (of in een overschrijving per agent via agents.list[].memorySearch), tenzij anders vermeld.

Providerselectie

Wanneer provider niet is ingesteld, gebruikt OpenClaw embeddings van OpenAI. Stel provider expliciet in om Bedrock, DeepInfra, Gemini, GitHub Copilot, Mistral, Ollama, Voyage, een lokaal GGUF-model of een OpenAI-compatibel /v1/embeddings-eindpunt te gebruiken. Verouderde configuraties die nog provider: "auto" bevatten, worden omgezet naar openai.

Wanneer provider niet is ingesteld, de verouderde instelling provider: "auto" aanwezig is, of provider: "none" bewust alleen-FTS-modus selecteert, kan het ophalen van herinneringen nog steeds lexicale FTS-rangschikking gebruiken wanneer embeddings niet beschikbaar zijn.

Expliciet ingestelde niet-lokale providers sluiten af bij fouten. Als u memorySearch.provider instelt op een concrete provider met een externe backend, zoals Bedrock, DeepInfra, Gemini, GitHub Copilot, LM Studio, Mistral, Ollama, OpenAI, Voyage of een OpenAI-compatibele aangepaste provider, en die provider tijdens runtime niet beschikbaar is, retourneert memory_search een resultaat dat aangeeft dat de service niet beschikbaar is, in plaats van stilzwijgend alleen-FTS-ophaling te gebruiken. Herstel de provider-/authenticatieconfiguratie, schakel over naar een bereikbare provider of stel provider: "none" in als u bewust alleen-FTS-ophaling wilt.

Aangepaste provider-ID's

memorySearch.provider kan verwijzen naar een aangepaste vermelding models.providers.<id> voor geheugenspecifieke provideradapters zoals ollama, of voor OpenAI-compatibele model-API's zoals openai-responses / openai-completions. OpenClaw bepaalt de api-eigenaar van die provider voor de embeddingadapter, terwijl de aangepaste provider-ID behouden blijft voor de verwerking van eindpunten, authenticatie en modelvoorvoegsels. Hierdoor kunnen opstellingen met meerdere GPU's of hosts geheugenembeddings toewijzen aan een specifiek lokaal eindpunt:

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

API-sleutel bepalen

Voor externe embeddings is een API-sleutel vereist. Bedrock gebruikt in plaats daarvan de standaardreferentieketen van de AWS SDK (instantie-rollen, SSO, toegangssleutels of een Bedrock-API-sleutel).

Configuratie van extern eindpunt

Gebruik provider: "openai-compatible" voor een algemene OpenAI-compatibele /v1/embeddings-server die de algemene OpenAI-chatreferenties niet moet overnemen.

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

Providerspecifieke configuratie

{  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

Time-out voor inline-embeddings

Indexeringsgedrag

Alles valt onder memorySearch.sync, tenzij anders vermeld:

Configuratie voor hybride zoeken

Alles onder memorySearch.query:

En onder memorySearch.query.hybrid:

Volledig voorbeeld

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

Aanvullende geheugenpaden

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

Paden kunnen absoluut of relatief ten opzichte van de werkruimte zijn. Mappen worden recursief gescand op .md-bestanden. De verwerking van symbolische koppelingen hangt af van de actieve backend: de ingebouwde engine slaat symbolische koppelingen over, terwijl QMD het gedrag van de onderliggende QMD-scanner volgt.

Gebruik voor agentgebonden zoekopdrachten in transcripten van andere agents agents.list[].memorySearch.qmd.extraCollections in plaats van memory.qmd.paths. Deze extra verzamelingen volgen dezelfde structuur { path, name, pattern? }, maar worden per agent samengevoegd en kunnen expliciete gedeelde namen behouden wanneer het pad naar buiten de huidige werkruimte verwijst. Als hetzelfde herleide pad zowel in memory.qmd.paths als in memorySearch.qmd.extraCollections voorkomt, behoudt QMD de eerste vermelding en slaat het duplicaat over.

Multimodaal geheugen (Gemini)

Indexeer afbeeldingen en audio naast Markdown met Gemini Embedding 2:

Ondersteunde indelingen: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (afbeeldingen); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).

Cache voor embeddings

Voorkomt dat ongewijzigde tekst tijdens herindexering of transcriptupdates opnieuw wordt omgezet in embeddings. Laat maxEntries niet ingesteld voor een onbeperkte cache; stel deze waarde in wanneer schijfgroei belangrijker is dan de maximale herindexeringssnelheid. Als er een waarde is ingesteld, worden de oudste vermeldingen (op basis van het tijdstip van de laatste update) als eerste verwijderd zodra de cache de limiet overschrijdt.

Batchindexering

Beschikbaar voor gemini, openai en voyage. OpenAI-batchverwerking is doorgaans het snelst en voordeligst voor grote aanvullingen met historische gegevens.

remote.nonBatchConcurrency bepaalt het aantal gelijktijdige inline-embeddingaanroepen voor lokale/zelfgehoste providers en gehoste providers wanneer de batch-API's van de provider niet actief zijn. Ollama gebruikt standaard 1 voor indexering zonder batches om overbelasting van kleinere lokale hosts te voorkomen; stel op krachtigere machines een hogere waarde in.

Dit staat los van sync.embeddingBatchTimeoutSeconds, dat de time-out voor inline-embeddingaanroepen bepaalt.

Zoeken in sessiegeheugen (experimenteel)

Indexeer sessietranscripten en maak ze beschikbaar via memory_search:

Treffers uit sessietranscripten volgen ook tools.sessions.visibility. De standaardzichtbaarheid tree geeft alleen toegang tot de huidige sessie en de sessies die deze heeft gestart. Als u vanuit een andere sessie, zoals een privébericht, een niet-gerelateerde, door dezelfde agent via de Gateway gestarte sessie wilt ophalen, verruimt u de zichtbaarheid bewust naar agent (of alleen naar all wanneer ophalen tussen agents ook vereist is en het beleid voor communicatie tussen agents dit toestaat).

In de onderstaande voorbeelden staan deze instellingen onder agents.defaults. U kunt ook gelijkwaardige memorySearch-instellingen toepassen in een overschrijving per agent wanneer slechts één agent sessietranscripten moet indexeren en doorzoeken.

Voor ophalen tussen de Gateway en privéberichten van dezelfde 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" },  },}

Bij gebruik van QMD exporteren agents.defaults.memorySearch.experimental.sessionMemory en sources: ["sessions"] op zichzelf geen transcripten naar QMD. Stel daarnaast memory.qmd.sessions.enabled: true in.

SQLite-vectorversnelling (sqlite-vec)

Wanneer sqlite-vec niet beschikbaar is, valt OpenClaw automatisch terug op cosinusgelijkenis binnen het proces.

Indexopslag

Ingebouwde geheugenindexen bevinden zich in de OpenClaw SQLite-database van elke agent op agents/<agentId>/agent/openclaw-agent.sqlite.

Configuratie van QMD-backend

Stel memory.backend = "qmd" in om deze in te schakelen. Alle QMD-instellingen staan onder memory.qmd:

searchMode: "search" gebruikt uitsluitend lexicaal zoeken/BM25. OpenClaw voert voor deze modus geen controles op de gereedheid van semantische vectoren of onderhoud aan QMD-embeddings uit, ook niet tijdens memory status --deep; vsearch en query blijven vereisen dat QMD-vectoren en embeddings gereed zijn.

rerank: false wijzigt alleen de QMD-modus query en vereist QMD 2.1 of nieuwer. In de directe CLI-modus geeft OpenClaw --no-rerank door; in de door mcporter ondersteunde MCP-modus geeft het rerank: false door aan het uniforme queryhulpmiddel van QMD. Laat deze optie oningesteld om het standaardgedrag van QMD voor het herrangschikken van queryresultaten te gebruiken.

OpenClaw geeft de voorkeur aan de huidige vormen voor QMD-collecties en MCP-query's, maar houdt oudere QMD-versies werkend door zo nodig compatibele vlaggen voor collectiepatronen en oudere namen van MCP-hulpmiddelen te proberen. Wanneer QMD ondersteuning voor meerdere collectiefilters aangeeft, worden collecties met dezelfde bron met één QMD-proces doorzocht; oudere QMD-builds behouden het compatibiliteitspad per collectie. Dezelfde bron betekent dat duurzame geheugencollecties (standaardgeheugenbestanden plus aangepaste paden) samen worden gegroepeerd, terwijl collecties met sessietranscripten een afzonderlijke groep blijven, zodat brondiversificatie nog steeds beide invoerbronnen heeft.

mcporter-integratie

Alles staat onder memory.qmd.mcporter. Leidt QMD-zoekopdrachten via een langlevende mcporter MCP-daemon in plaats van voor elke query qmd te starten, waardoor de overhead van een koude start voor grotere modellen afneemt.

Vereist dat mcporter is geïnstalleerd en beschikbaar is via PATH, plus een geconfigureerde mcporter-server die qmd mcp uitvoert. Houd dit uitgeschakeld voor eenvoudigere lokale configuraties waarbij de kosten van het starten van een proces per query aanvaardbaar zijn.

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

Wanneer QMD-initialisatie bij het starten van de Gateway is ingeschakeld, start OpenClaw QMD alleen voor daarvoor in aanmerking komende agents. Als update.onBoot waar is en er geen interval- of embed-onderhoud is geconfigureerd, gebruikt het opstartproces een eenmalige manager voor de vernieuwing bij het opstarten en sluit deze vervolgens. Als een update- of embed-interval is geconfigureerd, opent het opstartproces de langlevende QMD-manager, zodat deze de watcher en intervaltimers kan beheren; update.onBoot: false slaat alleen de onmiddellijke vernieuwing bij het opstarten over.

Volledig QMD-voorbeeld

{  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 wordt geconfigureerd onder plugins.entries.memory-core.config.dreaming, niet onder agents.defaults.memorySearch.

Dreaming wordt als één geplande verwerkingsronde uitgevoerd en gebruikt interne lichte/diepe/REM-fasen als implementatiedetail.

Zie Dreaming voor het conceptuele gedrag en de slash-opdrachten.

Gebruikersinstellingen

Voorbeeld

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

Gerelateerd

• Configuratiereferentie
• Overzicht van geheugen
• Zoeken in geheugen