QMD skill for OpenClaw: local memory search that actually finds the right note

The QMD skill is for the moment when your OpenClaw agent technically has the information, but keeps failing to pull back the right piece of it at the right time.

That usually starts slowly. The default memory setup works fine when your agent only needs MEMORY.md, a few daily logs, and a small workspace. Then the workload expands: more notes, more docs, longer transcripts, more old project context, more things that matter but do not belong in the prompt every turn. Retrieval quality starts to matter more than raw model quality.

That is where QMD becomes useful.

In OpenClaw, QMD is a local-first search sidecar that adds BM25, vector search, reranking, and query expansion to agent memory. The practical result is simple: your agent can search more material, rank it better, and still stay local.

If you are new to the product, start with what OpenClaw is and how OpenClaw works. If you already understand the runtime and just want the search upgrade, the QMD path is one of the cleanest ways to improve recall without turning your agent into a cloud-memory science project.

What the QMD skill actually adds

The default OpenClaw memory engine is intentionally simple. That is a strength. It keeps the system understandable, local, and easy to run.

But simple memory breaks down in predictable ways:

  • exact keyword matches miss semantically related notes
  • semantically similar notes surface, but the best one is buried
  • older transcripts exist, but they are not easy to retrieve when you need them
  • useful project docs live outside the standard memory files
  • the agent remembers too much vaguely and not enough precisely

QMD changes the retrieval layer rather than the writing layer.

According to the OpenClaw QMD memory engine docs, QMD adds:

  • BM25 lexical search for exact-match recall
  • vector search for semantic similarity
  • reranking and query expansion for better final ordering
  • indexing of extra directories beyond the standard memory tree
  • optional indexing of session transcripts
  • automatic fallback to builtin memory when QMD is unavailable

That last point matters more than it sounds. QMD is an upgrade path, not an all-or-nothing bet. If the sidecar breaks, OpenClaw falls back instead of leaving the agent blind.

When builtin memory is enough — and when it is not

You probably do not need QMD on day one.

Builtin memory is enough when:

  • the agent works mostly from current-session context
  • durable memory is short and curated
  • the workspace is small
  • recall mistakes are rare and cheap
  • you do not need transcript search or extra note collections

QMD starts earning its keep when:

  • the agent needs to search across a larger pile of notes, docs, and transcripts
  • you want local recall without shipping data to a hosted memory product
  • the agent keeps finding related notes instead of the right note
  • you want one search layer over memory files plus extra project directories
  • you need better recall quality for long-running operator workflows

A good rule is this: if your current complaint is “the model forgot,” better prompting may help. If your complaint is “the note exists but retrieval keeps missing it,” that is a search problem, and QMD is a search answer.

Why QMD fits OpenClaw especially well

QMD is not just a generic local search tool. It fits the OpenClaw operating model unusually well.

First, it stays local. The QMD docs describe it as a local-first sidecar, and the upstream QMD repository positions it as a local search engine for docs, knowledge bases, meeting notes, and anything else you need to remember. That matches the OpenClaw bias toward self-hosted control.

Second, it keeps the memory model legible. You are not replacing your memory files with a black-box SaaS. OpenClaw still owns the memory workflow; QMD improves how those files are indexed and searched.

Third, it expands scope in a practical way. OpenClaw can point QMD at additional directories and, if enabled, session transcripts. That is useful for operators who want the agent to search notes, documentation, and prior conversations together instead of juggling separate systems.

The live Qmd skill page also makes the workflow concrete: index local files, update the collection, run lexical search, run vector search, or use the hybrid query path. In other words, this is not a vague “better memory” promise. It is a very specific retrieval toolchain.

The best use cases for the QMD skill

QMD is strongest in workflows where memory quality directly changes agent output quality.

Good examples:

  1. Long-running research workflows where the agent needs to reuse prior notes, source snippets, or transcripts. If you liked the pattern in our NotebookLM CLI workflow post, QMD is a natural complement.
  2. Project documentation recall where useful information lives outside MEMORY.md and the daily memory tree.
  3. Session-history retrieval when you want the agent to recall earlier conversations without manually pasting them back in.
  4. Operator playbooks and runbooks where exact commands matter, but semantic retrieval still helps when the query wording changes.
  5. Private knowledge bases where local search matters for privacy, speed, or cost reasons.

Weak use cases:

  • tiny setups with very little durable context
  • workflows where the bottleneck is action safety rather than recall
  • teams that will not maintain local dependencies like QMD and its model requirements

QMD is powerful, but it is still infrastructure. If you do not need better retrieval yet, do not add moving parts just because the architecture sounds elegant.

How to think about setup without overcomplicating it

The official docs cover the exact config, so this article should not pretend to replace them. The important operational idea is simpler than the installation details.

You are enabling a search engine beside OpenClaw, not inside every prompt.

At a high level, the flow is:

  1. Install QMD so the binary is available to OpenClaw.
  2. Set memory backend to qmd.
  3. Let OpenClaw manage the QMD home, collections, and update cycle.
  4. Optionally point QMD at extra paths or session transcripts.
  5. Keep builtin fallback available in case the sidecar is missing or unhealthy.

The QMD memory engine docs are especially useful here because they document not just the happy path, but the real operational knobs: update intervals, search modes, transcript indexing, group-chat scope, timeout tuning, and the explicit command override when PATH issues cause spawn qmd ENOENT failures.

That last failure mode is common enough to plan for. If your shell can run qmd but the OpenClaw service cannot, the problem is usually environment mismatch, not the memory system itself.

QMD improves recall, not judgment

A better search backend does not remove the need for guardrails.

If the agent can retrieve more material, it can also retrieve sensitive or stale material more effectively. That means QMD should sit inside the same operational boundaries you already want for OpenClaw: scoped tools, deliberate memory hygiene, clear human review for risky actions, and regular cleanup of what deserves to stay durable.

Our OpenClaw guardrails guide covers the broader security posture, and it matters here too. Better memory search is only an advantage if the surrounding workflow is still bounded.

The right mental model is not “QMD makes the agent smarter.” It is “QMD makes the agent’s search less sloppy.”

FAQ

What is the QMD skill in OpenClaw?

The QMD skill adds a local search and indexing workflow for OpenClaw agents. It combines BM25, vector search, and reranking so agents can retrieve memory, notes, docs, and optionally transcripts more accurately.

When should I switch OpenClaw memory to QMD?

Switch when builtin memory is no longer finding the right context reliably enough, especially if you need transcript recall, extra indexed directories, or stronger hybrid search over a larger local knowledge base.

Is QMD fully local?

Yes, that is the intended model. OpenClaw’s QMD docs describe it as a local-first sidecar, and the upstream project is built around local indexing and search.

Does QMD replace OpenClaw memory files?

No. It improves how memory and other indexed files are searched. Your existing files and memory workflow stay in place.

What if QMD fails?

OpenClaw can fall back to the builtin memory engine. That makes QMD safer to adopt than a memory system that becomes a hard dependency for every run.

The bottom line

The QMD skill is worth adding when your agent has crossed from “a helpful assistant with a few notes” into “an operating system with too much context to search badly.”

If your durable knowledge base is growing, your transcripts matter, and recall quality is starting to shape the usefulness of the agent, QMD is one of the cleanest upgrades you can make. It stays local, it fits the OpenClaw model, and it improves retrieval in the place where many agent workflows quietly fail.

That is the real reason to care about it. Not because hybrid search sounds impressive, but because the right note, found at the right time, is often the difference between an agent that feels reliable and one that feels lucky.

Sources: OpenClaw QMD memory engine docs, OpenClaw memory overview, Qmd skill page on OpenClaw, QMD GitHub repository