### QMD Setup Commands

Source: https://github.com/ehc-io/qmd/blob/main/skills/qmd/SKILL.md

Provides the necessary commands to install the qmd CLI and add a collection for searching.

```bash
npm install -g @tobilu/qmd
```

```bash
qmd collection add ~/notes --name notes
```

```bash
qmd embed
```

--------------------------------

### Install QMD CLI and Collections

Source: https://github.com/ehc-io/qmd/blob/main/skills/qmd/references/mcp-setup.md

Install the QMD command-line interface globally and add a markdown collection for knowledge processing.

```bash
npm install -g @tobilu/qmd
qmd collection add ~/path/to/markdown --name myknowledge
qmd embed
```

--------------------------------

### QMD Collection Management Examples

Source: https://github.com/ehc-io/qmd/blob/main/CLAUDE.md

Examples demonstrating how to manage collections, including listing, creating, removing, renaming, and listing files within a collection.

```sh
# List all collections
qmd collection list
```

```sh
# Create a collection with explicit name
qmd collection add ~/Documents/notes --name mynotes --mask '**/*.md'
```

```sh
# Remove a collection
qmd collection remove mynotes
```

```sh
# Rename a collection
qmd collection rename mynotes my-notes
```

```sh
# List all files in a collection
qmd ls mynotes
```

```sh
# List files with a path prefix
qmd ls journals/2025
qmd ls qmd://journals/2025
```

--------------------------------

### Install QMD CLI

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Install the QMD CLI globally using npm or Bun. Ensure Node.js or Bun meets the system requirements.

```sh
npm install -g @tobilu/qmd
```

```sh
bun install -g @tobilu/qmd
```

--------------------------------

### Install QMD Globally

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Install QMD globally using npm or Bun. Alternatively, use npx or bunx to run it directly without global installation.

```sh
# Install globally (Node or Bun)
npm install -g @tobilu/qmd
# or
bun install -g @tobilu/qmd

# Or run directly
npx @tobilu/qmd ...
bunx @tobilu/qmd ...
```

--------------------------------

### QMD Search Examples

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Examples demonstrating how to use QMD search commands with specific options for result filtering and output formatting.

```sh
# Get 10 results with minimum score 0.3
qmd query -n 10 --min-score 0.3 "API design patterns"
```

```sh
# Output as markdown for LLM context
qmd search --md --full "error handling"
```

```sh
# JSON output for scripting
qmd query --json "quarterly reports"
```

--------------------------------

### Start MCP server with `qmd mcp`

Source: https://context7.com/ehc-io/qmd/llms.txt

Starts the Model Context Protocol server for IDE integrations or programmatic access. Supports stdio and HTTP transports.

```bash
# Start stdio MCP server (for Claude Desktop / Claude Code)
qmd mcp
```

```bash
# Start HTTP MCP server on port 8181
qmd mcp --http --port 8181
```

```bash
# Run HTTP server as a background daemon
qmd mcp --http --daemon --port 8181
```

```bash
# Stop the daemon
qmd mcp stop
```

--------------------------------

### Install SQLite for Extensions

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Install SQLite using Homebrew on macOS, which is required for QMD extension support.

```sh
brew install sqlite
```

--------------------------------

### CLI Usage

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Examples of how to use the QMD query functionality from the command-line interface (CLI).

```APIDOC
## CLI

```bash
# Single line (implicit expand)
qmd query "how does auth work"

# Multi-line with types
qmd query $'lex: auth token\nvec: how does authentication work'

# Structured
qmd query $'lex: keywords\nvec: question\nhyde: hypothetical answer...'
```
```

--------------------------------

### QMD Context Management Examples

Source: https://github.com/ehc-io/qmd/blob/main/CLAUDE.md

Demonstrates how to add, list, check, and remove context for directories and collections, including global context and virtual paths.

```sh
# Add context to current directory (auto-detects collection)
qmd context add "Description of these files"
```

```sh
# Add context to a specific path
qmd context add /subfolder "Description for subfolder"
```

```sh
# Add global context to all collections (system message)
qmd context add / "Always include this context"
```

```sh
# Add context using virtual paths
qmd context add qmd://journals/ "Context for entire journals collection"
qmd context add qmd://journals/2024 "Journal entries from 2024"
```

```sh
# List all contexts
qmd context list
```

```sh
# Check for collections or paths without context
qmd context check
```

```sh
# Remove context
qmd context rm qmd://journals/2024
qmd context rm /  # Remove global context
```

--------------------------------

### QMD Development Commands

Source: https://github.com/ehc-io/qmd/blob/main/CLAUDE.md

Commands for running QMD from source and installing it globally.

```sh
bun src/qmd.ts <command>   # Run from source
```

```sh
bun link               # Install globally as 'qmd'
```

--------------------------------

### Develop QMD CLI

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Clone the QMD repository, install dependencies, and link the CLI for local development.

```sh
git clone https://github.com/tobi/qmd
cd qmd
npm install
npm link
```

--------------------------------

### createStore() and hybridQuery()

Source: https://context7.com/ehc-io/qmd/llms.txt

Demonstrates how to create a QMD store and perform a hybrid search with automatic LLM query expansion. Includes examples of using hooks for real-time feedback during the search process.

```APIDOC
## createStore() and hybridQuery()

### Description
Initializes a QMD store with a specified database path and performs a hybrid search. The `hybridQuery` function automatically expands the user's query using an LLM and then performs a search across different retrieval methods (lexical, vector, etc.). It also supports optional hooks to monitor the search process.

### Usage
```typescript
import { createStore, hybridQuery } from "./store.js";

const store = createStore("/path/to/index.sqlite");

// Hybrid search with automatic LLM query expansion
const results = await hybridQuery(store, "how does authentication work", {
  collection: "wiki",
  limit: 5,
  minScore: 0.2,
  hooks: {
    onStrongSignal: (score) => console.error(`Strong BM25 signal: ${score}`),
    onExpand: (orig, expanded, ms) => console.error(`Expanded in ${ms}ms`),
    onRerankDone: (ms) => console.error(`Reranked in ${ms}ms`),
  },
});

for (const r of results) {
  console.log(`${r.docid} ${(r.score * 100).toFixed(0)}% ${r.displayPath}`);
  console.log(r.bestChunk.slice(0, 200));
}

store.close();
```

### Parameters for `createStore()`
- **dbPath** (string) - Required - The file path for the QMD SQLite database.
```

--------------------------------

### Claude Code Plugin Installation

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Install the QMD plugin for Claude Code from the marketplace or manually add it using the provided commands.

```bash
claude marketplace add tobi/qmd
claude plugin add qmd@qmd
```

--------------------------------

### Lex Query Examples

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Demonstrates various ways to construct lex queries using keywords, exact phrases, and exclusions.

```plaintext
lex: CAP theorem consistency
lex: "machine learning" -"deep learning"
lex: auth -oauth -saml
```

--------------------------------

### QMD CLI Query Examples

Source: https://github.com/ehc-io/qmd/blob/main/skills/qmd/SKILL.md

Illustrates various ways to use the qmd CLI for searching markdown content. Supports auto-expansion, structured queries, and explicit expansion.

```bash
qmd query "question"              # Auto-expand + rerank
```

```bash
qmd query $'lex: X\nvec: Y'       # Structured
```

```bash
qmd query $'expand: question'     # Explicit expand
```

```bash
qmd search "keywords"             # BM25 only (no LLM)
```

```bash
qmd get "#abc123"                 # By docid
```

```bash
qmd multi-get "journals/2026-*.md" -l 40  # Batch pull snippets by glob
```

```bash
qmd multi-get notes/foo.md,notes/bar.md   # Comma-separated list, preserves order
```

--------------------------------

### Install Git Hooks Manually

Source: https://github.com/ehc-io/qmd/blob/main/skills/release/SKILL.md

Installs the project's git hooks, including the pre-push hook, which enforces release and CI checks.

```bash
skills/release/scripts/install-hooks.sh
```

--------------------------------

### Explicit Expand Query Example

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Demonstrates the explicit `expand:` prefix for queries that should be processed by the local query expansion model.

```plaintext
expand: error handling best practices
# equivalent
error handling best practices
```

--------------------------------

### Example Release Entry in CHANGELOG.md

Source: https://github.com/ehc-io/qmd/blob/main/skills/release/SKILL.md

Illustrates the structure for a released version entry in the CHANGELOG.md file, including optional highlights and detailed changes/fixes.

```markdown
## [1.1.0] - 2026-03-01

QMD now runs on both Node.js and Bun, with up to 2.7x faster reranking
through parallel contexts. GPU auto-detection replaces the unreliable
`gpu: "auto"` with explicit CUDA/Metal/Vulkan probing.
```

```markdown
### Changes

- Runtime: support Node.js (>=22) alongside Bun. The `qmd` wrapper
  auto-detects a suitable install via PATH. #149 (thanks @igrigorik)
- Performance: parallel embedding & reranking — up to 2.7x faster on
  multi-core machines.

### Fixes

- Prevent VRAM waste from duplicate context creation during concurrent
  `embedBatch` calls. #152 (thanks @jkrems)
```

--------------------------------

### CLI Multi-Line Query

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Example of executing a multi-line QMD query with specified types (lex, vec) using the CLI.

```bash
qmd query $'lex: auth token\nvec: how does authentication work'
```

--------------------------------

### QMD Query Syntax Examples

Source: https://context7.com/ehc-io/qmd/llms.txt

Demonstrates single-line plain queries for LLM expansion and multi-line typed queries using prefixes like `lex`, `vec`, and `hyde`. Shows basic lex query syntax including phrase matching and exclusion.

```plaintext
# Single plain line — passed to local LLM for expansion into lex/vec/hyde variants
how does authentication work
expand: how does authentication work   # explicit equivalent

# Multi-line typed query document
lex: "connection pool" timeout -redis
vec: why do database connections time out under load
hyde: Connection pool exhaustion happens when all connections are busy...

# Lex query syntax
lex: word              # prefix match — "perf" matches "performance"
lex: "exact phrase"    # must appear verbatim
lex: -exclude          # exclude documents containing this term
lex: "rate limiter" -"test data" -mock   # combine all three
```

--------------------------------

### Start QMD MCP Server with HTTP Transport

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Start the QMD MCP server using the HTTP transport. It can run in the foreground or as a background daemon, and the port can be customized.

```sh
# Foreground (Ctrl-C to stop)
qmd mcp --http                    # localhost:8181
qmd mcp --http --port 8080        # custom port

# Background daemon
qmd mcp --http --daemon           # start, writes PID to ~/.cache/qmd/mcp.pid
qmd mcp stop                      # stop via PID file
qmd status                        # shows "MCP: running (PID ...)" when active
```

--------------------------------

### CLI Structured Multi-Line Query

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Example of executing a structured multi-line QMD query (lex, vec, hyde) using the CLI.

```bash
qmd query $'lex: keywords\nvec: question\nhyde: hypothetical answer...'
```

--------------------------------

### CLI Single Line Query

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Example of executing a single-line QMD query using the CLI, which is treated as an implicit expand query.

```bash
qmd query "how does auth work"
```

--------------------------------

### Vec Query Examples

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Illustrates natural language questions for semantic similarity search using vec queries.

```plaintext
vec: how does the rate limiter handle burst traffic
vec: what is the tradeoff between consistency and availability
```

--------------------------------

### Retrieve Document by Path or DocID with `get` Tool

Source: https://context7.com/ehc-io/qmd/llms.txt

Use the `get` tool to fetch full document content by its `#docid` or file path. Supports line range slicing and optional line numbers. Ensure the `file` argument is correctly formatted.

```json
{
  "tool": "get",
  "arguments": {
    "file": "#a3f2c1",
    "lineNumbers": true
  }
}
```

```json
{
  "tool": "get",
  "arguments": {
    "file": "wiki/db/connection-pooling.md:20",
    "maxLines": 40,
    "lineNumbers": true
  }
}
```

```json
{
  "content": [{
    "type": "resource",
    "resource": {
      "uri": "qmd://wiki/db/connection-pooling.md",
      "name": "wiki/db/connection-pooling.md",
      "title": "Connection Pool Configuration",
      "mimeType": "text/markdown",
      "text": "<!-- Context: Database architecture documentation -->\n\n20: ## Pool Sizing\n21: \n22: Set `pool.max` to..."
    }
  }]
}
```

--------------------------------

### MCP/HTTP API Usage

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Examples of how to use the QMD query functionality via an MCP/HTTP API, showing both string and structured formats.

```APIDOC
## MCP/HTTP API

The `query` tool accepts a query document:

```json
{
  "q": "lex: CAP theorem\nvec: consistency vs availability",
  "collections": ["docs"],
  "limit": 10
}
```

Or structured format:

```json
{
  "searches": [
    { "type": "lex", "query": "CAP theorem" },
    { "type": "vec", "query": "consistency vs availability" }
  ]
}
```
```

--------------------------------

### Collection Filtering Examples

Source: https://github.com/ehc-io/qmd/blob/main/skills/qmd/SKILL.md

Demonstrates how to filter search results by specifying one or multiple collections. Omit to search all collections.

```json
{ "collections": ["docs"] }
```

```json
{ "collections": ["docs", "notes"] }
```

--------------------------------

### Run QMD MCP Server in HTTP Mode

Source: https://github.com/ehc-io/qmd/blob/main/skills/qmd/references/mcp-setup.md

Start the QMD MCP server in HTTP mode, optionally as a background daemon, and learn how to stop it.

```bash
qmd mcp --http              # Port 8181
qmd mcp --http --daemon     # Background
qmd mcp stop                # Stop daemon
```

--------------------------------

### MCP/HTTP API Query (String)

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Example of sending a QMD query as a single string in the 'q' field of an HTTP API request.

```json
{
  "q": "lex: CAP theorem\nvec: consistency vs availability",
  "collections": ["docs"],
  "limit": 10
}
```

--------------------------------

### MCP/HTTP API Query (Structured)

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Example of sending a QMD query using a structured format with a 'searches' array in an HTTP API request.

```json
{
  "searches": [
    { "type": "lex", "query": "CAP theorem" },
    { "type": "vec", "query": "consistency vs availability" }
  ]
}
```

--------------------------------

### SFT Training Commands

Source: https://github.com/ehc-io/qmd/blob/main/finetune/README.md

Execute the supervised fine-tuning (SFT) process using the `train.py` script. A `--dry-run` option is available to preview the configuration without starting the training.

```bash
uv run train.py sft --config configs/sft.yaml
uv run train.py sft --config configs/sft.yaml --dry-run  # preview config
```

--------------------------------

### Agentic Workflows with QMD Output Formats

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Utilize QMD's --json and --files output formats for agentic workflows. Get structured results for LLMs, list relevant files, or retrieve full document content.

```sh
# Get structured results for an LLM
qmd search "authentication" --json -n 10

# List all relevant files above a threshold
qmd query "error handling" --all --files --min-score 0.4

# Retrieve full document content
qmd get "docs/api-reference.md" --full
```

--------------------------------

### Multi-Line Query Example

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Combines multiple query types (lex, vec, hyde) in a single query document for enhanced search results.

```plaintext
lex: rate limiter algorithm
vec: how does rate limiting work in the API
hyde: The API implements rate limiting using a token bucket algorithm...
```

--------------------------------

### Get document by filepath

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Retrieves a document using its file path. Supports fuzzy matching to suggest similar file names if an exact match is not found.

```sh
qmd get notes/meeting.md
```

--------------------------------

### Retrieve a single document with `qmd get`

Source: https://context7.com/ehc-io/qmd/llms.txt

Fetches document content by virtual path, filesystem path, or docid. Supports line range slicing and displaying line numbers.

```bash
# By virtual path
qmd get qmd://notes/2025/meeting-notes.md
```

```bash
# By short docid from search results
qmd get "#a3f2c1"
```

```bash
# Start at line 50, show 30 lines
qmd get qmd://wiki/api/rate-limiting.md:50 -l 30
```

```bash
# With line numbers (useful for LLM context)
qmd get qmd://notes/todo.md --line-numbers
```

--------------------------------

### Get document with line range

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Retrieves a specific portion of a document by specifying a starting line number and a maximum number of lines. Useful for extracting specific sections.

```sh
qmd get notes/meeting.md:50 -l 100
```

--------------------------------

### Hyde Query Example

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Shows an example of a hyde query, which is a hypothetical answer passage used for embedding.

```plaintext
hyde: The rate limiter uses a sliding window algorithm with a 60-second window. When a client exceeds 100 requests per minute, subsequent requests return 429 Too Many Requests.
```

--------------------------------

### List configured contexts with `qmd context list`

Source: https://context7.com/ehc-io/qmd/llms.txt

Displays all configured contexts, showing the hierarchy of collections and their associated descriptions.

```bash
# List all configured contexts
qmd context list
```

--------------------------------

### Cloud Training via HuggingFace Jobs

Source: https://github.com/ehc-io/qmd/blob/main/finetune/README.md

Execute supervised fine-tuning (SFT), evaluation, and GGUF conversion using HuggingFace Jobs. Ensure you have HF_TOKEN set as a secret. SFT takes approximately 45 minutes on an A10G GPU.

```bash
# 1. SFT: teach the model the output format (~45 min on A10G, ~$1.50)
hf jobs uv run --flavor a10g-large --secrets HF_TOKEN --timeout 2h jobs/sft.py

# 2. Evaluate against test queries (needs local GPU or use eval job)
uv run eval.py tobil/qmd-query-expansion-1.7B

# 3. Convert to GGUF for local deployment (Ollama, llama.cpp)
uv run convert_gguf.py --size 1.7B

# NOTE: GRPO is currently experimental and moved to finetune/experiments/grpo
# if you want to run it manually, use:
#   cd finetune && uv run python experiments/grpo/grpo.py
```

--------------------------------

### Local Training with GPU

Source: https://github.com/ehc-io/qmd/blob/main/finetune/README.md

Initiate supervised fine-tuning (SFT) or an experimental GRPO run locally if you have a GPU available. The SFT process uses a configuration file for hyperparameters.

```bash
uv run train.py sft  --config configs/sft.yaml

# Experimental GRPO
cd finetune && uv run python experiments/grpo/grpo.py
```

--------------------------------

### Convert Model to GGUF (Preset)

Source: https://github.com/ehc-io/qmd/blob/main/finetune/README.md

Use the conversion script with a preset size to merge base and SFT adapters, then quantize to GGUF format. This is suitable for standard model sizes.

```bash
uv run convert_gguf.py --size 1.7B
```

--------------------------------

### SFT Training (Local)

Source: https://github.com/ehc-io/qmd/blob/main/finetune/CLAUDE.md

Command to initiate Supervised Fine-Tuning (SFT) locally, requiring CUDA. Uses a specified configuration file.

```bash
uv run train.py sft --config configs/sft.yaml
```

--------------------------------

### Programmatic QMD Store and Hybrid Search

Source: https://context7.com/ehc-io/qmd/llms.txt

Use `createStore` to initialize a QMD index and `hybridQuery` for LLM-expanded searches. Configure search parameters like collection, limit, and minimum score. Optional hooks can monitor search progress.

```typescript
import { createStore, hybridQuery, structuredSearch } from "./store.js";

const store = createStore("/path/to/index.sqlite");

// Hybrid search with automatic LLM query expansion
const results = await hybridQuery(store, "how does authentication work", {
  collection: "wiki",
  limit: 5,
  minScore: 0.2,
  hooks: {
    onStrongSignal: (score) => console.error(`Strong BM25 signal: ${score}`),
    onExpand: (orig, expanded, ms) => console.error(`Expanded in ${ms}ms`),
    onRerankDone: (ms) => console.error(`Reranked in ${ms}ms`),
  },
});

for (const r of results) {
  console.log(`${r.docid} ${(r.score * 100).toFixed(0)}% ${r.displayPath}`);
  console.log(r.bestChunk.slice(0, 200));
}

// Structured search — skip internal LLM expansion, provide your own sub-queries
const structured = await structuredSearch(store, [
  { type: "lex", query: '"OAuth2" token refresh' },
  { type: "vec", query: "how to refresh an OAuth2 access token" },
  { type: "hyde", query: "When the access token expires, call /oauth/token with grant_type=refresh_token and the stored refresh_token value. The server returns a new access_token." },
], {
  collections: ["wiki", "notes"],
  limit: 10,
});

store.close();
```

--------------------------------

### Prepare Data for Training

Source: https://github.com/ehc-io/qmd/blob/main/finetune/README.md

Format JSONL data for the Qwen3 chat template, deduplicate entries, and split into training and validation sets. This script prepares the dataset for model training.

```bash
uv run dataset/prepare_data.py
```

--------------------------------

### get tool

Source: https://context7.com/ehc-io/qmd/llms.txt

Retrieves the full content of a document by its path or docid. Supports line range slicing and optional line numbers.

```APIDOC
## get tool

### Description
Fetches the full content of a document. Supports `#docid` references from search results, line range slicing via `:linenum` suffix, and optional line numbers.

### Arguments
- **file** (string) - Required - The path to the file or a `#docid`. Can include a line number suffix (e.g., `file.md:20`).
- **maxLines** (integer) - Optional - The maximum number of lines to retrieve, starting from the specified line number.
- **lineNumbers** (boolean) - Optional - Whether to include line numbers in the response.

### Request Example (by docid)
```json
{
  "tool": "get",
  "arguments": {
    "file": "#a3f2c1",
    "lineNumbers": true
  }
}
```

### Request Example (with line offset)
```json
{
  "tool": "get",
  "arguments": {
    "file": "wiki/db/connection-pooling.md:20",
    "maxLines": 40,
    "lineNumbers": true
  }
}
```

### Response Example
```json
{
  "content": [
    {
      "type": "resource",
      "resource": {
        "uri": "qmd://wiki/db/connection-pooling.md",
        "name": "wiki/db/connection-pooling.md",
        "title": "Connection Pool Configuration",
        "mimeType": "text/markdown",
        "text": "<!-- Context: Database architecture documentation -->\n\n20: ## Pool Sizing\n21: \n22: Set `pool.max` to..."
      }
    }
  ]
}
```
```

--------------------------------

### SFT Training (HuggingFace Jobs)

Source: https://github.com/ehc-io/qmd/blob/main/finetune/CLAUDE.md

Command to run SFT training on HuggingFace Jobs, specifying the instance type, required secrets, and timeout.

```bash
hf jobs uv run --flavor a10g-large --secrets HF_TOKEN --timeout 2h jobs/sft.py
```

--------------------------------

### Create Ollama Model from GGUF

Source: https://github.com/ehc-io/qmd/blob/main/finetune/README.md

Create a new Ollama model using a Modelfile that points to the downloaded GGUF file. Then, run the model with Ollama.

```bash
echo 'FROM ./qmd-query-expansion-1.7B-q4_k_m.gguf' > Modelfile
ollama create qmd-expand -f Modelfile
ollama run qmd-expand
```

--------------------------------

### Run GRPO Training with Unified Entrypoint

Source: https://github.com/ehc-io/qmd/blob/main/finetune/experiments/grpo/README.md

Use the unified entrypoint to run GRPO training with a specified configuration file. This method is deprecated in the main pipeline.

```bash
uv run train.py grpo --config finetune/experiments/grpo/grpo.yaml
```

--------------------------------

### Collections Configuration (`index.yml`)

Source: https://context7.com/ehc-io/qmd/llms.txt

Define collections, their paths, patterns, and contexts in the `~/.config/qmd/index.yml` file. Global context can be set, and individual collections can have specific context mappings.

```yaml
# ~/.config/qmd/index.yml

# Global context injected for all collections
global_context: "If you see [[WikiWord]] links, search for that term for more context."

collections:
  notes:
    path: ~/Documents/Notes
    pattern: "**/*.md"
    update: "git pull --ff-only"   # optional: run before qmd update
    context:
      "/": "Personal notes vault"
      "/journal/2024": "Daily notes from 2024"
      "/journal/2025": "Daily notes from 2025"
      "/meetings": "Team meeting notes and summaries"

  wiki:
    path: ~/Documents/Wiki
    pattern: "**/*.md"
    includeByDefault: true          # include in default queries (true = default)
    context:
      "/": "Internal technical wiki"
      "/api": "REST API documentation"
      "/architecture": "System design and architecture decisions"

  archive:
    path: ~/Documents/Archive
    pattern: "**/*.md"
    includeByDefault: false         # excluded from default queries; search with -c archive

```

--------------------------------

### Get multiple documents by glob pattern

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Retrieves multiple documents that match a specified glob pattern. This is efficient for fetching sets of related files.

```sh
qmd multi-get "journals/2025-05*.md"
```

--------------------------------

### Get multiple documents by comma-separated list

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Retrieves multiple documents specified in a comma-separated list. This method supports both file paths and document IDs (docids).

```sh
qmd multi-get "doc1.md, doc2.md, #abc123"
```

--------------------------------

### Attach context descriptions with `qmd context add`

Source: https://context7.com/ehc-io/qmd/llms.txt

Attaches human-written descriptions to collections or paths, stored in `~/.config/qmd/index.yml`. These contexts aid LLMs in understanding folder contents.

```bash
# Set root context for a whole collection
qmd context add qmd://notes/ "Personal markdown notes vault — daily journals, meetings, and ideas"
```

```bash
# Set context for a subfolder via virtual path
qmd context add qmd://notes/journal/2024 "Daily notes from 2024"
```

```bash
# Set context for the current working directory
qmd context add "API documentation for the payments service"
```

```bash
# Set global context applied to all collections
qmd context add / "If you see [[WikiWord]] links, search for that term for more context"
```

--------------------------------

### Get document by docid

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Retrieves a document using its unique document ID (docid), typically obtained from search results. This provides direct access to specific documents.

```sh
qmd get "#abc123"
```

--------------------------------

### Prepare Data Script

Source: https://github.com/ehc-io/qmd/blob/main/finetune/CLAUDE.md

Command to run the data preparation script, which generates ephemeral train/val JSONL files.

```bash
uv run dataset/prepare_data.py
# Creates: data/train/train.jsonl, data/train/val.jsonl (ephemeral)
```

--------------------------------

### Download GGUF Model for Ollama

Source: https://github.com/ehc-io/qmd/blob/main/finetune/README.md

Download a pre-quantized GGUF model file from Hugging Face. This prepares the model for use with Ollama.

```bash
huggingface-cli download tobil/qmd-query-expansion-1.7B-gguf \
    qmd-query-expansion-1.7B-q4_k_m.gguf --local-dir .
```

--------------------------------

### Convert Model to GGUF (Custom)

Source: https://github.com/ehc-io/qmd/blob/main/finetune/README.md

Convert models to GGUF format using custom base, SFT, and GRPO adapters. Specify the output path for the GGUF file.

```bash
uv run convert_gguf.py --base Qwen/Qwen3-1.7B \
                       --sft tobil/qmd-query-expansion-1.7B-sft \
                       --grpo tobil/qmd-query-expansion-1.7B-grpo \
                       --output tobil/qmd-query-expansion-1.7B-gguf
```

--------------------------------

### Claude Desktop MCP Server Configuration

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Configure Claude Desktop to use QMD as an MCP server by specifying the command and arguments in the `claude_desktop_config.json` file.

```json
{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}
```

--------------------------------

### Qwen3 Chat Prompt Format with /no_think

Source: https://github.com/ehc-io/qmd/blob/main/finetune/README.md

This prompt format is used for all tools, utilizing the Qwen3 chat template with the `/no_think` directive to suppress chain-of-thought reasoning and ensure direct output.

```text
<|im_start|>user
/no_think Expand this search query: {query}<|im_end|>
<|im_start|>assistant

```

--------------------------------

### QMD Core Commands

Source: https://github.com/ehc-io/qmd/blob/main/CLAUDE.md

These are the primary commands for interacting with QMD, covering collection management, context, document retrieval, and search.

```sh
qmd collection add . --name <n>   # Create/index collection
```

```sh
qmd collection list               # List all collections with details
```

```sh
qmd collection remove <name>      # Remove a collection by name
```

```sh
qmd collection rename <old> <new> # Rename a collection
```

```sh
qmd ls [collection[/path]]        # List collections or files in a collection
```

```sh
qmd context add [path] "text"     # Add context for path (defaults to current dir)
```

```sh
qmd context list                  # List all contexts
```

```sh
qmd context check                 # Check for collections/paths missing context
```

```sh
qmd context rm <path>             # Remove context
```

```sh
qmd get <file>                    # Get document by path or docid (#abc123)
```

```sh
qmd multi-get <pattern>           # Get multiple docs by glob or comma-separated list
```

```sh
qmd status                        # Show index status and collections
```

```sh
qmd update [--pull]               # Re-index all collections (--pull: git pull first)
```

```sh
qmd embed                         # Generate vector embeddings (uses node-llama-cpp)
```

```sh
qmd query <query>                 # Search with query expansion + reranking (recommended)
```

```sh
qmd search <query>                # Full-text keyword search (BM25, no LLM)
```

```sh
qmd vsearch <query>               # Vector similarity search (no reranking)
```

```sh
qmd mcp                           # Start MCP server (stdio transport)
```

```sh
qmd mcp --http [--port N]         # Start MCP server (HTTP, default port 8181)
```

```sh
qmd mcp --http --daemon           # Start as background daemon
```

```sh
qmd mcp stop                      # Stop background MCP daemon
```

--------------------------------

### Configure MCP Server for OpenClaw

Source: https://github.com/ehc-io/qmd/blob/main/skills/qmd/references/mcp-setup.md

Configure the MCP server settings for the QMD tool within OpenClaw's configuration file.

```json
{
  "mcp": {
    "servers": {
      "qmd": { "command": "qmd", "args": ["mcp"] }
    }
  }
}
```

--------------------------------

### Indexing Flow Diagram

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Visual representation of the QMD indexing process, illustrating how collections, glob patterns, markdown files, and content hashing are processed to generate document IDs and store data in SQLite.

```text
Collection ──► Glob Pattern ──► Markdown Files ──► Parse Title ──► Hash Content
    │                                                   │              │
    │                                                   │              ▼
    │                                                   │         Generate docid
    │                                                   │         (6-char hash)
    │                                                   │              │
    └──────────────────────────────────────────────────►└──► Store in SQLite
                                                                       │
                                                                       ▼
                                                                  FTS5 Index
```

--------------------------------

### Run GRPO Training Script

Source: https://github.com/ehc-io/qmd/blob/main/finetune/experiments/grpo/README.md

Execute the standalone GRPO training script from the repository root. Ensure you are in the correct directory before running.

```bash
cd /home/tobi/qmd
uv run finetune/experiments/grpo/grpo.py
```

--------------------------------

### Batch document retrieval with `qmd multi-get`

Source: https://context7.com/ehc-io/qmd/llms.txt

Retrieves multiple documents using glob patterns or comma-separated lists. Skips files larger than `--max-bytes` (default 10 KB). Supports XML and JSON output formats.

```bash
# All May 2025 journal entries
qmd multi-get "journals/2025-05*.md"
```

```bash
# Specific comma-separated files
qmd multi-get "notes/todo.md,notes/done.md,notes/backlog.md"
```

```bash
# XML output with 50-line limit per file
qmd multi-get "wiki/api/*.md" --xml -l 50
```

```bash
# JSON output
qmd multi-get "journals/2025-05*.md" --json
```

--------------------------------

### HuggingFace Jobs Management

Source: https://github.com/ehc-io/qmd/blob/main/finetune/CLAUDE.md

Provides commands for managing HuggingFace Jobs, including listing, viewing logs, inspecting status, and canceling jobs.

```bash
hf jobs ps                    # List running jobs
```

```bash
hf jobs logs <job-id>         # Stream logs
```

```bash
hf jobs inspect <job-id>      # Check status
```

```bash
hf jobs cancel <job-id>       # Cancel a job
```

--------------------------------

### QMD Search and Retrieval Options

Source: https://github.com/ehc-io/qmd/blob/main/CLAUDE.md

Details various options available for search and retrieval commands, including filtering by collection, number of results, score thresholds, and output formats.

```sh
# Search & retrieval
-c, --collection <name>  # Restrict search to a collection (matches pwd suffix)
-n <num>                 # Number of results
--all                    # Return all matches
--min-score <num>        # Minimum score threshold
--full                   # Show full document content
--line-numbers           # Add line numbers to output
```

```sh
# Multi-get specific
-l <num>                 # Maximum lines per file
--max-bytes <num>        # Skip files larger than this (default 10KB)
```

```sh
# Output formats (search and multi-get)
--json, --csv, --md, --xml, --files
```

--------------------------------

### Manage QMD Collections

Source: https://github.com/ehc-io/qmd/blob/main/README.md

Commands for adding, listing, removing, and renaming document collections. Specify paths and glob masks for custom collection creation.

```sh
# Create a collection from current directory
qmd collection add . --name myproject
```

```sh
# Create a collection with explicit path and custom glob mask
qmd collection add ~/Documents/notes --name notes --mask "**/*.md"
```

```sh
# List all collections
qmd collection list
```

```sh
# Remove a collection
qmd collection remove myproject
```

```sh
# Rename a collection
qmd collection rename myproject my-project
```

```sh
# List files in a collection
qmd ls notes
qmd ls notes/subfolder
```

--------------------------------

### Vec Query Syntax

Source: https://github.com/ehc-io/qmd/blob/main/docs/SYNTAX.md

Instructions for writing Vec queries, which are natural language questions.

```APIDOC
## Vec Query Syntax

Vec queries are natural language questions. No special syntax — just write what you're looking for.

```
vec: how does the rate limiter handle burst traffic
vec: what is the tradeoff between consistency and availability
```
```