Droste

---

クイックスタート

v1.3.0 を PyPI または GitHub Releases からインストールします。 リリース状況を参照してください。

# Windows
python -m pip install --upgrade droste-memory

# macOS / Linux
python3 -m pip install --upgrade droste-memory

droste index . # index the current repo
droste view    # open the fractal galaxy in your browser

一度インストールすれば、インデックスを作成して表示できます。droste view を実行すると、 コードのズーム可能な全画面マップが開きます。スクロールしてプロジェクトの星からフォルダーの軌道へ、 さらに個々の関数とインデックス化された関係へと進みます。

自分で見るのではなく、エージェントに使わせたいですか？

droste explore "checkout flow" --tokens 1500

返されたノード ID を --focus に指定し、--level map、structure、または source を選ぶと、同じ領域を異なる詳細度で移動できます。used は、選択したトークナイザーに基づいて コンパクトな応答全体を計測します。ソース本文が収まらない場合は、明示的にダウングレードされます。 後でオフラインで使えるよう、小さなトークナイザー語彙は一度だけ droste explore --prepare-tokenizers で準備してください。ワークフロー、利用記録、計測済みの上限を参照してください。 従来の droste context --budget インターフェースでは、引き続き文字数を基準に予算を設定します。

日常的なコード調査には、次を使います。

droste check                         # verify source hashes and index coverage
droste find calculate                # find symbol IDs, paths and line numbers
droste references calculate --direction both
droste references helper --file src/math.py --direction callers --depth 3
droste watch .                       # refresh after additions, edits, renames or deletions

references は、名前が曖昧な場合の候補を返します。推測するのではなく、ファイルまたはシンボル ID を選択してください。 Python のリンクには呼び出し式とソース行が含まれます。 ほかの言語のリンクでは、ヒューリスティックな解決方法が示されます。check は、古いインデックス、不完全なインデックス、または検証できないインデックスに対してステータス 1 で終了します。コンテキストの応答では、簡易的なサイズ／更新日時の確認によって、古い状態やカバー範囲が不完全な状態を警告します。check はさらに SHA-256 ハッシュを検証します。古いインデックスを信頼する前に実行してください。

インデックス作成では、ネストされた .gitignore ルールとプロジェクトルートの .drosteignore（Git の ignore 構文。最後に適用）が尊重されます。シンボリックリンク、生成されたバンドル、依存関係ディレクトリ、Droste 自身のストレージは除外されます。独立した書き込み処理を実行する場合は、プロジェクトごとに明示的な --db を指定してください。watch はルートの更新をまとめ、変更のない抽出処理／埋め込みを再利用します。view はスナップショットのままなので、更新されたグラフを表示するには開き直してください。

引数なしで droste を実行すると、コマンドパレットが表示されます。

                  .-----------------------.
             .----'           |           '----.
         .---'          .-----+-----.          '---.
       .'          .----'     |     '----.          '.
      /        .---'      .---+---.      '---.        \
     /      .-'        .-'    |    '-.        '-.      \
    |     .'        .-'   .---+---.   '-.        '.     |
    |    /        .'    .'    |    '.    '.        \    |
    |   |        |     |   .--+--.   |     |        |   |
    | --+--------+-----+---+  @  +---+-----+--------+-- |
    |   |        |     |   '--+--'   |     |        |   |
    |    \        '.    '.    |    .'    .'        /    |
    |     '.        '-.   '---+---'   .-'        .'     |
     \      '-.        '-.    |    .-'        .-'      /
      \        '---.      '---+---'      .---'        /
       '.          '----.     |     .----'          .'
         '---.          '-----+-----'          .---'
             '----.           |           .----'
                  '-----------------------'

DROSTE-MEMORY // RIGID FRACTAL RADIAL LAYOUT
Local Graph Engine v1.3.0-Alpha-Sharded

Commands
  droste index <path> [--reset]
  droste status
  droste zoom <symbol_name>
  droste context [query] --budget 1500
  droste explore [query] --tokens 2000 --level map|structure|source
  droste mcp

Fast path: droste context hub_core --budget 1000 | clip

---

異なる点

Droste は、語彙検索と意味検索を、静的コードグラフおよびインタラクティブなマップと組み合わせます。グラフを使えば、クエリと共通する単語が少なくても、呼び出し元や呼び出し先をコンテキストに含められます。グラフベースの MCP 検索を提供する他のツールもあります。詳しくは、日付入りのエコシステムレビューをご覧ください。

Droste は、小規模な Python CLI、予算に応じたコンテキスト、視覚的な探索に重点を置いています。グラフは静的な近似であり、名前の照合や言語間ブリッジによって誤検出が発生することがあり、実行時の動作を証明するものではありません。

便利な構成要素は次のとおりです。

• 説明可能な静的参照。 Python の呼び出しでは、字句スコープ、インポートのエイリアス、明示的な self／cls メンバーを使用します。動的レシーバーは解決されないままです。他の言語では、ローカル名または一意の名前で照合し、候補が曖昧な場合はスキップします。
• 言語間ブリッジ。 Droste は言語をまたいでリンクします。アプリケーションコードと SQL 関数／テーブル（.rpc('x')、.from('table')）、エッジ関数、さらに任意の 2 言語間で名前が同じハンドラーを結び付けます。Dart／TS／Python のフロントエンドとデータベースが、マップ上で別々の世界ではなくなります。
• 視覚的な探索。 インタラクティブな放射状マップで、ファイル、シンボル、インデックス化された関係をたどれます。
• 設定不要でローカル。 クラウド、アカウント、API キーは不要です。fastembed（ONNX、torch 不使用）により実際の意味検索が可能になり、決定論的なフォールバックによってどこでも実行できます。

マルチ言語対応：Python（AST）と、Dart、TypeScript／JavaScript、Go、Rust、Java、C#、C／C++、Kotlin、Swift、Ruby、PHP、SQL 用の tree-sitter に対応し、シンボルとエッジの両方を扱います。

対象範囲について： 測定された優位性は、構造的／因果的な検索にあります。純粋に意味上の「概念」を問うクエリでは、ベクトル検索のベースラインと競合する水準であり、大きく上回るわけではありません。言語間ブリッジは、対象がインデックス化されたリポジトリ内で実際に定義されている場合（例：マイグレーション内の SQL スキーマ）に最も効果を発揮します。

---

ベンチマーク

公開ソース検証では、手動でラベル付けされたエッジのアサーションを使い、Requests と CPython の固定リビジョンを検証します。現時点では 20 件中 19 件のアサーションに合格しています。期待されるエッジ 16 件中 15 件を検出し、禁止されたエッジは 4 件中 0 件を出力しました。検出できなかったエッジについては記録してあります。この小規模なコーパスは、エージェントタスクのベンチマークでも、競合製品との比較でもありません。

python eval/public_corpus.py --output public-results.json

評価スクリプトは、同じコードから参照用に抽出した呼び出し元／呼び出し先の関係を使い、構造検索を語彙検索およびベクトル検索のベースラインと比較します。これはグラフ近傍の検索を測定するものであり、エージェントのタスク完了能力や他製品に対する優位性を測定するものではありません。固定された公開コーパス、固定リビジョン、完全な結果ファイルを公開するまで、以前の目立つ数値は掲載しません。

python eval/comparative_eval.py --repos /path/to/public/repo --sample 60 --seed 7 --json results.json

意味検索の比較には、実際の埋め込みバックエンドを使用してください。オフラインのハッシュモードは決定論的ですが、意味的な類似性は提供しません。

---

仕組み

• 静的グラフ。 Python のスコープとインポートから名前付き呼び出しを解決します。それ以外のサポート対象言語では、tree-sitter が定義と参照を提供します。名前に基づくリンクと、言語をまたぐ DB／文字列ブリッジはヒューリスティックであり、参照結果にその旨が示されます。実行時の動作や完全な型解決を保証するものではありません。
• ハイブリッドシード。 クエリは、字句スコアと意味的コサイン類似度（fastembed bge-small-en-v1.5、384 次元）を正規化して組み合わせたスコアで照合され、グラフがシードを双方向に展開します（呼び出し先と呼び出し元）。
• 段階的エクスプローラー。 explore はメタデータを含む応答全体を、参照トークン数で予算管理します。ノード ID を使ってマップ、構造、ソースをたどり、保持したビューの内容を再送しないよう、完全一致するビューを確認します。
• レガシーコンテキストパッカー。 context --budget の単位は文字数で、最小値は 500 です。ソース全体、コントラクト、または明示的なソーススタブは、区切り文字も含め、この実効上限に収まります。このレガシーインターフェースでは、トークナイザー固有のカウントは保証されません。
• シャーディングされた永続化。 データベース固有の .droste/ ディレクトリ内にファイルごとにシャードを作成し、blake2b による変更追跡で、再インデックス時には変更箇所だけを書き換えます。ファイルは原子的に置き換え、メタデータを最後に書き込みます。複数ファイルの更新はトランザクションではありません。DB ごとに書き込み元を 1 つにし、書き込みが中断された後は再インデックスしてください。

---

MCP サーバーとして使う

Droste はそのまま使える MCP サーバーです。AI エージェントは、ファイルを手当たり次第に読み込む代わりに、主なコードメモリとして Droste を呼び出せます。クライアント設定ファイル（例：Cursor、Claude Desktop、Codex）に以下を追加してください。

まず、現在の PyPI リリースをインストールするか、アップグレードしてください。

# Windows
python -m pip install --upgrade droste-memory

# macOS / Linux
python3 -m pip install --upgrade droste-memory

droste mcp --help

Codex の場合、Windows では C:\Users\<you>\.codex\config.toml に、macOS／Linux では ~/.codex/config.toml に以下を追加してください。

[mcp_servers.droste]
command = "droste"
args = ["mcp"]
startup_timeout_sec = 120

インストール済みパッケージでは、デフォルトのデータベースが Windows の %LOCALAPPDATA%/Droste、macOS の ~/Library/Application Support/Droste、Linux の ${XDG_DATA_HOME:-~/.local/share}/droste に保存されます。ソースチェックアウトでは、リポジトリ内のデータベースが維持されます。DROSTE_DB を設定するか、--db を渡すと保存先を変更できます。古いインストール内にある既存のデータベースは自動的に移動されません。引き続き使うには、--db で古いファイルを指定するか、ソースを再インデックスしてください。

明示的にオフラインで運用するには、DROSTE_EMBEDDING_BACKEND=hash を設定してください。デフォルトの auto バックエンドでは、初回使用時に埋め込みモデルがダウンロードされる場合があります。コードはローカルで処理されます。ハッシュモードでは、決定論的でネットワーク不要の埋め込みを得る代わりに、意味検索の精度が低下します。droste view はスナップショットを提供するため、インデックス作成後に再実行してください。

デフォルトでは、droste mcp は Droste のグローバルなローカルデータベースを使用します。手早く使う場合や小規模なワークフローでは問題ありません。複数のリポジトリを本格的に扱う場合は、リポジトリごとにデータベースを使ってください。各プロジェクトのメモリが分離され、エージェントが reset=true を指定して安全にそのプロジェクトを再インデックスできます。

--db オプションはグローバルオプションなので、mcp より前に指定してください。

# Windows example
[mcp_servers.droste]
command = "droste"
args = ["--db", "C:/Users/you/AppData/Local/Droste/my-project/droste_memory_db.json", "mcp"]
startup_timeout_sec = 120

# macOS / Linux example
[mcp_servers.droste]
command = "droste"
args = ["--db", "/Users/you/.local/share/droste/my-project/droste_memory_db.json", "mcp"]
startup_timeout_sec = 120

JSON ベースの MCP クライアントの場合：

{
  "mcpServers": {
    "droste": {
      "command": "droste",
      "args": ["mcp"]
    }
  }
}

同じ分離 DB のパターンは JSON クライアントでも使えます。

{
  "mcpServers": {
    "droste": {
      "command": "droste",
      "args": [
        "--db",
        "/absolute/path/to/droste_memory_db.json",
        "mcp"
      ]
    }
  }
}

MCP 設定を変更した後は、クライアントを再起動してください。プロジェクトをインデックス化し、droste_check_index を呼び出してから、コンテキストを取得する前にシンボル検索と参照検索を使用してください。変更を加える前に、実際のソースを確認してください。

主なツール：droste_index_project、droste_check_index、droste_find_symbols、droste_references、droste_explore、droste_get_context、droste_status。 補助キャンバスツール：inject_concept、move_camera_and_zoom、get_space_status。 droste_explore は、トークン予算を使った段階的な探索経路です。既存の MCP 接続では再接続するまで以前のプロセスが維持され、新しい接続ではアップグレード後のツール一覧が読み込まれます。保持ビューのハンドルが有効なのは、クライアントが対応するテキストを保持している間だけです。コンパクション後はハンドルをクリアしてください。

エージェントスキルとして使う

Droste には、Codex と Claude 用のエージェントスキルテンプレートも同梱されています。これらは、分離された DB、インデックス作成、droste context、MCP の設定、ルート汚染を防ぐガードレールなど、Droste を安全に使う方法をエージェントに教えます。

Codex スキル：

integrations/codex-skill/droste-code-memory/

Claude 互換スキル：

integrations/claude-skill/droste-code-memory/

Codex スキルをインストールするには、フォルダーを Codex のスキルディレクトリにコピーします。

# macOS / Linux
mkdir -p ~/.codex/skills
cp -R integrations/codex-skill/droste-code-memory ~/.codex/skills/

# Windows PowerShell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\skills" | Out-Null
Copy-Item -Recurse -Force integrations\codex-skill\droste-code-memory "$env:USERPROFILE\.codex\skills\"

続いて、Codex に次のように依頼します。

Use $droste-code-memory to index this repository and retrieve causal context before editing.

Claude の場合は、Claude スキルのフォルダーを Claude スキルパッケージとしてインポートまたはコピーし、SKILL.md、references/、scripts/ をまとめて配置してください。

---

開発

pip install -e ".[dev]"
pytest                            # deterministic regression suite (tests/)
python eval/comparative_eval.py   # retrieval benchmark vs lexical & vector cores

tests/ = 不変条件と並行処理（往復、ダーティオラクル、パッカーのガードレール、プロセス間のシャード競合）。eval/ = パフォーマンス／品質ベンチマーク。

---

ステータス

v1.3.0（アルファ版）。 トークン予算に応じた段階的な探索、テスト済みの CLI／MCP ワークフロー、ソースの鮮度チェック、明示的に制限された静的グラフを備えています。動的ディスパッチ、レシーバー型の推論、言語をまたいだ完全な解決は、現時点での保証対象外です。データベースごとに書き込み担当を 1 つにしてください。検証と制限を参照してください。

v1.3.0 の新機能

• droste explore と droste_explore を使って、map → structure → source を検索・ズームできます。
• 実際の o200k_base／cl100k_base トークン数で、レスポンス全体のサイズを制限します。
• クライアントがビューを引き続き保持していると確認できた場合に限り、完全に変更のないビューを再利用します。
• ナビゲーション前にソースハッシュを検証し、詳細度の低下や省略箇所を明示します。
• 記録済みのインタラクティブデモ、正確な公開レスポンス、および 10 番目の MCP ツールのインストール済み wheel 検証を追加します。

v1.2.1 の新機能

• 明示的で一意なシンボル検索を、意味的に似た候補より優先します。
• コンパクトなコンテキストでも、完全なソース位置情報を保持します。
• 未解決の検出やトレース上の弱点を含む、実践的な Requests 調査を公開します。比較によるパフォーマンスの主張はありません。

v1.2.0 の新機能

• Python のスコープ／インポート解決を修正し、曖昧な名前の一致を推測しないようにしました。
• find、references、check と対応する MCP ツールを、ソースの根拠とともに追加しました。
• 編集、追加、削除、名前変更の後に、サポート対象のすべての言語を更新します。
• カバレッジの一部欠落と古いコンテキストを報告し、--reset 中もほかのルートを保持します。
• ignore ルールに従い、Java、C#、Ruby、PHP のファイルを実際に収集します。
• キャッシュされた埋め込みをモデル ID ごとに分離し、バックエンドの切り替え時に再構築します。
• 独立した公開ソースのアサーションを追加し、9 つすべての MCP ツールを実行して検証します。

v1.1.7 の新機能

• 互換性のある 1.x SDK を必須にすることで、新規インストール時の MCP 起動を復旧しました。
• 現行の tree-sitter Python API で、多言語の構文エッジを復旧しました。
• droste --db ... view が指定されたデータベースを可視化するよう修正しました。
• 読み取り専用インストールの場合も含め、ビューアーのスナップショットに一時ストレージを使用します。
• 同じフォルダーを共有するデータベース間で、シャード、レジストリ、埋め込みキャッシュを分離しました。
• インストール済みパッケージでは書き込み可能なユーザーデータストレージを使用し、DROSTE_DB で上書きできるようにしました。
• Windows CI、wheel の内容チェック、インストール済み CLI／ビューアー／MCP のスモークテストを追加しました。
• デモのホームページを復旧し、競合製品との差別化を更新しました。

v1.1.6 の新機能

• インストール済みパッケージにビジュアライザーの HTML／テンプレートと公開デモグラフを同梱し、PyPI wheel で droste view が使えるよう修正しました。
• クリーンインストールから次の 3 コマンドを実行できることを確認しました。 pip install droste-memory、droste index .、droste view。

v1.1.5 の新機能

• プロジェクトのスキャン対象から Droste 自身の .droste/、.tmp/、*.egg-info ディレクトリを除外し、自己インデックスによる汚染を修正しました。
• フォーカスノードの直接の呼び出し元／呼び出し先を、二次的な字句一致より先に固定することで、少ない予算でのコンテキストパッキングを改善しました。
• 完全なコンテキストに収まらない場合でも、重要なワームホールが消えないよう、因果的に真に隣接するノードのコンパクトなスタブを必ず含めるようにしました。

v1.1.4 の新機能

• Python 3.12 専用の Path.walk() の使用を置き換え、Python 3.10／3.11 との互換性を修正しました。
• 一致する PyPI リリースが公開されてからのみメタデータを公開するよう、MCP Registry への公開処理を強化しました。
• 複数バージョンのリリースに関するデバッグを迅速化するため、CI の診断機能を改善しました。

v1.1.3 の新機能

• エージェント側で Droste を導入するための、Codex および Claude 向けの公開スキルテンプレートを追加しました。

v1.1.2 の新機能

• README／PyPI の説明に MCP Registry の所有者メタデータを追加しました。
• 公式 MCP Registry への公開用に server.json を追加しました。
• MCP Registry への公開と可視性チェックのため、手動およびスケジュール実行のワークフローを追加しました。

v1.1.1 の新機能

• パッケージングとプライバシーを強化しました。生成されたビジュアライザーの JSON ファイル（graph.json、status.json、context.json）をソース配布物から除外しつつ、公開用の visualizer/demo_graph.json は引き続き含めています。

v1.1.0 の新機能

• MCP のコンテキストをルートごとに分離しました。droste_index_project はアクティブなリポジトリを記録し、droste_get_context／droste_status は、エージェントが別の root を明示的に渡さない限り、そのルートに絞り込みます。
• 安全なルートを推定できない場合、マルチルートデータベースが複数のリポジトリを暗黙に混在させることはなくなりました。その場合、Droste は適切な警告を返します。
• 古い端末エンコーディングで UnicodeEncodeError によるクラッシュを避けるため、Windows の CLI 出力を UTF-8 コンソール向けに保護しています。
• 検索順位がクエリを考慮するようになりました。通常の実装に関するクエリではランタイムコードにわずかな加点を行い、クエリがテストやドキュメントを求める場合は、それらも引き続きすべて表示します。

ライセンス

MIT — LICENSE を参照してください。