QMD — Query Markup Documents

個人のナレッジベース用ローカルオンデバイス検索エンジン。マークダウン ノート、会議トランスクリプト、ドキュメント、テキストベースのファイルをインデックス化し、 キーワード検索、セマンティック理解、LLM搭載の再ランキングを組み合わせたハイブリッド検索を提供します — すべてローカルで実行され、クラウド依存がありません。

Tobi Lütke によって作成。MIT ライセンス。

使用する場面

• ユーザーがノート、ドキュメント、ナレッジベース、または会議トランスクリプトを検索するよう依頼している
• 大量のマークダウン/テキストファイルコレクション全体で何かを見つけたい
• キーワード grep ではなくセマンティック検索（「X コンセプトについてのノートを探す」）を希望している
• ユーザーが既に qmd コレクションをセットアップしており、クエリしたいと考えている
• ユーザーがローカルナレッジベースやドキュメント検索システムをセットアップしたいと依頼している
• キーワード：「ノートを検索する」「ドキュメントで見つける」「ナレッジベース」「qmd」

前提条件

Node.js >= 22（必須）

# バージョン確認
node --version  # 22 以上である必要があります

# macOS — Homebrew 経由でインストールまたはアップグレード
brew install node@22

# Linux — NodeSource または nvm を使用
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# または nvm を使用：
nvm install 22 && nvm use 22

SQLite 拡張サポート（macOS のみ）

macOS システム SQLite には拡張読み込み機能がありません。Homebrew 経由でインストールしてください：

brew install sqlite

qmd をインストール

npm install -g @tobilu/qmd
# または Bun を使用：
bun install -g @tobilu/qmd

初回実行時に 3 つのローカル GGUF モデルを自動ダウンロードします（合計約 2GB）：

モデル	用途	サイズ
embeddinggemma-300M-Q8_0	ベクトル埋め込み	約 300MB
qwen3-reranker-0.6b-q8_0	結果の再ランキング	約 640MB
qmd-query-expansion-1.7B	クエリ拡張	約 1.1GB

インストールを確認

qmd --version
qmd status

クイックリファレンス

コマンド	機能	速度
qmd search "query"	BM25 キーワード検索（モデルなし）	約 0.2 秒
qmd vsearch "query"	セマンティックベクトル検索（1 モデル）	約 3 秒
qmd query "query"	ハイブリッド + 再ランキング（すべて 3 モデル）	約 2～3 秒（ウォーム）、約 19 秒（コールド）
qmd get <docid>	ドキュメント全文を取得	即座
qmd multi-get "glob"	複数のファイルを取得	即座
qmd collection add <path> --name <n>	ディレクトリをコレクションとして追加	即座
qmd context add <path> "description"	検索精度を向上させるメタデータを追加	即座
qmd embed	ベクトル埋め込みを生成/更新	さまざま
qmd status	インデックスの状態とコレクション情報を表示	即座
qmd mcp	MCP サーバーを起動（stdio）	継続
qmd mcp --http --daemon	MCP サーバーを起動（HTTP、ウォームモデル）	継続

セットアップのワークフロー

1. コレクションを追加

ドキュメントを含むディレクトリを qmd に指定します：

# ノートディレクトリを追加
qmd collection add ~/notes --name notes

# プロジェクトドキュメントを追加
qmd collection add ~/projects/myproject/docs --name project-docs

# 会議トランスクリプトを追加
qmd collection add ~/meetings --name meetings

# すべてのコレクションをリスト表示
qmd collection list

2. コンテキスト説明を追加

コンテキストメタデータは、検索エンジンが各コレクションに何が含まれているかを理解するのに役立ちます。 これにより検索品質が大幅に向上します：

qmd context add qmd://notes "個人的なノート、アイデア、日記エントリ"
qmd context add qmd://project-docs "メインプロジェクトの技術ドキュメント"
qmd context add qmd://meetings "チーム同期からの会議トランスクリプトと実行項目"

3. 埋め込みを生成

qmd embed

これにより、すべてのコレクション内のすべてのドキュメントが処理され、ベクトル埋め込みが生成されます。 新しいドキュメントまたはコレクションを追加した後に再実行してください。

4. 確認

qmd status   # インデックスの状態、コレクション統計、モデル情報を表示

検索パターン

高速キーワード検索（BM25）

最適な用途：正確な用語、コード識別子、名前、既知のフレーズ。 モデルが読み込まれていません — ほぼ即座の結果。

qmd search "authentication middleware"
qmd search "handleError async"

セマンティックベクトル検索

最適な用途：自然言語の質問、概念的なクエリ。 埋め込みモデルを読み込みます（最初のクエリで約 3 秒）。

qmd vsearch "how does the rate limiter handle burst traffic"
qmd vsearch "ideas for improving onboarding flow"

ハイブリッド検索と再ランキング（最高の品質）

最適な用途：品質が最も重要な重要なクエリ。 すべて 3 つのモデルを使用 — クエリ拡張、並列 BM25 + ベクトル、再ランキング。

qmd query "what decisions were made about the database migration"

構造化マルチモードクエリ

1 つのクエリで異なる検索タイプを組み合わせて精度を向上させます：

# 正確な用語の BM25 + コンセプトのベクトル
qmd query $'lex: rate limiter\nvec: how does throttling work under load'

# クエリ拡張付き
qmd query $'expand: database migration plan\nlex: "schema change"'

クエリ構文（lex/BM25 モード）

構文	効果	例
term	プレフィックスマッチ	perf は「performance」とマッチ
"phrase"	正確なフレーズ	"rate limiter"
-term	用語を除外	performance -sports

HyDE（仮説的ドキュメント埋め込み）

複雑なトピックの場合、答えがどのようなものかを書きます：

qmd query $'hyde: The migration plan involves three phases. First, we add the new columns without dropping the old ones. Then we backfill data. Finally we cut over and remove legacy columns.'

コレクションにスコープ

qmd search "query" --collection notes
qmd query "query" --collection project-docs

出力形式

qmd search "query" --json        # JSON 出力（解析に最適）
qmd search "query" --limit 5     # 結果を制限
qmd get "#abc123"                # ドキュメント ID で取得
qmd get "path/to/file.md"       # ファイルパスで取得
qmd get "file.md:50" -l 100     # 特定の行範囲を取得
qmd multi-get "journals/*.md" --json  # glob でバッチ取得

MCP 統合（推奨）

qmd は MCP サーバーを公開し、ネイティブ MCP クライアント経由で Hermes Agent に検索ツールを直接提供します。これが推奨される統合です — 設定すると、このスキルをロードすることなくエージェントが qmd ツールを自動的に取得します。

オプション A：Stdio モード（シンプル）

~/.logos/config.yaml に追加：

mcp_servers:
  qmd:
    command: "qmd"
    args: ["mcp"]
    timeout: 30
    connect_timeout: 45

これにより以下のツールが登録されます：mcp_qmd_search、mcp_qmd_vsearch、 mcp_qmd_deep_search、mcp_qmd_get、mcp_qmd_status。

トレードオフ： モデルは最初の検索呼び出し時に読み込まれ（コールド時約 19 秒）、 その後セッション中はウォーム状態のままです。時々の使用には問題ありません。

オプション B：HTTP デーモンモード（高速、頻繁な使用に推奨）

qmd デーモンを別途起動 — メモリ内でモデルをウォーム状態に保ちます：

# デーモンを起動（エージェント再起動時に保持）
qmd mcp --http --daemon

# デフォルトで http://localhost:8181 で実行

その後、Hermes Agent を HTTP 経由で接続するように設定します：

mcp_servers:
  qmd:
    url: "http://localhost:8181/mcp"
    timeout: 30

トレードオフ： 実行中は約 2GB の RAM を使用しますが、すべてのクエリが高速です （約 2～3 秒）。検索が頻繁なユーザーに最適です。

デーモンを継続実行

macOS（launchd）

cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.qmd.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>qmd</string>
    <string>mcp</string>
    <string>--http</string>
    <string>--daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/qmd-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/qmd-daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

Linux（systemd ユーザーサービス）

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target

[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

MCP ツールリファレンス

接続すると、これらのツールが mcp_qmd_* として利用可能になります：

MCP ツール	マップ先	説明
mcp_qmd_search	qmd search	BM25 キーワード検索
mcp_qmd_vsearch	qmd vsearch	セマンティックベクトル検索
mcp_qmd_deep_search	qmd query	ハイブリッド検索 + 再ランキング
mcp_qmd_get	qmd get	ID またはパスでドキュメントを取得
mcp_qmd_status	qmd status	インデックスの状態と統計

MCP ツールはマルチモード検索のための構造化 JSON クエリを受け入れます：

{
  "searches": [
    {"type": "lex", "query": "authentication middleware"},
    {"type": "vec", "query": "how user login is verified"}
  ],
  "collections": ["project-docs"],
  "limit": 10
}

CLI 使用（MCP なし）

MCP が設定されていない場合、ターミナル経由で qmd を直接使用します：

terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)

セットアップと管理タスクでは、常にターミナルを使用してください：

terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")

検索パイプラインの仕組み

内部を理解すると、適切な検索モードの選択に役立ちます：

1. クエリ拡張 — 微調整された 1.7B モデルが 2 つの代替クエリを生成します。 オリジナルは融合で 2 倍の重みを取得します。
2. 並列検索 — BM25（SQLite FTS5）とベクトル検索がすべてのクエリ変形で 同時に実行されます。
3. RRF 融合 — Reciprocal Rank Fusion（k=60）が結果をマージします。 上位ランクボーナス：#1 は +0.05、#2-3 は +0.02。
4. LLM 再ランキング — qwen3-reranker がトップ 30 候補を採点（0.0～1.0）します。
5. 位置認識ブレンディング — ランク 1～3：75% 検索 / 25% 再ランカー。 ランク 4～10：60/40。ランク 11 以上：40/60（ロングテールで再ランカーをより信頼）。

スマートチャンキング： ドキュメントは自然な区切り点（見出し、 コードブロック、空白行）で分割され、約 900 トークンを対象に 15% のオーバーラップがあります。 コードブロックはブロック中間で分割されることはありません。

ベストプラクティス

1. 常にコンテキスト説明を追加 — qmd context add により検索精度が大幅に向上します。 各コレクションに含まれる内容を説明してください。
2. ドキュメント追加後に再度埋め込み — コレクションに新しいファイルが追加されるたびに qmd embed を再実行する必要があります。
3. 速度重視の場合は qmd search を使用 — コード識別子や正確な名前の高速なキーワード検索が必要な場合、 BM25 は即座でモデルが不要です。
4. 品質重視の場合は qmd query を使用 — 質問が概念的である、またはユーザーが最良の結果を必要とする場合、 ハイブリッド検索を使用してください。
5. MCP 統合を優先 — 設定されると、エージェントはこのスキルをロードすることなく ネイティブツールを取得します。
6. 頻繁なユーザーはデーモンモード — ユーザーがナレッジベースを定期的に検索する場合、 HTTP デーモンセットアップを推奨してください。
7. 構造化検索の最初のクエリは 2 倍の重みを取得 — lex と vec を組み合わせるときは、 最も重要/確実なクエリを最初に配置してください。

トラブルシューティング

「初回実行時にモデルをダウンロード中」

通常です — qmd は初回使用時に自動的に約 2GB の GGUF モデルをダウンロードします。 これは一度限りの操作です。

コールド スタート レイテンシ（約 19 秒）

これはモデルがメモリに読み込まれていない場合に発生します。解決策：

• HTTP デーモンモード（qmd mcp --http --daemon）を使用してウォーム状態を保つ
• モデルが不要な場合は qmd search（BM25 のみ）を使用
• MCP stdio モード最初の検索でモデルを読み込み、セッション中はウォーム状態のまま

macOS：「拡張をロードできません」

Homebrew SQLite をインストール：brew install sqlite その後、システム SQLite より前に PATH に確保してください。

「コレクションが見つかりません」

qmd collection add <path> --name <name> を実行してディレクトリを追加し、 その後 qmd embed を実行してインデックス化します。

埋め込みモデルオーバーライド（CJK/多言語）

非英語コンテンツについては、QMD_EMBED_MODEL 環境変数を設定します：

export QMD_EMBED_MODEL="your-multilingual-model"

データストレージ

• インデックス & ベクトル： ~/.cache/qmd/index.sqlite
• モデル： 初回実行時にローカルキャッシュに自動ダウンロード
• クラウド依存がない — すべてローカルで実行

リファレンス

• GitHub: tobi/qmd
• QMD Changelog