Local Rag

MIMIRS

北欧神話の知恵と知識の神 ミーミルにちなんで名付けられました。

AI コーディングエージェントのための永続的なプロジェクトメモリ。セットアップはコマンド1つ、メンテナンスは不要です。

エージェントは毎回のセッションを何も知らない状態で開始します — ファイル名を推測し、キーワードで grep し、無関係なファイルでコンテキストを浪費し、昨日話し合ったことをすべて忘れてしまいます。

ある実際のプロジェクトでは、典型的なプロンプトが 380K トークンとエンドツーエンドで約12秒 を消費していました。

mimirs でインデックス化した後は 91K トークン、約3秒 — そのコードベースでは76%の削減です。数値はリポジトリのサイズ、クエリ、モデルによって変わります。

クイックスタート

1. 前提条件

Bun (curl -fsSL https://bun.sh/install | bash) と、macOS では最新の SQLite — Apple が同梱しているものは拡張機能をサポートしていません。

brew install sqlite

Linux と Windows には互換性のある SQLite がすでに同梱されています。

2. エディタのセットアップ (自動)

bunx mimirs init --ide claude   # or: cursor, windsurf, copilot, jetbrains, all

これにより MCP サーバーの設定、エディタのルール、.mimirs/config.json、.gitignore のエントリが作成されます。--ide all を付けて実行すると、対応するすべてのエディタを一度にセットアップできます。

init は Claude Code、Cursor、Windsurf、Copilot、JetBrains (Junie) に対応しています。それ以外 — Codex、Zed、カスタムクライアント — については、以下のスニペットのいずれかをコピーしてください。

3. エディターのセットアップ (手動リファレンス)

mimirs MCP サーバーは stdio 経由で動作します。どのクライアントでも必要なものは同じ 3 つです。command (bunx)、args (["mimirs@^1", "serve"])、そしてプロジェクトルートを指す RAG_PROJECT_DIR 環境変数です。

なぜ @latest ではなく @^1 なのですか? この範囲指定なら 1.x 系に留まるため、バグ修正や新機能は引き続き自動的に届きますが、破壊的変更を含む将来の 2.0 が、あなたが望まない限り適用されることはありません。メジャーバージョンを上げるには、引数を編集するか bunx mimirs init を再実行してください。すでに設定に mimirs@latest がある場合、bunx mimirs init を再実行すると mimirs@^1 に書き換えられます。

「command not found: bunx」/ サーバーが起動に失敗する (でもターミナルでは bunx が動く) 場合 Dock やデスクトップランチャーから起動されたエディターはシェルプロファイルを読み込まないため、~/.bun/bin が PATH に入っていません。以下のスニペットでは、command に素の bunx ではなく which bunx で取得した絶対パスを使用してください。bunx mimirs init は絶対パスを自動的に書き込みます (既存の設定を修正するには再実行してください)。また、bunx mimirs doctor がこの問題を検出します。

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "servers": {
    "mimirs": {
      "type": "stdio",
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

[mcp_servers.mimirs]
command = "bunx"
args = ["mimirs@^1", "serve"]
env = { RAG_PROJECT_DIR = "/absolute/path/to/your/project" }

[mcp_servers.mimirs]
command = "bunx"
args = ["mimirs@^1", "serve"]

[mcp_servers.mimirs.env]
RAG_PROJECT_DIR = "/absolute/path/to/your/project"

{
  "mcpServers": {
    "mimirs": {
      "command": "bunx",
      "args": ["mimirs@^1", "serve"],
      "env": {
        "RAG_PROJECT_DIR": "/read/only/project",
        "RAG_DB_DIR": "/home/me/.cache/mimirs/myproject"
      }
    }
  }
}

4. 最初のインデックス

MCP サーバーは最初のクエリ時に遅延インデックスを作成するので、接続が完了すればエージェントに何か尋ねるだけで大丈夫です。事前に完全なインデックスを強制的に作成するには (大規模なリポジトリで便利です):

bunx mimirs index            # current directory
bunx mimirs status           # how many files, chunks, embeddings

5. デモを試す (任意)

bunx mimirs demo

手動ワークフロー（init なし）

init は便利機能です。エディターの設定（MCP 設定、エージェントルール、.gitignore、.mimirs/config.json）を行います。ただし、インデックスは構築しませんし、以下のどの手順にも init は必要ありません。インデックスとデフォルト設定は、最初にインデックスを作成またはクエリしたときに自動的に作成されます。

1. MCP サーバーを手動で追加します。 上記の手動リファレンスから、お使いのクライアント用のスニペットを貼り付けます。command: "bunx"、args: ["mimirs@^1", "serve"]、そしてプロジェクトルートを指す RAG_PROJECT_DIR を指定します。MCP のセットアップはこれだけです。

init を使わない場合、エージェントルールファイルが存在しないため、アシスタントはツールの存在を認識できません。プロンプトで mimirs に言及するか、CLAUDE.md からツール一覧をコピーしてエディターのルールに追加してください。

2. インデックスを構築します。 MCP サーバーは最初のツール呼び出し時に遅延してインデックスを作成するため、エージェント経由であればこの手順は省略できます。事前にインデックスを作成する場合（大規模リポジトリで推奨され、以下の CLI の search/read の前には必須です）:

bunx mimirs index                                # current directory
bunx mimirs index /path/to/repo                  # a specific directory
bunx mimirs index --patterns "src/**/*.ts,*.md"  # restrict to globs
bunx mimirs status                               # files, chunks, embeddings

init も設定ファイルも不要です。デフォルトが適用され、インデックスは <project>/.mimirs/ に書き込まれます。

3. CLI からクエリします。 読み取りコマンドは 2 つあり、どちらもカレントディレクトリのインデックスに対して実行されます（別の場所を指定するには --dir を使用します）:

# Where is it? — ranked file paths + snippet previews
bunx mimirs search "where is auth handled" --top 10

# What is it? — the actual matching code chunks (functions, classes, sections)
bunx mimirs read "jwt validation" --top 8 --threshold 0.3

--ext .ts,.tsx、--in src,packages/core、または --exclude tests で対象を絞り込めます。注意: CLI の search/read は自動インデックス作成を行いません。先に mimirs index を実行してください（オンデマンドでインデックスを作成するのは MCP サーバーだけです）。

Claude Code プラグイン

より深い統合のために、mimirs は Claude Code プラグインとしても利用できます。Claude Code セッションで:

/plugin marketplace add https://github.com/TheWinci/mimirs.git
/plugin install mimirs

このプラグインは MCP サーバー、3 つのフック — SessionStart（コンテキストの要約）、PostToolUse（編集時の自動再インデックス作成）、SessionEnd（自動チェックポイント） — 、そして一般的な作業のためにツールを編成するワークフロースキルのセットを接続します: explore、plan、review、debug、research、recall、catch-up、handoff、doc-gaps、scout、wiki。

プラグインなしでスキルを使いたいですか? スキルは skills/ 配下の単なる SKILL.md ファイルです。気に入ったものをプロジェクトの .claude/skills/<name>/（リポジトリと共有）または ~/.claude/skills/<name>/（すべてのプロジェクト）にコピーすると、Claude Code が次のセッションで読み込みます。スキルは Claude Code の機能であるため、他のエディターには適用されません — ただし、MCP ツール自体はどこでも動作します。

検索品質

Recall@10 で 89～97%、Recall@20 で 97～100%、MRR 0.69～0.77。3 言語にわたる 4 つの実在するコードベースで、層化された難易度混在のクエリセット（各 72～120 クエリ、約 ⅓ が難問）を用いてベンチマークし、2026-06-04 に現在のパイプラインで再測定しました。完全な方法論は BENCHMARKS.md にあります。

大規模なリポジトリ（Kubernetes、Excalidraw）では、一部の正しいファイルがトップ 10 のちょうど外側にランクされる程度に大きいため、トップ 20 までで recall は 97～100% に達します。そのため、大規模リポジトリでは searchTopK: 15–20 を設定してください。

コーディングエージェントとの比較（ContextBench）

また、ContextBench（実際のリポジトリにおけるゴールドコンテキスト検索）で mimirs を実行しました。ContextBench の他のエントリは完全なコーディングエージェント——マルチステップの探索者——であり、単一呼び出しのツールではありません。フォーカスされたクエリ（LLM が issue を読んだ後に送信するもの）が与えられた場合、mimirs の 1 回の検索呼び出しは、エージェントの軌跡全体に対して次のようにランク付けされます。

mimirs は単一呼び出しで両方のカバレッジ指標をリードしています。ファイル精度が意図的に最下位なのは、ゴールドファイルを見逃すことは致命的（LLM が修正すべきコードを決して目にしない）であり、余分なファイル参照はフィルタリングするのにほとんどコストがかからないためです。したがって mimirs はリコールを最大化し、精度のパスはモデルに任せます。そしてこの低いファイル精度は、主に指標そのものによるアーティファクトです。mimirs が返す非ゴールドファイルの約 86% は、ノイズではなく修正に結合した関連コンテキスト（呼び出し元、型、類似実装）です——ゴールドに対して測定すると精度は 0.19、関連性に対して測定すると 0.87 です。

同じリコールを、わずかなコストで。 grep のみのエージェント（生の issue、インデックスなし、修正をのぞき見しない）と同じ 15 の issue を特定する直接対決では、mimirs は関連クラスタを 1 回の約 15 ms の呼び出しで、LLM トークンゼロで提供します。エージェントは収束するまでに issue あたり約 11.5 回のツール呼び出し（それぞれが LLM ステップ）を要し——しかもプライマリファイルで停止しました。マルチファイルの修正では、エージェントはゴールドファイルの 22% にしか到達しませんでしたが、mimirs はその単一呼び出しで 56% に到達しました——依存関係グラフが、issue が決して名指ししないセカンダリファイルを浮かび上がらせます。

n=15 のサンプル対エージェントの 500 セット——方向性を示すもの。エージェントのツール呼び出しは自己申告で上限あり。完全なリーダーボード、注意事項、関連性 + コストの表は BENCHMARKS.md にあります。

比較

なぜ既存のツールではないのか？

• Continue.dev の @codebase — 最も近い重複（ローカル RAG、オープンソース）ですが、検索はエディタ拡張機能の中に存在します。Mimirs はスタンドアロンの MCP サーバーであり、エージェントが計画を立てられる明示的なツール（search、read_relevant、project_map、search_conversation、annotate）に加え、会話の追跡と wiki ジェネレーターを内蔵しています。
• Aider の repo-map — リポジトリの静的な tree-sitter サマリーで、埋め込みはありません。巧妙で軽量ですが、サマリーは検索ではありません——mimirs はベクトル + BM25 でクエリごとにチャンクをランク付けし、グラフ中心性でブーストします。
• Sourcegraph Cody / OpenCtx — コード検索に優れていますが、インデックス作成はクラウドインフラとアカウントに依存しています。Mimirs は bunx 一つで使え、マシンから決して出ません。
• llama-index / LangChain / 自作 — これらはライブラリです。Mimirs はバッテリー同梱です。AST 対応のチャンキング、ハイブリッド検索、ファイルウォッチャー、会話追跡、アノテーションがすでに配線されています。

仕組み

1. 解析とチャンク分割 — タイプに応じた戦略でコンテンツを分割します。コードは関数/クラスの境界（tree-sitter により 24 言語に対応）、Markdown は見出し、YAML/JSON はトップレベルのキーで分割します。埋め込みモデルのトークン上限を超えるチャンクは、ウィンドウ処理してマージされます。

2. 埋め込み — 各チャンクは all-MiniLM-L6-v2（Transformers.js + ONNX によるインプロセス処理、API 呼び出しなし）を使って 384 次元のベクトルになります。ベクトルは sqlite-vec に保存されます。

3. 依存関係グラフの構築 — AST チャンク分割の際に import 指定子とエクスポートされたシンボルを取得し、その後解決してファイルレベルの依存関係グラフとシンボルレベルのコールグラフを構築します。impact はある関数の推移的な呼び出し元をたどり（影響範囲 + 実行すべきテスト）、trace はあるシンボルが別のシンボルにどう到達するかを調べ、mimirs affected CLI は git diff を実行すべきテストの正確なセットに変換します。

4. ハイブリッド検索 — クエリはベクトル類似度と BM25 を並行して実行し、逆順位融合（重み付き、デフォルト 0.5）で統合します。これは 2 つのスコアラーの大きく異なるスコアスケールに対して堅牢です。識別子は分割される（camelCase/snake_case）ため、depends の検索は getDependsOn に一致します。その後、結果は依存関係グラフの中心性とパスのヒューリスティクスによってブーストされます。read_relevant はエンティティ名と正確な行範囲（path:start-end）を含む個々のチャンクを返します。

5. 監視と再インデックス — ファイルの変更は 2 秒のデバウンスで検出されます。変更されたファイルは再インデックスされ、削除されたファイルは削除されます。

6. 会話とチェックポイント — Claude Code の JSONL トランスクリプトをリアルタイムで追跡します。エージェントは重要なタイミングでチェックポイントを作成し、将来のセッションで検索できます。

7. アノテーション — ファイルやシンボルに付与されたノートは、read_relevant の結果内に [NOTE] ブロックとしてインラインで表示されます。

8. 分析 — すべてのクエリがログに記録されます。分析では、結果ゼロのクエリ、関連性の低いクエリ、および期間ごとのトレンドが明らかになります。

データの取り扱い

mimirs は完全にあなたのマシン上で動作します。リポジトリが追跡しているファイルに加え、未追跡だが gitignore されていないファイルもインデックスします（そのため、gitignore し忘れた .env が読み取られる可能性があります — .env、*.pem、*.key、SSH キーなどの一般的なシークレットパターンはデフォルトで除外されます。独自のパターンは .mimirs/config.json の exclude に追加してください）。ファイルの内容と埋め込みは、ローカルの SQLite ファイルである <project>/.mimirs/index.db に保存されます。会話のインデックス作成は、~/.claude/projects/<this-project>/ 配下の現在のプロジェクトのトランスクリプトのみを読み取ります。

唯一のネットワーク呼び出しは、huggingface.co からの埋め込みモデル（Xenova/all-MiniLM-L6-v2）の一度きりのダウンロードで、~/.cache/mimirs/models にキャッシュされます。あなたのコードがマシンから出ることはありません — どのサーバーにも何も送信されません。

対応言語

tree-sitter グラマーを用いた bun-chunk による AST 対応のチャンク分割：

TypeScript、JavaScript、Python、Go、Rust、Java、C、C++、C#、Ruby、PHP、Scala、Kotlin、Lua、Zig、Elixir、Haskell、OCaml、Dart、Bash/Zsh、TOML、YAML、HTML、CSS/SCSS/LESS

その他にインデックスされるもの：Markdown、JSON、XML、SQL、GraphQL、Protobuf、Terraform、Dockerfiles、Makefiles など。既知の拡張子を持たないファイルは、段落分割にフォールバックします。

ドキュメント

• ツール出力の例 — あなたのエージェントが MCP 経由で実際に受け取るもの
• MCP ツール、CLI、分析
• 設定と例
• ベンチマーク

スタック

すべてのデータはプロジェクト内の .mimirs/ に存在します — .gitignore に追加してください。