Shelfmark

shelfmark

ファイルシステム全体ではなく、AI エージェントに適切なコンテキストを与えましょう。

Shelfmark は、長年にわたって散在してきたドキュメントを、AI エージェント向けの管理されたコンテキストマップに変えます。エージェントは、どんな資料があるのかを見つけ、その種類を把握し、タスクに関連するドキュメントを選択できます。ファイルを開いてコンテキストを消費する前に、必要な資料を絞り込めます。

ドキュメントの移行は不要です。コンテンツの重複保存もありません。完璧なフォルダー構成も必要ありません。

uv tool install shelfmark          # or: pipx install shelfmark

ローカル利用を前提 · メタデータのみ · 管理された検索 · MCP 向けに構築

---

貴重な知識は、おそらくフォルダーの中に眠っています

レポート、プレゼンテーション、モデル、調査資料、提案書、作業ドキュメントは、何年にもわたって蓄積していきます。丁寧に整理されたものもあれば、ファイルが詰め込まれたプロジェクトフォルダー、古いアーカイブ、ダウンロードフォルダー、あるいは当時は意味があった資料群の中に埋もれているものもあります。

その価値は今も残っています。問題は、エージェントが見つけられないものは活用できないということです。そして、エージェントにファイルシステムへの無制限のアクセスを与えても解決にはなりません。何千ものファイルを探し、解釈し、絞り込む作業をコンテキストウィンドウに押しつけることになるからです。

Shelfmark は、まずエージェントにマップを提供します。

限られたリソースであるコンテキスト

エージェントにすべてのドキュメントが必要なわけではありません。どんな資料があり、何が関係しそうで、どこから来たのか、そしてそもそも利用すべきかを知る必要があります。

Shelfmark は、エージェントとファイルの間にある検索レイヤーです。エージェントはカタログを検索して候補を絞り込み、タスクに本当に必要な資料だけを取得します。これにより、ファイルシステム全体を巨大なプロンプトにすることなく、既存のドキュメント群を作業用コンテキストとして活用できます。

新たなドキュメントストアではなく、参照情報のカタログ

Shelfmark は、参照情報と派生メタデータのローカル SQLite カタログを構築します。対象となるのは、パス、ファイル名、形式、サイズ、ドキュメントの種類、作成者、日付、分類、選択された Office プロパティ、プレゼンテーションのタイトル、任意のコンテンツハッシュです。

ドキュメントをカタログにコピーすることはありません。ドキュメント本文のテキストをインデックス化することもありません。管理、同期、保守が必要な別のリポジトリを作ることもありません。ファイルは元の場所に残り、カタログはその参照先と、メタデータから確認できる情報を記録します。

ドキュメントを見つけても、その内容が公開されるわけではありません。

雑然としたフォルダーを、エージェントが活用できるコンテキストに

Shelfmark を使うために、整った情報アーキテクチャを設計する必要はありません。蓄積されたプロジェクトファイル、忘れられたアーカイブ、長年にわたってドキュメントが置かれてきたフォルダーを指定してください。

すでに存在する情報、つまりファイル名、拡張子、パス、作成者、日付、Office プロパティ、独自の分類ルールをもとにインベントリを構築し、資料全体に仮想的な構造を作り出します。ファイルを移動したり名前を変更したりしなくても、エージェントはドキュメントの種類、クライアント、プロジェクト、目的、作成者、年、場所から検索できます。

フォルダーが整理されていなくても、見つけやすくすることはできます。

Shelfmark は、メタデータでわかることの限界についても正直です。有用なプロパティのない final7.pdf というファイル名だけでは、誰かが内容を読まない限り、その意味はわかりません。Shelfmark は確実性を作り上げるのではなく、わかっていることを示します。実際には存在しない見出しを 12 個列挙する代わりに、プレースホルダーのスライドタイトルを除外するのも同じ理由です。

選択的なコンテキストのために構築

• 開く前に見つける。 どのファイルに注目するかを決める前に、何千もの参照資料を検索できます。
• コンテキストウィンドウを維持する。 関連性がない可能性のある文書全体ではなく、簡潔なカタログ結果を表示します。
• これまでの作業を活用する。 レポート、モデル、提案書、調査、手法を、新しいタスクや今後の業務でも見つけられるようにします。
• 出所を明確にする。 パス、日付、作成者、文書の種類、周辺のコンテキストにより、エージェントが関連性を判断しやすくなります。
• 手探りの探索を減らす。 ディレクトリを何度もたどり、ファイルを一つずつ確認する代わりに、構造化検索を行います。
• 発見とアクセスを分ける。 Shelfmark は資料の特定を支援します。元のファイルを開くかどうかは、別途制御できる判断です。

ルートが信頼境界になります

Shelfmark がたどるのは、設定したルートだけです。

シンボリックリンクはたどりません。 ルート内のリンクは通常のファイルとして読み取られますが、そうしなければ設定したツリーの外へそのままたどれてしまいます。また、hash はファイルを開きます。スキップされたリンクは報告され、黙って除外されることはありません。別のツリーをインデックス化するには、追加のルートとして登録してください。境界を広げるには、設定で明示します。リンクを置くことで広げることはできません。

カタログがいずれかのルート内にある場合、その作成は拒否されます。データベースが自分自身をインデックス化すると、更新のたびに増え続けるためです。どちらのチェックでも解決済みパスを比較するため、.. やシンボリックリンクされたルートで回避することはできません。

ガバナンスは検索レイヤーに組み込まれています

役立つ文書をすべて同じように扱うべきとは限りません。Shelfmark は、通常混同される2つの問いを分けて扱います。

• 所有者は誰か、再利用できるのは誰か？ → rights：OWN ／ REFERENCE ／ RESTRICTED
• この文書を現在のコンテキストの外に持ち出してよいか？ → confidential：0 ／ 1

手法はあなたの所有物であっても、それを含むクライアント向け成果物は機密扱いのままかもしれません。この2つを別々にモデル化することで、エージェントは、発見できるものすべてを自由に共有できると見なすことなく、再利用可能な知識を見つけられます。

プライベート／秘密のパターンに一致するファイルは RESTRICTED になります。どのツールも、そのパス、名前、メタデータ、内容を返しません。引数で上書きすることもできず、ハッシュ化のために開かれることもありません。また、データベースは読み取り専用で開かれます。corpus_stats() が報告するのは、封印されたファイルのコーパス全体での件数だけで、それ以外の情報は一切ありません。どのルートか、どのフォルダーかも示しません。この件数だけは意図的に開示されます。これについて何も知らせないと、コーパスの規模を誤って伝えることになるためです。

ガバナンスはカタログによって適用され、プロンプトの文言任せにはなりません。

マップの信頼性を確認する

エージェントがカタログの最新性を把握していなければ、検索結果は役に立ちません。

MCP サーバーは実行中に独自のインデックスを最新の状態に保つため、スケジュールを設定する必要も、エージェントが覚えておく必要もありません。インデックスを最新に保てない場合（未構築、古い状態、更新失敗、時刻を判断できない場合、またはインデックスがファイルシステムと一致しなくなった場合）、すべてのツールが回答の前にその旨を伝え、corpus_stats() はインデックスとディスクを全件比較します。

古いスナップショットが、完全な知識として提示されることはありません。

知識集約型の業務のために設計

コンサルタントおよびアドバイザー	関係のないクライアント資料を公開せずに、過去の分析、提案書、フレームワーク、成果物を見つけられます。
研究者およびアナリスト	一貫したメタデータを通じて、レポート、データセット、資料の大規模なコレクションをたどれます。
製品および戦略チーム	プロジェクトや時間をまたいで、意思決定、調査、ロードマップ、過去の考察を再び結び付けられます。
スタジオおよび独立事業者	クライアントのファイルや知的財産を管理しながら、長年蓄積した作業を再利用可能なコンテキストに変えられます。
エージェント開発者	MCP を介して、ローカルエージェントにガバナンスの効いた発見レイヤーを提供できます。

仕組み

1. 既存のフォルダーを Shelfmark に指定します。 1 つ以上のルートを指定できます。ファイルは元の場所に残ります。
2. ローカルカタログを作成します。 許可されたルートを走査し、利用可能なメタデータを抽出して分類ルールを適用し、参照情報を SQLite に書き込みます。
3. 所有権と機密性を確認します。 shelfmark review でご自身のフォルダーに関する簡単な質問に回答すると、その内容が設定に書き込まれます。
4. MCP 互換のエージェントを接続します。 構造化ツールを使って、カタログのレコードを検索、閲覧、確認します。
5. 必要なものだけを取得します。 別途コンテンツにアクセスする前に、エージェントが関連する成果物を特定します。

インストール

uv tool install shelfmark          # or: pipx install shelfmark
# from a checkout:
uv tool install /path/to/shelfmark

Python ≥ 3.11。macOS、Linux、Windows に対応しています。CI では、Windows 固有の動作（OneDrive のプレースホルダー検出、ルート境界でのジャンクション拒否）を含め、3 つすべての OS でスイート全体を実行しています。

Codex プラグイン

MCP サーバーと、カタログ管理、コンテキスト検索、アーカイブ調査の各スキルを、バージョン管理された 1 つのプラグインとしてインストールします。

codex plugin marketplace add Dankaro-projects/shelfmark
codex plugin add shelfmark@shelfmark

次に、uvx shelfmark init を実行し、その後 uvx shelfmark refresh を実行してローカルカタログを一度作成します。プラグインは、固定されたバージョンの Shelfmark MCP サーバーを stdio 経由で起動します。ドキュメントのパスとメタデータはローカルマシンに保持されます。

MCP の設定なしで、3 つの付属スキルをインストールするには、次を実行します。

pnpm dlx skills add Dankaro-projects/shelfmark --full-depth

メールの取り込みは任意です。必要な追加パッケージは、扱う形式によって異なります。.msg はどの環境でもホイールが利用できますが、.pst には libpff-python が必要です。このパッケージはホイールを公開しておらず、C ソースからコンパイルするため、ビルドツールチェーン（Visual C++ Build Tools、build-essential、または Xcode のコマンドラインツール）が必要です。

uv tool install "shelfmark[msg]"      # .msg — no compiler needed
uv tool install "shelfmark[pst]"      # .pst — compiles from C source
uv tool install "shelfmark[email]"    # both

クイックスタート

3 つのコマンドを実行するだけで、init がドキュメントを自動的に見つけます。デフォルトのルートで見つからない場合は、ドキュメントがあるフォルダーを探して走査し、キーを 1 回押すだけで設定を修正できます。

$ shelfmark init
Wrote ~/.config/shelfmark/config.toml

WARNING: ~/Documents does not exist on this machine.

These folders do hold documents:
  1. ~/Paperwork  (~6 document files)
  2. ~/Downloads  (~1 document file)
Index which folder? [1] — a number, a path, or 'k' to keep ~/Documents:
  Root set to ~/Paperwork. Edit ~/.config/shelfmark/config.toml any time.

$ shelfmark refresh
cataloguing ~/Paperwork -> ~/.local/share/shelfmark/catalog.db
seen 6  new 6  updated 0  unchanged 0  rematerialised 0
evicted 0  corrupt 0  restricted 0

$ claude mcp add shelfmark -s user -- shelfmark-mcp

これでインストールから接続まで完了です。エージェントの最初の呼び出しは次のようになります（上記のコーパスに対する実際の corpus_stats() の応答です）。

# shelfmark corpus
6 files · 0.0 GB
✓ index fresh — matches disk, last refresh 0 min ago

## Roots
root                     files  own+shareable
Clients                      4              0
Decks                        2              0

## Rights × confidential
  REFERENCE    may leave                5
  UNKNOWN      unreviewed → held        1

## doc_type (what files ARE)
  report 4, deck 2

任意ですが、5 分かける価値があります。shelfmark review では、未分類の大きなサブツリーに関する簡単な質問に回答すると、その内容が設定に書き込まれ、権利が UNKNOWN のままにならなくなります。shelfmark stats はいつでも集計結果を表示します。shelfmark config は、各権利ルールを確認される順序で表示し、それぞれが現在何個のファイルに適用されているかも示します。

セッションでは、まず corpus_stats() で全体を把握し、browse_folder() で移動してから、search_docs()／get_file() で検索・確認します。

MCP ツール

ツール	確認できる内容
corpus_stats()	全体の内容と、正確な鮮度情報。最初に呼び出してください。
browse_folder(prefix)	フォルダー内の内容：件数、サイズ、ファセットの内訳。
search_docs(query, …)	ファセットフィルターに対応したメタデータの全文検索。
get_file(path)	1 つのファイルの完全なレコード：権利、著者情報、スライドタイトル、同一コピー、ディスク上の状態。
search_emails(query, …)	取り込み済みの .pst／.msg メールアーカイブの全文検索（任意）。

結果のリストでは、切り詰められた場合に必ずその旨を示します（showing 100 of 195 …）。不明なフィルター値は、空のコーパスとしてではなく、候補とともに無効なフィルターとして報告されます。また、抜粋には切り詰め位置が示されます。

設定

コーパス固有の設定はすべて config.toml に記述します。コードには中立的なデフォルト値のみが含まれています。設定の解決順序は、--config フラグ → $SHELFMARK_CONFIG → ~/.config/shelfmark/config.toml です。注釈付きの完全なリファレンスについては、config.example.toml を参照してください。主な項目は次のとおりです。

セクション	制御する内容
[[roots]]	インデックスを作成するツリーです。ラベルのないプライマリルートを1つ指定し、追加のルートにはラベルのプレフィックスが付きます。
[index]	SQLite カタログの保存先です。インデックス対象のすべてのルート、およびクラウド同期フォルダーの外に置く必要があります。変更を伴うバイナリ DB のため、この条件は強制されます。
[privacy]	秘密情報やプライベートなサブツリーを RESTRICTED に分類する正規表現です。.env、鍵／証明書ファイル、id_rsa、バックアップコード、身分証明書は、組み込みルールですでに対象になっています。
[authors]	自分の名前／会社、クライアントの作成者、生成ツールに対する正規表現です。OOXML の作成者情報に基づく OWN／REFERENCE の分類に使われます。
[rights]	2軸モデルに対するパスプレフィックスルールです。rights（再利用できるか）× confidential（外部に持ち出せるか）を定義します。
[facets]	作業用／個人用として扱うトップレベルのフォルダーと、パス内でクライアント名／プロジェクト名が置かれる場所を指定します。
[doc_types]／[context_types]	ファイル名／フォルダーに対する追加ルールです。組み込みの英語／スペイン語（EN／ES）デフォルトより先に評価されます。組み込みルールは名前で無効にできます。

shareable_only の意味

shareable_only=True は、明示的に分類されていることを意味します。つまり、confidential=0 AND rights IN (OWN, REFERENCE) です。レビューされていないファイルは除外されます。未レビューは、共有可能と確認済みであることと同じではありません。

rights の設定：shelfmark review

ほとんどのファイルには OOXML の作成者情報がありません。コーパスの大部分は PDF、Markdown、画像であるため、作成者情報で分類できるファイルはごくわずかです。分類に使える唯一の仕組みはパスルールです。パスルールは初期状態では空なので、新しいカタログの大半は UNKNOWN となり、shareable_only の結果もほぼ空になります。

この情報はコーパスではなく、あなた自身が持っているものです。そのため、review ではその情報を尋ねます。カタログが把握している内容を画面に表示しながら、効果の大きいものから確認できます。

[1/8] Projects
      493 unclassified of 662 files · folder reads as: pitch
      is: note 202, document 89, code 88, pdf 51
      authored by: R. Okonjo (31), A. Lindqvist (12), openpyxl (9)
      e.g. programme-overview.pptx · phase-two-proposal.pptx
      answer [skip]:

own、own-private、reference、client、personal、scratch、または skip と回答してください。約1,900ファイルのコーパスでは、5つの回答で未分類ファイルの80％、8つの回答で90％を分類できました。

shelfmark review                 # dry run — shows what it would write
shelfmark review --apply         # writes the prefixes, re-derives rights

終了したいときにいつでも終了でき、未分類のサブツリーだけを対象にするため、再実行すれば前回の続きから進められます。また、書き込むのは設定であり、データ内の rights 値ではありません。そのため、設定を編集して shelfmark rights を再実行すれば、どの回答も取り消せます。作成者情報に十分な偏りがあり、根拠として使える場合はデフォルトの回答を提示します。情報が乏しい場合は推測せず、何も提示しません。

分類ルールの編集

実際に問題が起きてわかった、つまずきやすい点が2つあります。

1. 短い正規表現の選択肢は、両端をアンカーで固定してください。 アンカーのない rfi は、「Dockerfile」やスペイン語の「perfil」の中にも一致します。選択肢を追加または削除する前に、実際に一致するファイル名を一覧表示してください。

2. ルールを編集しても、既存ファイルの分類は更新されません。 ビルダーは増分処理を行うため、ルールを変更した後は、必ず次を実行してください。

   shelfmark reclassify all          # dry run — shows what would change
   shelfmark reclassify all --apply
   

   この場合、build --rebuild は使用しないでください。ファイル名がすでに DB にあるのに、すべてを再走査し、クラウド同期ツリーではローカルから退避済みのファイルまで再びダウンロードしてしまいます。

最新の状態を保つ

shelfmark refresh                # build + rights + prune + assertions
shelfmark refresh --if-needed    # only if a write landed or the index is old

refresh は（サイズ、mtime、クラウド上でのローカル保持状態）に基づいて増分処理を行います。約3万ファイルのツリーでも数秒で完了し、実行のたびに正しさを検証します。検証項目には、走査の網羅性（OS に拒否された走査を成功とみなさないこと）、削除済みファイルのガード付きプルーニング（大量削除の疑いがある場合やルートがマウントされていない場合は拒否）、ガバナンスの不変条件（検索インデックスに RESTRICTED の行がないこと、封印されていない秘密情報がないこと、検索できない非 RESTRICTED の行がないこと）が含まれます。結果は DB の隣にある REFRESH_STATUS.json に保存され、MCP サーバーは corpus_stats() が呼び出されるたびにその内容を報告します。

インデックスへの変更を見送るガードは、必ずその旨を stderr に出力して、0以外の終了コードで終了します。拒否を隠して、一見問題のなさそうな概要だけを表示することはありません。

何かがおかしいのに、何も知らせてくれないとき

shelfmark doctor

ひっそり起きる問題について、セットアップをチェックします。カタログがクラウド同期フォルダー内にある（同期クライアントは書き込みのたびにアップロードし、.db、-wal、-shm を異なるタイミングでコピーする場合、整合性の崩れたデータベースが復元され、開けても誤った応答を返します）、プロセスがルートを読み取れない（macOS では通常、空の走査の原因となっている「フルディスクアクセス」が必要です）、データベースフォルダーに書き込み権限がない、コーパスの大半がクラウドから退避されていてその影響が生じている、カタログに読み取りツールがインストールされていないメール形式がある、といった問題を調べます。

問題点ではなく修正方法を示し、それぞれの推測の根拠を出力するので、必要に応じて判断を覆せます。また、致命的な問題があればゼロ以外の終了コードを返すため、セットアップスクリプトのゲートとして使えます。

チェック内容を変えるフラグはありません。あるフラグが変えるのは、出力の対象だけです。

shelfmark doctor --report

コーパスを除いた同じ判定を JSON で出力します。件数、状態、判定コードは含まれますが、パス、ファイル名、ルートのラベル、設定文字列は含まれません。ここから外部への通信は一切行われないため、マシン上のカタログに問題があっても、助けになり得る人には見えません。これはローカル専用ツールが使える唯一の共有手段で、約 1.5 KB なので issue に貼り付けられます。また、失敗の連続回数も含まれています。「壊れている」と「火曜日からずっと壊れている。113 回実行」の違いがわかります。

省略のない全体像は次のとおりです。

{
  "shelfmark": "0.4.7", "python": "3.13.13",
  "platform": "darwin", "machine": "arm64", "release": "25.5.0",
  "roots": {"configured": 3, "readable": 3},
  "catalogue": {"files": 32942, "evicted": 0,
                "rights": {"OWN": 3933, "REFERENCE": 27818,
                           "RESTRICTED": 955, "UNKNOWN": 236}},
  "status": {"state": "ok", "detail_kind": "clean",
             "failing_since": null, "consecutive_failures": 0},
  "findings": [{"code": "reader_missing_msg", "status": "warn",
                "count": 2318}],
  "worst": "warn"
}

情報の削除は、誰かが覚えておかなければならない慣習ではありません。レポートには自由記述のテキストが一切コピーされないため、後からチェックが追加されても、そこから情報が漏れることはありません。また、テストではルート名、ファイル名、設定にカナリア文字列を埋め込み、それが出力に含まれていれば失敗するようにしています。

ガードによって処理が止められたとき

2 つのサイズガードでは、「ルートが読み取り不能だった」のか「ファイルが本当に削除された」のかを判別できません。どちらも走査結果が少なく見えるためです。そのため処理を拒否し、両方の可能性を示して、インデックスには手を加えません。

FAILED — walk saw 63/123 catalogued files, below the 80% floor — either the
root was unreadable to this process or that many files really went away.
Index NOT updated; re-run with --force if the deletion was real.

どちらだったのか確認してください。ファイルが本当に削除されている場合は、次のようにします。

shelfmark refresh --force        # accept the short walk, prune past the ceiling

--force は、何かを削除する前にカタログを catalog.db.bak-preprune にバックアップします。一方、ルートがアンマウントされていたり読み取り不能だったりしただけなら、それを修正して通常どおり更新してください。行はまだ残っています。

実例：誰かがフォルダー名を変更する

これは、ガードが存在する理由となった問題を、最初から最後まで追った例です。200 ファイルのコーパスで、Clients/Acme に 60 個のドキュメント、Admin に 140 個あります。以下はすべて実際の出力で、パスだけ短縮しています。

1 — クリーンビルド。

$ shelfmark refresh
cataloguing ~/Paperwork -> ~/.local/share/shelfmark/catalog.db
seen 200  new 200  updated 0  unchanged 0  rematerialised 0
evicted 0  corrupt 0  restricted 0

2 — Clients/Acme が Clients/ACME Corp に名前変更されます。 何も削除されていませんが、古い名前の下にあるカタログ済みのパスはすべて参照先がなくなり、走査では見たことのないファイルが 60 個見つかります。

$ shelfmark refresh
seen 200  new 60  updated 0  unchanged 140  rematerialised 0

prune REFUSED — 60 of 200 rows are no longer on disk, over the 2% ceiling.
  Nothing was deleted; the index still lists them. A real deletion, an
  unreadable subtree, or an upgrade widening the default skip list all look
  like this. Check what went missing, then re-run with --force to accept it.

拒否するのは正しい判断です。この時点では、名前変更と大量削除は同じ事象だからです。ステータスは ok ではなく degraded になります。実行自体は完了しましたが、カタログにはファイルが存在しない行が 60 件あると認識されています。

3 — もう一度実行します。 カタログには両方のコピーが残っているため、剪定上限ではなくカバレッジの下限が適用されます。

$ shelfmark refresh
FAILED — walk saw 200/260 catalogued files, below the 80% floor — the root
was unreadable to this process, that many files really went away, or an
upgrade widened the default skip list. Index NOT updated; re-run with
--force if the deletion or the new skip list is right.

その後の実行でも、毎回失敗したままです。ひっそり収まることはありません。

4 — その間に、エージェントが受け取る内容。 何事もなかったかのように応答するツールはありません。警告が先頭に表示され、連続回数も含まれます。

⚠ the last refresh FAILED (walk saw 200/260 catalogued files, below the 80%
floor … — 2 consecutive runs since 2026-08-11T08:46:01Z) — answers below
come from the previous snapshot.

showing 3 of 120 match(es) for '"acme"':

- Clients/Acme/acme_note_055.md
    note  [UNKNOWN]

パスに注目してください。まだ応答は返っていますが、古い名前に基づいています。だからこそ、バナーは省略できません。

5 — 何が問題なのかを確認します。

$ shelfmark doctor
  [ok  ]  root (primary) is readable
  [ok  ]  the catalogue is outside any sync folder
  [ok  ]  the corpus is materialised on disk
  [FAIL]  the last refresh FAILED — 2 consecutive runs since 2026-08-11T08:46:01Z
     walk saw 200/260 catalogued files, below the 80% floor — …
     -> The refresh already said this on stderr; if you are only seeing it now,
       whatever runs it is discarding its output.

2 of 5 checks need attention.
$ echo $?
1

6 — ファイルは実際に移動したので、これを受け入れます。

$ shelfmark refresh --force
seen 200  new 0  updated 0  unchanged 200  rematerialised 0
--force: accepting coverage 200/260 (below the 80% floor)
--force: pruned 60 rows, over the 2% ceiling (backup: catalog.db.bak-preprune)

7 — 確認します。stats の最後は時計ではなく、実際の走査結果であることに注目してください。

$ shelfmark doctor
  [ok  ]  the last refresh completed cleanly
1 of 5 checks need attention.

$ shelfmark stats
✓ index fresh — matches disk, last refresh 0 min ago

残る警告は 100% of the catalogue has UNKNOWN rights です。これは shelfmark review を実行する前のコーパスなら、どれでも当てはまります。権利を設定するを参照してください。

スケジュール設定は不要です

MCP サーバーは独自のインデックスを最新の状態に保ちます。クライアントによって起動され、セッション中はずっと動作し、起動時に一度、その後は refresh.max_age_seconds が経過するたびに更新します。インストールも、タイマーの設定も、コマンドを覚える必要もありません。

これは、クライアントがすでに起動している常駐プロセスのほうが、スケジューラーよりも適切なトリガーになるためです。そのプロセスはクライアントと同じファイルアクセス権を引き継ぎ、質問しているまさにそのときに実行されています。別の方法でカタログを管理している場合は、shelfmark-mcp --no-auto-refresh を使えば更新されません。

エディターのフックは、今では仕組みそのものではなく最適化です。エージェントがファイルを書き込んでから検索可能になるまでの遅延を、更新間隔分からターン終了時まで短縮します。Claude Code の場合は、~/.claude/settings.json に次を設定します。

{
  "hooks": {
    "SessionStart": [{"hooks": [{"type": "command",
      "command": "shelfmark hook session-start", "timeout": 60}]}],
    "PostToolUse": [{"matcher": "Write|Edit|MultiEdit|NotebookEdit",
      "hooks": [{"type": "command", "command": "shelfmark mark-dirty"}]}],
    "Stop": [{"hooks": [{"type": "command",
      "command": "shelfmark hook stop"}]}]
  }
}

mark-dirty は、インデックス対象のルート内に書き込みが行われた場合にのみマーカーを作成します（それ以外の書き込みでは、ほぼ負荷はありません）。hook stop はターンの終了時にそのマーカーを確認します。hook session-start は更新してから、MCP サーバーと同じ方法でインデックスとディスクの内容を照合し、問題がある場合にのみあなたとエージェントに通知します。

これらを >/dev/null 2>&1 で囲まないでください。このページの以前の版ではまさにその方法を案内していましたが、その結果、カタログが4日間も気づかれないまま不正な状態になりました。更新時に報告される拒否や失敗はすべて stderr に出力されるため、リダイレクトすると、その通知を受け取る唯一の手段が失われます。カタログが正常な場合、shelfmark hook は何も出力せず、常に終了コード 0 を返します。抑制するものはもうありません。

クライアントを実行していないときも最新の状態に保ちたい場合

MCP を使わない場合や、非常に大きなツリーに対する最初のクエリをすぐに行いたい場合にのみ有用です。Linux では、systemd --user タイマーで shelfmark refresh --if-needed を実行する方法が簡潔です。

macOS では、障害の原因は launchd ではなく TCC です。デフォルトでは、LaunchAgent は ~/Documents、~/Desktop、~/Downloads へのアクセスを拒否されます。os.walk はエラーを握りつぶすため、ビルドは少数のファイルだけを走査して 終了コード 0 で終了します。すべての層が成功を報告する一方で、インデックスは更新されません。ジョブを実行するインタープリターにフルディスクアクセスを許可すれば、LaunchAgent を問題なく使えます。どちらの場合も、対象範囲のアサーションによって許可されていない状態を検出できます。何もインデックス化されないまま黙って処理が進むのではなく、更新が明示的に失敗します。

Windows では、同じコマンドをタスク スケジューラで実行するのが相当する方法です。スケジュール実行の手順はまだ実環境でテストされていません。設定する場合は、対象範囲のアサーションが、スケジュールの不具合によってインデックスが古いまま黙って放置されるのを防ぐ役割を果たします。

コンテンツのハッシュ化と重複

更新時にファイルの内容が読み込まれることはありません（高速性を保つ必要があるためです）。重複検出用のハッシュを作成するには、次を実行します。

shelfmark hash                   # reads every unhashed, non-sensitive file
shelfmark hash --limit 2000      # chip away at it

機密情報を含む行のファイルは開かれず、シンボリックリンクも開かれません。クラウド同期されたツリーでは、データのないプレースホルダーファイルはスキップされます。読み込むと、空文字列のハッシュが黙って返され、異なるファイルが同一に見えてしまうためです。大量に実体化した後は、再実行してください。

Shelfmark の特長

• デスクトップ検索は、人がファイル内のテキストを見つけるのに役立ちます。
• ドキュメント管理システムでは、ドキュメントを新しい環境にインポートして管理する必要があります。
• 検索システムは、ドキュメントの内容を解析してチャンクに分割し、検索インデックスやベクトルストアにコピーします。
• ファイルシステムツールはエージェントに直接アクセスを提供し、何を見つけるかの判断をすべてエージェントに委ねます。

Shelfmark は異なる層に位置します。すでに所有しているドキュメントを対象とする、ローカルで、管理された、メタデータベースのマップであり、エージェントが必要なコンテキストを選択できるよう特化して構築されています。

Shelfmark が目指していないもの

ドキュメント管理システムではありません。ファイルシステムを置き換えるものではありません。埋め込みを必要としません。フォルダーを再編成しません。読み込んだことのないコンテンツを理解しているとは主張しません。また、見つけられるドキュメントはすべて安全に共有できるとも想定しません。

エージェントに、よりよい出発点を提供します。

以下は未対応機能ではなく、方針として決めたことです。

• 埋め込みなし。 まずメタデータの FTS とファセットを使用します。
• コンテンツ抽出なし。 設計上、本文テキストはインデックスに含めません。

実際の検索漏れを判断材料にする

この2つの方針は、競合製品の機能一覧ではなく、実際の証拠に基づいて見直すべきです。そのため、shelfmark は何も見つからなかった検索をローカルに記録し、その意味を知らせます。

shelfmark misses            # the evidence
shelfmark misses --clear    # forget it

このレポートが答えるのは、「メタデータ検索で見つけられた可能性はあるか？」という1つの問いです。ファイル名、パス、作成者、タイトル、スライドのタイトルのいずれにもない語句は、どのように表現しても見つけられません。これはコンテンツ抽出によって解決できる問題です。一方、コーパスに含まれているのに見つからなかった語句は、表現またはフィルターの問題であり、別の対処が必要です。この区別がなければ、検索漏れのログからわかるのは、人々が検索しているということだけです。

73 searches returned nothing   (2026-06-02 → 2026-08-07)

Most-missed terms:
    9  abatement
    7  timeline      (nowhere in your metadata)
    6  commitments   (nowhere in your metadata)

41 of 62 distinct terms (66%) appear nowhere in your filenames,
paths, authors, titles or slide titles.

These are mostly things metadata search could NEVER have found, however
phrased. That is the pattern the README says should reopen content
extraction — not embeddings.

不適切なフィルター、実現不可能な年の範囲、古いインデックスに対する検索は、検索漏れとして記録されません。いずれも呼び出し元にすでに理由が説明されており、記録すれば本当に必要な情報が埋もれてしまうためです。記録はローカルに保持され、上限が設けられ、お使いのマシンの外に出ることはありません。[misses] enabled = false で無効にできます。自分の検索語句を記録することはプライバシーに関わる選択であり、それを許容できるかどうかはコーパスによって実際に異なります。

よくある質問

Shelfmark はドキュメントをアップロードしますか？ いいえ。ローカルで動作し、ローカルのカタログを作成します。ドキュメントの内容がカタログにコピーされることはありません。

カタログには何が含まれますか？ ファイル参照と、そこから取得したメタデータです。パス、ファイル名、種類、サイズ、日付、作成者、分類、選択した Office プロパティ、プレゼンテーションのタイトル、オプションのコンテンツハッシュが含まれます。

ドキュメントの内容を読み取りますか？ ファイルカタログでは本文テキストをインデックス化しません。意図的に設けた例外が2つあります。shelfmark hash は重複検出のためにコンテンツハッシュを計算する際にファイルを開きます。また、オプションのメール取り込みでは、search_emails が機能するようにメッセージ本文をインデックス化できます。どちらもオプトイン方式のコマンドで、シンボリックリンクはスキップし、プライバシールールを尊重します。秘密またはプライベートのパターンに一致するファイルやアーカイブが、どちらかによって開かれることはありません。

最初にフォルダーを再編成する必要がありますか？ いいえ。ファイル名やメタデータを改善すると分類の精度は向上しますが、正式な構造は必要ありません。

名前が適切でないファイルをすべて理解できますか？ いいえ。意味のない名前が付けられ、埋め込みメタデータもないファイルは、読み取らない限り特定が困難なままです。Shelfmark は推測せず、把握していることだけを伝えます。

エージェントにファイルシステムへのアクセスを許可するだけではだめですか？ ファイルシステムへのアクセスがあれば、エージェントはファイルを開けます。Shelfmark は、どのファイルを開く価値があるか、そしてどのファイルを結果から完全に除外すべきかを判断するのに役立ちます。

ベクトルデータベースを使わないのはなぜですか？ ベクトルデータベースは、コンテンツから意味的に検索するためのものです。Shelfmark が解決するのは、それより前の段階の問題です。つまり、どのコンテンツを処理するかを決める前に、何が存在するかを見つけ、管理することです。両者は併用できますが、先に使うのはこちらです。

どのエージェントが使用できますか？ ローカル MCP サーバーに対応するクライアントであれば、どれでも使用できます。claude mcp add shelfmark -s user -- shelfmark-mcp で登録するか、クライアントに shelfmark-mcp コマンドを指定してください。

開発

uv run --group dev pytest        # the suite ships in the sdist, so this
                                 # runs from the release artifact too

OOXML ファイルを含むテストコーパスは、実行のたびに合成されます。フィクスチャのバイナリはコミットされず、実際のドキュメントが読み取られることもありません。

ライセンス

MIT — LICENSE を参照してください。自由に使用、変更、再配布できます。

mcp-name: io.github.Dankaro-projects/shelfmark