qmd

qmd - クイック Markdown 検索

Markdown のメモ、ドキュメント、ナレッジベースを対象とするローカル検索エンジンです。一度インデックスを作成すれば、高速に検索できます。

使用する場面（トリガーフレーズ）

• 「メモ／ドキュメント／ナレッジベースを検索して」
• 「関連するメモを見つけて」
• 「コレクションから Markdown ドキュメントを取得して」
• 「ローカルの Markdown ファイルを検索して」

デフォルトの動作（重要）

• qmd search（BM25）を優先してください。通常はすぐに結果が返るため、デフォルトで使用します。
• キーワード検索で見つからず、意味的類似性が必要な場合にのみ qmd vsearch を使用してください（コールドスタート時は非常に遅くなる場合があります）。
• ユーザーが最高品質のハイブリッド検索結果を明示的に求め、長い実行時間やタイムアウトを許容できる場合を除き、qmd query は避けてください。

前提条件

• Bun >= 1.0.0
• macOS：brew install sqlite（SQLite 拡張機能）
• PATH に $HOME/.bun/bin が含まれていることを確認してください

Bun のインストール（macOS）：brew install oven-sh/bun/bun

インストール

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

セットアップ

qmd collection add /path/to/notes --name notes --mask "**/*.md"
qmd context add qmd://notes "Description of this collection"  # optional
qmd embed  # one-time to enable vector + hybrid search

インデックス対象

• Markdown コレクション（一般的には **/*.md）を対象としています。
• テストでは、「雑然とした」Markdown でも問題ありませんでした。チャンク分割はコンテンツに基づいて行われ（1 チャンクあたり数百トークン程度）、見出しや構造に厳密に従うものではありません。
• コード検索の代替にはなりません。リポジトリやソースツリーにはコード検索ツールを使用してください。

検索モード

• qmd search（デフォルト）：高速なキーワード検索（BM25）
• qmd vsearch（最後の手段）：意味的類似性検索（ベクトル）。ベクトル検索の前にローカル LLM で処理を行うことが多いため、遅くなる場合があります。
• qmd query（通常は使用を避ける）：ハイブリッド検索と LLM による再ランキング。vsearch より遅くなることが多く、タイムアウトする場合もあります。

パフォーマンスに関する注意

• qmd search は通常、すぐに結果が返ります。
• クエリの拡張時にローカルモデル（例：Qwen3-1.7B）が実行ごとにメモリへ読み込まれるため、マシンによっては qmd vsearch に約 1 分かかることがあります。ベクトル検索自体は通常高速です。
• qmd query は vsearch に LLM による再ランキングを追加するため、さらに遅く、対話的な用途では信頼性が低くなる可能性があります。
• 意味検索を繰り返し行う必要がある場合は、毎回コールドスタートの LLM を起動するのではなく、プロセスやモデルをウォーム状態に保つ方法（環境で利用できる場合は、長時間稼働する qmd／MCP サーバーモードなど）を検討してください。

よく使うコマンド

qmd search "query"             # default
qmd vsearch "query"
qmd query "query"
qmd search "query" -c notes     # Search specific collection
qmd search "query" -n 10        # More results
qmd search "query" --json       # JSON output
qmd search "query" --all --files --min-score 0.3

便利なオプション

• -n <num>：結果の件数
• -c, --collection <name>：対象をコレクションに限定
• --all --min-score <num>：しきい値を超える一致をすべて返す
• --json / --files：エージェント向けの出力形式
• --full：ドキュメント全体を返す

取得

qmd get "path/to/file.md"       # Full document
qmd get "#docid"                # By ID from search results
qmd multi-get "journals/2025-05*.md"
qmd multi-get "doc1.md, doc2.md, #abc123" --json

メンテナンス

qmd status                      # Index health
qmd update                      # Re-index changed files
qmd embed                       # Update embeddings

インデックスを最新に保つ

メモの追加や編集に応じて結果が最新になるよう、インデックス作成を自動化してください。

• キーワード検索（qmd search）では、通常 qmd update だけで十分です（高速です）。
• 意味検索／ハイブリッド検索（vsearch／query）を利用する場合は、qmd embed も実行するとよいでしょう。ただし、時間がかかる場合があります。

スケジュール設定の例（cron）：

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

# Optional: nightly embedding refresh (can be slow):
0 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd embed

Clawdbot／エージェント環境が組み込みのスケジューラーに対応している場合は、システムの cron の代わりに、そこで同じコマンドを実行できます。

モデルとキャッシュ

• ローカルの GGUF モデルを使用します。初回実行時に自動でダウンロードされます。
• デフォルトのキャッシュ：~/.cache/qmd/models/（XDG_CACHE_HOME で上書きできます）。

Clawdbot のメモリ検索との違い

• qmd は、コレクションに明示的にインデックス登録した ローカルファイル（メモ／ドキュメント）を検索します。
• Clawdbot の memory_search は、エージェントのメモリ（過去のやり取りから保存された事実やコンテキスト）を検索します。
• 併用してください。「以前、何を決めた／学んだか？」には memory_search、「ディスク上のメモ／ドキュメントには何が書かれているか？」には qmd を使います。