Skip to content
Back to search

qmd

SkillWorks with Claude CodeGitHub

Local hybrid search for markdown notes and docs. Use when searching notes, finding related content, or retrieving documents from indexed collections.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/levineam-qmd-skill/badge.svg)](/listings/levineam-qmd-skill)

HTML

<a href="/listings/levineam-qmd-skill"><img src="/api/listings/levineam-qmd-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 129 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: qmd
  3. description: Local hybrid search for markdown notes and docs. Use when searching notes, finding related content, or retrieving documents from indexed collections.
  4. homepage: https://github.com/tobi/qmd
  5. metadata: {"clawdbot":{"emoji":"🔍","os":["darwin","linux"],"requires":{"bins":["bun","qmd"]},"install":[{"id":"bun-qmd","kind":"shell","command":"bun install -g https://github.com/tobi/qmd","bins":["qmd"],"label":"Install qmd via Bun"}]}}
  6. ---
  7. # qmd - Quick Markdown Search
  8. Local search engine for Markdown notes, docs, and knowledge bases. Index once, search fast.
  9. ## When to use (trigger phrases)
  10. - "search my notes / docs / knowledge base"
  11. - "find related notes"
  12. - "retrieve a markdown document from my collection"
  13. - "search local markdown files"
  14. ## Default behavior (important)
  15. - Prefer `qmd search` (BM25). It's typically instant and should be the default.
  16. - Use `qmd vsearch` only when keyword search fails and you need semantic similarity (can be very slow on a cold start).
  17. - Avoid `qmd query` unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes/timeouts.
  18. ## Prerequisites
  19. - Bun >= 1.0.0
  20. - macOS: `brew install sqlite` (SQLite extensions)
  21. - Ensure PATH includes: `$HOME/.bun/bin`
  22. Install Bun (macOS): `brew install oven-sh/bun/bun`
  23. ## Install
  24. `bun install -g https://github.com/tobi/qmd`
  25. ## Setup
  26. ```bash
  27. qmd collection add /path/to/notes --name notes --mask "**/*.md"
  28. qmd context add qmd://notes "Description of this collection" # optional
  29. qmd embed # one-time to enable vector + hybrid search
  30. ```
  31. ## What it indexes
  32. - Intended for Markdown collections (commonly `**/*.md`).
  33. - In our testing, "messy" Markdown is fine: chunking is content-based (roughly a few hundred tokens per chunk), not strict heading/structure based.
  34. - Not a replacement for code search; use code search tools for repositories/source trees.
  35. ## Search modes
  36. - `qmd search` (default): fast keyword match (BM25)
  37. - `qmd vsearch` (last resort): semantic similarity (vector). Often slow due to local LLM work before the vector lookup.
  38. - `qmd query` (generally skip): hybrid search + LLM reranking. Often slower than `vsearch` and may timeout.
  39. ## Performance notes
  40. - `qmd search` is typically instant.
  41. - `qmd vsearch` can be ~1 minute on some machines because query expansion may load a local model (e.g., Qwen3-1.7B) into memory per run; the vector lookup itself is usually fast.
  42. - `qmd query` adds LLM reranking on top of `vsearch`, so it can be even slower and less reliable for interactive use.
  43. - If you need repeated semantic searches, consider keeping the process/model warm (e.g., a long-lived qmd/MCP server mode if available in your setup) rather than invoking a cold-start LLM each time.
  44. ## Common commands
  45. ```bash
  46. qmd search "query" # default
  47. qmd vsearch "query"
  48. qmd query "query"
  49. qmd search "query" -c notes # Search specific collection
  50. qmd search "query" -n 10 # More results
  51. qmd search "query" --json # JSON output
  52. qmd search "query" --all --files --min-score 0.3
  53. ```
  54. ## Useful options
  55. - `-n <num>`: number of results
  56. - `-c, --collection <name>`: restrict to a collection
  57. - `--all --min-score <num>`: return all matches above a threshold
  58. - `--json` / `--files`: agent-friendly output formats
  59. - `--full`: return full document content
  60. ## Retrieve
  61. ```bash
  62. qmd get "path/to/file.md" # Full document
  63. qmd get "#docid" # By ID from search results
  64. qmd multi-get "journals/2025-05*.md"
  65. qmd multi-get "doc1.md, doc2.md, #abc123" --json
  66. ```
  67. ## Maintenance
  68. ```bash
  69. qmd status # Index health
  70. qmd update # Re-index changed files
  71. qmd embed # Update embeddings
  72. ```
  73. ## Keeping the index fresh
  74. Automate indexing so results stay current as you add/edit notes.
  75. - For keyword search (`qmd search`), `qmd update` is usually enough (fast).
  76. - If you rely on semantic/hybrid search (`vsearch`/`query`), you may also want `qmd embed`, but it can be slow.
  77. Example schedules (cron):
  78. ```bash
  79. # Hourly incremental updates (keeps BM25 fresh):
  80. 0 * * * * export PATH="$HOME/.bun/bin:$PATH" && qmd update
  81. # Optional: nightly embedding refresh (can be slow):
  82. 0 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd embed
  83. ```
  84. If your Clawdbot/agent environment supports a built-in scheduler, you can run the same commands there instead of system cron.
  85. ## Models and cache
  86. - Uses local GGUF models; first run auto-downloads them.
  87. - Default cache: `~/.cache/qmd/models/` (override with `XDG_CACHE_HOME`).
  88. ## Relationship to Clawdbot memory search
  89. - `qmd` searches *your local files* (notes/docs) that you explicitly index into collections.
  90. - Clawdbot's `memory_search` searches *agent memory* (saved facts/context from prior interactions).
  91. - Use both: `memory_search` for "what did we decide/learn before?", `qmd` for "what's in my notes/docs on disk?".
README.md · README · 9 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # QMD Skill
  2. This repository contains a Codex/Clawd skill definition for **qmd** (Quick Markdown Search).
  3. - Skill file: `SKILL.md`
  4. - Homepage: https://github.com/tobi/qmd
  5. ## Usage
  6. Import or install this skill in your Codex/Clawd environment by pointing to this repo and reading `SKILL.md`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.