qmd

AI Community

Skill notes

When to Use

"search my notes / docs / knowledge base" "find related notes" "find files matching [pattern]" — use instead of find to avoid hangs on large directories "what did we decide about X?"

Default Behavior (important)

Prefer qmd search (BM25) — it's instant and should be the default. Use qmd vsearch only when keyword search fails and you need semantic similarity. Avoid qmd query unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes. Always use --json flag for structured output when invoking from an agent.

Search Mode Selection

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

Search Options

Option · Description -n NUM · Number of results (default: 5, 20 with --json) -c, --collection · Scope to specific collection --min-score NUM · Minimum score threshold --full · Return complete document content

Output Formats

--files — paths + scores (for file discovery) --json — structured with snippets --md — markdown formatted -n 10 — limit results

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
AI
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@diegosouzapw · no license declared
Token usage
Lean
Setup complexity
Plug-and-play
External API key
Not required
Operating systems
macOS · Linux · Windows
Runtime requirements
Bun
Detected file/system behavior
  • Read-only
  • Write / modify
  • Env read
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Author source file SKILL.md

# qmd - Local Markdown Search

Local search engine for Markdown notes, docs, and knowledge bases. Index once, search fast. Use instead of `find` for file discovery across large directories.

## Installation

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

## Setup

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

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

# List your collections
qmd collection list
```

## When to Use

- "search my notes / docs / knowledge base"
- "find related notes"
- "find files matching [pattern]" — use instead of `find` to avoid hangs on large directories
- "what did we decide about X?"

## Default Behavior (important)

- Prefer `qmd search` (BM25) — it's instant and should be the default.
- Use `qmd vsearch` only when keyword search fails and you need semantic similarity.
- Avoid `qmd query` unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes.
- **Always use `--json` flag** for structured output when invoking from an agent.

## Search Commands

```bash
# Fast keyword search (default)
qmd search "authentication flow" --json
qmd search "config" --json -c notes

# Semantic search (slower, for conceptual queries)
qmd vsearch "how does login work" --json
qmd vsearch "best practices for error handling" --json -n 20

# Combined with reranking (best quality, slowest)
qmd query "implementing user auth" --json
qmd query "deployment process" --json --min-score 0.5
```

### Search Mode Selection

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

### Search Options

| Option | Description |
|--------|-------------|
| `-n NUM` | Number of results (default: 5, 20 with --json) |
| `-c, --collection` | Scope to specific collection |
| `--min-score NUM` | Minimum score threshold |
| `--full` | Return complete document content |
| `--json` | Structured JSON output (agent-friendly) |
| `--files` | File paths only (fast discovery) |
| `--all` | Return all matches |

## Retrieve Documents

```bash
# Get full file
qmd get docs/guide.md --json

# Get by document hash ID
qmd get "#a1b2c3" --json

# Get specific lines
qmd get notes/meeting.md:50 -l 30 --json

# Get multiple files by glob
qmd multi-get "docs/*.md" --json
qmd multi-get "*.yaml" -l 50 --max-bytes 10240
```

## Output Formats

- `--files` — paths + scores (for file discovery)
- `--json` — structured with snippets
- `--md` — markdown formatted
- `-n 10` — limit results

## Maintenance

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

## Keeping Index Fresh

```bash
# Hourly incremental updates (BM25):
0 * * * * export PATH="$HOME/.bun/bin:$PATH" && qmd update

# Optional: nightly embedding refresh:
0 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd embed
```

## MCP Server

qmd can run as an MCP server for direct agent integration:

```bash
qmd mcp
```

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

## Performance

- `qmd search` is typically instant.
- `qmd vsearch` can take ~1 minute on first run (loads local LLM).
- `qmd query` adds LLM reranking — can be slow, avoid for interactive use.

## Models (auto-downloaded)

All run locally — no API keys needed.

- Embedding: embeddinggemma-300M
- Reranking: qwen3-reranker-0.6b
- Generation: Qwen3-0.6B
- Cache location: `~/.cache/qmd/models/`
- Override with `XDG_CACHE_HOME` environment variable.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.