### Installation and Initial Setup

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

Instructions for installing the QMD CLI and adding a knowledge collection.

```APIDOC
## Installation and Setup

### Install QMD CLI
```bash
npm install -g @tobilu/qmd
```

### Add Knowledge Collection
```bash
qmd collection add ~/path/to/markdown --name myknowledge
```

### Embed Data
```bash
qmd embed
```
```

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

### QMD Library Quick Start Example

Source: https://github.com/tobi/qmd/blob/main/README.md

Initialize a QMD store with specified database path and collection configurations. Perform a search and log the results with their scores. Close the store when done.

```typescript
import { createStore } from '@tobilu/qmd'

const store = await createStore({
  dbPath: './my-index.sqlite',
  config: {
    collections: {
      docs: { path: '/path/to/docs', pattern: '**/*.md' },
    },
  }
})

const results = await store.search({ query: "authentication flow" })
console.log(results.map(r => `${r.title} (${Math.round(r.score * 100)}%)`))

await store.close()
```

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

### QMD Development Setup

Source: https://github.com/tobi/qmd/blob/main/CLAUDE.md

Instructions for running QMD from source and installing it globally using Bun. This is useful for development and testing.

```sh
bun src/cli/qmd.ts <command>   # Run from source
bun link               # Install globally as 'qmd'
```

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

### Install QMD for Development

Source: https://github.com/tobi/qmd/blob/main/README.md

Clone the QMD repository, install dependencies, and link the package locally for development purposes.

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

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

### Install QMD as a Library

Source: https://github.com/tobi/qmd/blob/main/README.md

Install the QMD library for use in your Node.js or Bun applications using npm.

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

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

### Install and Add Collection

Source: https://github.com/tobi/qmd/blob/main/skills/qmd/SKILL.md

Installs the QMD CLI globally and adds a new collection named 'notes' from a specified directory.

```bash
npm install -g @tobilu/qmd
qmd collection add ~/notes --name notes
```

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

### Install QMD with npm or Bun

Source: https://github.com/tobi/qmd/blob/main/README.md

Install the QMD CLI globally using either npm or Bun package managers.

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

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

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

### Examples of Search and Output Formatting

Source: https://github.com/tobi/qmd/blob/main/README.md

Provides practical examples of using search commands with various options like result count, output format, and explain flag.

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

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

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

# Inspect how each result was scored (RRF + rerank blend)
qmd query --json --explain "quarterly reports"

# Use separate index for different knowledge base
qmd --index work search "quarterly reports"
```

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

### Install QMD Globally

Source: https://github.com/tobi/qmd/blob/main/README.md

Install QMD globally using npm or Bun for command-line access. Alternatively, use npx or bunx to run commands 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 ...
```

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

### Manage Collections

Source: https://github.com/tobi/qmd/blob/main/README.md

Examples for adding, listing, getting default names, removing, and renaming collections in Tobi QMD.

```typescript
// Add a collection
await store.addCollection("myapp", {
  path: "/src/myapp",
  pattern: "**/*.ts",
  ignore: ["node_modules/**", "*.test.ts"],
})
```

```typescript
// List collections with document stats
const collections = await store.listCollections()
// => [{ name, pwd, glob_pattern, doc_count, active_count, last_modified, includeByDefault }]
```

```typescript
// Get names of collections included in queries by default
const defaults = await store.getDefaultCollectionNames()
```

```typescript
// Remove / rename
await store.removeCollection("myapp")
await store.renameCollection("old-name", "new-name")
```

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

### QMD Context Management Examples

Source: https://github.com/tobi/qmd/blob/main/CLAUDE.md

Provides examples for managing context within QMD, including adding context to directories, global context, and using virtual paths for context management.

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

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

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

# 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"

# List all contexts
qmd context list

# Check for collections or paths without context
qmd context check

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

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

### Lex Query Syntax Examples

Source: https://github.com/tobi/qmd/blob/main/docs/SYNTAX.md

Provides examples of lex query syntax, demonstrating prefix matching, exact phrases, and term exclusion.

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

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

### Claude Plugin Installation for QMD

Source: https://github.com/tobi/qmd/blob/main/README.md

Install the QMD plugin for Claude via the marketplace or configure MCP manually in `~/.claude/settings.json` if not using the plugin.

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

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

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

### Install Git Hooks Manually

Source: https://github.com/tobi/qmd/blob/main/skills/release/SKILL.md

Installs Git hooks manually using the provided script. This is an alternative to automatic installation via bun install.

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

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

### Install QMD MCP Server

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

Install the QMD CLI globally and add a markdown collection. The embed command is used to process markdown files for searching.

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

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

### MCP Client Configuration

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

Configuration examples for different clients to connect to the QMD MCP server.

```APIDOC
## Configure MCP Client

### Claude Code (`~/.claude/settings.json`)
```json
{
  "mcpServers": {
    "qmd": { "command": "qmd", "args": ["mcp"] }
  }
}
```

### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "qmd": { "command": "qmd", "args": ["mcp"] }
  }
}
```

### OpenClaw (`~/.openclaw/openclaw.json`)
```json
{
  "mcp": {
    "servers": {
      "qmd": { "command": "qmd", "args": ["mcp"] }
    }
  }
}
```
```

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

### CLI Multi-line Query with Types

Source: https://github.com/tobi/qmd/blob/main/docs/SYNTAX.md

Example of executing a multi-line QMD query with specified types using the CLI.

```bash
# Multi-line with types
qmd query $'lex: auth token
vec: how does authentication work'
```

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

### Release Version Heading Example (Markdown)

Source: https://github.com/tobi/qmd/blob/main/skills/release/SKILL.md

Example of a version heading in a changelog file, indicating the released version and date.

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

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

### Install SQLite for Extension Support (macOS)

Source: https://github.com/tobi/qmd/blob/main/README.md

Install SQLite using Homebrew on macOS to enable extension support required by QMD.

```sh
brew install sqlite
```

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

### Crafting QMD Searches

Source: https://github.com/tobi/qmd/blob/main/skills/qmd/SKILL.md

Examples of crafting QMD searches using title/alias anchors, semantic paraphrasing, and negative space to refine results. Includes examples for exact-ish title lookup, semantic concept lookup, and source lookup.

```bash
# Exact-ish title lookup
qmd search '"arm the rebels" merchants tools big companies' -c concepts
```

```bash
# Semantic concept lookup
qmd query $'intent: Find the customer proximity concept, not generic customer delight.\nlex: support pseudonymous merchant customer interviews\nvec: founder stays close to merchant reality through support and product use'
```

```bash
# Source lookup
qmd search "six-week cadence WhatsApp merchant relationships Shawn Ryan" -c sources -n 10
```

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

### Hyde Query Example

Source: https://github.com/tobi/qmd/blob/main/docs/SYNTAX.md

Demonstrates a hyde query, which uses a hypothetical answer passage to guide search.

```text
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.
```

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

### Changelog Entry Example (Markdown)

Source: https://github.com/tobi/qmd/blob/main/skills/release/SKILL.md

Example of a detailed changelog entry following Keep a Changelog conventions, including highlights, changes, and 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.

### 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)
```

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

### List and Remove Contexts

Source: https://github.com/tobi/qmd/blob/main/README.md

Lists all configured contexts and provides an example for removing a specific context.

```bash
# List all contexts
qmd context list

# Remove context
qmd context rm qmd://notes/old
```

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

### RESTful URL Examples

Source: https://github.com/tobi/qmd/blob/main/test/eval-docs/api-design-principles.md

Illustrates the use of nouns for resources and HTTP methods for actions, contrasting good and bad practices.

```text
GET /users/123
POST /orders
DELETE /products/456
```

```text
GET /getUser?id=123
POST /createOrder
GET /deleteProduct/456
```

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

### CLI Structured Query

Source: https://github.com/tobi/qmd/blob/main/docs/SYNTAX.md

Example of executing a structured QMD query with multiple types using the CLI.

```bash
# Structured
qmd query $'lex: keywords
vec: question
hyde: hypothetical answer...'
```

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

### SFT Training Command with Dry Run

Source: https://github.com/tobi/qmd/blob/main/finetune/README.md

Execute the supervised fine-tuning (SFT) process for the Qwen3-1.7B model using a specified configuration file. 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
```

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

### Vec Query Examples

Source: https://github.com/tobi/qmd/blob/main/docs/SYNTAX.md

Shows examples of vec queries, which use natural language for semantic similarity searches.

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

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

### Start QMD MCP Server in HTTP Mode

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

Start the QMD MCP server in HTTP mode, optionally as a background daemon. Use the 'stop' command to terminate a running daemon.

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

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

### QMD Collection Management Examples

Source: https://github.com/tobi/qmd/blob/main/CLAUDE.md

Demonstrates common operations for managing QMD collections, including listing, adding, removing, renaming, and listing files within a collection.

```sh
# List all collections
qmd collection list

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

# Remove a collection
qmd collection remove mynotes

# Rename a collection
qmd collection rename mynotes my-notes

# List all files in a collection
qmd ls mynotes

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

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

### Unreleased Changelog Heading Example (Markdown)

Source: https://github.com/tobi/qmd/blob/main/skills/release/SKILL.md

Example of the heading for the unreleased section in a changelog file, used to accumulate new entries.

```markdown
## [Unreleased]
```

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

### CLI Single Line Query

Source: https://github.com/tobi/qmd/blob/main/docs/SYNTAX.md

Example of executing a single-line QMD query using the CLI, which defaults to an expand query.

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

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

### Explicit Expand Query Example

Source: https://github.com/tobi/qmd/blob/main/docs/SYNTAX.md

Shows the explicit `expand:` prefix for queries, which is equivalent to the default untyped form and triggers local query expansion.

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

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

### Output Format: TTY Example

Source: https://github.com/tobi/qmd/blob/main/README.md

Illustrates the default colorized CLI output format, including clickable terminal hyperlinks for file paths when stdout is a TTY.

```text
docs/guide.md:42 #a1b2c3
Title: Software Craftsmanship
Context: Work documentation
Score: 93%

This section covers the **craftsmanship** of building
quality software with attention to detail.
See also: engineering principles


notes/meeting.md:15 #d4e5f6
Title: Q4 Planning
Context: Personal notes and ideas
Score: 67%

Discussion about code quality and craftsmanship
in the development process.
```

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

### Intent Line Example

Source: https://github.com/tobi/qmd/blob/main/docs/SYNTAX.md

Demonstrates using an `intent:` line to provide context for disambiguating queries, improving search relevance.

```text
intent: web page load times and Core Web Vitals
lex: performance
vec: how to improve performance
```

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

### HTTP Mode

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

Commands to start, run in daemon mode, and stop the QMD MCP server in HTTP mode.

```APIDOC
## HTTP Mode

### Start HTTP Server (Port 8181)
```bash
qmd mcp --http
```

### Start HTTP Server in Daemon Mode
```bash
qmd mcp --http --daemon
```

### Stop Daemon
```bash
qmd mcp stop
```
```

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

### Multi-Line Query Example

Source: https://github.com/tobi/qmd/blob/main/docs/SYNTAX.md

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

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

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

### Agent-Friendly QMD Output Formats

Source: https://github.com/tobi/qmd/blob/main/README.md

Utilize --json and --files output formats for structured results and file lists, ideal for integrating QMD with AI agents. Retrieve full document content using the --full flag with the 'get' command.

```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
```

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

### QMD Output Format Example

Source: https://github.com/tobi/qmd/blob/main/finetune/CLAUDE.md

Defines the structured output for QMD query expansion, including hypothetical passages (hyde), keywords (lex), and semantic reformulations (vec).

```text
hyde: A hypothetical document passage that would answer the query.
lex: keyword1
lex: keyword2
vec: semantic query reformulation
vec: another semantic variation
```

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

### Get and Multi-get Options

Source: https://github.com/tobi/qmd/blob/main/README.md

Details options for retrieving specific documents or parts of documents, including line number targeting and size limits.

```sh
# Get options
qmd get <file>[:line]  # Get document, optionally starting at line
-l <num>               # Maximum lines to return
--from <num>           # Start from line number

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

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

### Run QMD MCP Server with HTTP Transport

Source: https://github.com/tobi/qmd/blob/main/README.md

Start the QMD MCP server using HTTP transport, optionally specifying a custom port. The server can run in the foreground or as a background daemon.

```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
```

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

### Basic Search and Retrieve Workflow

Source: https://github.com/tobi/qmd/blob/main/skills/qmd/SKILL.md

Demonstrates a typical loop for searching documents and then retrieving their full content. Use `qmd search` for initial candidate discovery and `qmd multi-get` to fetch multiple documents.

```bash
qmd search "merchant reality support interviews" -n 5
# leads: #abc123 concepts/customer-proximity.md; #def432 sources/merchant-call.md
qmd multi-get "#abc123,#def432" --format md
```

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

### Create Tobi QMD Store

Source: https://github.com/tobi/qmd/blob/main/README.md

Demonstrates three modes for creating a store: inline configuration, YAML config file, and reopening a previous DB.

```typescript
import { createStore } from '@tobilu/qmd'

// 1. Inline config — no files needed besides the DB
const store = await createStore({
  dbPath: './index.sqlite',
  config: {
    collections: {
      docs: { path: '/path/to/docs', pattern: '**/*.md' },
      notes: { path: '/path/to/notes' },
    },
  },
})
```

```typescript
// 2. YAML config file — collections defined in a file
const store2 = await createStore({
  dbPath: './index.sqlite',
  configPath: './qmd.yml',
})
```

```typescript
// 3. DB-only — reopen a previously configured store
const store3 = await createStore({ dbPath: './index.sqlite' })
```

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

### createStore

Source: https://github.com/tobi/qmd/blob/main/README.md

Initializes a new QMD store. It can be configured inline, via a YAML file, or by reopening an existing database.

```APIDOC
## createStore

### Description
Initializes a new QMD store. It can be configured inline, via a YAML file, or by reopening an existing database.

### Method
`createStore(options)`

### Parameters
- **options** (object) - Required - Configuration options for the store.
  - **dbPath** (string) - Required - Path to the SQLite database file.
  - **config** (object) - Optional - Inline configuration for collections.
    - **collections** (object) - Required if `config` is provided - Defines collections.
      - **[collectionName]** (object) - Required - Configuration for a specific collection.
        - **path** (string) - Required - Filesystem path for the collection.
        - **pattern** (string) - Optional - Glob pattern for files within the path.
  - **configPath** (string) - Optional - Path to a YAML configuration file for collections.

### Request Example
```typescript
// Inline config
const store = await createStore({
  dbPath: './index.sqlite',
  config: {
    collections: {
      docs: { path: '/path/to/docs', pattern: '**/*.md' },
      notes: { path: '/path/to/notes' },
    },
  },
});

// YAML config file
const store2 = await createStore({
  dbPath: './index.sqlite',
  configPath: './qmd.yml',
});

// DB-only (reopen)
const store3 = await createStore({ dbPath: './index.sqlite' });
```
```

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

### Cloud Training via HuggingFace Jobs

Source: https://github.com/tobi/qmd/blob/main/finetune/README.md

Execute supervised fine-tuning (SFT) for query expansion models using HuggingFace Jobs. This process does not require a local GPU and provides an estimated cost and time. Subsequent steps for evaluation and GGUF conversion are also outlined.

```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
```

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

### Filtering and Pagination with Query Parameters

Source: https://github.com/tobi/qmd/blob/main/test/eval-docs/api-design-principles.md

Shows how to use query parameters for filtering, sorting, and pagination.

```text
GET /products?category=electronics&sort=price&page=2&limit=20
```

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

### get, getDocumentBody, multiGet

Source: https://github.com/tobi/qmd/blob/main/README.md

Retrieves documents from the store, either individually by path or ID, or in batches.

```APIDOC
## get, getDocumentBody, multiGet

### Description
Retrieves documents from the store, either individually by path or ID, or in batches. Allows fetching document content with optional line ranges.

### Methods
- `store.get(identifier)`
- `store.getDocumentBody(path, options)`
- `store.multiGet(identifier, options)`

### Parameters
- **identifier** (string) - Required - The path (e.g., "docs/readme.md") or ID (e.g., "#abc123") of the document to retrieve.
- **path** (string) - Required - The path of the document to retrieve the body for.
- **options** (object) - Optional - Options for retrieval.
  - **fromLine** (number) - Optional - The starting line number for `getDocumentBody`.
  - **maxLines** (number) - Optional - The maximum number of lines to retrieve for `getDocumentBody`.
  - **maxBytes** (number) - Optional - The maximum total size in bytes for documents retrieved by `multiGet`.

### Request Example
```typescript
// Get a document by path or docid
const doc = await store.get("docs/readme.md");
const byId = await store.get("#abc123");

if (!("error" in doc)) {
  console.log(doc.title, doc.displayPath, doc.context);
}

// Get document body with line range
const body = await store.getDocumentBody("docs/readme.md", {
  fromLine: 50,
  maxLines: 100,
});

// Batch retrieve by glob or comma-separated list
const { docs, errors } = await store.multiGet("docs/**/*.md", {
  maxBytes: 20480,
});
```
```

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

### Basic Search Commands

Source: https://github.com/tobi/qmd/blob/main/README.md

Demonstrates how to perform full-text, vector, and hybrid searches.

```sh
# Full-text search (fast, keyword-based)
qmd search "authentication flow"

# Vector search (semantic similarity)
qmd vsearch "how to login"

# Hybrid search with re-ranking (best quality)
qmd query "user authentication"
```

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

### Create a Collection (CLI)

Source: https://github.com/tobi/qmd/blob/main/README.md

Create a new QMD collection from a specified directory. You can provide a custom name and a glob mask for file inclusion.

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

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

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

### SFT Training Script (Local)

Source: https://github.com/tobi/qmd/blob/main/finetune/CLAUDE.md

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

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

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

### Update and Embed Index

Source: https://github.com/tobi/qmd/blob/main/README.md

Code examples for re-indexing collections by scanning the filesystem and generating vector embeddings with progress reporting.

```typescript
// Re-index collections by scanning the filesystem
const result = await store.update({
  collections: ["docs"],  // optional — defaults to all
  onProgress: ({ collection, file, current, total }) => {
    console.log(`[${collection}] ${current}/${total} ${file}`)
  },
})
// => { collections, indexed, updated, unchanged, removed, needsEmbedding }
```

```typescript
// Generate vector embeddings
const embedResult = await store.embed({
  force: false,           // true to re-embed everything
  chunkStrategy: "auto",  // "regex" (default) or "auto" (AST for code files)
  onProgress: ({ current, total, collection }) => {
    console.log(`Embedding ${current}/${total}`)
  },
})
```

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

### Local Training with GPU

Source: https://github.com/tobi/qmd/blob/main/finetune/README.md

Initiate supervised fine-tuning (SFT) for the query expansion model on a local machine with a GPU. Configuration is managed via a YAML file. An experimental GRPO run is also available.

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

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

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

### MCP/HTTP API Structured Searches

Source: https://github.com/tobi/qmd/blob/main/docs/SYNTAX.md

Example of sending a QMD query using a JSON payload with a structured 'searches' array.

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

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

### MCP/HTTP API Query Document

Source: https://github.com/tobi/qmd/blob/main/docs/SYNTAX.md

Example of sending a QMD query using a JSON payload with a single query string.

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

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

### Get Document by Line Number and Length

Source: https://github.com/tobi/qmd/blob/main/README.md

Retrieves a specific range of lines from a document. Useful for extracting sections of text.

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

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

### API Versioning in URL

Source: https://github.com/tobi/qmd/blob/main/test/eval-docs/api-design-principles.md

Illustrates the preferred method of API versioning using URL prefixes.

```text
/v1/users
/v2/users
```

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

### Get Multiple Documents by Glob Pattern

Source: https://github.com/tobi/qmd/blob/main/README.md

Retrieves multiple documents that match a specified glob pattern. Useful for batch processing.

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

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

### Retrieve Documents

Source: https://github.com/tobi/qmd/blob/main/README.md

Demonstrates how to get single documents by path or ID, retrieve document bodies with line ranges, and perform batch retrievals.

```typescript
// Get a document by path or docid
const doc = await store.get("docs/readme.md")
const byId = await store.get("#abc123")

if (!("error" in doc)) {
  console.log(doc.title, doc.displayPath, doc.context)
}
```

```typescript
// Get document body with line range
const body = await store.getDocumentBody("docs/readme.md", {
  fromLine: 50,
  maxLines: 100,
})
```

```typescript
// Batch retrieve by glob or comma-separated list
const { docs, errors } = await store.multiGet("docs/**/*.md", {
  maxBytes: 20480,
})
```

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

### Experimental GRPO Run

Source: https://github.com/tobi/qmd/blob/main/finetune/README.md

Manually initiate an experimental GRPO run by navigating to the `finetune` directory and executing the GRPO script. This is an optional step and not part of the default production pipeline.

```bash
# Optional experimental GRPO run
cd finetune && uv run python experiments/grpo/grpo.py
```

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

### Quality Scoring Self-Test

Source: https://github.com/tobi/qmd/blob/main/finetune/CLAUDE.md

Command to run a self-test on the quality scoring script, which is the single source of truth for scoring examples based on a defined rubric.

```bash
uv run reward.py   # Self-test
```

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

### Prepare Data for Training

Source: https://github.com/tobi/qmd/blob/main/finetune/README.md

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

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

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

### Convert Model to GGUF Format

Source: https://github.com/tobi/qmd/blob/main/finetune/README.md

Convert base and SFT adapters into a single model and produce quantized GGUF files for deployment. Use presets for specific model sizes or provide custom paths.

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

```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
```

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

### JSON Error Response Structure

Source: https://github.com/tobi/qmd/blob/main/test/eval-docs/api-design-principles.md

Provides an example of a consistent JSON error response format, including error code, message, and relevant field.

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email format is invalid",
    "field": "email"
  }
}
```

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

### Get Multiple Documents by Comma-Separated List

Source: https://github.com/tobi/qmd/blob/main/README.md

Retrieves multiple documents using a comma-separated list of filenames or docids. Supports direct docid references.

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

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

### QMD CLI Options for Search and Retrieval

Source: https://github.com/tobi/qmd/blob/main/CLAUDE.md

Details various command-line options available for QMD search and retrieval operations, including filtering by collection, number of results, 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

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

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

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

### Manage Context

Source: https://github.com/tobi/qmd/blob/main/README.md

Illustrates adding, setting global context, listing, and removing context for collections and globally.

```typescript
// Add context for a path within a collection
await store.addContext("docs", "/api", "REST API reference documentation")
```

```typescript
// Set global context (applies to all collections)
await store.setGlobalContext("Internal engineering documentation")
```

```typescript
// List all contexts
const contexts = await store.listContexts()
// => [{ collection, path, context }]
```

```typescript
// Remove context
await store.removeContext("docs", "/api")
await store.setGlobalContext(undefined)  // clear global
```

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

### Retrieving Single Documents

Source: https://github.com/tobi/qmd/blob/main/skills/qmd/SKILL.md

Fetch individual documents using their docid or full path with the `qmd get` command. Supports both internal docids and `qmd://` paths.

```bash
qmd get "#abc123"
```

```bash
qmd get qmd://concepts/ai-before-headcount.md
```

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

### Get Document Content with Full Path

Source: https://github.com/tobi/qmd/blob/main/skills/qmd/SKILL.md

Retrieves document content, replacing the QMD URL and docid header with the on-disk path. This is useful for passing paths to non-QMD tools.

```text
$ qmd get "#abc123" --full-path
/Users/you/notes/concepts/note.md
---

1: # Metrics as instruments
```

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

### Hierarchical Relationships in URLs

Source: https://github.com/tobi/qmd/blob/main/test/eval-docs/api-design-principles.md

Demonstrates how to express relationships between resources using URL hierarchy.

```text
GET /users/123/orders
GET /users/123/orders/456
```

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

### SFT Training Script (Cloud)

Source: https://github.com/tobi/qmd/blob/main/finetune/CLAUDE.md

Command to run SFT training on HuggingFace Jobs, specifying a machine flavor, required secrets, and a timeout. Uses a specific jobs script.

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

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

### Read Specific Line Ranges with Flags

Source: https://github.com/tobi/qmd/blob/main/skills/qmd/SKILL.md

Equivalent to using the :from:count suffix, this method uses explicit flags `--from` and `-l` to specify the starting line and number of lines to read.

```bash
qmd get "#abc123" --from 120 -l 40
```

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

### Configure OpenClaw MCP Client

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

Configure OpenClaw to use the QMD MCP server by specifying the command and arguments in the openclaw.json file.

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

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

### Get Document Content with Line Numbers

Source: https://github.com/tobi/qmd/blob/main/skills/qmd/SKILL.md

Retrieves document content with default line numbering and includes the document ID and QMD path. Use `--no-line-numbers` for raw content.

```text
qmd://concepts/note.md  #abc123
---

1: # Metrics as instruments
2:
3: Treat dashboards like cockpit instruments...
```

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

### Prepare Data Script

Source: https://github.com/tobi/qmd/blob/main/finetune/CLAUDE.md

Command to run the data preparation script, which loads data via the schema, applies chat templates, deduplicates, and splits into training and validation sets.

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

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

### Configure Editor URI

Source: https://github.com/tobi/qmd/blob/main/README.md

Shows how to configure the editor link target using the QMD_EDITOR_URI environment variable for various editors.

```sh
# VS Code (default)
export QMD_EDITOR_URI="vscode://file/{path}:{line}:{col}"

# Cursor
export QMD_EDITOR_URI="cursor://file/{path}:{line}:{col}"

# Zed
export QMD_EDITOR_URI="zed://file/{path}:{line}:{col}"

# Sublime Text
export QMD_EDITOR_URI="subl://open?url=file://{path}&line={line}"
```

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

### Search Tobi QMD Store

Source: https://github.com/tobi/qmd/blob/main/README.md

Shows how to perform simple and structured searches, including options for collection, limit, and explanation.

```typescript
// Simple query — auto-expanded via LLM, then BM25 + vector + reranking
const results = await store.search({ query: "authentication flow" })
```

```typescript
// With options
const results2 = await store.search({
  query: "rate limiting",
  intent: "API throttling and abuse prevention",
  collection: "docs",
  limit: 5,
  minScore: 0.3,
  explain: true,
})
```

```typescript
// Pre-expanded queries — skip auto-expansion, control each sub-query
const results3 = await store.search({
  queries: [
    { type: 'lex', query: '"connection pool" timeout -redis' },
    { type: 'vec', query: 'why do database connections time out under load' },
  ],
  collections: ["docs", "notes"],
})
```

```typescript
// Skip reranking for faster results
const fast = await store.search({ query: "auth", rerank: false })
```

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

### Inspecting Ranking with `qmd query`

Source: https://github.com/tobi/qmd/blob/main/skills/qmd/SKILL.md

Inspect the ranking of a structured query by using the `--format json --explain` flags. This is useful for understanding how QMD interprets and ranks your query.

```bash
qmd query --format json --explain $'intent: ...\nlex: ...\nvec: ...'
```

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

### Claude Desktop MCP Server Configuration

Source: https://github.com/tobi/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"]
    }
  }
}
```