Qmd Setup

Skill: qmd-setup

Name: qmd-setup Description: Install and configure QMD semantic search memory for the knowledge base.

Overview

QMD adds semantic search to the memory system. Instead of relying solely on file paths and keyword matching, agents can query the knowledge base with natural language and get ranked results by meaning.

When to Use

1. Growing knowledge base — When the KB has grown beyond what agents can navigate by file path alone. If agents are frequently missing relevant information because they didn't know which file to check, QMD helps.

2. Cross-brand queries — When agents need to find information across multiple brands or domains without knowing exactly where it lives. QMD searches everything at once.

3. New team member onboarding — When adding new agents or reconfiguring the team. QMD helps new agents discover existing knowledge without being briefed on every file.

Setup Flow

Step 1: Check Current State

First, check whether QMD is already installed and what the current memory configuration looks like.

# Check if qmd is installed
which qmd

# Check current memory config
cat ~/.openclaw/openclaw.json | python3 -m json.tool | grep -A 10 '"memory"'

If QMD is already installed and configured: You're done. Verify it's working (skip to Step 4). If QMD is installed but not configured: Skip to Step 3. If QMD is not installed: Continue to Step 2.

Step 2: Install QMD

Recommended: Install with bun (faster):

bun install -g @tobilu/qmd

Alternative: Install with npm:

npm install -g @tobilu/qmd

Verify installation:

which qmd
qmd --version

If you see a path and version number, installation succeeded. If you get ERR_DLOPEN_FAILED, see the Troubleshooting section below.

Step 3: Configure

Option A: Automatic configuration (recommended):

node scripts/patch-config.js --force-qmd

This patches openclaw.json to set:

• memory.backend to "qmd"
• memory.qmd.paths to the default shared KB directories
• memory.qmd.update.interval to "5m"

Option B: Manual configuration:

Edit ~/.openclaw/openclaw.json and add or update the memory section:

{
  "memory": {
    "backend": "qmd",
    "qmd": {
      "includeDefaultMemory": true,
      "paths": [
        { "path": "memory", "name": "daily-notes", "pattern": "**/*.md" },
        { "path": "skills", "name": "agent-skills", "pattern": "**/*.md" },
        { "path": "shared", "name": "shared-knowledge", "pattern": "**/*.md" }
      ],
      "update": { "interval": "5m" }
    }
  }
}

Configuration fields:

Step 4: Restart and Verify

# Restart the gateway to pick up the new config
openclaw gateway restart

# Check the logs for QMD initialization
openclaw gateway logs | grep -i qmd

Expected log output:

[INFO] Memory backend: qmd
[INFO] QMD indexing 4 paths...
[INFO] QMD indexed 42 documents in 1.3s
[INFO] QMD ready — next reindex in 300s

Test a semantic query:

# If your system supports it:
openclaw memory search "skincare brand ingredients"

If results come back with relevant documents, QMD is working correctly.

Troubleshooting

better-sqlite3 Node Version Mismatch

QMD depends on better-sqlite3, which is a native Node.js addon. If the Node.js version used to install QMD differs from the Node.js version running the gateway, you will get:

Error: ERR_DLOPEN_FAILED
Module was compiled against a different Node.js version

Fix:

1. Identify which Node.js the gateway uses:

   which node
   node --version
   

2. Rebuild better-sqlite3 with that Node.js:

   # For bun global installs:
   cd ~/.bun/install/global/node_modules/better-sqlite3
   npm rebuild better-sqlite3
   
   # For npm global installs:
   cd $(npm root -g)/better-sqlite3
   npm rebuild better-sqlite3
   

3. Verify the fix:

   node -e "require('better-sqlite3')"
   # No output = success
   

4. Restart the gateway:

   openclaw gateway restart
   

Other Common Issues

Uninstall

To remove QMD and revert to file-based memory:

1. Update configuration: Edit ~/.openclaw/openclaw.json and change:

   {
     "memory": {
       "backend": "file"
     }
   }
   

   You can leave the qmd section in place — it will be ignored when the backend is "file".

2. Restart the gateway:

   openclaw gateway restart
   

3. (Optional) Remove QMD package:

   # If installed with bun:
   bun remove -g @tobilu/qmd
   
   # If installed with npm:
   npm uninstall -g @tobilu/qmd
   

4. (Optional) Remove the SQLite database:

   rm ~/.openclaw/memory/main.sqlite
   

After uninstalling, agents will use file-based memory (MEMORY.md + direct file reads). This works fine for small-to-medium knowledge bases and requires no additional dependencies.