local-vault

local-vault

生ファイルのフォルダーを、LLM が grep できる Markdown vault に変換し、その vault の内容に基づいて責任ある形で質問に回答します。

基本的な考え方： SOURCE = 生ファイル（信頼できる情報源）。VAULT = ソースファイルごとに 1 つの .md ファイルを作成し、検索用のフロントマター（概要／タグ／同義語）と source へのバックリンクを付けたものです。LLM が読むのは vault のレイヤーで、ユーザーが確認するために参照するのは生ファイルです。

異なる 2 つの作業があります。ユーザーがどちらを求めているかを確認してください。

• A. 変換／同期 — ファイルを取り込んで vault に入れたい → パイプライン（scripts/sync.py）を実行します。
• B. 検索／回答 — 既存の vault から回答を得たい → 以下の 検索とフィードバックのプロトコル に従います。この場合、パイプラインは実行しないでください。

---

A. 変換／同期

初回セットアップ（未設定の場合はユーザーに代わって実施します）

1. Python の依存関係（仮想環境なし、ユーザーレベル）：

   python3 -m pip install --user requests python-dotenv pypdf pymupdf4llm openpyxl python-pptx
   

2. pandoc（docx/rtf/odt/epub 用）：brew install pandoc（macOS）／ディストリビューションのパッケージ。
3. ffmpeg（音声／動画の文字起こしにのみ使用）：brew install ffmpeg（macOS）／ディストリビューションのパッケージ。Whisper エンジンはプラットフォームに応じて自動選択されます。Apple Silicon では（GPU）mlx-whisper、それ以外では（クロスプラットフォーム対応の CPU/CUDA）faster-whisper が選ばれます。初回起動時のプロンプトでユーザーが同意すると、自動インストールされます（手動での pip は不要です）。音声／動画を含む状態で初めて実行すると、ツールにモデルサイズの選択肢（tiny 約 75 MB／small 約 480 MB／turbo 約 1.6 GB／large-v3 約 3 GB）が表示され、選択またはスキップできます。選択内容は .env（KB_WHISPER_MODEL）に保存されるため、再度尋ねられることはありません。すべてローカルで完結し、トークン／クォータは不要です。モデルは一度ダウンロードすれば、以降はオフラインで利用できます。
4. PATH 上の claude CLI — パイプラインはフロントマターの情報補完と PPT 画像の OCR に claude -p を使用します。存在しない場合、これらの手順はスキップされます（致命的なエラーにはなりません）。
5. パスを設定する — 方法は 2 つあります。
   • ガイド付き（ユーザーにおすすめ）： ターミナルで python3 scripts/sync.py を実行するだけです。初回実行時（パスがまだ設定されていない場合）に、対話式ウィザードが起動します。生ファイルのフォルダーと vault のフォルダー（および任意の MinerU トークン）を尋ね、フォルダーを作成して scripts/.env を書き込み、ツールの使い方を表示します。その後、もう一度実行すると変換が始まります。
   • 手動： scripts/.env.example を scripts/.env にコピーし、KB_SOURCE_DIR（生ファイル）と KB_TARGET_DIR（Markdown vault）に絶対パスを設定します。MINERU_TOKEN は任意です（レガシー形式の .doc/.ppt、.html、スキャン PDF、画像にのみ必要です。https://mineru.net で取得してください）。
   • あなた（Claude）がユーザーのセットアップを行う場合は、手動の方法を優先してください。2 つのフォルダーをユーザーに尋ねてから、scripts/.env を直接書き込みます（ウィザードが起動するのは対話型 TTY の場合のみであり、claude -p のサブプロセスでは起動しません）。

実行する

python3 scripts/sync.py

macOS では、初回実行時（ウィザードまたは通常実行）に、クリックして実行できる sync.command もナレッジベースのルート（SOURCE フォルダーの親フォルダー）に配置されます。 このファイルには sync.py の絶対パスが埋め込まれています（ツールとデータは別の場所にあります。 /plugin install では、スクリプトは ~/.claude/plugins/cache/… 内にあり、データフォルダーから 離れているため、相対パスのランチャーは機能しません）。その後の日常的な手順は、SOURCE に ファイルを入れる → sync.command をダブルクリックする → VAULT 内の .md を読む、です。 ランチャーは冪等です。以前のバージョンが SOURCE フォルダー内に残した古い自動生成コピーは 自動的に削除されます（ユーザーが作成したものには触れません）。ルートに別の sync.command がすでに存在する場合、対話型ターミナルでは更新／スキップを促します。 非対話型の場合、古くなった自動生成ランチャーは自動修復されますが、ユーザーがカスタマイズした ランチャーには触れません。

設定ファイルがない状態で初めてターミナルから実行すると、セットアップウィザードが起動します （上記を参照）。.env が存在する場合：

• 増分処理：SOURCE 内で、VAULT に対応する .md がないファイルだけを処理します。 再変換するには、まずその .md を削除してから、もう一度実行してください。
• ローカルの処理経路（xlsx/csv/docx/pptx/md/txt/コード＋デジタル PDF）では MinerU トークンは不要です。 トークンは遅延検証され、ファイルの処理に MinerU が実際に必要になったときだけ確認されます。
• 孤立ファイルの退避：ソースファイルが削除されると、対応するツール生成の .md と attachments/<stem>/ 内の画像は orphaned/<date>/ フォルダーに移動されます （ユーザーがメモを追加している可能性があるため、完全には削除しません）。空になった attachments/ は削除されます。ユーザーが作成した .md（コンバーターのマーカーがないもの）には 決して触れません。

ルーティング（ファイルの種類ごとに使用するツール）

種類	ツール	備考
.xlsx	openpyxl デュアルリード	シートごとに、値のグリッド（A/B/C＋行番号付き）と数式のリストを出力します
.csv / .tsv	csv → Markdown テーブル	CSV_MAX_ROWS を超える行は切り捨てます
.pdf（デジタル）	pymupdf4llm	ローカル処理で高速、クォータ不要です。PYMUPDF4LLM_WRITE_IMAGES（デフォルトで有効）が設定されている場合、ページの 12％以上の大きさの画像（PYMUPDF4LLM_IMAGE_SIZE_LIMIT）は attachments/ に出力され、その後、最小バイト数の条件でフィルタリングされ、重複が除去されます。pymupdf4llm がクラッシュした場合（フォント不足など）、MinerU を試す前にローカルでプレーンテキスト抽出を試します
.pdf（スキャン）	MinerU vlm（フォールバック）	1 ページあたりの文字数が少なすぎる場合に実行されます
.docx/.rtf/.odt/.epub	pandoc	画像は attachments/ に抽出されます
.html/.htm	pandoc（ローカル）	まず style/class/id 属性とレイアウト用の div/section/span を取り除き、コンテンツだけを残します。テーブルは損失なく保持されます。MinerU／トークンは不要です
.pptx	python-pptx	タイトル／本文／テーブル／グラフ／ノート＋画像。スマート OCR（下記参照）
.md/.markdown/.txt	パススルー	そのままコピーします。frontmatter のみ追加し、本文には手を加えません
.json/.yaml/.py/…	コードのパススルー	フェンス付きコードブロックで囲み、frontmatter を追加します
音声 .mp3/.m4a/.wav/…＋動画 .mp4/.mov/.m4v	whisper（ローカル。エンジンは自動選択：Apple Silicon では mlx-whisper、それ以外では faster-whisper）	音声をテキストに変換します。トークン／クォータは不要です。初回実行時に、サイズを表示したうえでモデルを選択します。また、同意するとエンジンが自動インストールされます（このマシンにキャッシュ済みのモデルがあれば、再確認せずに再利用します）。各セグメントに [mm:ss] のタイムスタンプと検出された言語が付きます。動画では音声トラックのみが対象です（ffmpeg でコンテナから音声を取り出します）。ffmpeg が必要です。明瞭な音声に最適です。歌や音楽の文字起こし精度は低くなります
レガシー形式の .doc/.ppt、画像	MinerU（クラウド）	ローカルライブラリではこれらのファイルを読み取れません
その他すべて（numbers/pages/zip/…）	スキップ	修正のヒントとともに最後に報告され、何も通知せずに無視されることはありません

PPT のスマート OCR

スライドに埋め込まれた画像は claude -p（画像は Read ツールで読み取ります）を使って OCR を実行します。ただし、装飾的なロゴごとに処理の遅い claude を起動しないよう、同一画像を重複排除して（OCR は 1 回のみ）、OCR_MIN_IMAGE_BYTES 未満の画像をスキップし、コンテンツを含む固有の画像は並行して処理します（OCR_MAX_WORKERS）。PowerPoint のネイティブなグラフオブジェクトは直接読み取り、カテゴリと系列の値を表に変換します。OCR を完全に無効にするには、OCR_PPTX_IMAGES = False に設定してください（画像の抽出と参照は引き続き行われます）。

すべての .md に書き込まれるフロントマター

---
source: "[[…/<file>.<ext>]]"   # backlink to the raw file
source_type: pdf | xlsx | docx | pptx | md | …
converted_by: pymupdf4llm | pandoc | python-pptx | excel-openpyxl | csv | passthrough | whisper | "MinerU vlm" | …
# enrich (best-effort via claude -p, may be missing on failure):
abstract: |
  3-sentence summary.
auto_tags: [..]
synonyms: [English + 中文 同义词]   # so any phrasing greps the right doc
key_data: ["important numbers/facts"]
---

調整（scripts/config.py）

PYMUPDF4LLM_MIN_CHARS_PER_PAGE（スキャン PDF のしきい値） · PYMUPDF4LLM_WRITE_IMAGES（デジタル PDF の画像抽出の有効／無効。.env： 無効にするには KB_PDF_NO_IMAGES=1） · PYMUPDF4LLM_IMAGE_SIZE_LIMIT（ページ面積に対する割合で指定する抽出の下限。デフォルトは 0.12） · PYMUPDF4LLM_IMAGE_MIN_BYTES（このサイズ未満の画像を除外。デフォルトは 6000） · OCR_PPTX_IMAGES / OCR_MIN_IMAGE_BYTES / OCR_MAX_WORKERS（PPT 画像の OCR） · EXCEL_MAX_CELLS_PER_SHEET · CSV_MAX_ROWS · ENRICH_FRONTMATTER。

---

B. 検索とフィードバックのプロトコル（ボルト内の情報に基づく回答）

ユーザーからボルト内の情報に基づく回答や、ボルト内の資料間の比較を求められたら、ボルトを直接読み取ってください（grep と .md の読み取り）。その際、問題がないかを自分で確認し、見つかった問題を伝えてください。回答するだけで終わらせないでください。

ボルトのヘルスチェック（セッション中、ボルトについて最初に質問されたとき）

find "$KB_TARGET_DIR" -name "*.md" -not -path "*/.obsidian/*" | wc -l   # file count

おおよその規模を判定し、問題がある場合にのみ伝えてください： 小規模（100 ファイル未満）ならエージェントによる grep で十分です · 中規模（100～500）ならキーワードのヒット数に注意してください · 大規模（500～2000）ならセマンティック検索レイヤー（Smart Connections など）の導入を提案してください · 超大規模（2000 超）なら本格的な RAG レイヤーを推奨してください。

複雑なクエリの後のセルフチェック（条件に該当した場合のみ警告）

シグナル	ユーザーへの伝え方
1 回の grep で 30 ファイル超にヒット	キーワードが広すぎます。より絞り込んだものを提示するか、セマンティック検索を追加してください
5 ファイル以上を読んでも回答が見つからない	同義語の不足が原因か、実際にボルト内にない可能性があります。読み取ったファイルを列挙してください
同じトピックについて繰り返し質問される	そのトピックのインデックス／MOC の作成を提案してください
「X を扱っている章はどれか」という質問に全文の読み通しが必要	その文書のアウトラインを充実させることを提案してください
文書に abstract がない	情報の補完に失敗した可能性があります。やり直しを提案してください
質問に正確な数値／数式が必要	source のバックリンクをクリックして、原文と照合するよう案内してください

トピックに関する質問 → MOC の追加順序と発展

MOC（Map of Content）は、あるテーマへの入口となるユーザーのノートです。フロントマターの type: moc を持ち、<vault>/索引/（または index/）に保存されます。

1. 複数の文書にまたがるトピックについて質問されたら、まず関連する MOC があるか確認してください。ある場合は、最初にそれを読み、回答の骨組みとして使ってください。
2. 該当する MOC がなく、ユーザーがこのテーマについて繰り返し質問する場合は、最小限の MOC（フロントマターと ## related files のリストのみ。ほかは追加しない）の作成を提案してください。
3. MOC の構成は、実際の利用に応じて発展させてください。あらかじめ設計してはいけません。パターン（よく尋ねられるサブトピック、繰り返し現れる判断、未解決の質問）に気づいたら、それを定着させることを提案してください。実際に作成するかどうかはユーザーが決め、あなたが下書きします。

頻度制限（しつこくならないため）： MOC の発展に関する提案は、セッションごとに1 回までとします。この MOC を 7 日以内に提案していた場合は提案を省略してください。何気ない質問が 1 回あっただけではなく、複数のシグナルから実際のパターンが確認できることを条件とします。提案は、単一の > 💡 … 引用ブロックに収めてください。

禁止事項

• 毎回の回答に「ヒント」を大量に付け加えないでください。シグナルが発生したときだけ伝えてください。
• 質問に回答するだけのために変換パイプラインを実行しないでください。
• ボルト内の .md ファイルを一括編集しないでください（ユーザーのノートとツールの出力が混在しています）。
• grep で見つからなかった内容を作り上げないでください。推測するよりも「ボルト内にありません」と伝えてください。
• 原文を MOC にコピーしないでください。Wiki リンクと 1 行の注釈のみを記載してください。

---

メモ

• このパイプラインは、実行中の Claude セッションに依存しません。CLI であり、任意の enrich／OCR ステップで claude -p を呼び出すだけです。
• ドキュメントの本文を書き換えることはありません。自動処理はすべてフロントマターのみを対象とするため、このツール自体によるコンテンツ損失のリスクはありません。
• 正式なテスト済みソースは作者の開発プロジェクトにあります。ここにある scripts/ はパッケージ化されたスナップショットです。