QMD memory engine

​

What it adds over builtin

• Reranking and query expansion for better recall.
• Index extra directories - project docs, team notes, anything on disk.
• Index session transcripts - recall earlier conversations.
• Fully local - runs with the official llama.cpp provider plugin and auto-downloads GGUF models.
• Automatic fallback - if QMD is unavailable, OpenClaw falls back to the builtin engine seamlessly.

​

Getting started

​

Prerequisites

• Install QMD: npm install -g @tobilu/qmd or bun install -g @tobilu/qmd
• SQLite build that allows extensions (brew install sqlite on macOS).
• QMD must be on the gateway’s PATH.
• macOS and Linux work out of the box. Windows is best supported via WSL2.

​

Enable

{
  memory: {
    backend: "qmd",
  },
}

​

How the sidecar works

• OpenClaw creates collections from workspace memory files and configured memory.qmd.paths. The QMD adapter owns update, embedding, debounce, and timeout heuristics; these are not user configuration.
• QMD continues to own its index.sqlite, YAML collection config, and model downloads under the per-agent QMD home; these are external-tool artifacts, not OpenClaw state tables. OpenClaw-owned coordination lives only in SQLite: one shared lease limits embedding work across agents, while one lease in each agent database serializes that agent’s collection, update, and embed writes. Runtime no longer creates QMD file-lock sidecars. openclaw doctor --fix removes retired sidecars only after proving their old process owner is stale. Upgrades are a clean cutover: stop and restart every OpenClaw process that shares the state directory before using the new version. Mixed old/new QMD writers are unsupported; runtime intentionally does not dual-lock the retired sidecars.
• The default workspace collection tracks MEMORY.md plus the memory/ tree. Lowercase memory.md is not indexed as a root memory file.
• QMD’s own scanner ignores hidden paths and common dependency/build directories such as .git, .cache, node_modules, vendor, dist, and build. Gateway startup keeps QMD lazy; the manager initializes when memory is first used.
• Searches use the configured searchMode (default: search; also supports vsearch and query). search is BM25-only, so OpenClaw skips semantic vector readiness probes and embedding maintenance in that mode. If a mode fails, OpenClaw retries with qmd query.
• When searchMode is query, set memory.qmd.rerank to false to use QMD’s hybrid query path without the reranker (requires QMD 2.1 or newer). OpenClaw passes --no-rerank to the direct QMD CLI path and rerank: false to QMD’s MCP query tool.
• With QMD releases that advertise multi-collection filters, OpenClaw groups same-source collections into one QMD search invocation. Older QMD releases keep the compatible per-collection fallback.
• If QMD fails entirely, OpenClaw falls back to the builtin SQLite engine. Repeated chat-turn attempts back off briefly after an open failure so a missing binary or broken sidecar dependency does not create a retry storm; openclaw memory status and one-shot CLI probes still recheck QMD directly.

​

Search performance and compatibility

qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main

qmd --help | grep -i collection

​

Model overrides

export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"
export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"

​

Indexing extra paths

{
  memory: {
    backend: "qmd",
    qmd: {
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

​

Indexing session transcripts

{
  memory: {
    backend: "qmd",
    search: {
      experimental: { sessionMemory: true },
      sources: ["memory", "sessions"],
    },
    qmd: {
      sessions: { enabled: true },
    },
  },
}

​

Search scope

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

​

Citations

​

When to use

• Reranking for higher-quality results.
• To search project docs or notes outside the workspace.
• To recall past session conversations.
• Fully local search with no API keys.

​

Troubleshooting

{
  memory: {
    backend: "qmd",
    qmd: {
      command: "/absolute/path/to/qmd",
    },
  },
}

​

Configuration

​

Related

• Memory overview
• Builtin memory engine
• Honcho memory