手元のPCだけで動く！メモ・議事録・ドキュメントを横断検索するAIミニ検索エンジン — qmd

アーキテクチャ・仕組み

QMDは3つの検索手法を組み合わせたハイブリッド検索パイプラインを採用しています：

1. BM25全文検索: SQLite FTS5を利用したキーワードベースの高速検索
2. ベクトル意味検索: 文書をベクトル化（埋め込み）し、意味的な類似度で検索
3. LLMリランキング: AI（大規模言語モデル）が検索結果の関連度を再評価して並べ替え

検索パイプラインの流れ

• ユーザーのクエリをLLMで2つの変形クエリに拡張（元のクエリは×2の重み付け）
• 各クエリでBM25とベクトル検索を並列実行
• **RRF（Reciprocal Rank Fusion）**で結果を統合（k=60）
• 上位30件をLLMで再ランキング
• 位置対応ブレンディング：上位1-3位はRRF 75%/リランカー 25%、4-10位は60%/40%、11位以降は40%/60%

使用AIモデル（すべてローカル実行）

モデルは初回利用時にHuggingFaceから自動ダウンロードされ、~/.cache/qmd/models/にキャッシュされます。

スマートチャンキング

文書を約900トークン単位、15%オーバーラップで分割。Markdownの見出し・コードブロック・水平線などの構造を考慮してスコアリングし、意味的なまとまりを保つ位置で分割します。

AST対応チャンキング（--chunk-strategy auto）: tree-sitterでソースコードの構文木を解析し、関数・クラス・import文の境界で分割。対応言語は .ts, .tsx, .js, .jsx, .py, .go, .rs。

対応環境

• Node.js >= 22 または Bun >= 1.0.0
• macOS: Homebrewでsqliteのインストールが必要
• LLM実行は node-llama-cpp を使用（GGUF形式モデル）

多言語対応

QMD_EMBED_MODEL環境変数でカスタム埋め込みモデルに切り替え可能。日本語・中国語・韓国語にはQwen3-Embedding-0.6Bが推奨（119言語対応）。

MCP（Model Context Protocol）サーバー

• stdio（デフォルト）とHTTPトランスポートに対応
• HTTP版はデーモンとして起動可能で、モデルをVRAMに常駐させて応答速度を向上
• Claude Desktop、Claude Codeと直接連携可能
• 公開ツール: query, get, multi_get, status

SDK（ライブラリとしての利用）

@tobilu/qmdをnpmパッケージとしてインストールし、Node.js/Bunアプリケーションに検索機能を組み込める。createStore()で初期化し、search(), get(), multiGet()などのAPIを利用可能。TypeScriptの型定義も完備。

データストレージ

SQLiteベース（~/.cache/qmd/index.sqlite）。sqlite-vecエクステンションでベクトルインデックスを管理。

出力形式

CLI（カラー出力、OSC 8ターミナルハイパーリンク対応）、JSON、CSV、Markdown、XMLに対応。QMD_EDITOR_URIでVS Code、Cursor、Zed、Sublime Textへのリンクをカスタマイズ可能。

ライセンス

MIT（商用利用含め自由に利用可能）

# グローバルにインストール（Node.js または Bun）
npm install -g @tobilu/qmd
# または
bun install -g @tobilu/qmd

# インストールなしで直接実行も可能
npx @tobilu/qmd ...

# コレクション（検索対象フォルダ）を登録
qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings

# コンテキスト（説明文）を追加して検索精度を向上
qmd context add qmd://notes "Personal notes and ideas"

# ベクトル埋め込みを生成（初回のみ必要、モデルは自動ダウンロード）
qmd embed

# 検索開始！
qmd search "project timeline"      # キーワード検索
qmd vsearch "how to deploy"        # 意味検索
qmd query "quarterly planning"     # ハイブリッド検索（最高品質）