Memory Qmd

Bun is not as ubiquitous as Node.js. If the user does not have Bun installed, setup.sh will fail with exit code 2 and provide installation instructions.

Configuration

Configuration is stored in config.json alongside this file. Key settings:

• index_path: Location of the SQLite index (~/.cache/qmd/index.sqlite)
• search.default_mode: Default search mode (query for hybrid)
• search.modes: Available search modes with their minimum score thresholds
• relevance: Normalization formula for raw BM25 scores

Per-project collections are configured via the qmd CLI, not through config.json.

Usage

Store

QMD indexes existing files on disk — "storing" means adding files to a collection via glob patterns, then generating vector embeddings.

Step 1 — Create a collection:

qmd collection add <name> --pattern "**/*.md" --path /project/path

Step 2 — Generate embeddings:

qmd embed <name>

Step 3 — (Optional) Add context descriptions:

qmd context add -c <name> "This collection contains API documentation for the auth module"

Updating after file changes:

qmd update <name>

Collections can use any glob pattern: **/*.swift, src/**/*.ts, docs/**/*.md, etc.

Retrieve

Retrieve a specific indexed document by its QMD URI:

qmd get qmd://<collection>/path/to/file

Retrieve multiple documents in one call:

qmd multi_get qmd://<collection>/file1,qmd://<collection>/file2

Use multi_get when you need 3 or more files — never call get repeatedly.

Search

QMD provides three search modes. Mode selection is critical for result quality.

Mode Selection Guide

Quick rule: Know the exact word? Use search. Describing behavior? Use vsearch. Not sure? Use query.

Search Examples

# BM25 keyword — find a specific function
qmd search "handleAuthCallback" -c myproject --minScore 0.1

# Vector semantic — find code related to a concept
qmd vsearch "how does the payment flow handle retries" -c myproject --minScore 0.3

# Hybrid — broad exploration
qmd query "error handling middleware" -c myproject --minScore 0.3

Result Handling

• < 2 results above minScore: Broaden the search — try query mode, drop collection filter, or rephrase
• 2-5 results: Ideal. Use qmd get to read the top hits
• > 5 results: Consider narrowing with a more specific query or higher minScore

Always specify -c collection when the project has per-layer collections.

Interface Contract

Input

• store(key, content, metadata?) — Maps to qmd collection add + qmd embed
• retrieve(query, options?) — Maps to qmd get qmd://<collection>/path
• search(pattern, scope?) — Maps to qmd search|vsearch|query "pattern" -c scope

Output Format

All backends return the same JSON structure:

{
  "query_echo": "original query string",
  "results": [
    {
      "content": "matched file content or excerpt",
      "relevance": 0.82,
      "source": "qmd",
      "timestamp": "2026-03-10T14:30:00Z"
    }
  ],
  "result_count": 2,
  "status": "success",
  "error_message": null,
  "error_code": null,
  "backend_duration_ms": 230,
  "normalized_relevance": 0.82,
  "backend": "qmd"
}

Failure Codes

Relevance Normalization

BM25 raw scores are inherently low (typically 0.1-0.3 for good results) due to camelCase tokenization in code. This is normal, not a sign of poor results.

Normalization formula: normalized = min(raw * 3, 1.0)

Vector search (vsearch) scores are already in 0.0-1.0 range and do not need normalization.

Router Integration

• Normalized relevance >= 0.4 -> "good enough", no fallback needed
• Normalized relevance < 0.4 or status = empty -> trigger fallback to next backend
• status = error -> immediate fallback, log error

Limitations

• Bun dependency: Bun is not as widely installed as Node.js. Users must install it separately, which adds friction.
• BM25 struggles with semantic queries: Keyword search cannot understand meaning — "authentication flow" will not match "login process" unless both terms appear in the text.
• Vector embedding startup cost: First-time qmd embed on a large collection can take minutes. Subsequent updates are incremental.
• Index staleness: After file changes, the index must be updated with qmd update. If the user forgets, search results may be outdated or incomplete.
• camelCase tokenization: BM25 scores are naturally low because camelCase identifiers are split into tokens. A minScore of 0.1 is appropriate for search mode — do not set it higher or you will miss valid results.
• No real-time indexing: Unlike some backends, QMD does not watch for file changes. Reindexing is manual or hook-driven.

Tier

Starter — included in the $49 OpenClaw Memory Stack package. Requires Bun runtime (free, open source) and no paid API keys. The only barrier to entry is installing Bun.