This page covers the full configuration surface for OpenClaw memory search. For Remote embeddings require<\/strong> an API key for the embedding provider. OpenClaw Set If you want to pre-download models manually (and warm the same index OpenClaw OpenClaw’s QMD state lives under your state dir<\/strong> (defaults to “`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}<\/p>\n STATE_DIR=”${OPENCLAW_STATE_DIR:-$HOME\/.openclaw}”<\/p>\n export XDG_CONFIG_HOME=”$STATE_DIR\/agents\/main\/qmd\/xdg-config” qmd update qmd query “test” -c memory-root –json >\/dev\/null 2>&1 Notes:<\/p>\n OpenClaw can index image and audio files from “`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} Notes:<\/p>\n “`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} If you don’t want to set an API key, use Why OpenAI batch is fast and cheap:<\/p>\n Config example:<\/p>\n “`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}} Vector + Keyword -> Weighted Merge -> Temporal Decay -> Sort -> MMR -> Top-K Results<\/p>\n memory\/2026-02-10.md -> “Configured Omada router, set VLAN 10 for IoT devices” decayedScore = score x e^(-lambda x ageInDays)<\/p>\n memory\/2025-09-15.md -> “Rod works Mon-Fri, standup at 10am, pairing at 2pm” (148 days old)
\nthe conceptual overview (file layout, memory tools, when to write memory, and the
\nautomatic flush), see Memory<\/a>.<\/p>\nMemory search defaults<\/h2>\n
\n
agents.defaults.memorySearch<\/code> (not top-level
\n memorySearch<\/code>).<\/li>\nmemorySearch.provider<\/code> is not set, OpenClaw auto-selects:
\n 1. local<\/code> if a memorySearch.local.modelPath<\/code> is configured and the file exists.
\n 2. openai<\/code> if an OpenAI key can be resolved.
\n 3. gemini<\/code> if a Gemini key can be resolved.
\n 4. voyage<\/code> if a Voyage key can be resolved.
\n 5. mistral<\/code> if a Mistral key can be resolved.
\n 6. Otherwise memory search stays disabled until configured.<\/li>\npnpm approve-builds<\/code>.<\/li>\nmemorySearch.provider = \"ollama\"<\/code> is also supported for local\/self-hosted
\n Ollama embeddings (\/api\/embeddings<\/code>), but it is not auto-selected.<\/li>\n<\/ul>\n
\nresolves keys from auth profiles, models.providers.*.apiKey<\/code>, or environment
\nvariables. Codex OAuth only covers chat\/completions and does not<\/strong> satisfy
\nembeddings for memory search. For Gemini, use GEMINI_API_KEY<\/code> or
\nmodels.providers.google.apiKey<\/code>. For Voyage, use VOYAGE_API_KEY<\/code> or
\nmodels.providers.voyage.apiKey<\/code>. For Mistral, use MISTRAL_API_KEY<\/code> or
\nmodels.providers.mistral.apiKey<\/code>. Ollama typically does not require a real API
\nkey (a placeholder like OLLAMA_API_KEY=ollama-local<\/code> is enough when needed by
\nlocal policy).
\nWhen using a custom OpenAI-compatible endpoint,
\nset memorySearch.remote.apiKey<\/code> (and optional memorySearch.remote.headers<\/code>).<\/p>\nQMD backend (experimental)<\/h2>\n
memory.backend = \"qmd\"<\/code> to swap the built-in SQLite indexer for
\nQMD<\/a>: a local-first search sidecar that combines
\nBM25 + vectors + reranking. Markdown stays the source of truth; OpenClaw shells
\nout to QMD for retrieval. Key points:<\/p>\nPrerequisites<\/h3>\n
\n
memory.backend = \"qmd\"<\/code>).<\/li>\nbun install -g https:\/\/github.com\/tobi\/qmd<\/code> or grab
\n a release) and make sure the qmd<\/code> binary is on the gateway’s PATH<\/code>.<\/li>\nbrew install sqlite<\/code> on
\n macOS).<\/li>\nnode-llama-cpp<\/code> and auto-downloads GGUF
\n models from HuggingFace on first use (no separate Ollama daemon required).<\/li>\n
\n ~\/.openclaw\/agents\/<agentId>\/qmd\/<\/code> by setting XDG_CONFIG_HOME<\/code> and
\n XDG_CACHE_HOME<\/code>.<\/li>\n
\n installed. Windows is best supported via WSL2.<\/li>\n<\/ul>\nHow the sidecar runs<\/h3>\n
\n
\n ~\/.openclaw\/agents\/<agentId>\/qmd\/<\/code> (config + cache + sqlite DB).<\/li>\nqmd collection add<\/code> from memory.qmd.paths<\/code>
\n (plus default workspace memory files), then qmd update<\/code> + qmd embed<\/code> run
\n on boot and on a configurable interval (memory.qmd.update.interval<\/code>,
\n default 5 m).<\/li>\n
\n timers are armed even before the first memory_search<\/code> call.<\/li>\n
\n blocked; set memory.qmd.update.waitForBootSync = true<\/code> to keep the previous
\n blocking behavior.<\/li>\nmemory.qmd.searchMode<\/code> (default qmd search --json<\/code>; also
\n supports vsearch<\/code> and query<\/code>). If the selected mode rejects flags on your
\n QMD build, OpenClaw retries with qmd query<\/code>. If QMD fails or the binary is
\n missing, OpenClaw automatically falls back to the builtin SQLite manager so
\n memory tools keep working.<\/li>\n
\n controlled by QMD itself.<\/li>\n
\n expansion) on the first qmd query<\/code> run.<\/li>\nXDG_CONFIG_HOME<\/code>\/XDG_CACHE_HOME<\/code> automatically when it runs QMD.<\/li>\n
\n uses), run a one-off query with the agent’s XDG dirs.<\/p>\n~\/.openclaw<\/code>).
\nYou can point qmd<\/code> at the exact same index by exporting the same XDG vars
\nOpenClaw uses:<\/p>\nPick the same state dir OpenClaw uses<\/h1>\n
\nexport XDG_CACHE_HOME=”$STATE_DIR\/agents\/main\/qmd\/xdg-cache”<\/p>\n(Optional) force an index refresh + embeddings<\/h1>\n
\nqmd embed<\/p>\nWarm up \/ trigger first-time model downloads<\/h1>\n
\n“`<\/p>\n<\/li>\n<\/ul>\nConfig surface (
memory.qmd.*<\/code>)<\/h3>\n\n
command<\/code> (default qmd<\/code>): override the executable path.<\/li>\nsearchMode<\/code> (default search<\/code>): pick which QMD command backs
\n memory_search<\/code> (search<\/code>, vsearch<\/code>, query<\/code>).<\/li>\nincludeDefaultMemory<\/code> (default true<\/code>): auto-index MEMORY.md<\/code> + memory\/**\/*.md<\/code>.<\/li>\npaths[]<\/code>: add extra directories\/files (path<\/code>, optional pattern<\/code>, optional
\n stable name<\/code>).<\/li>\nsessions<\/code>: opt into session JSONL indexing (enabled<\/code>, retentionDays<\/code>,
\n exportDir<\/code>).<\/li>\nupdate<\/code>: controls refresh cadence and maintenance execution:
\n (interval<\/code>, debounceMs<\/code>, onBoot<\/code>, waitForBootSync<\/code>, embedInterval<\/code>,
\n commandTimeoutMs<\/code>, updateTimeoutMs<\/code>, embedTimeoutMs<\/code>).<\/li>\nlimits<\/code>: clamp recall payload (maxResults<\/code>, maxSnippetChars<\/code>,
\n maxInjectedChars<\/code>, timeoutMs<\/code>).<\/li>\nscope<\/code>: same schema as session.sendPolicy<\/code><\/a>.
\n Default is DM-only (deny<\/code> all, allow<\/code> direct chats); loosen it to surface QMD
\n hits in groups\/channels.<\/li>\nmatch.keyPrefix<\/code> matches the normalized<\/strong> session key (lowercased, with any
\n leading agent:<id>:<\/code> stripped). Example: discord:channel:<\/code>.<\/li>\nmatch.rawKeyPrefix<\/code> matches the raw<\/strong> session key (lowercased), including
\n agent:<id>:<\/code>. Example: agent:main:discord:<\/code>.<\/li>\nmatch.keyPrefix: \"agent:...\"<\/code> is still treated as a raw-key prefix,
\n but prefer rawKeyPrefix<\/code> for clarity.<\/li>\nscope<\/code> denies a search, OpenClaw logs a warning with the derived
\n channel<\/code>\/chatType<\/code> so empty results are easier to debug.<\/li>\n
\n qmd\/<collection>\/<relative-path><\/code> in memory_search<\/code> results; memory_get<\/code>
\n understands that prefix and reads from the configured QMD collection root.<\/li>\nmemory.qmd.sessions.enabled = true<\/code>, OpenClaw exports sanitized session
\n transcripts (User\/Assistant turns) into a dedicated QMD collection under
\n ~\/.openclaw\/agents\/<id>\/qmd\/sessions\/<\/code>, so memory_search<\/code> can recall recent
\n conversations without touching the builtin SQLite index.<\/li>\nmemory_search<\/code> snippets now include a Source: <path#line><\/code> footer when
\n memory.citations<\/code> is auto<\/code>\/on<\/code>; set memory.citations = \"off\"<\/code> to keep
\n the path metadata internal (the agent still receives the path for
\n memory_get<\/code>, but the snippet text omits the footer and the system prompt
\n warns the agent not to cite it).<\/li>\n<\/ul>\nQMD example<\/h3>\n
``json5 theme={\"theme\":{\"light\":\"min-light\",\"dark\":\"min-dark\"}}
\nmemory: {
\n backend: \"qmd\",
\n citations: \"auto\",
\n qmd: {
\n includeDefaultMemory: true,
\n update: { interval: \"5m\", debounceMs: 15000 },
\n limits: { maxResults: 6, timeoutMs: 4000 },
\n scope: {
\n default: \"deny\",
\n rules: [
\n { action: \"allow\", match: { chatType: \"direct\" } },
\n \/\/ Normalized session-key prefix (strips<\/code>agent::).
\n { action: \"deny\", match: { keyPrefix: \"discord:channel:\" } },
\n \/\/ Raw session-key prefix (includes<\/code>agent::`).
\n { action: “deny”, match: { rawKeyPrefix: “agent:main:discord:” } },
\n ]
\n },
\n paths: [
\n { name: “docs”, path: “~\/notes”, pattern: “*\/<\/em>.md” }
\n ]
\n }
\n}<\/p>\n\n### Citations and fallback\n\n* `memory.citations` applies regardless of backend (`auto`\/`on`\/`off`).\n* When `qmd` runs, we tag `status().backend = "qmd"` so diagnostics show which\n engine served the results. If the QMD subprocess exits or JSON output can't be\n parsed, the search manager logs a warning and returns the builtin provider\n (existing Markdown embeddings) until QMD recovers.\n\n## Additional memory paths\n\nIf you want to index Markdown files outside the default workspace layout, add\nexplicit paths:\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\nagents: {\n defaults: {\n memorySearch: {\n extraPaths: ["..\/team-docs", "\/srv\/shared-notes\/overview.md"]\n }\n }\n}\n<\/code><\/pre>\n\n
.md<\/code> files.<\/li>\nmemorySearch.multimodal.enabled = true<\/code>, OpenClaw also indexes supported image\/audio files under extraPaths<\/code> only. Default memory roots (MEMORY.md<\/code>, memory.md<\/code>, memory\/**\/*.md<\/code>) stay Markdown-only.<\/li>\nMultimodal memory files (Gemini image + audio)<\/h2>\n
memorySearch.extraPaths<\/code> when using Gemini embedding 2:<\/p>\n
\nagents: {
\n defaults: {
\n memorySearch: {
\n provider: “gemini”,
\n model: “gemini-embedding-2-preview”,
\n extraPaths: [“assets\/reference”, “voice-notes”],
\n multimodal: {
\n enabled: true,
\n modalities: [“image”, “audio”], \/\/ or [“all”]
\n maxFileBytes: 10000000
\n },
\n remote: {
\n apiKey: “YOUR_GEMINI_API_KEY”
\n }
\n }
\n }
\n}<\/p>\n\nNotes:\n\n* Multimodal memory is currently supported only for `gemini-embedding-2-preview`.\n* Multimodal indexing applies only to files discovered through `memorySearch.extraPaths`.\n* Supported modalities in this phase: image and audio.\n* `memorySearch.fallback` must stay `"none"` while multimodal memory is enabled.\n* Matching image\/audio file bytes are uploaded to the configured Gemini embedding endpoint during indexing.\n* Supported image extensions: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif`.\n* Supported audio extensions: `.mp3`, `.wav`, `.ogg`, `.opus`, `.m4a`, `.aac`, `.flac`.\n* Search queries remain text, but Gemini can compare those text queries against indexed image\/audio embeddings.\n* `memory_get` still reads Markdown only; binary files are searchable but not returned as raw file contents.\n\n## Gemini embeddings (native)\n\nSet the provider to `gemini` to use the Gemini embeddings API directly:\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\nagents: {\n defaults: {\n memorySearch: {\n provider: "gemini",\n model: "gemini-embedding-001",\n remote: {\n apiKey: "YOUR_GEMINI_API_KEY"\n }\n }\n }\n}\n<\/code><\/pre>\n\n
remote.baseUrl<\/code> is optional (defaults to the Gemini API base URL).<\/li>\nremote.headers<\/code> lets you add extra headers if needed.<\/li>\ngemini-embedding-001<\/code>.<\/li>\ngemini-embedding-2-preview<\/code> is also supported: 8192 token limit and configurable dimensions (768 \/ 1536 \/ 3072, default 3072).<\/li>\n<\/ul>\nGemini Embedding 2 (preview)<\/h3>\n
\nagents: {
\n defaults: {
\n memorySearch: {
\n provider: “gemini”,
\n model: “gemini-embedding-2-preview”,
\n outputDimensionality: 3072, \/\/ optional: 768, 1536, or 3072 (default)
\n remote: {
\n apiKey: “YOUR_GEMINI_API_KEY”
\n }
\n }
\n }
\n}<\/p>\n\n> **Re-index required:** Switching from `gemini-embedding-001` (768 dimensions)\n> to `gemini-embedding-2-preview` (3072 dimensions) changes the vector size. The same is true if you\n> change `outputDimensionality` between 768, 1536, and 3072.\n> OpenClaw will automatically reindex when it detects a model or dimension change.\n\n## Custom OpenAI-compatible endpoint\n\nIf you want to use a custom OpenAI-compatible endpoint (OpenRouter, vLLM, or a proxy),\nyou can use the `remote` configuration with the OpenAI provider:\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\nagents: {\n defaults: {\n memorySearch: {\n provider: "openai",\n model: "text-embedding-3-small",\n remote: {\n baseUrl: "https:\/\/api.example.com\/v1\/",\n apiKey: "YOUR_OPENAI_COMPAT_API_KEY",\n headers: { "X-Custom-Header": "value" }\n }\n }\n }\n}\n<\/code><\/pre>\nmemorySearch.provider = \"local\"<\/code> or set
\nmemorySearch.fallback = \"none\"<\/code>.<\/p>\nFallbacks<\/h3>\n
\n
memorySearch.fallback<\/code> can be openai<\/code>, gemini<\/code>, voyage<\/code>, mistral<\/code>, ollama<\/code>, local<\/code>, or none<\/code>.<\/li>\nBatch indexing (OpenAI + Gemini + Voyage)<\/h3>\n
\n
agents.defaults.memorySearch.remote.batch.enabled = true<\/code> to enable for large-corpus indexing (OpenAI, Gemini, and Voyage).<\/li>\nremote.batch.wait<\/code>, remote.batch.pollIntervalMs<\/code>, and remote.batch.timeoutMinutes<\/code> if needed.<\/li>\nremote.batch.concurrency<\/code> to control how many batch jobs we submit in parallel (default: 2).<\/li>\nmemorySearch.provider = \"openai\"<\/code> or \"gemini\"<\/code> and uses the corresponding API key.<\/li>\n\n
\nagents: {
\n defaults: {
\n memorySearch: {
\n provider: “openai”,
\n model: “text-embedding-3-small”,
\n fallback: “openai”,
\n remote: {
\n batch: { enabled: true, concurrency: 2 }
\n },
\n sync: { watch: true }
\n }
\n }
\n}<\/p>\n\n## How the memory tools work\n\n* `memory_search` semantically searches Markdown chunks (~400 token target, 80-token overlap) from `MEMORY.md` + `memory\/**\/*.md`. It returns snippet text (capped ~700 chars), file path, line range, score, provider\/model, and whether we fell back from local to remote embeddings. No full file payload is returned.\n* `memory_get` reads a specific memory Markdown file (workspace-relative), optionally from a starting line and for N lines. Paths outside `MEMORY.md` \/ `memory\/` are rejected.\n* Both tools are enabled only when `memorySearch.enabled` resolves true for the agent.\n\n## What gets indexed (and when)\n\n* File type: Markdown only (`MEMORY.md`, `memory\/**\/*.md`).\n* Index storage: per-agent SQLite at `~\/.openclaw\/memory\/<agentId>.sqlite` (configurable via `agents.defaults.memorySearch.store.path`, supports `{agentId}` token).\n* Freshness: watcher on `MEMORY.md` + `memory\/` marks the index dirty (debounce 1.5s). Sync is scheduled on session start, on search, or on an interval and runs asynchronously. Session transcripts use delta thresholds to trigger background sync.\n* Reindex triggers: the index stores the embedding **provider\/model + endpoint fingerprint + chunking params**. If any of those change, OpenClaw automatically resets and reindexes the entire store.\n\n## Hybrid search (BM25 + vector)\n\nWhen enabled, OpenClaw combines:\n\n* **Vector similarity** (semantic match, wording can differ)\n* **BM25 keyword relevance** (exact tokens like IDs, env vars, code symbols)\n\nIf full-text search is unavailable on your platform, OpenClaw falls back to vector-only search.\n\n### Why hybrid\n\nVector search is great at "this means the same thing":\n\n* "Mac Studio gateway host" vs "the machine running the gateway"\n* "debounce file updates" vs "avoid indexing on every write"\n\nBut it can be weak at exact, high-signal tokens:\n\n* IDs (`a828e60`, `b3b9895a...`)\n* code symbols (`memorySearch.query.hybrid`)\n* error strings ("sqlite-vec unavailable")\n\nBM25 (full-text) is the opposite: strong at exact tokens, weaker at paraphrases.\nHybrid search is the pragmatic middle ground: **use both retrieval signals** so you get\ngood results for both "natural language" queries and "needle in a haystack" queries.\n\n### How we merge results (the current design)\n\nImplementation sketch:\n\n1. Retrieve a candidate pool from both sides:\n\n* **Vector**: top `maxResults * candidateMultiplier` by cosine similarity.\n* **BM25**: top `maxResults * candidateMultiplier` by FTS5 BM25 rank (lower is better).\n\n2. Convert BM25 rank into a 0..1-ish score:\n\n* `textScore = 1 \/ (1 + max(0, bm25Rank))`\n\n3. Union candidates by chunk id and compute a weighted score:\n\n* `finalScore = vectorWeight * vectorScore + textWeight * textScore`\n\nNotes:\n\n* `vectorWeight` + `textWeight` is normalized to 1.0 in config resolution, so weights behave as percentages.\n* If embeddings are unavailable (or the provider returns a zero-vector), we still run BM25 and return keyword matches.\n* If FTS5 can't be created, we keep vector-only search (no hard failure).\n\nThis isn't "IR-theory perfect", but it's simple, fast, and tends to improve recall\/precision on real notes.\nIf we want to get fancier later, common next steps are Reciprocal Rank Fusion (RRF) or score normalization\n(min\/max or z-score) before mixing.\n\n### Post-processing pipeline\n\nAfter merging vector and keyword scores, two optional post-processing stages\nrefine the result list before it reaches the agent:\n\n<\/code><\/pre>\n\nBoth stages are **off by default** and can be enabled independently.\n\n### MMR re-ranking (diversity)\n\nWhen hybrid search returns results, multiple chunks may contain similar or overlapping content.\nFor example, searching for "home network setup" might return five nearly identical snippets\nfrom different daily notes that all mention the same router configuration.\n\n**MMR (Maximal Marginal Relevance)** re-ranks the results to balance relevance with diversity,\nensuring the top results cover different aspects of the query instead of repeating the same information.\n\nHow it works:\n\n1. Results are scored by their original relevance (vector + BM25 weighted score).\n2. MMR iteratively selects results that maximize: `lambda x relevance - (1-lambda) x max_similarity_to_selected`.\n3. Similarity between results is measured using Jaccard text similarity on tokenized content.\n\nThe `lambda` parameter controls the trade-off:\n\n* `lambda = 1.0` -- pure relevance (no diversity penalty)\n* `lambda = 0.0` -- maximum diversity (ignores relevance)\n* Default: `0.7` (balanced, slight relevance bias)\n\n**Example -- query: "home network setup"**\n\nGiven these memory files:\n\n<\/code><\/pre>\n
\nmemory\/2026-02-08.md -> “Configured Omada router, moved IoT to VLAN 10”
\nmemory\/2026-02-05.md -> “Set up AdGuard DNS on 192.168.10.2”
\nmemory\/network.md -> “Router: Omada ER605, AdGuard: 192.168.10.2, VLAN 10: IoT”<\/p>\n\nWithout MMR -- top 3 results:\n\n<\/code><\/pre>\n\n
\nWith MMR (lambda=0.7) -- top 3 results:\n\n<\/code><\/pre>\n\n
\nThe near-duplicate from Feb 8 drops out, and the agent gets three distinct pieces of information.\n\n**When to enable:** If you notice `memory_search` returning redundant or near-duplicate snippets,\nespecially with daily notes that often repeat similar information across days.\n\n### Temporal decay (recency boost)\n\nAgents with daily notes accumulate hundreds of dated files over time. Without decay,\na well-worded note from six months ago can outrank yesterday's update on the same topic.\n\n**Temporal decay** applies an exponential multiplier to scores based on the age of each result,\nso recent memories naturally rank higher while old ones fade:\n\n<\/code><\/pre>\n\nwhere `lambda = ln(2) \/ halfLifeDays`.\n\nWith the default half-life of 30 days:\n\n* Today's notes: **100%** of original score\n* 7 days ago: **~84%**\n* 30 days ago: **50%**\n* 90 days ago: **12.5%**\n* 180 days ago: **~1.6%**\n\n**Evergreen files are never decayed:**\n\n* `MEMORY.md` (root memory file)\n* Non-dated files in `memory\/` (e.g., `memory\/projects.md`, `memory\/network.md`)\n* These contain durable reference information that should always rank normally.\n\n**Dated daily files** (`memory\/YYYY-MM-DD.md`) use the date extracted from the filename.\nOther sources (e.g., session transcripts) fall back to file modification time (`mtime`).\n\n**Example -- query: "what's Rod's work schedule?"**\n\nGiven these memory files (today is Feb 10):\n\n<\/code><\/pre>\n
\nmemory\/2026-02-10.md -> “Rod has standup at 14:15, 1:1 with Zeb at 14:45” (today)
\nmemory\/2026-02-03.md -> “Rod started new team, standup moved to 14:15” (7 days old)<\/p>\n\nWithout decay:\n\n<\/code><\/pre>\n\n
\nWith decay (halfLife=30):\n\n<\/code><\/pre>\n