qmd

qmd - Markdown の高速検索

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

使用するタイミング（トリガーフレーズ）

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

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

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

検索モード

モード	コマンド	速度	用途
BM25（デフォルト）	qmd search	即時	キーワードの一致
ベクトル	qmd vsearch	コールドスタート時は約1分	意味的類似性
ハイブリッド	qmd query	最も遅い	LLM による再ランキング（リクエストがない限り使用しない）

よく使うコマンド

qmd search "query"              # default - fast keyword search
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

セットアップ（未インストールの場合）

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

# Create collection
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

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

• qmd search は通常、すぐに結果が返ります
• qmd vsearch はコールドスタート時に約1分かかることがあります（クエリ拡張のためにローカル LLM を読み込みます）
• qmd query は vsearch に LLM による再ランキングを追加するため、さらに遅くなります

よくある問題

検索クエリが曖昧すぎる（無関係な結果が返る）

問題：「メモ」や「プロジェクト」のような広すぎるクエリでは、関連性の低い結果が何百件も返ります。

解決策：

• 具体的なキーワードを使います。qmd search "Python async context managers" のように検索し、qmd search "Python" は避けます
• キーワードを組み合わせます：qmd search "deadline March quarterly review"
• 完全一致するフレーズは引用符で囲みます：qmd search "exact phrase match"
• 結果のスコアを確認します：qmd search "query" --all --min-score 0.5 を使って、信頼度の低い一致を除外します

インデックスが更新されていない（最近のファイルが見つからない）

**問題：**新しく作成したファイルや最近変更したファイルが検索結果に表示されません。

解決策：

# Check index status
qmd status

# Re-index all changed files
qmd update

# Full re-index if update doesn't help
qmd collection remove <name>
qmd collection add /path/to/notes --name <name> --mask "**/*.md"
qmd embed  # if vector search enabled

パスフィルターの設定が不適切（関連するディレクトリが除外される）

**問題：**コレクションのマスクが狭すぎるか、コレクションのパスが間違っているため、ファイルが見つかりません。

解決策：

# List current collections
qmd status

# Verify collection path matches your notes location
# If path changed, re-add collection:
qmd collection remove <old-name>
qmd collection add /path/to/notes --name <name> --mask "**/*.md"

# Common issue: subdirectories excluded by mask
# If notes are in journals/2025/*, use: --mask "**/*.md"
# Not: --mask "*.md" (which only matches top level)

大規模なボルトで検索がタイムアウトする（パフォーマンスの問題）

**問題：**大規模なナレッジベース（1000件以上のファイル）では、qmd query または qmd vsearch が停止したり、タイムアウトしたりします。

解決策：

• 大規模なボルトでは qmd query を避けます（LLM による再ランキングが遅すぎます）
• 代わりに qmd search を使います（BM25 は非常に大きなコレクションでも高速です）
• 意味検索が必要な場合は、-n 5 を指定して結果を制限し、qmd vsearch を使います
• すべてのコレクションではなく、1つのコレクションを検索するには、-c <collection> で検索範囲を限定します：

  qmd search "query" -c notes -n 5  # faster than searching all collections
  

• ボルトに5000件を超えるファイルがある場合は、複数のコレクションに分割することを検討してください

設定がない（qmd が初期化されていない）

問題：qmd status に「No collections」と表示されるか、qmd search で結果が返りません。

解決策：

# Install qmd if missing
bun install -g https://github.com/tobi/qmd

# Set up a collection
qmd collection add /path/to/notes --name notes --mask "**/*.md"

# Enable vector search (optional but recommended)
qmd embed

# Verify setup
qmd status  # Should show your collection with file count

意味検索で無関係な結果が返る（vsearch/query）

**問題：**ベクトル検索ではトピックは一致するものの、実際に求めていた内容が見つかりません。

解決策：

• qmd search に切り替えます（BM25 によるキーワード一致は、具体的な語句の検索により正確です）
• 実際のキーワードを含めてクエリを言い換えます。「私の目標は何ですか？」ではなく「goals quarterly review objectives」とします
• 利用できる場合は qmd query を使います（LLM による再ランキングが追加されます）が、実行に時間がかかることを許容できる場合に限ります
• ベクトル検索で件数を減らし、信頼度の高い一致を得るには -n 3 を使います