qmd-search

qmd 検索

qmd を使って、ローカルの Markdown ナレッジベースを意味ベースで検索します。5 つのモード（BM25 キーワード、ベクトル類似度、ハイブリッド（拡張＋再ランク付け）、ネイティブスクリプトのリテラル grep、統合 find）をすべてデバイス上で実行します。Obsidian の組み込み検索と比べた主な利点は、意味を照合し、クエリと共通の単語がないノートも見つけられ、言語をまたいで機能することです（例：ロシア語のクエリで英語のノートを取得できます）。

各モードの使い分け

• ハイブリッド（query） — デフォルトです。実際の質問や曖昧な意図（「過剰設計をやめるにはどうすればよいか」など）に適しています。品質が最も高く、初回実行時に再ランク付け／拡張モデルをダウンロードします（初回のみ時間がかかります）。
• ベクトル（vsearch） — 概念をすばやく検索します（「身体性コンピューティングに関するノート」など）。
• BM25（search） — 正確なキーワード、名前、またはファイル名を検索します。即時に実行され、モデルは不要です。
• grep（-m grep） — .md ファイルを対象に、固定文字列で ripgrep によるリテラル検索を行います。固有名詞、音訳、正確なフレーズ、ロシア語の語幹／語形変化、不在確認のための監査経路です。 インデックスを介さず、入力したスクリプト／綴りと完全に一致するものだけを検索します。

バイリンガル／固有名詞のルール（必ず守ってください）

このボルトは英語とロシア語のバイリンガルです。埋め込みモデルは概念の検索には十分ですが、固有名詞／具体的な実体の検索は苦手で、BM25 は入力したスクリプトと一致するものだけを検索します。そのため、次の点に注意してください。

英語の意味検索を 1 回行っただけで、「ボルト内に存在しない」と結論づけないでください。 名前、人、ペット、場所、外国語の用語、バイリンガルのトピックを検索する場合は、次の手順に従います。

1. まず意味検索を行います（query／vsearch）。
2. ありそうなネイティブスクリプトの綴りや語幹を考え、試します。例： Ziggy → Зигги/Зиги、dog/pet → собак, пёс, щенок, питомц, животн。語幹を使い（собак で собака/собаку/собаки を検索できます）、主格形だけにしないでください。
3. 不在と結論づける前に、リテラル検索を実行します：qmd-search.sh -m grep -n 20 "Зигги"。
4. リテラル検索のヒットを使って、似た名前を区別します（例：ペットの Зигги とフロイトの Зигмунд）。
5. すべて失敗した場合は、「次のクエリでは見つかりませんでした：…」と伝え、試した語句を列挙します。「ボルト内に存在しません」とは言わないでください。不在確認では -n を約 20 に増やしてください。

主な使い方 — ラッパー

同梱のラッパーを使ってください。qmd の標準エラー出力に表示されるスピナーを抑制し、結果を score path 形式で整形します（qmd の JSON を解析するため、ファイル名にカンマが含まれていても安全です）。また、qmd embed の実行中（検索結果が空になるため）は、最善を尽くして検索の実行を拒否します（--force で上書きできます）。

~/.claude/skills/qmd-search/scripts/qmd-search.sh [-m query|search|vsearch|grep|find] [-n N] [-c COLLECTION] [--snippet] [--min-score X] [--json] [--full] <query...>

例：

qmd-search.sh "what helps with anxiety"                 # hybrid (default)
qmd-search.sh -m vsearch -n 8 "behavioral health from photos"
qmd-search.sh -m search sensorium                       # BM25 keyword
qmd-search.sh -m grep -n 20 "Зигги"                     # literal native-spelling / absence check
qmd-search.sh -m find "Зигги собака"                    # fused: semantic + literal in one call
qmd-search.sh --snippet "agent orchestration"           # rows + matching snippets
qmd-search.sh --min-score 0.5 "quarterly planning"      # drop low-relevance hits
qmd-search.sh --json "agent orchestration"              # structured output for further processing

ヒットしたら、上位のファイルを直接読む（通常のボルトパスです）か、qmd get "<path>:<line>" -l <N> で該当箇所を取得します。

セットアップ／インデックス作成（qmd status でボルトがインデックス化されていないと表示された場合のみ）

qmd collection add ~/Brains/brain --name brain        # index the vault
qmd context add qmd://brain "short description of the vault"
qmd embed                                              # build vectors; re-run until status shows 0 pending
qmd cleanup                                            # compact the index

大規模な編集後に更新します：qmd update && qmd embed。qmd status を使えば、いつでも状態を確認できます。

運用ルール（必ず守ってください）

• 埋め込み処理は同時に 1 つだけにし、埋め込み中は絶対に検索しないでください。どちらも結果が空または不正になる原因です。ラッパーは検索をガードします。手動で qmd を実行する場合は、先に qmd status を確認してください。
• 埋め込み処理で保留中の件数がいつまでも 0 にならない場合は、ディスク容量を確認してください（df -h）。ディスクがいっぱいだと、書き込みがエラーを表示せず失敗します。references/cli-reference.md →「運用上の注意」を参照してください。
• ベクトルスコアは控えめです（約 0.4～0.6）。絶対値ではなく、順位で判断してください。

MCP（ネイティブツール）と CLI ラッパー

qmd には query、get、multi_get、status の各ツールを公開する MCP サーバー（qmd mcp、stdio）が付属しています。ホストに登録されている場合（例：.mcp.json）、ハイブリッド検索にはネイティブの query ツールを優先してください。スピナー／JSON 解析／終了コードにまつわる問題がなく、構造化された結果が返されます。次のように登録します。

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

MCP では対応していない機能が必要な場合は、ラッパー（scripts/qmd-search.sh）を使ってください。対象となる機能は、BM25 のみの検索（search）、ベクトルのみの検索（vsearch）、リテラル／ネイティブスクリプトの**grep検索、統合find**モード、--snippet、--min-score です。上記のバイリンガル／固有名詞のルールは、どちらの方法にも適用されます。

品質／評価

evals/fixture.example.json と scripts/run-evals.sh は qmd bench を実行し、検索品質をスコア化します（バックエンドごとの適合率／再現率／MRR）。ベースラインと解釈については、evals/BASELINE.md を参照してください。ラッパー、インデックス、または埋め込みモデルを変更した後に再実行してください。ベースラインと比べてスコアが低下した場合は、回帰です。

リファレンス

コマンドの全仕様、クエリ文法（lex:／vec:／hyde:）、出力形式、モデル、および復旧手順については、references/cli-reference.md を参照してください。