Naar hoofdinhoud gaan

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.

Deze pagina vermeldt elke configuratieknop voor geheugenzoekopdrachten in OpenClaw. Zie voor conceptuele overzichten:

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.
Alle instellingen voor geheugenzoekopdrachten staan onder 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:
  1. de Plugin moet zijn ingeschakeld en gericht zijn op de huidige agent-id
  2. het verzoek moet een geschikte interactieve persistente chatsessie zijn
Zie Active Memory voor het activatiemodel, Plugin-eigen configuratie, transcriptpersistentie en het veilige uitrolpatroon.

Providerselectie

SleutelTypeStandaardBeschrijving
providerstringautomatisch gedetecteerdEmbeddingadapter-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
modelstringproviderstandaardNaam van het embeddingmodel
fallbackstring"none"Fallback-adapter-ID wanneer de primaire adapter faalt
enabledbooleantrueGeheugenzoekopdrachten in- of uitschakelen

Volgorde van automatische detectie

Wanneer provider niet is ingesteld, selecteert OpenClaw de eerste beschikbare optie:
1

local

Geselecteerd als memorySearch.local.modelPath is geconfigureerd en het bestand bestaat.
2

github-copilot

Geselecteerd als een GitHub Copilot-token kan worden gevonden (env-var of auth-profiel).
3

openai

Geselecteerd als een OpenAI-sleutel kan worden gevonden.
4

gemini

Geselecteerd als een Gemini-sleutel kan worden gevonden.
5

voyage

Geselecteerd als een Voyage-sleutel kan worden gevonden.
6

mistral

Geselecteerd als een Mistral-sleutel kan worden gevonden.
7

deepinfra

Geselecteerd als een DeepInfra-sleutel kan worden gevonden.
8

bedrock

Geselecteerd als de credentialketen van de AWS SDK wordt gevonden (instancerol, toegangssleutels, profiel, SSO, webidentiteit of gedeelde configuratie).
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:
{
  models: {
    providers: {
      "ollama-5080": {
        api: "ollama",
        baseUrl: "http://gpu-box.local:11435",
        apiKey: "ollama-local",
        models: [{ id: "qwen3-embedding:0.6b" }],
      },
    },
  },
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama-5080",
        model: "qwen3-embedding:0.6b",
      },
    },
  },
}

API-sleutelresolutie

Externe embeddings vereisen een API-sleutel. Bedrock gebruikt in plaats daarvan de standaardcredentialketen van de AWS SDK (instancerollen, SSO, toegangssleutels).
ProviderEnv-varConfiguratiesleutel
BedrockAWS-credentialketenGeen API-sleutel nodig
DeepInfraDEEPINFRA_API_KEYmodels.providers.deepinfra.apiKey
GeminiGEMINI_API_KEYmodels.providers.google.apiKey
GitHub CopilotCOPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKENAuth-profiel via device-login
MistralMISTRAL_API_KEYmodels.providers.mistral.apiKey
OllamaOLLAMA_API_KEY (placeholder)
OpenAIOPENAI_API_KEYmodels.providers.openai.apiKey
VoyageVOYAGE_API_KEYmodels.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:
remote.baseUrl
string
Aangepaste API-basis-URL.
remote.apiKey
string
API-sleutel overschrijven.
remote.headers
object
Extra HTTP-headers (samengevoegd met providerstandaarden).
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

Providerspecifieke configuratie

SleutelTypeStandaardBeschrijving
modelstringgemini-embedding-001Ondersteunt ook gemini-embedding-2-preview
outputDimensionalitynumber3072Voor Embedding 2: 768, 1536 of 3072
Het wijzigen van het model of outputDimensionality activeert automatisch een volledige herindexering.
OpenAI-compatibele embeddingendpoints kunnen kiezen voor providerspecifieke input_type-verzoekvelden. Dit is handig voor asymmetrische embeddingmodellen die verschillende labels vereisen voor query- en documentembeddings.
SleutelTypeStandaardBeschrijving
inputTypestringniet ingesteldGedeelde input_type voor query- en documentembeddings
queryInputTypestringniet ingesteldinput_type tijdens query’s; overschrijft inputType
documentInputTypestringniet ingesteldIndex-/document-input_type; overschrijft inputType
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}
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.

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:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}
SleutelTypeStandaardBeschrijving
modelstringamazon.titan-embed-text-v2:0Elke Bedrock-embeddingmodel-ID
outputDimensionalitynumbermodelstandaardVoor Titan V2: 256, 512 of 1024
Ondersteunde modellen (met familiedetectie en standaarddimensies):
Model-IDProviderStandaarddimensiesConfigureerbare dimensies
amazon.titan-embed-text-v2:0Amazon1024256, 512, 1024
amazon.titan-embed-text-v1Amazon1536
amazon.titan-embed-g1-text-02Amazon1536
amazon.titan-embed-image-v1Amazon1024
amazon.nova-2-multimodal-embeddings-v1:0Amazon1024256, 384, 1024, 3072
cohere.embed-english-v3Cohere1024
cohere.embed-multilingual-v3Cohere1024
cohere.embed-v4:0Cohere1536256-1536
twelvelabs.marengo-embed-3-0-v1:0TwelveLabs512
twelvelabs.marengo-embed-2-7-v1:0TwelveLabs1024
Varianten met throughput-suffix (bijv. 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:
  1. Omgevingsvariabelen (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
  2. SSO-tokencache
  3. Webidentiteitstokencredentials
  4. Gedeelde credentials- en configuratiebestanden
  5. ECS- of EC2-metadatacredentials
Regio wordt opgelost vanuit 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:
{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}
Voor least privilege beperk je InvokeModel tot het specifieke model:
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
SleutelTypeStandaardwaardeBeschrijving
local.modelPathstringautomatisch gedownloadPad naar GGUF-modelbestand
local.modelCacheDirstringstandaard van node-llama-cppCachemap voor gedownloade modellen
local.contextSizenumber | "auto"4096Grootte 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).
Standaardmodel: 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:
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
Als 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

sync.embeddingBatchTimeoutSeconds
number
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 onder memorySearch.query.hybrid:
SleutelTypeStandaardwaardeBeschrijving
enabledbooleantrueHybride BM25 + vectorzoeken inschakelen
vectorWeightnumber0.7Gewicht voor vectorscores (0-1)
textWeightnumber0.3Gewicht voor BM25-scores (0-1)
candidateMultipliernumber4Vermenigvuldiger voor kandidaatpoolgrootte
SleutelTypeStandaardwaardeBeschrijving
mmr.enabledbooleanfalseMMR-herrangschikking inschakelen
mmr.lambdanumber0.70 = maximale diversiteit, 1 = maximale relevantie

Volledig voorbeeld

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            vectorWeight: 0.7,
            textWeight: 0.3,
            mmr: { enabled: true, lambda: 0.7 },
            temporalDecay: { enabled: true, halfLifeDays: 30 },
          },
        },
      },
    },
  },
}

Aanvullende geheugenpaden

SleutelTypeBeschrijving
extraPathsstring[]Aanvullende mappen of bestanden om te indexeren
{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}
Paden kunnen absoluut of werkruimte-relatief zijn. Mappen worden recursief gescand op .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:
SleutelTypeStandaardwaardeBeschrijving
multimodal.enabledbooleanfalseMultimodale indexering inschakelen
multimodal.modalitiesstring[]["image"], ["audio"], of ["all"]
multimodal.maxFileBytesnumber10000000Maximale bestandsgrootte voor indexering
Geldt alleen voor bestanden in extraPaths. Standaardgeheugenroots blijven uitsluitend Markdown. Vereist gemini-embedding-2-preview. fallback moet "none" zijn.
Ondersteunde formaten: .jpg, .jpeg, .png, .webp, .gif, .heic, .heif (afbeeldingen); .mp3, .wav, .ogg, .opus, .m4a, .aac, .flac (audio).

Embedding-cache

SleutelTypeStandaardBeschrijving
cache.enabledbooleanfalseCache chunk-embeddings in SQLite
cache.maxEntriesnumber50000Max. gecachte embeddings
Voorkomt dat ongewijzigde tekst opnieuw wordt ge-embed tijdens herindexering of transcriptupdates.

Batchindexering

SleutelTypeStandaardBeschrijving
remote.nonBatchConcurrencynumber4Parallelle inline embeddings
remote.batch.enabledbooleanfalseBatch-embedding-API inschakelen
remote.batch.concurrencynumber2Parallelle batchtaken
remote.batch.waitbooleantrueWachten op batchvoltooiing
remote.batch.pollIntervalMsnumberPoll-interval
remote.batch.timeoutMinutesnumberBatch-time-out
Beschikbaar voor 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 via memory_search:
SleutelTypeStandaardBeschrijving
experimental.sessionMemorybooleanfalseSessie-indexering inschakelen
sourcesstring[]["memory"]Voeg "sessions" toe om transcripten op te nemen
sync.sessions.deltaBytesnumber100000Bytedrempel voor herindexering
sync.sessions.deltaMessagesnumber50Berichtdrempel voor herindexering
Sessie-indexering is opt-in en wordt asynchroon uitgevoerd. Resultaten kunnen licht verouderd zijn. Sessielogboeken staan op schijf, dus behandel toegang tot het bestandssysteem als de vertrouwensgrens.

SQLite-vectorversnelling (sqlite-vec)

SleutelTypeStandaardBeschrijving
store.vector.enabledbooleantrueGebruik sqlite-vec voor vectorquery’s
store.vector.extensionPathstringgebundeldOverschrijf sqlite-vec-pad
Wanneer sqlite-vec niet beschikbaar is, valt OpenClaw automatisch terug op in-process cosinusgelijkenis.

Indexopslag

SleutelTypeStandaardBeschrijving
store.pathstring~/.openclaw/memory/{agentId}.sqliteIndexlocatie (ondersteunt {agentId}-token)
store.fts.tokenizerstringunicode61FTS5-tokenizer (unicode61 of trigram)

QMD-backendconfiguratie

Stel memory.backend = "qmd" in om dit in te schakelen. Alle QMD-instellingen staan onder memory.qmd:
SleutelTypeStandaardBeschrijving
commandstringqmdPad naar QMD-uitvoerbaar bestand; stel een absoluut pad in wanneer service-PATH afwijkt van je shell
searchModestringsearchZoekopdracht: search, vsearch, query
includeDefaultMemorybooleantrueMEMORY.md + memory/**/*.md automatisch indexeren
paths[]arrayExtra paden: { name, path, pattern? }
sessions.enabledbooleanfalseSessietranscripten indexeren
sessions.retentionDaysnumberTranscriptbewaartermijn
sessions.exportDirstringExportmap
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.
SleutelTypeStandaardBeschrijving
update.intervalstring5mVernieuwingsinterval
update.debounceMsnumber15000Bestandswijzigingen debouncen
update.onBootbooleantrueVernieuwen wanneer de langlevende QMD-manager opent; bewaakt ook opt-in startvernieuwing
update.startupstringoffOptionele vernieuwing bij Gateway-start: off, idle of immediate
update.startupDelayMsnumber120000Vertraging voordat startup: "idle"-vernieuwing wordt uitgevoerd
update.waitForBootSyncbooleanfalseManager openen blokkeren tot de eerste vernieuwing is voltooid
update.embedIntervalstringAfzonderlijk embeddingritme
update.commandTimeoutMsnumberTime-out voor QMD-commando’s
update.updateTimeoutMsnumberTime-out voor QMD-updatebewerkingen
update.embedTimeoutMsnumberTime-out voor QMD-embeddingbewerkingen
SleutelTypeStandaardBeschrijving
limits.maxResultsnumber6Maximaal aantal zoekresultaten
limits.maxSnippetCharsnumberSnippetlengte begrenzen
limits.maxInjectedCharsnumberTotaal aantal geïnjecteerde tekens begrenzen
limits.timeoutMsnumber4000Zoektime-out
Bepaalt welke sessies QMD-zoekresultaten kunnen ontvangen. Hetzelfde schema als session.sendPolicy:
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
De meegeleverde standaardinstelling staat directe sessies en kanaalsessies toe, terwijl groepen nog steeds worden geweigerd.Standaard is alleen DM. match.keyPrefix matcht de genormaliseerde sessiesleutel; match.rawKeyPrefix matcht de ruwe sleutel inclusief agent:<id>:.
memory.citations geldt voor alle backends:
WaardeGedrag
auto (standaard)Source: <path#line>-footer opnemen in snippets
onFooter altijd opnemen
offFooter weglaten (pad wordt intern nog steeds aan agent doorgegeven)
QMD-opstartvernieuwingen gebruiken een eenmalig subprocesspad tijdens het starten van de Gateway. De langlevende QMD-manager blijft eigenaar van de reguliere bestandswatcher en intervaltimers wanneer geheugenzoekopdracht wordt geopend voor interactief gebruik.

Volledig QMD-voorbeeld

{
  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

Dreaming wordt geconfigureerd onder plugins.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

SleutelTypeStandaardmodelBeschrijving
enabledbooleanfalseDreaming volledig in- of uitschakelen
frequencystring0 3 * * *Optioneel cronritme voor de volledige Dreaming-sweep
modelstringstandaardmodelOptionele modeloverride voor de Dream Diary-subagent

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",
          },
        },
      },
    },
  },
}
  • Dreaming schrijft machinestatus naar memory/.dreams/.
  • Dreaming schrijft menselijk leesbare narratieve uitvoer naar DREAMS.md (of bestaand dreams.md).
  • dreaming.model gebruikt de bestaande vertrouwenspoort voor Plugin-subagents; stel plugins.entries.memory-core.subagent.allowModelOverride: true in 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.

Gerelateerd