Your Memory Deserves a Search Engine

In the last two chapters, you fixed memory and learned how to use it. Your agent now saves things before compaction, prunes context intelligently, and uses hybrid search to find what it saved. That's solid — and for most people, it's enough.

But if you're the kind of person who takes notes obsessively, runs multiple agents, and generates daily reports from workflows... your memory folder is going to get big. Dozens of daily logs. Security reports from Argus every 6 hours. Weekly summaries. Project notes. Decision records.

OpenClaw's built-in hybrid search is good. QMD is better.

QMD (Query Memory Documents) is an open-source search engine built specifically for this use case — searching through collections of Markdown files. It was created by Tobi (CEO of Shopify), who ran into the same problem you're about to hit: too many notes, not enough search.

What QMD Actually Does

QMD combines three search techniques that each catch what the others miss:

BM25 (keyword search) — Classic text matching. You search for "Argus baseline hash" and it finds files containing those exact words. Fast, precise, no surprises. This is what catches error codes, configuration values, and specific names that semantic search would gloss over.

Vector embeddings (semantic search) — Understands the meaning of your query, not just the words. You ask "what security problems did I have last week?" and it finds a report titled "Permission audit flagged world-readable config" — even though none of your search words appear in the result.

Reranking — Takes the combined results from BM25 and vector search, then re-sorts them so the most relevant results float to the top. Without reranking, you'd get a pile of "somewhat relevant" results. With it, the best answer is usually first.

All of this runs locally on your machine. No cloud APIs. No data leaving your system. Your memory stays private.

Install QMD

Open your Telegram chat with OpenClaw (or the Gateway) and paste this:

Install QMD (Query Memory Documents) for better memory search.

Here's what to do:

1. Check if Bun is installed (run: bun --version)
   - If not installed, install it: curl -fsSL https://bun.sh/install | bash

2. Check if SQLite is installed (run: sqlite3 --version)
   - If not installed, tell me and I'll help

3. Install QMD globally: bun install -g qmd

4. Verify it works: qmd --version

5. Update my ~/.openclaw/openclaw.json — add this setting,
   preserving everything else:

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

6. Restart the gateway

7. Confirm everything is working and show me the QMD version
   and updated config section.

Your agent will handle the prerequisites, install QMD, update the config, and restart the gateway. One prompt, fully set up.

Using QMD

Once installed, you can search your memory two ways: through your agent (automatic) or through the terminal (manual). Most of the time, you'll just ask your agent and it searches via QMD behind the scenes. But the terminal commands are useful for exploring and debugging.

Through Your Agent (Recommended)

Just ask questions the way you normally would:

What security issues did Argus find this week?

What decisions did we make about the budget?

Show me everything related to memory configuration.

With QMD as the backend, your agent's searches are faster and smarter. It combines keyword matching and semantic understanding automatically (thanks to the hybrid config from Chapter 7). You don't have to do anything differently — the search is just better.

Through the Terminal

QMD has four commands you'll use directly:

Text search — find files containing specific words:

qmd search "security agent"

Returns files that mention "security agent" with relevant snippets highlighted. This is BM25 keyword matching — finds exactly what you typed.

Semantic search — find files by meaning:

qmd query "what did I build yesterday"

Understands your intent. Finds yesterday's daily log even if it says "set up a monitoring workflow" rather than "built something."

Get a specific file:

qmd get memory/2026-02-19.md

List everything indexed:

qmd ls memory

Search vs. Query: When to Use Which

| | qmd search | qmd query | |---|---|---| | Method | BM25 keyword matching | Vector semantic matching | | Finds | Exact words you typed | Conceptually related content | | Speed | Fastest | Fast (after initial model download) | | Best for | Error codes, names, specific strings | Concepts, questions, fuzzy recall | | Misses | Synonyms, related concepts | Exact values, codes, unique identifiers |

Rule of thumb: Start with query for most questions. Fall back to search when you need to find a specific string.

When your agent searches automatically, it combines both approaches — you don't have to choose.

QMD in Action: A Real Example

Here's how QMD fits into everything you've built so far:

Tuesday 2 AM: Argus runs its heartbeat and finds a world-readable config file. It writes a report to memory/2026-02-18.md flagging the issue.

Tuesday 2:01 AM: QMD automatically indexes the new file.

Tuesday 8 AM: Your morning briefing workflow wakes up. It asks your agent for a summary of overnight reports. The agent searches memory via QMD, finds Argus's report, and includes it in your briefing.

Tuesday 8:05 AM: You read the briefing on your phone and message your agent:

What security issues did Argus find?

QMD's vector search matches the query to the permission audit report (even though "issues" doesn't appear in the report). The reranker puts the most relevant result first. Your agent gives you the answer with a source citation.

You didn't dig through files. You didn't remember paths. You didn't even have to be awake when the problem was found.

When You Don't Need QMD

Be honest about whether you need this right now:

• Fewer than 20 memory files? Built-in hybrid search is fine. QMD is overkill.
• Only one agent running? The built-in search handles single-agent memory well.
• Not generating automated reports? If you're only writing manual daily logs, you can find things by scrolling.

QMD shines when you have dozens or hundreds of files across multiple agents and workflows — when the answer is definitely in there somewhere, but where?

Come back to this chapter when your memory folder starts feeling too big to browse manually. You'll know.

Best Practices

Let QMD index automatically. Once configured as the backend, QMD watches your memory directory and indexes new files as they appear. No manual re-indexing needed.

Use clear headings in your memory files. QMD indexes heading structure. A file with ## Decisions, ## Learned, ## What's Next sections is easier to search than one long paragraph.

Keep the hybrid search config from Chapter 7. QMD and your hybrid settings work together. QMD handles execution. The hybrid config controls weighting, MMR, and temporal decay. Keep both.

Check the index if searches miss known files. If QMD can't find a file you know exists, ask your agent:

Run qmd ls memory and check if my recent files are indexed. If anything is missing, re-index with qmd index memory/.

Credits

Tobi (CEO of Shopify) created QMD and open-sourced it for the community. The tool was born from his own experience running OpenClaw with extensive memory — the same pain point this chapter addresses. Thanks to him for building it and making it freely available.

What's Next

You now have the complete memory stack:

• Chapters 7-8 fixed the three failure modes and taught you daily memory habits
• Chapter 9 added QMD for supercharged local search across your entire memory

Your agent saves reliably, searches intelligently, and retrieves accurately. That's your second brain, working.

But things will break. Cron jobs will fail silently. Memory files might get corrupted. Your gateway will crash at 3 AM and you won't know why. In Chapter 10, we'll cover troubleshooting — how to read logs, diagnose common problems, reset things when they go sideways, and know the difference between "something is actually broken" and "I just need to restart the gateway."

Now that your lobster is running on autopilot, you need to know how to pop the hood.