OpenClaw Memory QMD: Catch Silent Fallback

The safe answer is: do not treat a successful OpenClaw memory search as proof that QMD is healthy . First prove that the gateway can resolve the QMD binary and that QMD—not the builtin fallback—served the search. Then apply the readiness checks required by the configured search mode, confirm the index is fresh, and retrieve a synthetic canary. That distinction matters because OpenClaw deliberately falls back to its builtin memory engine if QMD fails. The fallback preserves useful memory behavior, but it changes the fact being tested. A result can be valid as “OpenClaw found a memory” while being invalid as “the configured QMD backend is ready.” The operating rule in this guide is: QMD is healthy only when executable availability, effective backend, update freshness, mode specific readiness, and canary retrieval agree. This is narrower than proving that an agent remembered the right thing in every situation. It is a backend health receipt: evidence that the intended retrieval path is available and current enough for the next memory dependent step. A green query can hide the wrong backend OpenClaw's QMD documentation describes QMD as a local first sidecar that combines BM25, vector search, and reranking. OpenClaw creates managed collections, runs updates, and—when semantic modes require them—maintains embeddings. It also documents automatic fallback to the builtin SQLite engine when QMD cannot open. Fallback is a sensible availability feature. It is not QMD evidence. Consider two runs that both retrieve the same synthetic sentence: Observation Run A Run B Configured backend qmd qmd Query returns the canary yes yes Effective backend qmd builtin QMD verdict healthy candidate fallback active The returned text cannot distinguish those runs. Backend identity must have higher precedence than retrieval success. Start in the environment that actually launches the gateway. An interactive shell can have a different PATH from a service: The first command should resolve an executable. The second records a version. The third asks OpenClaw to probe memory status rather than trusting a cached chat turn failure. If qmd version works only in your login shell, the official troubleshooting guidance recommends pinning an absolute memory.qmd.command and rechecking from the gateway environment. Do not log the entire service environment to prove this. A useful receipt needs only: The version above is an example from the current research snapshot, not a minimum requirement. The latest QMD GitHub release observed for this article was v2.5.3, published May 29, 2026. OpenClaw maintains compatibility paths for older QMD collection and MCP shapes, so “not latest” is not automatically “unhealthy.” Record the version because compatibility, diagnostics, and output fields change. On the publication runner used for this article, OpenClaw 2026.7.1 2 was installed and its configured builtin memory store reported ready, while qmd version returned command not found . That was not a QMD outage test—the runner was not configured as a QMD deployment. It was a useful boundary observation: a healthy OpenClaw memory command and QMD availability are separate facts. Readiness depends on searchMode QMD has three relevant search modes in the current OpenClaw contract: search is lexical BM25. vsearch uses vector evidence. query uses the hybrid/model backed path and can include reranking. The memory configuration reference is explicit that search is BM25 only. OpenClaw skips semantic vector readiness probes and embedding maintenance in that mode. Therefore, a blanket rule such as “pending embeddings means memory is unhealthy” is wrong. Use this mode aware gate: Search mode Fresh collection required Zero pending embeddings required Canary required search yes no yes vsearch yes yes yes query yes yes yes This is not an argument for lexical search over semantic search. It prevents a health checker from imposing a dependency that the selected mode does not use. OpenClaw's documented default QMD update interval is five minutes, while the embedding interval defaults to sixty minutes. Those values describe scheduling, not a universal health threshold. Build a freshness lease from your configuration and operational tolerance: For example, a five minute interval, a ninety second worst normal update, and a thirty second margin gives a seven minute lease. An update age of 421 seconds is stale under that policy; 419 seconds is still within the lease. Do not silently stretch the lease after an alert. If updates regularly exceed it, either fix the workload or revise the policy with recorded evidence. Otherwise a stale index becomes permanently green. The first semantic query can be unusually slow because QMD may download roughly 2 GB of GGUF models for query expansion and reranking. That makes “waiting for the documented first run dependency” different from “stuck forever.” Put a bounded installation or warm up window around the first probe, then require progress evidence or stop. Build a canary that proves the managed path A canary should be synthetic, unique, and safe to retain. It should not contain a customer fact, prompt, API key, email address, or real task decision. Create a Markdown file under a collection that OpenClaw actually manages—for the default workspace collection, that means MEMORY.md or the memory/ tree. Use a token such as: Record its relative source path and content hash, allow the configured update cycle to complete, then search for the exact token through OpenClaw: The receipt should establish: 1. the source file belongs to the intended managed collection; 2. the last successful update is within the freshness lease; 3. semantic vectors are ready if the mode needs them; 4. the effective backend is QMD; 5. the exact canary is returned from the expected source. An empty result does not immediately prove QMD is broken. The official contract names several narrower explanations: hidden paths are ignored, lowercase root memory.md is not the same as MEMORY.md , group/channel scope is denied by default, and extra path patterns can exclude a file. Preserve those distinctions so the repair stays bounded. Avoid invoking qmd update manually with arbitrary XDG directories. OpenClaw gives each agent a self contained managed QMD home. A direct command in the wrong environment can test a different index and produce a convincing but irrelevant green result. Likewise, do not use one successful canary to claim broad recall quality. The canary proves that a known document crossed the current ingestion and retrieval path. A representative recall benchmark, decision continuity test, and downstream outcome verification remain separate. Replay the verdict before wiring an alert The artifact created for this article accepts a normalized JSON receipt and returns one state. Its precedence is intentional: 1. config drift 2. qmd unavailable 3. fallback active 4. stale index 5. vector not ready 6. retrieval failed 7. healthy Here is the core decision: The six case replay produced six expected verdicts: Case Important evidence Verdict BM25 with 27 pending embeddings mode is search , canary found healthy QMD binary missing command unresolved qmd unavailable Canary found through builtin effective backend is builtin fallback active Collection age 721s, lease 420s update stale stale index Query mode with 14 pending embeddings vectors incomplete vector not ready Fresh vector mode, no canary retrieval absent retrieval failed This replay adds two useful controls. First, builtin fallback cannot borrow a green result from the retrieval layer. Second, BM25 search does not inherit a false dependency on vector maintenance. Each non healthy state gets one next action: QMD unavailable: resolve the binary from the gateway environment and probe again. Fallback active: inspect the QMD open failure; do not disable fallback just to make the checker red. Stale index: wait for or run the managed update path, then verify a new success time. Vectors not ready: finish embedding for the active model and check fingerprint consistency with current QMD diagnostics. Retrieval failed: inspect collection scope, file pattern, update evidence, and exact token before rebuilding anything. Rebuilding every index is not the default repair. It increases cost and destroys evidence that could distinguish a path error from a freshness error. Expire the receipt and keep the conclusion narrow A healthy receipt is time bounded. Store the check time, configured mode, QMD version, effective backend, last successful update, pending vector count where applicable, canary source hash, and verdict. Expire it when the freshness lease ends or any of those inputs changes. The receipt proves: the intended QMD executable was reachable; OpenClaw was using QMD at check time; the managed index was fresh enough; the selected mode's dependencies were ready; one safe known item was retrievable. It does not prove that every memory is relevant, that every decision survived compaction, that private data is correctly classified, or that an agent produced the intended deliverable. Those need separate evidence. Sidewisp's product direction is to make health boundaries like these visible across agent runtimes: identify what is working, expose the evidence, distinguish waiting from failure, and preserve human authority over repairs. Sidewisp is currently in private preview. The production OpenClaw adapter and monitoring engine are not generally shipped, so this guide is an operating pattern you can implement today—not a claim that Sidewisp already performs these QMD checks. If a memory dependent task matters, require the receipt before the task starts and verify the task's actual outcome afterward. That closes both false green gaps: “memory worked” without QMD, and “QMD worked” without the job being done.