qmd

QMD - Markdown ドキュメントを検索

検索の仕組み

QMD は、メモ、ドキュメント、ウィキ、文字起こし、プロジェクトのナレッジベースなど、ローカルの Markdown コレクションを検索します。答えがインデックス済みのローカルファイルにすでにある可能性がある場合は、ウェブ検索の前に使用してください。

ワークフローは常に次のとおりです。

1. 候補となるドキュメントを検索します。
2. qmd get または qmd multi-get でソース全体を取得します。
3. 取得したテキストに基づいて回答し、パスまたは docid を引用します。

ユーザーが事実、決定事項、引用、または細かなニュアンスを必要としている場合は、スニペットだけをもとに回答しないでください。スニペットは手がかりにすぎません。

典型的な流れ：

qmd search "merchant reality support interviews" -n 5
# leads: #abc123 concepts/customer-proximity.md; #def432 sources/merchant-call.md
qmd multi-get "#abc123,#def432" --format md

自分で intent:、lex:、vec:、hyde: フィールドを記述した、構造化された qmd query を基本にしてください。 組み込みモデルよりも、あなたのほうがクエリを適切に拡張できます。ユーザーの実際の目的、分野の用語、避けるべき類似するが誤った概念を把握しているからです。ユーザーの言葉をそのまま qmd query "..." に貼り付けて、拡張モデルが正しく推測することに期待しないでください。intent: を指定し、語彙的・意味的な用語を慎重に組み立ててください（適切な検索モードを選ぶを参照）。

取得した内容を報告する際は、必要がない限りファイル全体を貼り付けず、簡潔なメモで十分です。

Retrieved:
- #abc123 concepts/customer-proximity.md
- #def432 sources/merchant-call.md

適切な検索モードを選ぶ

正確な単語、タイトル、名前、コードシンボル、または珍しいフレーズがわかっている場合は、BM25 語彙検索を使用します。

qmd search "cockpit OKR Goodhart" -n 10
qmd search '"AI Before Headcount"' -c concepts -n 5

ユーザーがアイデアを間接的に説明している場合、ソースとは異なる言葉を使っている場合、または概念的な情報の検索が必要な場合は、構造化フィールドを使った qmd query を使用します。これがデフォルトのモードです。クエリ拡張に頼るのではなく、自分でフィールドを記述してください。 正確な手がかりと意味的な検索を組み合わせます。

qmd query $'intent: Find the concept note about metrics as instruments without letting OKRs replace judgment.\nlex: cockpit instruments OKR Goodhart metrics judgment\nvec: data informed not metric driven product judgment\nhyde: A concept note says metrics are useful like cockpit instruments, but leaders should remain data-informed rather than metric-driven because OKRs and dashboards can Goodhart product judgment.'

構造化クエリフィールド（それぞれ自分で記述してください。拡張モデルに任せないでください）：

• intent: 何を見つけようとしているのか、何を避けるべきかを記述します。必ず指定してください。類似するが誤った概念を避けるよう、ランキングを調整します。
• lex: ソースに含まれていると予想される正確な用語、別名、タイトル、コードシンボル、珍しい単語です。これは自分で行うキーワードの拡張です。
• vec: ソースに近い言い回しで、アイデアを自然言語で言い換えます。
• hyde: リクエストを満たすドキュメントや回答を説明します。

毎回 4 つすべてを使う必要はありませんが、ほぼ常に intent: と lex:／vec: のいずれか 1 つ以上を記述してください。単に qmd query "the user's sentence" と指定すると、自分だけが持つコンテキストを活用できず、組み込みの拡張機能にその再構成を任せることになります。構造化形式を優先してください。

本当に拡張するものがない場合（珍しいトークンが 1 つだけ、または原文どおりのフレーズなど）は、単独の qmd query ではなく、qmd search を使います。

qmd query --format json --explain $'intent: ...\nlex: ...\nvec: ...'  # inspect ranking

qmd query が遅い場合や、モデル／GPU のセットアップに失敗した場合は、より適切な語彙用語を使った qmd search に切り替えてください。

ソースを取得

検索結果には #abc123 のような docid と qmd://... パスが含まれます。取得してください。

qmd get "#abc123"
qmd get qmd://concepts/ai-before-headcount.md
qmd multi-get "#abc123,#def432" --format md
qmd multi-get 'concepts/{ai-before-headcount.md,data-informed-not-metric-driven.md}' --format md
qmd multi-get 'sources/podcast-2025-*.md' -l 80

複数の検索結果を比較する場合や、ページをまたいでコンテキストを集める場合は、multi-get を使用します。

出力には行番号と docid が含まれます — 両方を引用してください

get と multi-get はデフォルトで行番号付きで、ドキュメントの #docid と qmd:// パスを常に出力します。そのため、get の出力は次のようになります。

qmd://concepts/note.md  #abc123
---

1: # Metrics as instruments
2:
3: Treat dashboards like cockpit instruments...

回答では docid と正確な行番号を引用し、行番号を使って次の範囲を指定してください。コードブロックをそのまま再現する場合など、生のコンテンツをそのままコピーする必要があるときに限り、--no-line-numbers を渡してください。

元のファイルを開いたり編集したりする必要がある場合（たとえば、Read、Edit、またはエディターにパスを渡す場合）は、--full-path を追加してください。これを指定すると、qmd:// URL と docid のヘッダーがファイルのディスク上のパスに置き換わります。ファイルがディスク上に存在しなくなっている場合は、標準のヘッダーが使われます。

$ qmd get "#abc123" --full-path
/Users/you/notes/concepts/note.md
---

1: # Metrics as instruments

--full-path は qmd search と qmd query でも同じように機能します。結果のパスがファイルのディスク上のパスになります。ファイルが $PWD 内にある場合は ./ で始まる相対パス、そうでない場合は絶対実パスです。パスが識別子になるため、結果ごとの #docid は省略されます。先頭の ./ は意図的なもので、出力がファイルシステム上のパスであることを明確にし、コレクション相対の文字列と誤認されないようにしています。デフォルトの search/query 出力では引き続き qmd:// URI が使われます。QMD 以外のツールに渡せるパスが必要な場合に限り、--full-path を指定してください。

:from:count サフィックスで行範囲を読み取る — sed／head／tail にパイプしないでください

qmd get はファイルを自分で範囲指定して読み取ります。サフィックスまたはフラグを使い、行範囲を取り出すために sed -n、head、tail、awk を実行しないでください。パイプを使うと docid の解決、仮想パスの検索、行番号付け、ヘッダーが機能しなくなり、速度も落ち、エラーも起きやすくなります。

最も簡潔な形式は、パスまたは docid に直接付ける :from:count サフィックスです。これを優先してください。

qmd get "#abc123:120:40"                  # 40 lines starting at line 120
qmd get qmd://concepts/note.md:200:60     # lines 200–259
qmd get "#abc123:120"                      # from line 120 to end of file
qmd get "#abc123" --from 120 -l 40         # equivalent, using flags

サフィックスとフラグ：

• <path>:<from>:<count> — 行 <from> から開始し、<count> 行を読み取ります。検索ヒットの前後を読むのに最適です。
• <path>:<from> — <from> から開始し、ファイルの末尾まで読み取ります。
• --from <line> / -l <lines> — フラグで同じ指定ができます。明示的なフラグはサフィックスより優先されるため、... :5:2 -l 1 は 1 行を読み取ります。
• --no-line-numbers — N: の接頭辞を省略します（行番号はデフォルトで付与されます）。

誤り：qmd get "#abc123" | sed -n '120,160p' 正しい：qmd get "#abc123:120:40"

検索結果には各ヒットに :line アンカーが含まれます。これをそのまま qmd get path:line:<n> に渡すと、一致箇所の前後の範囲を読み取れます（出力の行番号は line から始まります）。

インデックス対象を確認する

qmd collection list
qmd ls
qmd status

広範囲の検索が誤ったコーパスに逸れる場合は、コレクションのフィルターを追加してください。

qmd search "headcount autonomous agents" -c concepts -n 10
qmd query "merchant support product reality" -c concepts -c sources -n 10

すべてを検索するには -c を省略します。

メタデータでフィルターする

ドキュメントには、qmd.metadata フロントマターブロックに型付きメタデータ（文字列、数値、ブール値、または一次元配列）を含めることができます。search、vsearch、query は再帰的な JSON AST を指定する --filter を受け付け、返される結果はすべてその条件を満たします。

qmd search "authentication" --filter '{"key":"status","operator":"eq","value":"published"}'
qmd query "dependency injection" --filter '{"operator":"and","operands":[{"key":"topics","operator":"all","value":["typescript"]},{"key":"status","operator":"nin","value":["draft","archived"]}]}'

ノードは operator によって区別されます。グループ and／or は operands を取り、not は単一の operand を取ります。条件は key と value に加え、比較用の演算子 eq／ne／gt／gte／lt／lte、包含判定用の in／nin／all、または存在判定用の exists を取ります。一致判定は型付きで厳密です。キーが存在しない場合、ne／nin には一致しません（そのようなキーも含めるには、or グループに exists: false の分岐を追加してください）。MCP の query ツールは、同じ AST を filter オブジェクトとして受け付けます。JSON 出力には各結果の metadata が含まれます。

MCP ツール：query

MCP サーバーを使用する場合は、構造化検索を優先してください。

{
  "searches": [
    { "type": "lex", "query": "cockpit OKR Goodhart" },
    { "type": "vec", "query": "data informed not metric driven product judgment" },
    { "type": "hyde", "query": "A concept note explains that metrics are useful as instruments, but leaders should not let OKRs or dashboards replace judgment." }
  ],
  "intent": "Find the concept note about using metrics as instruments without becoming metric-driven.",
  "collections": ["concepts"],
  "limit": 10
}

クエリの種類：

• lex — BM25 キーワード検索です。正確な用語、名前、タイトル、コードの検索に最適です。
• vec — ベクトル意味検索です。自然言語による概念の検索に最適です。
• hyde — 仮説的な回答／ドキュメントの一節を使ったベクトル検索です。

クエリの作成

効果的な QMD 検索では、次の 3 つを組み合わせます。

1. タイトル／別名の手掛かり： 正確なページタイトル、固有表現、フレーズ。
2. 意味的な言い換え： 人間がそのアイデアをどのように説明するか。
3. 除外すべき範囲： 近接しているものの誤った概念を避けるのに十分な意図の指定。

例：

# Exact-ish title lookup
qmd search '"arm the rebels" merchants tools big companies' -c concepts

# Semantic concept lookup
qmd query $'intent: Find the customer proximity concept, not generic customer delight.\nlex: support pseudonymous merchant customer interviews\nvec: founder stays close to merchant reality through support and product use'

# Source lookup
qmd search "six-week cadence WhatsApp merchant relationships Shawn Ryan" -c sources -n 10

セットアップとメンテナンス

ユーザーがセットアップまたはメンテナンスを依頼した場合にのみ、インデックスを変更してください。検索と取得は安全ですが、コレクションやインデックスの変更を安易に最初の手段にしてはいけません。

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

ヘルスチェックと診断：

qmd doctor
qmd status
qmd pull

qmd doctor は、設定、モデルキャッシュ、デバイス／GPU のセットアップ、ベクトルのフィンガープリント、一般的な環境変数による上書きを確認します。モデルを使用するコマンドが失敗した場合は、設定を変更する前に実行してください。

MCP のセットアップ

Claude Code、Claude Desktop、OpenClaw、HTTP サーバーの設定については、references/mcp-setup.md を参照してください。

注意点

• スニペットだけで済ませないでください。 主張を述べる前に、ドキュメントを取得してください。
• sed／head／tail でファイルを切り出さないでください。 path:from:count サフィックス（例：qmd get "#abc123:120:40"）または --from／-l を使ってください。出力にはすでに行番号が付いています。パイプを使うと、docid の解決、ヘッダー、仮想パスが壊れます。
• クエリ拡張に頼りすぎないでください。 intent:／lex:／vec:／hyde: は自分で記述してください。qmd query "user sentence" のような単純なクエリでは、あなたにしかないコンテキストが失われます。クエリを拡張するのはあなたであり、モデルは順位付けをするだけです。
• セマンティック検索を多用しないでください。 正確なタイトルや用語がわかっている場合は、BM25 の方が高速で、多くの場合より適切です。
• インデックスを安易に変更しないでください。 qmd collection add、qmd update、qmd embed はローカルの状態を変更し、コストがかかる場合があります。
• モデルを使用するコマンドは環境の影響を受けることがあります。 ローカルモデル／GPU が利用できないために qmd query、qmd vsearch、または再ランキングが失敗した場合は、qmd search と、より具体的な語句や構造化された語句を使ってください。
• ユーザーの曖昧な表現には意図を補ってください。 クエリ拡張が適切なドメインを推測することに期待せず、intent: を追加してください。
• コレクション名は重要です。 統合された Wiki ページは concepts、トランスクリプト／未加工のソースページは sources、コードやプロジェクトのドキュメントはドキュメント用コレクションを検索してください。