MIMRY

コーディングタスクで変更するファイルを特定し、エージェントが読む量を減らします。

スクリプトを使った検索ベンチマークで、タスクが変更するコードにたどり着くまでのトークン数を71%削減します。

MIMRYによってエージェントのトークン消費を節約できたら、スターを付けてください。

MIMRYは、AIコーディングエージェントに、タスクのために読むべきファイルと、その中の行を知らせるコマンドラインツールです。 リポジトリをシンボルと依存関係グラフに解析し、インデックスをマシン上に保持して、平易な言葉で記述されたタスクに関係するファイルをランク付けします。 インデックスは決定論的です。同じコードであれば、Windows、Linux、macOSのいずれでも同じグラフ、ランキング、コンテキストパックが生成され、作成にLLMは関与しません。 エージェントはシェルまたはMCP サーバー経由でMIMRYを呼び出します。

インストール

uv tool install mimry

Windows、Linux、macOSでPython 3.11以降が必要です。 pipx install mimryも使用できます。 システムのpipが制限されているディストリビューションでは、uvを使わない場合を参照してください。

初回のインデックス作成時に、必要なtree-sitter文法がユーザーごとに一度ダウンロードされ、キャッシュに保存されます。

メモ

アップグレードするには、mimry upgradeを実行してください。 Windowsでは、MIMRYサーバーの実行中はmimry upgradeを実行できません。先に停止するには、mimry upgrade --stop-serversを実行してください。

uvを使わない場合

MIMRYのインストールにはuvを推奨しますが、必須ではありません。 MIMRYには、専用環境のPython 3.11以降が必要です。 pipxとvenvではPATH上のPython 3を使用するため、バージョンが3.11以降である必要があります。

• pipx： Archではsudo pacman -S python-pipx、DebianおよびUbuntuではsudo apt install pipxを実行してpipxをインストールし、その後pipx install mimryを実行してください。
• 通常の仮想環境： DebianおよびUbuntuでは、まずsudo apt install python3-venvを実行してpython3-venvをインストールしてください。 python3 -m venv ~/.local/share/mimry-venvを実行し、続けて~/.local/share/mimry-venv/bin/pip install mimryを実行してください。 mkdir -p ~/.local/binを実行し、続けてln -s ~/.local/share/mimry-venv/bin/mimry ~/.local/bin/mimryを実行すると、コマンドをPATHに追加できます。

システムのpipが制限されているディストリビューションでは、通常のpip install mimryはexternally-managed-environmentエラーで失敗します。 Arch、CachyOS、Debian 12以降、Ubuntu 23.04以降などが該当するため、これらの環境では上記のいずれかの方法が必要です。 --break-system-packagesは使用しないでください。

Archでは、sudo pacman -S uvも使用できます。 AURパッケージは準備中です。詳しくは#64を参照してください。

mimry upgradeはMIMRYのインストールに使用したツールを使うため、インストール時と同じ方法で実行してください。

Docker

イメージ ghcr.io/jbacalso24/mimry にはすべての tree-sitter 文法が組み込まれているため、インデックス作成にネットワークは必要ありません。 タグは latest、1.2.3 のような完全なバージョン、および 1.2 のようなマイナーバージョンです。

リポジトリを /repo にマウントし、インデックスは名前付きボリューム /cache に保存します。 ボリュームがない場合、コンテナを起動するたびにインデックスがない状態になります。 Linux では、--user "$(id -u):$(id -g)" を追加すると、MIMRY がリポジトリ内に作成する .mimry/ フォルダーが自分の所有物になります。

docker run --rm -v "$PWD:/repo" -v mimry-cache:/cache ghcr.io/jbacalso24/mimry init
docker run --rm -v "$PWD:/repo" -v mimry-cache:/cache ghcr.io/jbacalso24/mimry index
docker run --rm -v "$PWD:/repo" -v mimry-cache:/cache ghcr.io/jbacalso24/mimry find "<query>"

エージェントで使う場合は、同じマウント設定で MCP サーバーを stdio 経由で実行します。

docker run -i --rm -v "$PWD:/repo" -v mimry-cache:/cache ghcr.io/jbacalso24/mimry mcp

MCP クライアントの設定では、$PWD は展開されないため、リポジトリの絶対パスを指定します。

{
  "mcpServers": {
    "mimry": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/absolute/path/to/repo:/repo", "-v", "mimry-cache:/cache", "ghcr.io/jbacalso24/mimry", "mcp"]
    }
  }
}

Claude Code プラグイン

Claude Code では、このプラグインを使うと、エージェントに MIMRY スキル、フック、MCP サーバーを一度に導入できます。 PATH 上に uv があれば、それ以外は必要ありません。

/plugin marketplace add jbacalso24/mimry
/plugin install mimry@mimry

これは mimry install --platform claude-code の代わりになるため、どちらか一方を使用してください。

その他のエージェント：npx skills

これはスキルのみをインストールします。MCP サーバーとフックについては、mimry install --platform <name> を実行してください（対応エージェントを参照）。

npx skills add jbacalso24/mimry

埋め込み（オプション）

find は意味に基づく検索にも対応しているため、動作を別の言葉で説明したタスクでも、異なる名前が付けられたファイルにたどり着けます。 追加機能をインストールしてモデルをダウンロードするまでは無効です。

uv tool install "mimry[embed]"
mimry embed download

mimry embed download は、Hugging Face から MIT ライセンスの 64 MB モデル（minishlab/potion-code-16M）を一度だけ取得して検証し、MIMRY のキャッシュに保存します。 その後の検索はすべてネットワーク通信なしでローカル実行されます。 この機能は、長いタスク説明（異なる単語が20語以上）に適用され、SWE-bench Verified Acc@10 を 81.4% から 83.2% に向上させました。短いクエリの順位付けは従来どおりです。 シグナルを無効にするには MIMRY_EMBED=0 を設定し、準備状況を確認するには mimry embed status を実行します。

クイックスタート

タスクの説明を指定して、リポジトリ内で mimry preflight を実行します。 初回の実行時にインデックスが作成されます。

mimry preflight "Fix session cookie not refreshed when SESSION_REFRESH_EACH_REQUEST is set"

Flask リポジトリでの出力：

Start with
   1  src/flask/sessions.py
      name matches · path matches · connected to other matches
      read first: lines 202-206 (get_cookie_secure), 233-247 (should_set_cookie)
   2  src/flask/ctx.py
      name matches · connected to other matches
      read first: lines 154-206 (copy_current_request_context), 395-403 (session)
   3  src/flask/testing.py
      name matches · connected to other matches
      read first: lines 135-183 (session_transaction), 193-202 (_request_from_builder_args)

同じ結果が、エージェント用のコンテキストパックとして .mimry/mimry-out/context/latest.md に書き込まれます。これには、一致したシンボル、関連ファイル、プロジェクトのテストコマンドが含まれます。

エージェントが自動的に MIMRY を使うようにするには、そのエージェント向けにインストールします。

mimry install --platform claude-code

ヒント

エージェントに指示しなくても MIMRY を使うようにするには、--always-on --hooks を追加します。--always-on は常に読み込まれるファイルにルールを追加し、--hooks は、リポジトリを広範囲に検索し始めたときに mimry find を提案する（セッションあたり最大3回）、既知のシンボルに対する grep にその定義と呼び出し元を付けて回答する、エージェントが大きなファイル全体を読むときにその概要を示す、といった処理を行います。また、フックはセッション開始時と各ファイルの編集後にバックグラウンドでインデックスを更新し、コンテキストが圧縮された後に作業中だったファイルを復元します。

タスクごとにファイル名を提示する（オプトイン）

--prompt-hook を指定すると、Claude Code で --hooks に加えてプロンプトフックが追加されます。 タスクを送信すると、このフックはインデックスに照らしてタスクを順位付けし、MIMRY が上位に挙げたファイル名と読むべき行を示す短いメモを追加します。 メモは800文字以内です。スラッシュコマンド、5語未満のプロンプト、コードに言及しないチャットプロンプト、同じセッション内で繰り返されたプロンプト、またはインデックス化されたファイルが3000個を超えるリポジトリやグラフが 8 MB を超えるリポジトリでは、フックは何も出力しません。 プロンプトに識別子、ソースファイル名、またはインデックス化されたファイルパスに含まれる単語がある場合、そのプロンプトはコードに言及していると見なされます。 追加しない限り、この機能は無効です。

mimry install --platform claude-code --project --hooks --prompt-hook

小規模なリポジトリでは、各プロンプトに約0.5秒かかり、その大半は検索コードの読み込みに費やされます。 無効にするには、Claude Code の起動環境で MIMRY_PROMPT_HOOK=0 を設定します。フックを削除する必要はありません。 --prompt-hook を指定せずに mimry install --platform claude-code --project --hooks を再度実行すると、フックが削除されます。

--hooks を使ったインストールでは、Stop フックも追加されます。 ターンが終了すると、そのターンのフィードバック受付期間を閉じてセッションのフィードバックを書き込むため、次のコマンドを実行するまで記録が保留されることはありません。

MIMRY が節約したトークンを確認する

mimry stats は、このセッションとリポジトリ全体で MIMRY が節約したトークン数を表示します。 MIMRY がセッション中に名前を挙げたファイルに対する範囲指定付きの Read（offset または limit を指定したもの）は、ファイルの残り全体のトークン数としてカウントされます。 フックがインデックスから回答する検索は、トークン数ではなく検索 1 回としてカウントされます。 トークン数は文字数 / 4 で推定するため、どの数値も正確ではなく概算です。 セッションの合計を Claude Code のステータス行に表示するには、Claude Code の設定で次のように設定します。

{"statusLine": {"type": "command", "command": "mimry stats --statusline"}}

機能

対応言語

MIMRY は tree-sitter で次の言語を解析します。 プログラミング言語ではシンボル、インポート、呼び出し、継承を扱います。マークアップ、スタイル、データ形式では、エージェントが検索に使う名前を扱います。詳細は表の下をご覧ください。

Fortran は自由形式のみ読み込みます。固定形式の .f および .for ファイルは MIMRY が使用する文法では解析できないため、シンボルもエッジも取得されません。

.pp と .m は最初に判定します。.pp ファイルの大半は Puppet であり、.m ファイルの大半は MATLAB であるためです。 .pp ファイルは unit、program、library のいずれかの行を含む場合に限り Pascal として扱い、.m ファイルは @interface、@implementation、@protocol、#import のいずれかの行を含む場合に限り Objective-C として扱います。 それ以外の .pp または .m ファイルは、シンボルのない検索可能なテキストとしてインデックス化されます。

マークアップ言語とスタイル言語では、エージェントが検索に使う名前を取得します。 CSS と SCSS では、クラスおよび id セレクター、カスタムプロパティ、キーフレーム、Sass ミックスイン、関数、プレースホルダー、変数を取得し、@import、@use、@forward はインポートとして扱います。 HTML では、各要素の id と、その要素が読み込むローカルのスタイルシートおよびスクリプトを取得します。 Vue と Svelte では、各コンポーネント（ファイル名を名前として使用）を取得し、<script> ブロックと <style> ブロックに JavaScript または TypeScript、および CSS または SCSS の処理を適用するため、行番号がファイルと一致します。 MIMRY は Markdown（見出し、リンク、フロントマター）、プレーンテキスト、PDF、Word、Excel、PowerPoint ファイルもインデックス化します。検索結果には、一致したページ、セクション、シート、スライドが表示されます。

ファイルによっては、テキスト以上の構造も取得します。

• SQL：.sql ファイルからスキーマオブジェクトと、それらが参照するテーブルを取得します。詳しくは以下をご覧ください。Python の文字列リテラルでは CREATE TABLE の名前が保持され、Alembic のマイグレーションではリビジョンの系譜が保持されます。
• Groovy と Gradle：.groovy、.gradle、.gvy ファイルからクラス、インターフェース、トレイト、列挙型、メソッド、関数、および Gradle ビルドの task エントリーを取得します。詳しくは以下をご覧ください。
• マニフェスト：package.json、pyproject.toml、tsconfig.json、vite.config.*、next.config.*、app.json、app.config.*、.env.example、CLAUDE.md、AGENTS.md、README.md からコマンド、フレームワーク、エントリーポイント、環境変数名を取得します。値は取得しません。

データ形式は、エージェントが検索に使う名前を取得します。 JSON、YAML、TOML では深さ 2 までのキーをパス名で取得します。たとえば、services.web や tool.ruff.line-length です。また、TOML では各テーブルヘッダーも取得します。 Kubernetes オブジェクトである YAML ドキュメントでは、Deployment/web のような <kind>/<name> リソースも取得します。 XML では id または name 属性を持つ各要素を取得し、Maven の pom.xml では groupId:artifactId を取得します。 MSBuild のプロジェクトファイルと props ファイルでは、PropertyGroup 内の各プロパティと各 Target 名を取得し、各 ProjectReference をインポートとして扱います。plist ではトップレベルの dict のキーを取得し、XAML では各 x:Name と x:Key を取得します。 Terraform では各 resource、data、module、variable、output、provider、locals エントリーを、参照される名前で取得します。たとえば、aws_s3_bucket.b、data.aws_iam_policy_document.p、module.bucket、var.region、local.name です。 var.region の参照から同じフォルダー内の変数を検索でき、モジュールのローカルな source からそのフォルダーにリンクします。 値はシンボルにならないため、値として保存されたシークレットがインデックス化されることはありません。 ロックファイルと 256 KiB を超えるファイルはシンボルを取得せず、マニフェストには上記の専用アダプターが適用されます。 すべてのデータファイルはテキストとしてもインデックス化されるため、mimry find でその内容を検索できます。

SQL ファイルでは、テーブル、ビュー、マテリアライズドビュー、インデックス、シーケンス、スキーマ、型、関数、プロシージャ、トリガーなど、各スキーマオブジェクトをソースに記述された名前で取得します。たとえば、public.users です。 テーブルを読み書きするビュー、関数、トリガー、インデックスはそのテーブルへの呼び出しエッジを持ち、外部キーの REFERENCES 先も同様です。 通常のクエリや ALTER TABLE はどのオブジェクトにも属さないため、エッジを追加しません。 パーサーが認識できないステートメントがあっても、その部分だけが対象となり、周囲のオブジェクトは保持されます。 BEGIN ... END 本体を持つトリガーでは、名前とテーブルは取得されますが、本体は読み取られません。 256 KiB を超えるファイルはシンボルを取得しないため、大きなダンプもテキスト検索できます。

Groovy と Gradle のファイルでは、各クラス、インターフェース、トレイト、列挙型、メソッド、トップレベルの def 関数をソースに記述された名前で取得します。 Spock のフィーチャーメソッドでは、adds two numbers のような文字列が名前として保持されます。 Gradle の task name または tasks.register("name") は task を取得しますが、plugins {} と dependencies {} のエントリーはシンボルになりません。 Groovy クラスの import は、そのクラスを宣言するファイルに正確にリンクし、a.b.* のようなワイルドカードインポートは、パッケージ a.b のすべてのファイルにリンクします。 import static a.b.C.* のような静的ワイルドカードインポートは、クラス C のファイルにリンクします。 メソッド本体内の呼び出しと、型の extends および implements 節は、呼び出しエッジと継承エッジを生成します。また、引数が括弧なしの name arg 形式の呼び出しは、同じファイル内のメソッドに対してのみ認識されます。 パーサーが読み取れないファイルの一部分があっても、その部分だけが対象となるため、@Service(Book) のようなアノテーション付きの型でもメソッドは保持されます。 クロージャーを代入したフィールドと、<< のような演算子メソッドはシンボルになりません。

その他の拡張子は、mimry.toml でサポートされている言語に割り当てることができます。詳しくは設定をご覧ください。

対応エージェント

mimry install --platform <name> は、MIMRY を使用するタイミングをエージェントに教えるスキルをインストールし、エージェントが対応している場合は MCP サーバーを登録します。

✅ は mimry install がセットアップすることを示し、「手動」は MCP サーバーを手作業で追加することを示します。 「なし」はエージェントが MCP に対応していないため、スキルのみで対応することを示します。 「未対応」は、エージェント用の MCP サーバーがまだ mimry install によって登録されないことを示します。

各エージェントのファイルの配置場所と MCP サーバーの登録方法については、docs/agents.md を参照してください。

claude mcp add --scope user mimry -- mimry-mcp   # Claude Code
codex mcp add mimry -- mimry-mcp                 # Codex

{
  "mcpServers": {
    "mimry": { "command": "mimry-mcp" }
  }
}

mimry preflight "<task>"            # list the files and lines to read first, and write a context pack
mimry find "<query>"                # rank files for a query
mimry symbol <name>                 # find where a function, class or heading is defined
mimry callers <name>                # list the functions that call a function, from the graph
mimry callees <name>                # list the functions a function calls, from the graph
mimry related "<query>"             # list files connected through imports and calls
mimry explain "<task>"              # show the key files and symbols, and how they connect
mimry why <file> --query "<task>"   # explain why a file ranked
mimry feedback ...                  # record which files helped
mimry status                        # check whether the index is current
mimry doctor                        # diagnose the install and the index

すべてのコマンドとオプションについては、docs/commands.md をご覧ください。 問題が発生した場合は、docs/troubleshooting.md をご覧ください。

設定

リポジトリのルートにある mimry.toml で、インデックスを作成するファイルを指定します。 チーム全員が同じインデックスを使えるように、このファイルをコミットしてください。

[index]
include = ["src/**", "docs/**"]            # index only these paths
exclude = ["**/fixtures/**", "legacy/**"]  # never index these paths
max_file_bytes = 2_000_000                 # size limit per file (default 1 MB)

[index.languages]
".inc" = "php"                             # parse .inc files as PHP
".h" = "cpp"                               # parse .h headers as C++ instead of C

MIMRY は、深さにかかわらず、build、bin、obj、dist、target、node_modules、vendor という名前のフォルダーを、キャッシュや仮想環境とともに常にスキップします。 include を指定しても、これらのフォルダーが対象に含まれることはありません。そのため、build/ 内の MSBuild プロジェクトファイルや props ファイル（build/Common.props など）からシンボルは取得されません。

ベンチマーク

ここに示す数値は、完全なエージェントセッションではなく、スクリプトによる検索ベンチマークの結果です。 2 つのスクリプトエージェントに同じタスク文と 10 回のファイル読み取り予算を与え、一方は mimry preflight から、もう一方は grep から開始します。 それぞれが固定ルールに従い、プルリクエストで変更されたすべてのファイルを読み終えるまでに読み取ったトークン数をベンチマークで計測します。 モデル駆動のエージェントは読み取るファイルを異なる方法で選ぶため、これらの数値は検索による節約を測る目安であり、実際のセッションで必ず得られる節約量ではありません。

6 つのオープンソースプロジェクトでマージされた 44 件のプルリクエストを対象に、MIMRY 0.8.4 で測定しました。この対象セットはリリースごとに再実行しています。

手法、プロジェクトごとの結果、再現方法については、benchmarks/tokens をご覧ください。

SWE-bench Verified の 500 件のイシューを対象に、mimry find をイシュー文とともに 1 回実行すると、修正で変更されるすべてのファイルが、81.4% のイシューで上位 10 件、71.8% で上位 5 件、44.8% で 1 位に表示されます。 オプションの埋め込みを使うと、これらの数値はそれぞれ 83.2%、75.6%、48.0% になります。 プロトコルとリポジトリごとの結果については、benchmarks/localization をご覧ください。

マージ済みのプルリクエストを使って自分のリポジトリで MIMRY を測定するには、mimry bench を実行してください。リポジトリのベンチマークをご覧ください。

1 つのタスクを最初から最後まで

holdout2 の実行で使われたタスク fastapi/typer#1820 を、スクリプトエージェントが読み取ったとおりに示します。「xdg-open で URL を起動するときに wait=False を尊重する」。 修正では typer/main.py が変更されました。 75.3% という節約率はこの実行の中央値であり、最高値ではなく、典型的なタスクを表しています。

MIMRY なし

エージェントは respect、wait、false、launching、urls、xdg、open で 7 回キーワード検索を実行し、1,927 トークンを消費します。 続いて typer/main.py を先頭から読み、読み取り 1 回あたりのベンチマーク上限である 2,000 行まで読み進め、13,491 トークンを消費します。 合計：15,418 トークン。

MIMRY あり

mimry preflight "Respect wait=False when launching URLs with xdg-open" の実行に 1,876 トークンを消費します。 続いてエージェントは、コンテキストパックの順に 6 つの行範囲を読み取り、1,937 トークンを消費します。

合計：3,813 トークン。

MIMRY は 1 つではなく 6 つのファイルを開きましたが、それでも読み取ったトークン数を 75.3% 削減しました。3,813 トークンに対し、15,418 トークンです。

この数値は results.holdout2.ranges.0.4.1.json に基づいており、トークンベンチマーク実行 38884765315 で MIMRY 0.4.1 を使って測定したものです。 再現方法については、実行方法をご覧ください。

仕組み

1. インデックス作成。 MIMRY は各ファイルを解析し、インポート、呼び出し、継承のシンボルとエッジを抽出して、リポジトリの外にあるユーザーのキャッシュディレクトリにインデックスを保存します。
2. ランキング。 MIMRY はタスクをファイル名、パス、コンテンツ、シンボル、グラフと照合し、解決できないインポートは推測せずに除外します。
3. 更新。 Git と同様に、MIMRY はファイルのメタデータを比較し、変更されたファイルだけを読み込み直します。

詳細は docs/how-it-works.md を参照してください。

プライバシー

インデックス作成と検索はローカルで実行されます。 認証情報を含むファイルはスキップされます。 コードファイルでは、password = "..." や cfg["password"] = "..." のような代入、if token == "..." のような比較、コメント、または URL のパスワードや認証情報クエリに含まれる、シークレットらしき値は、インデックスに渡る前に秘匿化されます。 シークレットを適切に秘匿化できないファイルはスキップされます。 フィードバックのテキストも秘匿化されます。 .gitignore に記載された未追跡のファイルはインデックスに追加されません。

貢献

バグ報告やプルリクエストを歓迎します。 セットアップとチェックについては CONTRIBUTING.md を参照してください。 MIMRY はパブリックアルファ版であり、1.0 より前にインターフェースが変更される場合があります。

貢献してくださった皆さんに感謝します。

ライセンス

MIT