ローカルドキュメント探しの工数を、CLI一発に圧縮した話
ローカルに仕様書や議事録が増えるほど、目的のドキュメントに到達するまでの探索コストが増える。
特に古いドキュメントは「保存場所」「ファイル名」「当時の表現」が曖昧になりやすく、キーワード検索ではヒット率が下がる。結果として、複数ファイルを開いて中身を確認する作業が発生し、時間がかかる。
この探索を短縮するために、ローカルファイルをデータ化してセマンティック検索（意味検索）できる仕組みを導入した。
整理のジレンマと方針転換
効率化のために整理（命名規則・フォルダ構造・タグ運用など）を徹底する方法はあるが、運用コストが継続的に発生する。
一方で、整理をしないと検索コストが上がる。このトレードオフがある。
そこで「整理に寄せる」のではなく、「検索側を強化して運用を単純化する」方針に寄せた。
具体的には、検索対象ディレクトリを決めて、そこにドキュメントを集約し、発見は検索に委ねる。
採用したツール：QMD（Quick Markdown Search）
採用したのは QMD（Quick Markdown Search）。Markdownを対象にローカルで検索できるCLIで、BM25全文検索・ベクトル検索・LLMリランキングを組み合わせた構成になっている。
作業環境は以下。
- OS：macOS
- 実行：ローカルLLMで実行
今回やったこと（フォークして調整）
公式リポジトリをフォークしてローカルに展開し、以下を実施した。
- 日本語対応：正規化を入れて検索の揺れを低減
- LLMモデルバージョンの不整合を解消（モデル指定を調整）
- bunと依存ライブラリを導入
- 動作確認
LLMモデル指定は以下のように調整した（自分の修正メモ）。
const DEFAULT_GENERATE_MODEL = "hf:ggml-org/Qwen3-0.6B-GGUF/Qwen3-0.6B-Q8_0.gguf";
// const DEFAULT_GENERATE_MODEL = "hf:ggml-org/Qwen3-1.7B-GGUF/Qwen3-1.7b-q8_0.gguf";
QMDの使い方（導入から検索まで）
以下は、READMEのQuick Startに沿った手順。
1) インストール
bun install -g https://github.com/ryujimorimoto/ja-qmd
2) 検索対象ディレクトリをコレクションとして登録
検索対象を複数登録できる。例：notes / meetings / docs。
qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings
qmd collection add ~/work/docs --name docs
3) コレクションに文脈情報を付与（任意）
検索結果に補助情報を持たせる用途。
qmd context add qmd://notes "Personal notes and ideas"
qmd context add qmd://meetings "Meeting transcripts and notes"
qmd context add qmd://docs "Work documentation"
4) 埋め込み（Embedding）作成
ベクトル検索を使う場合、事前にEmbeddingを生成する。
qmd embed
検索コマンドの使い分け
QMDは複数の検索方法を提供している。
キーワード検索（BM25中心）
qmd search "project timeline"
セマンティック検索（ベクトル検索）
qmd vsearch "how to deploy"
ハイブリッド検索＋LLMリランキング
qmd query "quarterly planning process"
今回の用途（要件のニュアンスで探す）では query が適している。
ドキュメント本文の内容も参照し、候補と一致度（スコア）を提示するため。
結果の取得（本文確認）
検索結果に出たファイルを取得して確認する。README上の例は以下。
qmd get "meetings/2024-01-15.md"
qmd get "#abc123"
qmd multi-get "journals/2025-05*.md"
qmd get notes/meeting.md:50 -l 100
補助オプション（絞り込み・出力形式）
コレクションを絞る、JSONで出すなど、運用に合わせた出力が可能。
qmd search "API" -c notes
qmd search "authentication" --json -n 10
qmd search "API" --all --files --min-score 0.3
qmd query "error handling" --all --files --min-score 0.4
インデックスの更新・状態確認
索引の状態確認や更新。
qmd status
qmd update
qmd update --pull
導入効果（作業時間）
- 導入前：探索に 10〜20分
- 導入後：探索に 数十秒
「こんな要件の仕様書を探して」という入力から、文脈で候補を提示し、本文まで確認して一致度（%）を返す挙動が得られた。
課題・改善点と今後
課題・改善点
- CLIで候補提示はできるが GUIがない
- まずMarkdownを対象にしているが、将来的には docs / csv / xlsm など他形式、画像・動画も検索対象にしたい
Discussion