local-rag

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

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

mimirsによるインデックス後：91Kトークン、約3秒 — そのコードベースでは76%削減。実際の数値はリポジトリの規模、クエリ、モデルによって異なります。

クイックスタート

1. 前提条件

Bun（curl -fsSL https://bun.sh/install | bash）と、macOSではモダンなSQLiteが必要です。Apple標準のSQLiteは拡張機能をサポートしていないためです：

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 です。

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

「command not found: bunx」/サーバーが起動しない（でもターミナルでは bunx が動く）場合？ Dockやデスクトップランチャーから起動したエディタはシェルのプロファイルを読み込まないため、~/.bun/bin がPATHに含まれません。以下のスニペットの素の bunx の代わりに、which bunx で得られる絶対パスを command に使ってください。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"
      }
    }
  }
}

WindsurfはプロジェクトではなくホームディレクトリからMCPサーバーを読み取ります。JetBrainsプラグイン版は ~/.codeium/mcp_config.json を使用します。

{
  "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"
      }
    }
  }
}

VS CodeのCopilotは servers マップ（mcpServers ではありません）と type フィールドを使用します。

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

CodexはJSONではなくTOMLを使用し、~/.codex/config.toml から読み取ります。プロジェクトごとに1ブロック。複数のリポジトリを接続する場合は一意のテーブル名を選んでください（mimirs-frontend、mimirs-api など）。

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

あるいは、同等の展開されたenvテーブルを使う場合：

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

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

プロジェクトが読み取り専用マウント上にある場合は、RAG_DB_DIR に書き込み可能な場所を設定してください。インデックスは <project>/.mimirs/ の代わりにそこに保存されます。

{
  "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

Related MCP server: codeix

手動ワークフロー（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クエリ、約1/3が難しいもの）を使用してベンチマークし、2026-06-04に現在のパイプラインで再測定しました。詳細な方法論は BENCHMARKS.md にあります。

大規模リポジトリ（Kubernetes、Excalidraw）は十分に大きいため、正解ファイルの一部がトップ10をわずかに外れてランクされます。トップ20までで再現率は97〜100%に達するので、大規模リポジトリでは searchTopK: 15–20 に設定してください。

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

また、mimirsを ContextBench（実リポジトリでのゴールドコンテキスト取得）でも実行しました。他のエントリは単一呼び出しのツールではなく、複数ステップで探索する本格的なコーディングエージェントです。焦点を絞ったクエリ（LLMがissueを読んだ後に送るもの）が与えられた場合、mimirsの1回の取得呼び出しは、エージェント全体の軌跡に対して次のようにランク付けされます：

mimirsは単一呼び出しで両方のカバレッジ指標でトップです。ファイル精度が最下位なのは意図的です。正解ファイルを逃すと致命的です（LLMは修正対象のコードを見られません）が、余分なファイル参照は簡単にフィルタリングできます。そのためmimirsは再現率を最大化し、精度の仕上げはモデルに任せます。そして、その低いファイル精度はほとんど指標の産物です。mimirsが返す非正解ファイルの約86%は、修正に紐づいた関連コンテキスト（呼び出し元、型、兄弟実装）であり、ノイズではありません。正解と比較した精度は0.19、関連性と比較した精度は0.87です。

同じ再現率で、コストはわずか。 grepのみのエージェント（生のissue、インデックスなし、修正内容を覗き見なし）と直接対決し、同じ15件のissueを特定した場合：mimirsはLLMトークンゼロの約15msの1回の呼び出しで関連クラスターを届けます。一方エージェントは収束までにissueあたり約11.5回のツール呼び出し（それぞれがLLMステップ）を要し、しかも主要ファイルで止まってしまいました。複数ファイルにまたがる修正では、エージェントは正解ファイルの**22%に到達したのに対し、mimirsはその1回の呼び出しで56%**に到達しました。依存関係グラフが、issueが名前すら挙げていない副次ファイルを浮かび上がらせるのです。

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

他との比較

既存のツールではだめなのか？

• Continue.dev の @codebase — 機能が最も重複するもの(ローカル RAG、オープンソース)だが、検索はエディタ拡張内に存在する。Mimirs は、エージェントが計画を立てられる明示的なツール(search、read_relevant、project_map、search_conversation、annotate)を備えたスタンドアロン MCP サーバーであり、さらに会話テーリングとウィキ生成機能が組み込まれている。

• Aider の repo-map — リポジトリの静的 tree-sitter サマリーであり、埋め込みなし。賢く軽量だが、サマリーは検索ではない — mimirs はクエリごとにチャンクをベクトル + BM25 でランク付けし、グラフ中心性でブーストする。

• Sourcegraph Cody / OpenCtx — コード検索に優れているが、インデックスはクラウドインフラとアカウントに依存している。Mimirs は bunx を実行するだけで、マシンの外に出ることはない。

• llama-index / LangChain / 自作 — これらはライブラリだ。Mimirs はバッテリー同梱:AST 認識チャンキング、ハイブリッド検索、ファイルウォッチャー、会話テーリング、アノテーションがすでに統合されている。

動作の仕組み

1. 解析とチャンク化 — 型に合わせた戦略でコンテンツを分割する:コードは関数/クラス境界(24言語にわたる tree-sitter を使用)、Markdown は見出し、YAML/JSON はトップレベルキー。埋め込みモデルのトークン上限を超えるチャンクは、ウィンドウ化されて結合される。

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

3. 依存関係グラフの構築 — インポート指定子とエクスポートされたシンボルは AST チャンキング中に取得され、ファイルレベルの依存関係グラフとシンボルレベルのコールグラフを構築するために解決される。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 にキャッシュされる。コードがマシンの外に出ることはない — 何もサーバーに送信されない。

サポート対象言語

bun-chunk と tree-sitter 文法による 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、その他。既知の拡張子を持たないファイルは、段落分割にフォールバックする。

ドキュメント

• Example tool outputs — エージェントが MCP 経由で実際に受け取るもの

• MCP ツール、CLI とアナリティクス

• 設定と例

• ベンチマーク

技術スタック

すべてのデータはプロジェクト内の .mimirs/ に保存される — .gitignore に追加しよう。