qmd collection add . --name <n>   # Create/index collection
qmd collection list               # List all collections with details
qmd collection remove <name>      # Remove a collection by name
qmd collection rename <old> <new> # Rename a collection
qmd ls [collection[/path]]        # List collections or files in a collection
qmd context add [path] "text"     # Add context for path (defaults to current dir)
qmd context list                  # List all contexts
qmd context check                 # Check for collections/paths missing context
qmd context rm <path>             # Remove context
qmd get <file>                    # Get document by path or docid (#abc123)
qmd multi-get <pattern>           # Get multiple docs by glob or comma-separated list
qmd status                        # Show index status and collections
qmd update [--pull]               # Re-index all collections (--pull: git pull first)
qmd embed                         # Generate vector embeddings (uses node-llama-cpp)
qmd query <query>                 # Search with query expansion + reranking (recommended)
qmd search <query>                # Full-text keyword search (BM25, no LLM)
qmd vsearch <query>               # Vector similarity search (no reranking)
qmd mcp                           # Start MCP server (stdio transport)
qmd mcp --http [--port N]         # Start MCP server (HTTP, default port 8181)
qmd mcp --http --daemon           # Start as background daemon
qmd mcp stop                      # Stop background MCP daemon

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

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

Search returns docid in results

qmd search "query" --json
Output: [{"docid": "#abc123", "score": 0.85, "file": "docs/readme.md", ...}]
Get document by docid

qmd get "#abc123"
qmd get abc123              # Leading # is optional
Docids also work in multi-get comma-separated lists

qmd multi-get "#abc123, #def456"

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

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

npx vitest run --reporter=verbose test/
bun test --preload ./src/test-preload.ts test/

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 ...
Create collections for your notes, docs, and meeting transcripts

qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings
qmd collection add ~/work/docs --name docs
Add context to help with search results, each piece of context will be returned when matching sub documents are returned. This works as a tree. This is the key feature of QMD as it allows LLMs to make much better contextual choices when selecting documents. Don't sleep on it!

qmd context add qmd://notes "Personal notes and ideas"
qmd context add qmd://meetings "Meeting transcripts and notes"
qmd context add qmd://docs "Work documentation"
Generate embeddings for semantic search

qmd embed
Search across everything

qmd search "project timeline"           # Fast keyword search
qmd vsearch "how to deploy"             # Semantic search
qmd query "quarterly planning process"  # Hybrid + reranking (best quality)
Get a specific document

qmd get "meetings/2024-01-15.md"
Get a document by docid (shown in search results)

qmd get "#abc123"
Get multiple documents by glob pattern

qmd multi-get "journals/2025-05*.md"
Search within a specific collection

qmd search "API" -c notes
Export all matches for an agent

qmd search "API" --all --files --min-score 0.3

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

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

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

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

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

npm install @tobilu/qmd

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()

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' },
    },
  },
})
// 2. YAML config file — collections defined in a file
const store2 = await createStore({
  dbPath: './index.sqlite',
  configPath: './qmd.yml',
})
// 3. DB-only — reopen a previously configured store
const store3 = await createStore({ dbPath: './index.sqlite' })

// Simple query — auto-expanded via LLM, then BM25 + vector + reranking
const results = await store.search({ query: "authentication flow" })
// 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,
})
// 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"],
})
// Skip reranking for faster results
const fast = await store.search({ query: "auth", rerank: false })

// BM25 keyword search (fast, no LLM)
const lexResults = await store.searchLex("auth middleware", { limit: 10 })
// Vector similarity search (embedding model, no reranking)
const vecResults = await store.searchVector("how users log in", { limit: 10 })
// Manual query expansion for full control
const expanded = await store.expandQuery("auth flow", { intent: "user login" })
const results4 = await store.search({ queries: expanded })

// 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,
})

// Add a collection
await store.addCollection("myapp", {
  path: "/src/myapp",
  pattern: "/*.ts",
  ignore: ["node_modules/", "*.test.ts"],
})
// List collections with document stats
const collections = await store.listCollections()
// => [{ name, pwd, glob_pattern, doc_count, active_count, last_modified, includeByDefault }]
// Get names of collections included in queries by default
const defaults = await store.getDefaultCollectionNames()
// Remove / rename
await store.removeCollection("myapp")
await store.renameCollection("old-name", "new-name")

// Add context for a path within a collection
await store.addContext("docs", "/api", "REST API reference documentation")
// Set global context (applies to all collections)
await store.setGlobalContext("Internal engineering documentation")
// List all contexts
const contexts = await store.listContexts()
// => [{ collection, path, context }]
// Remove context
await store.removeContext("docs", "/api")
await store.setGlobalContext(undefined)  // clear global

// 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 }
// 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})
  },
})

import type {
  QMDStore,            // The store interface
  SearchOptions,       // Options for search()
  LexSearchOptions,    // Options for searchLex()
  VectorSearchOptions, // Options for searchVector()
  HybridQueryResult,   // Search result with score, snippet, context
  SearchResult,        // Result from searchLex/searchVector
  ExpandedQuery,       // Typed sub-query { type: 'lex'|'vec'|'hyde', query }
  DocumentResult,      // Document metadata + body
  DocumentNotFound,    // Error with similarFiles suggestions
  MultiGetResult,      // Batch retrieval result
  UpdateProgress,      // Progress callback info for update()
  UpdateResult,        // Aggregated update result
  EmbedProgress,       // Progress callback info for embed()
  EmbedResult,         // Embedding result
  StoreOptions,        // createStore() options
  CollectionConfig,    // Inline config shape
  IndexStatus,         // From getStatus()
  IndexHealthInfo,     // From getIndexHealth()
} from '@tobilu/qmd'

import {
  extractSnippet,              // Extract a relevant snippet from text
  addLineNumbers,              // Add line numbers to text
  DEFAULT_MULTI_GET_MAX_BYTES, // Default max file size for multiGet (10KB)
  Maintenance,                 // Database maintenance operations
} from '@tobilu/qmd'

// Close the store — disposes LLM models and DB connection
await store.close()

┌─────────────────────────────────────────────────────────────────────────────┐
│                         QMD Hybrid Search Pipeline                          │
└─────────────────────────────────────────────────────────────────────────────┘
                              ┌─────────────────┐
                              │   User Query    │
                              └────────┬────────┘
                                       │
                        ┌──────────────┴──────────────┐
                        ▼                             ▼
               ┌────────────────┐            ┌────────────────┐
               │ Query Expansion│            │  Original Query│
               │  (fine-tuned)  │            │   (×2 weight)  │
               └───────┬────────┘            └───────┬────────┘
                       │                             │
                       │ 2 alternative queries       │
                       └──────────────┬──────────────┘
                                      │
              ┌───────────────────────┼───────────────────────┐
              ▼                       ▼                       ▼
     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
     │ Original Query  │     │ Expanded Query 1│     │ Expanded Query 2│
     └────────┬────────┘     └────────┬────────┘     └────────┬────────┘
              │                       │                       │
      ┌───────┴───────┐       ┌───────┴───────┐       ┌───────┴───────┐
      ▼               ▼       ▼               ▼       ▼               ▼
  ┌───────┐       ┌───────┐ ┌───────┐     ┌───────┐ ┌───────┐     ┌───────┐
  │ BM25  │       │Vector │ │ BM25  │     │Vector │ │ BM25  │     │Vector │
  │(FTS5) │       │Search │ │(FTS5) │     │Search │ │(FTS5) │     │Search │
  └───┬───┘       └───┬───┘ └───┬───┘     └───┬───┘ └───┬───┘     └───┬───┘
      │               │         │             │         │             │
      └───────┬───────┘         └──────┬──────┘         └──────┬──────┘
              │                        │                       │
              └────────────────────────┼───────────────────────┘
                                       │
                                       ▼
                          ┌───────────────────────┐
                          │   RRF Fusion + Bonus  │
                          │  Original query: ×2   │
                          │  Top-rank bonus: +0.05│
                          │     Top 30 Kept       │
                          └───────────┬───────────┘
                                      │
                                      ▼
                          ┌───────────────────────┐
                          │    LLM Re-ranking     │
                          │  (qwen3-reranker)     │
                          │  Yes/No + logprobs    │
                          └───────────┬───────────┘
                                      │
                                      ▼
                          ┌───────────────────────┐
                          │  Position-Aware Blend │
                          │  Top 1-3:  75% RRF    │
                          │  Top 4-10: 60% RRF    │
                          │  Top 11+:  40% RRF    │
                          └───────────────────────┘

brew install sqlite

Use Qwen3-Embedding-0.6B for better multilingual (CJK) support

export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
After changing the model, re-embed all collections:

qmd embed -f

npm install -g @tobilu/qmd
or

bun install -g @tobilu/qmd

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

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"
List all collections

qmd collection list
Remove a collection

qmd collection remove myproject
Rename a collection

qmd collection rename myproject my-project
List files in a collection

qmd ls notes
qmd ls notes/subfolder

Embed all indexed documents (900 tokens/chunk, 15% overlap)

qmd embed
Force re-embed everything

qmd embed -f
Enable AST-aware chunking for code files (TS, JS, Python, Go, Rust)

qmd embed --chunk-strategy auto
Also works with query for consistent chunk selection

qmd query "auth flow" --chunk-strategy auto

Add context to a collection (using qmd:// virtual paths)

qmd context add qmd://notes "Personal notes and ideas"
qmd context add qmd://docs/api "API documentation"
Add context from within a collection directory

cd ~/notes && qmd context add "Personal notes and ideas"
cd ~/notes/work && qmd context add "Work-related notes"
Add global context (applies to all collections)

qmd context add / "Knowledge base for my projects"
List all contexts

qmd context list
Remove context

qmd context rm qmd://notes/old

┌──────────────────────────────────────────────────────────────────┐
│                        Search Modes                              │
├──────────┬───────────────────────────────────────────────────────┤
│ search   │ BM25 full-text search only                           │
│ vsearch  │ Vector semantic search only                          │
│ query    │ Hybrid: FTS + Vector + Query Expansion + Re-ranking  │
└──────────┴───────────────────────────────────────────────────────┘

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"

Search options

-n <num>           # Number of results (default: 5, or 20 for --files/--json)
-c, --collection   # Restrict search to a specific collection
--all              # Return all matches (use with --min-score to filter)
--min-score <num>  # Minimum score threshold (default: 0)
--full             # Show full document content
--line-numbers     # Add line numbers to output
--explain          # Include retrieval score traces (query, JSON/CLI output)
--index <name>     # Use named index
Output formats (for search and multi-get)

--files            # Output: docid,score,filepath,context
--json             # JSON output with snippets
--csv              # CSV output
--md               # Markdown output
--xml              # XML output
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)

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.

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

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"

Show index status and collections with contexts

qmd status
Re-index all collections

qmd update
Re-index with git pull first (for remote repos)

qmd update --pull
Get document by filepath (with fuzzy matching suggestions)

qmd get notes/meeting.md
Get document by docid (from search results)

qmd get "#abc123"
Get document starting at line 50, max 100 lines

qmd get notes/meeting.md:50 -l 100
Get multiple documents by glob pattern

qmd multi-get "journals/2025-05*.md"
Get multiple documents by comma-separated list (supports docids)

qmd multi-get "doc1.md, doc2.md, #abc123"
Limit multi-get to files under 20KB

qmd multi-get "docs/*.md" --max-bytes 20480
Output multi-get as JSON for agent processing

qmd multi-get "docs/*.md" --json
Clean up cache and orphaned data

qmd cleanup

collections     -- Indexed directories with name and glob patterns
path_contexts   -- Context descriptions by virtual path (qmd://...)
documents       -- Markdown content with metadata and docid (6-char hash)
documents_fts   -- FTS5 full-text index
content_vectors -- Embedding chunks (hash, seq, pos, 900 tokens each)
vectors_vec     -- sqlite-vec vector index (hash_seq key)
llm_cache       -- Cached LLM responses (query expansion, rerank scores)

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

Document ──► Smart Chunk (~900 tokens) ──► Format each chunk ──► node-llama-cpp ──► Store Vectors
                │                           "title | text"        embedBatch()
                │
                └─► Chunks stored with:
                    - hash: document hash
                    - seq: chunk sequence (0, 1, 2...)
                    - pos: character position in original

Query ──► LLM Expansion ──► [Original, Variant 1, Variant 2]
                │
      ┌─────────┴─────────┐
      ▼                   ▼
   For each query:     FTS (BM25)
      │                   │
      ▼                   ▼
   Vector Search      Ranked List
      │
      ▼
   Ranked List
      │
      └─────────┬─────────┘
                ▼
         RRF Fusion (k=60)
         Original query ×2 weight
         Top-rank bonus: +0.05/#1, +0.02/#2-3
                │
                ▼
         Top 30 candidates
                │
                ▼
         LLM Re-ranking
         (yes/no + logprob confidence)
                │
                ▼
         Position-Aware Blend
         Rank 1-3:  75% RRF / 25% reranker
         Rank 4-10: 60% RRF / 40% reranker
         Rank 11+:  40% RRF / 60% reranker
                │
                ▼
         Final Results

const DEFAULT_EMBED_MODEL = "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf";
const DEFAULT_RERANK_MODEL = "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf";
const DEFAULT_GENERATE_MODEL = "hf:tobil/qmd-query-expansion-1.7B-gguf/qmd-query-expansion-1.7B-q4_k_m.gguf";

// For queries
"task: search result | query: {query}"
// For documents
"title: {title} | text: {content}"