LoreDocs

LoreDocs v0.1.31

AI プロジェクトのナレッジベースです。整理され、検索可能で、バージョン管理されています。

LoreDocs を使うと、Claude はプロジェクトのドキュメント（仕様書、ガイド、アーキテクチャ上の決定事項、リファレンスドキュメントなど）に継続的にアクセスできるため、セッション間でコンテキストを失いません。Claude Code、Cowork、Cursor、OpenAI Codex、Hermes Agent で利用できます。

Claude Code のプラグインマーケットプレイスから直接インストールするか、PyPI 経由でインストールできます：uvx loredocs

クイックスタート

前提条件： uv（高速な Python パッケージマネージャー）。

# Install uv: https://docs.astral.sh/uv/getting-started/installation/
# Clone and install
cd /path/to/loredocs
uv sync

詳しいインストール手順については、INSTALL.md を参照してください。

Claude Agent SDK を直接使用していますか？ 公開リポジトリを git clone し、SDK のローカルディレクトリ用プラグインローダーに指定してください。リポジトリのルートは自己完結型のプラグインディレクトリ（.claude-plugin/plugin.json + .mcp.json）です。SDK で個別にインストール可能なバンドルは存在せず、その必要もありません。

LoreDocs の使用方法

Claude Code（ターミナル）

claude --plugin-dir /path/to/loredocs

または、既存のセッション内で：

/plugin add /path/to/loredocs

読み込みが完了すると、Claude は LoreDocs の 48 個すべての MCP ツールに自動的にアクセスできるようになります。「このプロジェクト用のボールトを作成して」や「アーキテクチャのドキュメントを探して」と Claude に頼むと、自動的にツールを使います。

Cowork（デスクトップアプリ）

1. プロンプトボックスの横にある + をクリックします
2. Plugins > Add plugin を選択します
3. loredocs のソースフォルダーを指定します

データベースへの共有アクセス： Cowork はサンドボックス化された VM で動作します。Claude Code から保存したドキュメントにアクセスするには、Claude に次のように頼んでください：

「~/.loredocs フォルダーをマウントして」

Hermes Agent

Hermes Agent のユーザーは、~/.hermes/config.yaml の mcp_servers: の下に LoreDocs を MCP サーバーとして追加し（全項目については INSTALL.md を参照）、その後 Hermes を再起動してください。

これで、Hermes のセッションで LoreDocs の 48 個すべての MCP ツールを利用できます。

Hermes に関する開示事項

Hermes Agent で LoreDocs を使用する場合：

• インストール： 初回実行時に、uvx 経由で PyPI から指定したバージョンの loredocs がダウンロードされます。自動更新はありません。
• データの保存： すべてのボールトデータは、SQLite 形式でローカルの ~/.loredocs/ に保存されます。クラウドサービスや外部サーバーにデータが送信されることはありません。
• Pro ライセンスの検証： Pro ティアの有効化では、オフラインの Ed25519 暗号技術を使用してライセンスキーを検証します。検証中にネットワークリクエストは行われません。
• テレメトリー： LoreDocs はテレメトリーや使用状況データを収集または送信しません。
• ネットワーク通信： Pro のセマンティック検索では、初回使用時に一度だけ、Hugging Face から BAAI/bge-small-en-v1.5 埋め込みモデルをダウンロードします。オプションの Notion インポートでは、ユーザーが提供したトークンを使って Notion API を呼び出します。LoreDocs がこれ以外のネットワーク通信を行うことはありません。

仕組み

LoreDocs は、関連するドキュメントをまとめる名前付きコンテナーであるボールトに知識を整理します。各ボールトには、仕様書、ガイド、決定事項、チェックリスト、その他 Claude に記憶させたいあらゆるテキストを保存できます。

~/.loredocs/loredocs.db          <-- SQLite database (metadata, search index)
~/.loredocs/vaults/<vault-id>/   <-- Document files on disk

主な概念：

• ボールトは、プロジェクトやトピックごとに関連ドキュメントをまとめます
• ドキュメントは、メタデータ（タグ、カテゴリ、優先度、メモ）を含むテキストファイルです
• バージョン履歴は、すべてのドキュメントに対する変更をすべて追跡します
• 全文検索は SQLite FTS5 を使用し、あらゆる情報をすばやく見つけます
• インジェクションは、必要に応じてボールトの内容を Claude のコンテキストに読み込みます

データは常に利用可能です

LoreDocs は、MCP ツールが利用可能な場合はそれらを通じて動作し、利用できない場合は自動的に同梱スクリプトに切り替えます。MCP の状態にかかわらず、ボールト内のドキュメントは安全です。同じ追加、検索、取得の操作をどちらの場合でも実行できます。何かを設定する必要はありません。プラグインのスキルが切り替えを自動で処理します。

インストールの確認

インストール後、Claude に次のように頼んで LoreDocs が動作していることを確認してください：

「vault_list を実行して、結果を見せてください。」

ボールトの一覧（初めて使用する場合は空の一覧）が表示されれば、LoreDocs は接続されています。ツールが見つからないというエラーが表示された場合は、uv sync を再実行し、プラグインを再読み込みしてください。

推奨する CLAUDE.md の設定

最適なエクスペリエンスを得るには、次のスニペットを ~/.claude/CLAUDE.md（グローバル）またはプロジェクトの CLAUDE.md に追加してください。これにより、Claude がセッションをまたいで一貫して LoreDocs を使用できるようになります。

## LoreDocs (persistent project knowledge)

At session start:
1. Call `vault_list` to see available knowledge vaults.
2. Call `vault_inject_summary` for any vaults relevant to the current project.
3. Use this context to understand project architecture, decisions, and reference docs.

During the session:
- If you create significant documentation, add it to LoreDocs with `vault_add_doc`.
- Tag documents for easy cross-vault discovery with `vault_tag_doc`.

At session end:
- If new docs were created or updated, ensure they are stored in LoreDocs for future sessions.

Cowork ユーザー向け： Cowork はフックを自動実行しません。セッション開始時に vault_list と vault_inject_summary を呼び出すよう、プロジェクトの CLAUDE.md に指示を追加してください。

正式なプロジェクトナレッジ

複数のエージェントが動作する環境では、ツールやエージェントごとに、プレイブック、スタイルガイド、共有リファレンスドキュメントなど、共有スキルや設定の内容を場当たり的に複製することがよくあります。こうした複製は次第に食い違っていきます。一方のエージェントがソースを更新しても、もう一方は古いコピーを読み続けます。同じプロジェクト内のエージェントが、何も問題が起きていないように見えるまま、異なるナレッジに基づいて動作することになります。

LoreDocs は、すべてのエージェントが参照する唯一の正式なソースとしてボールトを使うことで、これを防ぎます。各エージェントがローカルファイルのコピーを読み込む代わりに、セッション開始時にすべてのエージェントが vault_inject_by_tag を呼び出し、ボールトで管理された同じバージョンを取得します。

推奨パターン

共有コンテンツ（プレイブック、チームのガイドライン、共有仕様）は、エージェントがコピーまたは複製するローカルファイルではなく、ボールトのドキュメントとして保存してください。

エージェントはセッション開始時にコンテンツを読み込みます。

vault_inject_by_tag: team-playbook

実行環境（Claude Code、Cowork、CLI、または将来の AI ツール）にかかわらず、すべてのエージェントが同じボールトを呼び出し、同じ最新バージョンを受け取ります。コンテンツを更新するには、ボールトのドキュメントを一度編集するだけで済みます。すべてのエージェントが次回のセッション開始時に変更を取得します。

ローカルファイル（.claude/skills/、.agents/、または実行環境固有の設定）は、ポインターまたはブートストラップ用のスタブに限定され、正式なコンテンツとしては使用されません。信頼できる唯一の情報源はボールトです。

例：エージェントチーム間でプレイブックを共有する

# Session start for any agent on the team:
# 1. Inject the shared playbook by tag
vault_inject_by_tag("team-playbook")

# 2. Inject any project-specific reference docs
vault_inject_by_tag("project-architecture")

# Working context is now current -- no local file copies needed.

共有コンテンツをボールトに保存するには（一度、または更新のたびに）：

# Store (or update) the shared playbook:
vault_update_doc(vault="team-knowledge", doc_id="playbook-id", content=open("PLAYBOOK.md").read())

# Or add it fresh (path= reads directly from disk -- no need to load into context):
vault_add_doc(vault="team-knowledge", name="Team Playbook", path="/absolute/path/to/PLAYBOOK.md", tags=["team-playbook"])

vault_inject_by_tag("team-playbook") を呼び出すエージェントは、どれも同じドキュメントを読み込みます。コピーも複製もなく、内容が食い違うこともありません。

プラン：Free と Pro

LoreDocs はローカルファーストで、無料で使用できます。Pro（$9/月）ではストレージ制限が解除され、セマンティック検索（意味ベースの検索）が利用可能になります。どちらのプランでもすべての処理はご利用のマシン上で行われます。Pro でもクラウド機能は追加されません。

	Free	Pro ($9/mo)
ボールト	3	無制限
ボールトあたりのドキュメント数	50	無制限
ストレージ	500 MB	無制限
ドキュメントあたりのバージョン履歴	5 バージョン	無制限
全文検索（FTS5）	はい	はい
コア MCP ツール（作成、検索、バージョン、タグ、注入、インポート／エクスポート）	はい	はい
ローカルファースト、クラウドなし、テレメトリーなし	はい	はい
セマンティック検索（vault_search semantic=true、vault_rebuild_index）	--	はい
埋め込みベースのドキュメント間の関連性（vault_find_related）	キーワードの共起のみ	キーワードと埋め込みによる自動リンク
製品をまたいだセッションのリンク（vault_link_session とその他 2 つ）	--	はい（LoreConvo Pro も必要）

Pro にアップグレード -- $9/month

チェックアウト後、チェックアウト時に使用したメールアドレス宛てにライセンスキーが自動送信されます。通常、数分以内に届きます。お問い合わせ：[email protected]。

Free プランの上限は書き込み前に適用されます。Pro では上限が解除されます。現在のプランと使用状況は、いつでも vault_tier_status で確認できます。Pro ライセンスを有効化するには、vault_set_tier を使用してください。

Pro のセマンティック機能は、ローカルの埋め込みモデル（BGE-small-en-v1.5）と LanceDB インデックスを使用します。データがご利用のマシンの外に送信されることはありません。

特徴

• Vault の整理：ドキュメントをプロジェクトごとにグループ化し、プロジェクトのメタデータと関連付けます
• ドキュメントのバージョン管理：完全な履歴を保持し、以前の任意のバージョンにロールバックできます
• タグ付けと分類：Vault を横断して検索できるよう、ドキュメントにタグを付けます
• 優先度：ドキュメントに「重大」「高」「通常」「低」の優先度を設定できます
• 全文検索：すべての Vault とドキュメントを対象に、キーワードをすばやく検索できます
• コンテキストへの注入：特定のドキュメント、タグ、または Vault の概要を Claude のコンテキストに読み込めます
• 一括操作：ディレクトリのインポート、一括タグ付け、マニフェストのエクスポートができます
• ドキュメントのリンク：Vault をまたいで関連ドキュメントを結び付けます
• 埋め込みベースのドキュメント関連付け（Pro）：vault_find_related は、キーワードの共起と埋め込みベースの自動リンクの両方を Pro ユーザーに返します。BGE-small-en-v1.5 を使用し、コサイン類似度は 0.75 以上、同一 Vault 内に範囲を限定します。Pro から Free にダウングレードすると、埋め込みリンクはアーカイブされます。
• 製品をまたいだセッションのリンク（Pro）：Vault のドキュメントを最も関連性の高い LoreConvo のセッションに自動でリンクし、その逆も行います。ツールは 3 つあります：vault_link_session、vault_get_session_links、vault_get_linked_sessions。LoreDocs Pro と LoreConvo Pro の両方が必要です。
• プラン管理：設定可能な制限を備えた Free／Pro プラン
• ローカルファースト：SQLite データベースを使用し、クラウドへの依存や API コストはありません

MCP ツール

LoreDocs は、機能別に整理された 48 個の MCP ツールをデフォルトで提供します（notion エクストラをインストールすると 49 個、notion エクストラをインストールして LOREDOCS_ENABLE_CAP_TOOLS=1 に設定すると 50 個です）。

Vault 管理（8 個のツール）

ツール	機能
vault_create	名前と説明を指定して、新しい Vault を作成します
vault_list	すべての Vault をドキュメント数とサイズとともに一覧表示します
vault_info	Vault の詳細情報を取得します
vault_archive	Vault をアーカイブします（データは保持され、一覧には表示されなくなります）
vault_delete	Vault とすべてのドキュメントを完全に削除します
vault_link_project	Vault をプロジェクトディレクトリにリンクします
vault_open_workspace	ディレクトリパスに紐付けられた Vault を開くか、作成します
loredocs_onboard	初回インストール時に、スターター Vault を使ってワークスペースをセットアップします

ドキュメント操作（10 個のツール）

ツール	機能
vault_add_doc	Vault に新しいドキュメントを追加します（インラインコンテンツまたはファイルパスから）
vault_update_doc	ドキュメントの内容を更新します（バージョン履歴が作成されます）
vault_remove_doc	Vault からドキュメントを削除します
vault_get_doc	全文を含むドキュメントを取得します
vault_list_docs	絞り込みや並べ替えを指定して、Vault 内のドキュメントを一覧表示します
vault_copy_doc	ドキュメントを別の Vault にコピーします
vault_move_doc	ドキュメントを別の Vault に移動します
vault_doc_history	ドキュメントのバージョン履歴を表示します
vault_doc_restore	ドキュメントを以前のバージョンに復元します

検索と発見（5 個のツール）

ツール	機能
vault_search	すべての Vault を対象に全文検索します
vault_search_by_tag	すべての Vault を対象に、タグでドキュメントを検索します
vault_find_related	指定したドキュメントに関連するドキュメントを見つけます（Pro のみ）
vault_suggest	読み込みに適した関連ドキュメントを事前に提案します
vault_rebuild_index	LanceDB のセマンティック検索インデックスを再構築します（Pro のみ。Pro の依存関係をインストールした後、一度実行してください）

整理（5 個のツール）

ツール	機能
vault_tag_doc	ドキュメントにタグを追加します
vault_bulk_tag	複数のドキュメントに一度にタグを付けます
vault_categorize	ドキュメントのカテゴリ（spec、guide、decision など）を設定します
vault_set_priority	ドキュメントの優先度を設定します
vault_add_note	ドキュメントにメモや注釈を追加します

コンテキスト注入（9 個のツール）

ツール	機能
vault_inject	ランク付けされた Vault ドキュメントをトークン予算内に収めてコンテキストに読み込みます
vault_inject_by_tag	タグに一致するすべてのドキュメントをトークン予算内に収めて読み込みます
vault_inject_summary	ドキュメントのタイトルと説明を含む Vault の概要を読み込みます
vault_prime	優先順位順にすべての Vault ドキュメントを事前に読み込みます（クエリなしで vault_inject を実行するのと同等です）
vault_get_injection_cap	Vault の注入ツールに設定されているトークン上限を取得します
vault_set_injection_cap	Vault の注入トークン上限を設定します（LOREDOCS_ENABLE_CAP_TOOLS=1 が必要です）
vault_get_session_token	注入ツール用のセッションごとのキャッシュキーを生成します
vault_estimate_tokens	実行前に注入呼び出しで使用するトークン数を見積もります
vault_get_server_capabilities	このサーバービルドがサポートする注入／トークン予算機能を報告します

インポート／エクスポート（5 個のツール）

ツール	機能
vault_import_dir	ファイルのディレクトリを Vault にインポートします
vault_import_notion	Notion のページとデータベースを Vault にインポートします（初回のみ。ライブ同期はありません）
vault_import_notion_setup	Notion インポートの準備状況と有効化方法を報告します（読み取り専用）
vault_export	ドキュメントをディスク上のファイルにエクスポートします
vault_export_manifest	Vault のメタデータを JSON マニフェストとしてエクスポートします

ドキュメントリンク（2 個のツール）

ツール	機能
vault_link_doc	2 つのドキュメント間にリンクを作成します
vault_unlink_doc	ドキュメント間のリンクを削除します

管理（4 個のツール）

ツール	機能
vault_tier_status	現在のティア制限と使用状況を確認します
vault_set_tier	アクティブなティア（free または pro）を設定します
get_license_tier	現在のティアとライセンスキーの状態を確認します
vault_verify	ドキュメントのバージョン履歴の整合性を確認し、必要に応じて修復します

製品間のセッションリンク（3 個のツール、Pro）

ツール	機能
vault_link_session	LoreConvo のセッションから LoreDocs のドキュメントへの手動リンクを作成します
vault_get_session_links	LoreDocs のドキュメントにリンクされた LoreConvo のセッションを返します
vault_get_linked_sessions	指定された LoreConvo のセッションにリンクされた LoreDocs のドキュメントを返します

ポータブルなプロジェクトワークスペース

LoreDocs と LoreConvo を組み合わせることで、Claude のあらゆる用途に対応するポータブルなプロジェクトワークスペースが実現します。セッションの記憶と構造化された知識を、すべてお使いのマシン上に保持します。

• LoreConvo は、話し合ったこと、決定したこと、未解決のまま残したことを記憶します（エピソード記憶＋意味記憶）
• LoreDocs は、Claude が必要とする参考ドキュメント、仕様書、ガイドを保存します（永続的な知識）

クラウド AI ワークスペースでは 1 つのエコシステムに縛られますが、LoreConvo と LoreDocs は Claude Code、Cursor、OpenAI Codex、Hermes Agent、Cowork で利用できます。どちらもデータをローカルの SQLite に保存します。外部サーバーに情報を送信することはありません。

要件

• Python 3.10+
• macOS または Linux
• uv パッケージマネージャー
• mcp と pydantic（uv sync により自動インストール）

対応するストレージ基盤

LoreDocs は、ドキュメントの内容をディスク上のプレーンファイルとして保存します。耐久性の保証は、ストレージ基盤となるファイルシステムによって異なります。

Vault のルートの場所	サポート状況	保証
ローカルディスク（ローカルボリューム上の APFS、ext4、NTFS）	対応	保証が適用されます。書き込みを誤って報告するストレージ基盤では、最新の保存内容が失われる可能性がありますが、ディスク上にすでにあるバージョンが破壊または破損することはありません。
クラウド同期フォルダー（Dropbox、iCloud Drive、OneDrive、Google Drive）	ベストエフォート	同期クライアントにより、最新の保存内容が失われたり、以前の状態に戻ったりする場合があります。
ネットワークマウント（SMB、NFS、sshfs）	ベストエフォート	アドバイザリロックが機能しない場合があり、同時にアクセスするクライアントによって更新が失われることがあります。
コンテナのバインドマウント／WSL の OS 間パス	ベストエフォート	基盤となるファイルシステムと同じ保証が適用されます。

既知のクラウド同期ディレクトリ内に Vault のルートがあることを検出すると、一度だけ警告が表示されます。LOREDOCS_SUPPRESS_SUBSTRATE_WARNING=1 で警告を抑制できます。

各ドキュメントディレクトリの metadata.json ファイルは、SQLite データベースから厳密に生成されます。正本はデータベースです。metadata.json を直接編集しないでください。変更内容は、次回のドキュメント更新時に上書きされます。

バージョン履歴の整合性

LoreDocs v0.1.21+ には、バージョンストレージの整合性を保つ機能が含まれています。

• アトミック書き込み：すべての変更で一時ファイルの作成と名前の変更を行い、保存先パスへの直接書き込みは行いません。クラッシュやディスク容量不足が発生しても、既存のデータは変更されません。
• インテントジャーナル：ハッシュで保護された冪等な再生により、クラッシュから復旧します。
• 5 つのソースによるアロケーター：コンテンツファイル、サイドカー、DB カウンター、リセットマーカー、ハイウォーターマークを基に、バージョン番号を単調増加させます。
• 不整合の検出：履歴の消失、飛び、ロールバック、欠落を検出して報告します。不整合がある場合、書き込みは拒否されます。読み取りは続行され、問題を示す divergence フィールドが設定されます。
• バージョンごとのサイドカー：history/v{N}.meta.json に、各バージョンの保存時刻、作成者、セッション ID、変更メモ、操作の種類が記録されます。
• 保持数のローテーション：無料プランではドキュメントごとに 5 バージョン、Pro では 100 バージョンが保持されます。古いバージョンは自動的にローテーションされます（番号は変更されません）。
• vault_verify：整合性の問題を報告し、追加のみの修復を実行できる診断ツールです。従来の Vault に異常がないか確認するには、LoreDocs をアップグレードする前に vault_verify --pre-upgrade を実行してください。

データとプライバシー

LoreDocs はローカルファーストです。すべてのデータは、お使いのマシン上の ~/.loredocs/ に保存されます。

• **収集するデータ：**ドキュメントを保存する際に指定するドキュメント名、内容、タグ、カテゴリ、Vault 名。テレメトリー、利用状況の分析データ、識別情報は自動収集されません。
• **保存場所：**SQLite データベースは ~/.loredocs/loredocs.db、ドキュメントファイルは ~/.loredocs/vaults/ に保存されます。クラウドストレージは使用しません。LOREDOCS_ROOT 環境変数でルートディレクトリを変更できます。
• **第三者との共有：**ありません。データがマシンの外部に送信されることはありません。
• 保持期間：vault_remove_doc、vault_delete、またはデータベースファイルの手動削除によって削除するまでデータを保持します。自動的な有効期限はありません。
• **お問い合わせ：**[email protected]

プライバシーポリシー全文：https://labyrinthanalyticsconsulting.com/privacy

トラブルシューティング

MCP ツールが Claude Code に表示されませんか？ 最初に uv sync を実行したことを確認してください。依存関係がインストールされた仮想環境が必要です。

「No module named 'mcp'」エラーが表示されますか？ .mcp.json は仮想環境の Python を参照しています。フォルダーを移動した場合は、uv sync を再実行してください。

Cowork から Code に保存したドキュメントが見えませんか？ 共有データベースに Cowork からアクセスできるよう、Claude に「mount my ~/.loredocs folder」と依頼してください。

フォールバックスクリプト（DB への直接アクセス）

MCP サーバーに接続できない場合（スケジュールされたタスクや自動化スクリプトなど）、scripts/query_loredocs.py を使って SQLite データベースに直接アクセスし、同じ主要な操作を実行できます。

# List all vaults
python scripts/query_loredocs.py --list

# Show vault details and document manifest
python scripts/query_loredocs.py --info "My Project Docs"

# Search documents across all vaults
python scripts/query_loredocs.py --search "architecture"

# Add a document to a vault
python scripts/query_loredocs.py --add-doc \
    --vault "My Project Docs" \
    --name "Architecture Overview" \
    --file docs/architecture.md \
    --tags '["architecture", "design"]'

# Add a document from stdin (type content, then Ctrl-D)
python scripts/query_loredocs.py --add-doc \
    --vault "My Project Docs" \
    --name "Quick Note" \
    --stdin <<'EOF'
# Quick Note
EOF

このスクリプトはデータベースを ~/.loredocs/loredocs.db から自動検出します（または --db-path を明示的に指定します）。FTS インデックスやディスク上のファイルストレージなど、MCP ツールと同じスキーマでデータを書き込みます。

更新情報

v0.1.31（2026-10-16）

セキュリティ

• CVE-2026-59951 を修正するため、MCP ライブラリ（mcp[cli]）を 1.28.1 から 1.30.0 に更新しました。起動時の互換性チェックで、1.30.0 が必要になりました。

改善点

• セマンティック検索では、埋め込みモデルをプロセスごとに一度だけ読み込み、共有するようになりました。これにより、メモリ使用量と再読み込み時間を削減できます。

完全なリリース履歴については、変更履歴をご覧ください。

ライセンス

Business Source License 1.1（BSL 1.1） - Labyrinth Analytics Consulting

個人利用および非営利利用は無料です（最大 3 つの Vault）。商用利用には有料ライセンスが必要です。2030-03-31 に Apache 2.0 に変更されます。詳細はLICENSEをご覧ください。

mcp-name: io.github.labyrinth-analytics/loredocs