home / skills / openclaw / skills / qmd-cli

qmd-cli skill

safe

This skill helps you locate and retrieve markdown documents from local knowledge bases using BM25, vector, and hybrid qmd searches.

npx playbooks add skill openclaw/skills --skill qmd-cli

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

2.7 KB

---
name: qmd
description: Search and retrieve markdown documents from local knowledge bases using qmd. Supports BM25 keyword search, vector semantic search, and hybrid search with LLM re-ranking. Use for querying indexed notes, documentation, meeting transcripts, and any markdown-based knowledge. Requires qmd CLI installed (bun install -g https://github.com/tobi/qmd).
---

# QMD - Local Markdown Search

Search and retrieve documents from locally indexed markdown knowledge bases.

## Installation

```bash
bun install -g https://github.com/tobi/qmd
```

## Setup

```bash
# Add a collection
qmd collection add ~/notes --name notes --mask "**/*.md"

# Generate embeddings (required for vsearch/query)
qmd embed
```

## Usage Rules

**Always use `--json` flag** for structured output when invoking qmd commands.

## Search Commands

### search (BM25 keyword search - fast)

```bash
qmd search "authentication flow" --json
qmd search "error handling" --json -n 10
qmd search "config" --json -c notes
```

### vsearch (vector semantic search)

```bash
qmd vsearch "how does login work" --json
qmd vsearch "authentication best practices" --json -n 20
```

### query (hybrid with LLM re-ranking - best quality)

```bash
qmd query "implementing user auth" --json
qmd query "deployment process" --json --min-score 0.5
```

### Search Options

| Option | Description |
|--------|-------------|
| `-n NUM` | Number of results (default: 5, or 20 with --json) |
| `-c, --collection NAME` | Restrict to specific collection |
| `--min-score NUM` | Minimum score threshold |
| `--full` | Return complete document content in results |
| `--all` | Return all matches |

## Retrieval Commands

### get (single document)

```bash
qmd get docs/guide.md --json
qmd get "#a1b2c3" --json
qmd get notes/meeting.md:50 -l 100 --json
```

### multi-get (multiple documents)

```bash
qmd multi-get "docs/*.md" --json
qmd multi-get "api.md, guide.md, #abc123" --json
qmd multi-get "notes/**/*.md" --json --max-bytes 20480
```

## Maintenance Commands

```bash
qmd update              # Re-index changed files
qmd status              # Check index health
qmd collection list     # List all collections
```

## Search Mode Selection

| Mode | Speed | Quality | Best For |
|------|-------|---------|----------|
| search | Fast | Good | Exact keywords, known terms |
| vsearch | Medium | Better | Conceptual queries, synonyms |
| query | Slow | Best | Complex questions, uncertain terms |

**Performance note:** `vsearch` and `query` have ~1 minute cold start latency for vector initialization. Prefer `search` for interactive use.

## MCP Server

qmd can run as an MCP server for direct integration:

```bash
qmd mcp
```

Exposes tools: `qmd_search`, `qmd_vsearch`, `qmd_query`, `qmd_get`, `qmd_multi_get`, `qmd_status`

Overview

This skill integrates the qmd CLI to search and retrieve markdown documents from local knowledge bases. It supports BM25 keyword search, vector semantic search, and hybrid LLM re-ranking to surface the most relevant notes, docs, and transcripts. Requires qmd installed (bun install -g https://github.com/tobi/qmd) and collections indexed with embeddings for vector queries.

How this skill works

The skill runs qmd commands with the --json flag to produce structured results. Use qmd search for fast BM25 keyword matches, qmd vsearch for semantic vector matching, and qmd query for hybrid searches with LLM re-ranking for highest relevance. Retrieval commands (get, multi-get) fetch full document content or snippets; maintenance commands keep indexes up to date.

When to use it

Searching personal or team markdown notes, docs, and meeting transcripts stored locally.
Looking for conceptual matches or synonyms — prefer vsearch for semantics.
Needing highest-quality, context-aware results — use query with LLM re-ranking.
Quick keyword lookups or interactive workflows — use search for speed.
Batch retrieval of specific files or ranges using get and multi-get.

Best practices

Always pass --json to qmd commands for predictable, structured output.
Index collections and run qmd embed before using vsearch or query.
Use search for interactive, low-latency lookups; reserve vsearch/query for deeper analysis.
Set --min-score and -n to control result quality and volume.
Run qmd update regularly and check qmd status to keep the index healthy.

Example use cases

Find implementation details across developer notes: qmd search "authentication flow" --json
Answer a conceptual question from meeting transcripts with semantic search: qmd vsearch "deployment risks" --json
Produce a focused, high-quality answer by running a hybrid query: qmd query "implementing user auth" --json --min-score 0.5
Retrieve full document text or a specific snippet for citation: qmd get notes/meeting.md:50 -l 100 --json
Aggregate multiple reference files before composing a summary: qmd multi-get "docs/*.md" --json --max-bytes 20480

FAQ

Do I need embeddings for all search modes?

No. BM25 keyword search (qmd search) works without embeddings. vsearch and query require embeddings generated with qmd embed.

How do I limit results to a specific collection?

Use the -c or --collection option, for example: qmd search "term" --json -c notes.