Deze pagina vermeldt elke configuratieknop voor geheugenzoekopdrachten in OpenClaw. Zie voor conceptuele overzichten:Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Memory overview
Hoe geheugen werkt.
Builtin engine
Standaard SQLite-backend.
QMD engine
Local-first sidecar.
Memory search
Zoekpijplijn en tuning.
Active memory
Geheugen-subagent voor interactieve sessies.
agents.defaults.memorySearch in openclaw.json, tenzij anders vermeld.
Als je zoekt naar de functietoggle en subagentconfiguratie voor Active Memory, die staat onder
plugins.entries.active-memory in plaats van memorySearch.Active Memory gebruikt een model met twee poorten:- de Plugin moet zijn ingeschakeld en gericht zijn op de huidige agent-id
- het verzoek moet een geschikte interactieve persistente chatsessie zijn
Providerselectie
| Sleutel | Type | Standaard | Beschrijving |
|---|---|---|---|
provider | string | automatisch gedetecteerd | Embeddingadapter-ID zoals bedrock, deepinfra, gemini, github-copilot, local, mistral, ollama, openai of voyage; kan ook een geconfigureerde models.providers.<id> zijn waarvan api naar een van die adapters verwijst |
model | string | providerstandaard | Naam van het embeddingmodel |
fallback | string | "none" | Fallback-adapter-ID wanneer de primaire adapter faalt |
enabled | boolean | true | Geheugenzoekopdrachten in- of uitschakelen |
Volgorde van automatische detectie
Wanneerprovider niet is ingesteld, selecteert OpenClaw de eerste beschikbare optie:
github-copilot
Geselecteerd als een GitHub Copilot-token kan worden gevonden (env-var of auth-profiel).
ollama wordt ondersteund maar niet automatisch gedetecteerd (stel dit expliciet in).
Aangepaste provider-id’s
memorySearch.provider kan naar een aangepaste models.providers.<id>-vermelding verwijzen. OpenClaw lost de api-eigenaar van die provider op voor de embeddingadapter, terwijl de aangepaste provider-id behouden blijft voor endpoint-, auth- en modelprefixafhandeling. Hierdoor kunnen multi-GPU- of multi-host-setups geheugenembeddings toewijzen aan een specifiek lokaal endpoint:
API-sleutelresolutie
Externe embeddings vereisen een API-sleutel. Bedrock gebruikt in plaats daarvan de standaardcredentialketen van de AWS SDK (instancerollen, SSO, toegangssleutels).| Provider | Env-var | Configuratiesleutel |
|---|---|---|
| Bedrock | AWS-credentialketen | Geen API-sleutel nodig |
| 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 | Auth-profiel via device-login |
| 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 dekt alleen chat/completions en voldoet niet voor embeddingverzoeken.
Configuratie van extern endpoint
Voor aangepaste OpenAI-compatibele endpoints of het overschrijven van providerstandaarden:Aangepaste API-basis-URL.
API-sleutel overschrijven.
Extra HTTP-headers (samengevoegd met providerstandaarden).
Providerspecifieke configuratie
Gemini
Gemini
| Sleutel | Type | Standaard | Beschrijving |
|---|---|---|---|
model | string | gemini-embedding-001 | Ondersteunt ook gemini-embedding-2-preview |
outputDimensionality | number | 3072 | Voor Embedding 2: 768, 1536 of 3072 |
OpenAI-compatible input types
OpenAI-compatible input types
OpenAI-compatibele embeddingendpoints kunnen kiezen voor providerspecifieke
Het wijzigen van deze waarden beïnvloedt de identiteit van de embeddingcache voor provider-batchindexering en moet worden gevolgd door een geheugenherindexering wanneer het upstreammodel de labels verschillend behandelt.
input_type-verzoekvelden. Dit is handig voor asymmetrische embeddingmodellen die verschillende labels vereisen voor query- en documentembeddings.| Sleutel | Type | Standaard | Beschrijving |
|---|---|---|---|
inputType | string | niet ingesteld | Gedeelde input_type voor query- en documentembeddings |
queryInputType | string | niet ingesteld | input_type tijdens query’s; overschrijft inputType |
documentInputType | string | niet ingesteld | Index-/document-input_type; overschrijft inputType |
Bedrock
Bedrock
Bedrock-embeddingconfiguratie
Bedrock gebruikt de standaardcredentialketen van de AWS SDK; er zijn geen API-sleutels nodig. Als OpenClaw op EC2 draait met een Bedrock-geactiveerde instancerol, stel dan alleen de provider en het model in:| Sleutel | Type | Standaard | Beschrijving |
|---|---|---|---|
model | string | amazon.titan-embed-text-v2:0 | Elke Bedrock-embeddingmodel-ID |
outputDimensionality | number | modelstandaard | Voor Titan V2: 256, 512 of 1024 |
| Model-ID | Provider | Standaarddimensies | Configureerbare dimensies |
|---|---|---|---|
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) erven de configuratie van het basismodel.Authenticatie: Bedrock-auth gebruikt de standaardresolutievolgorde voor credentials van de AWS SDK:- Omgevingsvariabelen (
AWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY) - SSO-tokencache
- Webidentiteitstokencredentials
- Gedeelde credentials- en configuratiebestanden
- ECS- of EC2-metadatacredentials
AWS_REGION, AWS_DEFAULT_REGION, de baseUrl van de amazon-bedrock-provider, of valt terug op us-east-1.IAM-machtigingen: de IAM-rol of -gebruiker heeft nodig:InvokeModel tot het specifieke model:Lokaal (GGUF + node-llama-cpp)
Lokaal (GGUF + node-llama-cpp)
| Sleutel | Type | Standaardwaarde | Beschrijving |
|---|---|---|---|
local.modelPath | string | automatisch gedownload | Pad naar GGUF-modelbestand |
local.modelCacheDir | string | standaard van node-llama-cpp | Cachemap voor gedownloade modellen |
local.contextSize | number | "auto" | 4096 | Grootte van het contextvenster voor de embeddingcontext. 4096 dekt typische chunks (128-512 tokens) en begrenst tegelijk niet-gewicht-VRAM. Verlaag naar 1024-2048 op beperkte hosts. "auto" gebruikt het getrainde maximum van het model - niet aanbevolen voor 8B+-modellen (Qwen3-Embedding-8B: 40 960 tokens -> ~32 GB VRAM versus ~8,8 GB bij 4096). |
embeddinggemma-300m-qat-Q8_0.gguf (~0,6 GB, automatisch gedownload). Bron-checkouts vereisen nog steeds goedkeuring voor native builds: pnpm approve-builds en daarna pnpm rebuild node-llama-cpp.Gebruik de zelfstandige CLI om hetzelfde providerpad te verifiëren dat de Gateway gebruikt:provider auto is, wordt local alleen geselecteerd wanneer local.modelPath naar een bestaand lokaal bestand wijst. hf:- en HTTP(S)-modelverwijzingen kunnen nog steeds expliciet worden gebruikt met provider: "local", maar ze zorgen er niet voor dat auto lokaal selecteert voordat het model op schijf beschikbaar is.Time-out voor inline embeddings
Overschrijf de time-out voor inline embeddingbatches tijdens geheugenindexering.Indien niet ingesteld, wordt de standaardwaarde van de provider gebruikt: 600 seconden voor lokale/zelfgehoste providers zoals
local, ollama en lmstudio, en 120 seconden voor gehoste providers. Verhoog dit wanneer lokale CPU-gebonden embeddingbatches gezond maar traag zijn.Configuratie voor hybride zoekopdrachten
Alles ondermemorySearch.query.hybrid:
| Sleutel | Type | Standaardwaarde | Beschrijving |
|---|---|---|---|
enabled | boolean | true | Hybride BM25 + vectorzoeken inschakelen |
vectorWeight | number | 0.7 | Gewicht voor vectorscores (0-1) |
textWeight | number | 0.3 | Gewicht voor BM25-scores (0-1) |
candidateMultiplier | number | 4 | Vermenigvuldiger voor kandidaatpoolgrootte |
- MMR (diversiteit)
- Tijdverval (recentheid)
| Sleutel | Type | Standaardwaarde | Beschrijving |
|---|---|---|---|
mmr.enabled | boolean | false | MMR-herrangschikking inschakelen |
mmr.lambda | number | 0.7 | 0 = maximale diversiteit, 1 = maximale relevantie |
Volledig voorbeeld
Aanvullende geheugenpaden
| Sleutel | Type | Beschrijving |
|---|---|---|
extraPaths | string[] | Aanvullende mappen of bestanden om te indexeren |
.md-bestanden. Symlinkafhandeling hangt af van de actieve backend: de ingebouwde engine negeert symlinks, terwijl QMD het gedrag van de onderliggende QMD-scanner volgt.
Gebruik voor agent-scoped cross-agent transcript search agents.list[].memorySearch.qmd.extraCollections in plaats van memory.qmd.paths. Die extra verzamelingen volgen dezelfde vorm { path, name, pattern? }, maar ze worden per agent samengevoegd en kunnen expliciete gedeelde namen behouden wanneer het pad buiten de huidige werkruimte wijst. Als hetzelfde opgeloste pad voorkomt in zowel memory.qmd.paths als memorySearch.qmd.extraCollections, behoudt QMD de eerste vermelding en slaat het duplicaat over.
Multimodaal geheugen (Gemini)
Indexeer afbeeldingen en audio naast Markdown met Gemini Embedding 2:| Sleutel | Type | Standaardwaarde | Beschrijving |
|---|---|---|---|
multimodal.enabled | boolean | false | Multimodale indexering inschakelen |
multimodal.modalities | string[] | — | ["image"], ["audio"], of ["all"] |
multimodal.maxFileBytes | number | 10000000 | Maximale bestandsgrootte voor indexering |
Geldt alleen voor bestanden in
extraPaths. Standaardgeheugenroots blijven uitsluitend Markdown. Vereist gemini-embedding-2-preview. fallback moet "none" zijn..jpg, .jpeg, .png, .webp, .gif, .heic, .heif (afbeeldingen); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).
Embedding-cache
| Sleutel | Type | Standaard | Beschrijving |
|---|---|---|---|
cache.enabled | boolean | false | Cache chunk-embeddings in SQLite |
cache.maxEntries | number | 50000 | Max. gecachte embeddings |
Batchindexering
| Sleutel | Type | Standaard | Beschrijving |
|---|---|---|---|
remote.nonBatchConcurrency | number | 4 | Parallelle inline embeddings |
remote.batch.enabled | boolean | false | Batch-embedding-API inschakelen |
remote.batch.concurrency | number | 2 | Parallelle batchtaken |
remote.batch.wait | boolean | true | Wachten op batchvoltooiing |
remote.batch.pollIntervalMs | number | — | Poll-interval |
remote.batch.timeoutMinutes | number | — | Batch-time-out |
openai, gemini en voyage. OpenAI-batches zijn doorgaans het snelst en goedkoopst voor grote backfills.
remote.nonBatchConcurrency bepaalt inline embedding-aanroepen die worden gebruikt door lokale/zelfgehoste providers en gehoste providers wanneer provider-batch-API’s niet actief zijn. Ollama gebruikt standaard 1 voor niet-batchindexering om kleinere lokale hosts niet te overbelasten; stel een hogere waarde in op grotere machines.
Dit staat los van sync.embeddingBatchTimeoutSeconds, dat de time-out voor inline embedding-aanroepen bepaalt.
Zoeken in sessiegeheugen (experimenteel)
Indexeer sessietranscripten en maak ze beschikbaar viamemory_search:
| Sleutel | Type | Standaard | Beschrijving |
|---|---|---|---|
experimental.sessionMemory | boolean | false | Sessie-indexering inschakelen |
sources | string[] | ["memory"] | Voeg "sessions" toe om transcripten op te nemen |
sync.sessions.deltaBytes | number | 100000 | Bytedrempel voor herindexering |
sync.sessions.deltaMessages | number | 50 | Berichtdrempel voor herindexering |
SQLite-vectorversnelling (sqlite-vec)
| Sleutel | Type | Standaard | Beschrijving |
|---|---|---|---|
store.vector.enabled | boolean | true | Gebruik sqlite-vec voor vectorquery’s |
store.vector.extensionPath | string | gebundeld | Overschrijf sqlite-vec-pad |
Indexopslag
| Sleutel | Type | Standaard | Beschrijving |
|---|---|---|---|
store.path | string | ~/.openclaw/memory/{agentId}.sqlite | Indexlocatie (ondersteunt {agentId}-token) |
store.fts.tokenizer | string | unicode61 | FTS5-tokenizer (unicode61 of trigram) |
QMD-backendconfiguratie
Stelmemory.backend = "qmd" in om dit in te schakelen. Alle QMD-instellingen staan onder memory.qmd:
| Sleutel | Type | Standaard | Beschrijving |
|---|---|---|---|
command | string | qmd | Pad naar QMD-uitvoerbaar bestand; stel een absoluut pad in wanneer service-PATH afwijkt van je shell |
searchMode | string | search | Zoekopdracht: search, vsearch, query |
includeDefaultMemory | boolean | true | MEMORY.md + memory/**/*.md automatisch indexeren |
paths[] | array | — | Extra paden: { name, path, pattern? } |
sessions.enabled | boolean | false | Sessietranscripten indexeren |
sessions.retentionDays | number | — | Transcriptbewaartermijn |
sessions.exportDir | string | — | Exportmap |
searchMode: "search" is alleen lexicaal/BM25. OpenClaw voert geen gereedheidsprobes voor semantische vectoren of QMD-embeddingonderhoud uit voor die modus, ook niet tijdens memory status --deep; vsearch en query blijven QMD-vectorgereedheid en embeddings vereisen.
OpenClaw geeft de voorkeur aan de huidige QMD-collectie- en MCP-queryvormen, maar houdt oudere QMD-releases werkend door waar nodig compatibele collectiepatroonflags en oudere MCP-toolnamen te proberen. Wanneer QMD ondersteuning voor meerdere collectiefilters adverteert, worden collecties met dezelfde bron met één QMD-proces doorzocht; oudere QMD-builds blijven het compatibiliteitspad per collectie gebruiken. Dezelfde bron betekent dat duurzame geheugencollecties samen worden gegroepeerd, terwijl sessietranscriptcollecties een aparte groep blijven, zodat brondiversificatie nog steeds beide invoeren heeft.
QMD-modeloverrides blijven aan de QMD-kant, niet in de OpenClaw-configuratie. Als je QMD’s modellen globaal moet overschrijven, stel dan omgevingsvariabelen zoals
QMD_EMBED_MODEL, QMD_RERANK_MODEL en QMD_GENERATE_MODEL in de Gateway-runtimeomgeving in.Updateschema
Updateschema
| Sleutel | Type | Standaard | Beschrijving |
|---|---|---|---|
update.interval | string | 5m | Vernieuwingsinterval |
update.debounceMs | number | 15000 | Bestandswijzigingen debouncen |
update.onBoot | boolean | true | Vernieuwen wanneer de langlevende QMD-manager opent; bewaakt ook opt-in startvernieuwing |
update.startup | string | off | Optionele vernieuwing bij Gateway-start: off, idle of immediate |
update.startupDelayMs | number | 120000 | Vertraging voordat startup: "idle"-vernieuwing wordt uitgevoerd |
update.waitForBootSync | boolean | false | Manager openen blokkeren tot de eerste vernieuwing is voltooid |
update.embedInterval | string | — | Afzonderlijk embeddingritme |
update.commandTimeoutMs | number | — | Time-out voor QMD-commando’s |
update.updateTimeoutMs | number | — | Time-out voor QMD-updatebewerkingen |
update.embedTimeoutMs | number | — | Time-out voor QMD-embeddingbewerkingen |
Limieten
Limieten
| Sleutel | Type | Standaard | Beschrijving |
|---|---|---|---|
limits.maxResults | number | 6 | Maximaal aantal zoekresultaten |
limits.maxSnippetChars | number | — | Snippetlengte begrenzen |
limits.maxInjectedChars | number | — | Totaal aantal geïnjecteerde tekens begrenzen |
limits.timeoutMs | number | 4000 | Zoektime-out |
Bereik
Bereik
Bepaalt welke sessies QMD-zoekresultaten kunnen ontvangen. Hetzelfde schema als De meegeleverde standaardinstelling staat directe sessies en kanaalsessies toe, terwijl groepen nog steeds worden geweigerd.Standaard is alleen DM.
session.sendPolicy:match.keyPrefix matcht de genormaliseerde sessiesleutel; match.rawKeyPrefix matcht de ruwe sleutel inclusief agent:<id>:.Citaties
Citaties
memory.citations geldt voor alle backends:| Waarde | Gedrag |
|---|---|
auto (standaard) | Source: <path#line>-footer opnemen in snippets |
on | Footer altijd opnemen |
off | Footer weglaten (pad wordt intern nog steeds aan agent doorgegeven) |
Volledig QMD-voorbeeld
Dreaming
Dreaming wordt geconfigureerd onderplugins.entries.memory-core.config.dreaming, niet onder agents.defaults.memorySearch.
Dreaming draait als één geplande sweep en gebruikt interne light/deep/REM-fasen als implementatiedetail.
Zie Dreaming voor conceptueel gedrag en slashcommando’s.
Gebruikersinstellingen
| Sleutel | Type | Standaardmodel | Beschrijving |
|---|---|---|---|
enabled | boolean | false | Dreaming volledig in- of uitschakelen |
frequency | string | 0 3 * * * | Optioneel cronritme voor de volledige Dreaming-sweep |
model | string | standaardmodel | Optionele modeloverride voor de Dream Diary-subagent |
Voorbeeld
- Dreaming schrijft machinestatus naar
memory/.dreams/. - Dreaming schrijft menselijk leesbare narratieve uitvoer naar
DREAMS.md(of bestaanddreams.md). dreaming.modelgebruikt de bestaande vertrouwenspoort voor Plugin-subagents; stelplugins.entries.memory-core.subagent.allowModelOverride: truein voordat je dit inschakelt.- Dream Diary probeert het één keer opnieuw met het standaardmodel van de sessie wanneer het geconfigureerde model niet beschikbaar is. Vertrouwens- of allowlistfouten worden gelogd en worden niet stilzwijgend opnieuw geprobeerd.
- Het beleid en de drempels voor de light/deep/REM-fasen zijn intern gedrag, geen gebruikersgerichte configuratie.