QMD - Quick Markdown Search

マークダウンコンテンツ用のローカル検索エンジン。

Status

!qmd status 2>/dev/null || echo "Not installed: npm install -g @tobilu/qmd"

MCP: query

{
  "searches": [
    { "type": "lex", "query": "CAP theorem consistency" },
    { "type": "vec", "query": "tradeoff between consistency and availability" }
  ],
  "collections": ["docs"],
  "limit": 10
}

クエリタイプ

Type	Method	Input
lex	BM25	キーワード — 正確な用語、名前、コード
vec	Vector	質問 — 自然言語
hyde	Vector	回答 — 仮想的な結果 (50-100 単語)

良いクエリの書き方

lex (キーワード)

• 2-5 語、つなぎ言葉なし
• 正確なフレーズ: "connection pool" (引用符あり)
• 除外語: performance -sports (マイナスプレフィックス)
• コード識別子が使える: handleError async

vec (セマンティック)

• 完全な自然言語の質問
• 具体的に: "how does the rate limiter handle burst traffic"
• コンテキストを含める: "in the payment service, how are refunds processed"

hyde (仮想的なドキュメント)

• 回答の形式に関して 50-100 単語を書く
• 結果に含まれると予想される語彙を使用

expand (自動展開)

• 単一行クエリを使用するか (暗黙の expand:)、独自の行で expand: question を使用
• ローカル LLM に lex/vec/hyde のバリエーションを生成させる
• expand: を他の型の行と混ぜないこと — スタンドアロンの expand クエリか完全なクエリドキュメントのどちらか

Intent (曖昧性排除)

クエリ用語が曖昧な場合、intent を追加して結果をステアリングします:

{
  "searches": [
    { "type": "lex", "query": "performance" }
  ],
  "intent": "web page load times and Core Web Vitals"
}

Intent は展開、再ランキング、チャンク選択、スニペット抽出に影響します。それ自体は検索を行わず、「performance」(Web パフォーマンス対チームの健全性対フィットネス) のようなクエリを曖昧さを排除するステアリング信号です。

タイプの組み合わせ

目的	アプローチ
正確な用語を知っている	lex のみ
語彙がわからない	単一行クエリを使用するか (暗黙の expand:)、または vec
最大限の再現率	lex + vec
複雑なトピック	lex + vec + hyde
曖昧なクエリ	上記の任意の組み合わせに intent を追加

最初のクエリは融合で 2 倍の重みを取得 — 最初に最善の推測を入力します。

Lex クエリ構文

Syntax	Meaning	Example
term	プレフィックスマッチ	perf は "performance" にマッチ
"phrase"	正確なフレーズ	"rate limiter"
-term	除外	performance -sports

注: -term は lex クエリのみで機能し、vec/hyde では機能しません。

コレクションフィルタリング

{ "collections": ["docs"] }              // 単一
{ "collections": ["docs", "notes"] }     // 複数 (OR)

すべてのコレクションを検索する場合は省略します。

その他の MCP ツール

Tool	用途
get	パスまたは #docid でドキュメントを取得
multi_get	glob/リストで複数を取得
status	コレクションとヘルス状態

CLI

qmd query "question"              # 自動展開 + 再ランキング
qmd query $'lex: X\nvec: Y'       # 構造化
qmd query $'expand: question'     # 明示的な展開
qmd query --json --explain "q"    # スコアトレースを表示 (RRF + 再ランキングブレンド)
qmd search "keywords"             # BM25 のみ (LLM なし)
qmd get "#abc123"                 # docid で取得
qmd multi-get "journals/2026-*.md" -l 40  # glob でバッチ取得スニペット
qmd multi-get notes/foo.md,notes/bar.md   # カンマ区切りリスト、順序を保持

HTTP API

curl -X POST http://localhost:8181/query \
  -H "Content-Type: application/json" \
  -d '{"searches": [{"type": "lex", "query": "test"}]}'

セットアップ

npm install -g @tobilu/qmd
qmd collection add ~/notes --name notes
qmd embed