sbusso/claudeclaw/add-qmd

Add QMD Memory Backend

QMD (https://github.com/tobi/qmd) is a local search engine for markdown files. It combines BM25 keyword search, vector semantic search, and LLM re-ranking — all running on-device via node-llama-cpp with GGUF models.

This skill upgrades ClaudeClaw's built-in grep-based memory_search MCP tool with QMD's hybrid search, giving agents much better recall across large memory collections.

Prerequisites

• ClaudeClaw with memory tools already working (memory_search, memory_save, memory_get)
• ~2GB disk space for GGUF embedding + reranking models (downloaded on first run)
• Node.js 20+

What This Skill Does

1. Installs QMD as an MCP server dependency
2. Configures QMD to index all group memory directories (groups/*/memory/, groups/*/CLAUDE.md, groups/*/conversations/)
3. Replaces the grep-based memory_search in agent/runner/src/ipc-mcp-stdio.ts with QMD's API
4. Adds QMD indexing to the agent startup flow (incremental re-index on each run)

Implementation Notes

QMD MCP Server

QMD exposes its search as an MCP server. Add to the agent runner's mcpServers config:

qmd: {
  command: 'npx',
  args: ['qmd', 'mcp', '--collection', collectionPath],
  env: {},
}

Indexing

QMD indexes markdown files into a local SQLite database. The collection should be configured per-group:

# Index a group's memory
qmd index --collection groups/{folder}/.qmd groups/{folder}/memory/ groups/{folder}/CLAUDE.md groups/{folder}/conversations/

Search Integration

Replace the grep-based memory_search tool body with a call to QMD's MCP:

// Before (grep-based):
const results = grepFiles(args.query, allFiles);
// After (QMD):
// Use the qmd MCP server's search tool
// Returns semantically ranked results with relevance scores

Fallback

If QMD is not installed or indexing fails, fall back to the built-in grep-based search. This ensures memory tools always work even without QMD.

Not Implemented Yet

This skill is a specification for future implementation. The built-in grep-based memory tools work without QMD. Run this skill when you want to upgrade to semantic search.