navigator

mentu-navigator

人間と AI エージェントのための、読み取り専用で来歴を重視したリポジトリナビゲーションツールです。

リポジトリを指定して質問すると、読むべきファイルと行の範囲をランキング順に返します。それぞれの範囲には、ランク付けの理由が付いています。読み取り対象のリポジトリに書き込みを行うことはありません。リポジトリ全体をコンテキストに取り込まずに、ドキュメントの多いリポジトリから質問への答えとなる文書を見つけなければならないエージェントと、そのエージェントの作業をレビューする人のために構築されています。

対象範囲。 ランキングのデフォルトは、事前登録された研究（エビデンスを参照）において、ドキュメント、つまり Markdown コーパスで評価されています。公開済みの比較ではほかのロケーターが優位とされているソースコードについては、評価されていません（エビデンスの対象範囲を参照）。コード構造を扱うコマンド（map、symbol、impact）はどのリポジトリでも機能しますが、その有用性は評価されていません。

mentu-navigatorは製品名です。mentu-navは短縮版の CLI です。

インストール

Node.js 20 以降が必要です。

npm install -g mentu-navigator     # CLI: mentu-nav, MCP server: mentu-navigator-mcp

インストールせずに実行するには：

npx -p mentu-navigator mentu-nav "where is retry handled?"

パッケージ名とコマンド名が異なるため、npx mentu-navigatorだけではバイナリを解決できません。上記のように-pを指定してください。

ライセンス：Apache-2.0。テレメトリは~/.mentu/pd1/に保存されるローカル限定の JSONL です（仕様：docs/TELEMETRY-SPEC.md）。MENTU_NAV_TELEMETRY=offで無効にできます。データがマシンの外に送信されることはありません。

Mentu における位置づけ

mentu-navigatorは検索機能を担います。 mentu-pdvは、このツールが使用するフロントマターのスキーマを検証し、locateが適用する降格セットを出力します。この2つはペアとして設計されており、スキーマは仕様として公開されています （SPEC-frontmatter.md）。

開発の背景

検索ツールは一致するテキストを見つけます。リポジトリナビゲーターはさらに、質問の意図を保持し、安全に作業するために必要な関連する契約、テスト、ドキュメント、Git の系譜、リスクのある領域も返します。

最初のリリースは、意図的に決定論的な設計になっています。

• 埋め込み表現を使用しません。
• バックグラウンドでインデックスを作成しません。
• 対象リポジトリに書き込みません。
• 文書へのルーティングに使う、オンデマンドで範囲を限定したフロントマターハンドルを使用します。ハンドルが文書の読み取りに取って代わることはありません。
• ファイルと行の来歴を示す、範囲を限定したスニペットを返します。
• コンテンツを読み取る前に、秘密情報を含むことが判明しているパスを除外します。

ワンコマンドで開始

cd /path/to/repository
mentu-nav
mentu-nav "where is DEMO-274 implemented and tested?"

対話型ターミナルには簡潔な人間向けの表示が、パイプにはコンパクトな JSON が出力されます。--jsonを指定すると、完全なエンベロープを取得できます。 エージェントは、コンパクトでトークン効率の高い JSON コントラクトを得るために--agentを使用してください。

mentu-nav --agent "where is DEMO-274 implemented and tested?"

エントリーポイントは、map、query、handles、symbol、impactへ自動的にルーティングします。スクリプトや高度な用途向けに、各コマンドを明示的に指定することもできます。

ドキュメントをコードとして扱うネットワークの場合：

mentu-nav handles "catalog lineage"

メタデータへのポインター、型付きの関係、診断情報を返します。すべてのポインターにはrequiresHydration: trueが付与されます。queryはこれらのポインターをソース本文のエビデンスとは分けて扱うため、要約が回答として暗黙に扱われることはありません。

機能

機能	回答する質問	エビデンス
map	ここには何がありますか？	ファイル、言語、契約、マニフェスト、型付きドキュメント、Git の状態
query	関連するエビデンスはどこにありますか？	ランク付けされたパス／行／スニペットのヒットとルーティング理由
locate	どの範囲を読むべきですか？	検索元の帰属情報付き BM25 ランキングのヒット（エビデンスに基づくデフォルト）
read-range	その範囲には何が書かれていますか？	見出し単位で区切られたスライス。フロントマターは別に返されます
handles	どのドキュメントや型付きの関係が関係する可能性がありますか？	フロントマターポインター、関係の解決、診断情報。ハイドレーションが必要
symbol	このシンボルの周辺には何がありますか？	定義、参照、テスト、ドキュメント、設定
impact	この変更は何に影響する可能性がありますか？	Git の範囲、チケット、契約、テスト、リスクシグナル

段階的な開示：locate と read-range

locate はエージェント向けのインターフェースです。デフォルトのアームは**ランク付けされた語彙検索 （BM25）**です。このデフォルトは好みで決めたのではなく、事前登録された研究に基づいています（下記の エビデンスを参照）。アームは2つあります。

• ランク付けされた語彙検索アーム：ウォーカーがすでに生成しているものと同じファイルセットを対象とする、メモリー内の Okapi BM25 です。スペイン語と英語には同梱の Snowball ステマーを使用し、各ドキュメントの lang フロントマタータグに基づいて振り分けます（フォールバックとして検出も行いますが、検出結果はログに記録されるだけで、書き込まれることはありません）。
• 完全一致アーム：セマンティクスに変更のない決定論的な query パイプラインです。

2つのアームを統合するアーム（両アームの逆順位融合）も、測定用として用意されています。もともとはデフォルトでしたが、事前登録された比較試験で通常の BM25 よりローカライズ精度が7.8ポイント低いと判明したため、独自の事前登録済みアブレーションルールに基づき、デフォルトの経路から除外されました（エビデンスを参照）。各ヒットには、どのアーム（または両方）がその結果を取得したかが示されます。

mentu-nav locate "compaction policy" --k 8
mentu-nav read-range docs/adr/ADR-014-ledger-compaction.md 38 62 --widen 1

locate は {path, line, range, snippet, score, retriever, why} を返します。これは読み取る範囲であり、回答ではありません。read-range はその範囲を返します。--widen を指定するたびに前後へさらに20行ずつ範囲を広げますが、包含する見出しの境界で止まります。フロントマターは個別のフィールドで返されるため、メタデータを本文の根拠と取り違えることはありません。ハンドルは引き続きポインターレイヤーとして変更されず、すべてのポインターに requiresHydration: true が含まれます。

固定パラメーター

これらは実装の詳細ではなく、設計パラメーターです。それぞれがアブレーションとして登録され、測定されます。変更する場合は、日付を明記した判断と再測定が必要です。

パラメーター	値	制御する内容
LOCATE_DEFAULT_K	8	locate がデフォルトで返すヒット数
LOCATE_MAX_K	40	呼び出し元が指定する値にかかわらず、k に設定できる上限
SNIPPET_MAX_CHARS	240	スニペットの長さ。空白は正規化され、1行になります
WIDEN_STEP_LINES	20	read-range の1回分の範囲拡大
RRF_K	60	逆順位融合の定数
DEMOTION_MULTIPLIER	0.5	降格されたドキュメントに適用するペナルティ

従来の query コマンドは、ユーザー向けのデフォルト結果数として40件を維持します。上記の固定値は locate に適用されます。

降格

--demotions <path> は pdv demotions JSON ファイルを読み込みます（リポジトリのルートを基準に解決されます）。対象ドキュメントのスコアに0.5を掛けます。降格されたドキュメントの順位は下がりますが、削除されることはありません。ドキュメントを利用できない状態にするほうが、より重大なエラーです。降格セットを読み取れない場合、または形式が不正な場合は、黙って無視せず、エンベロープの診断情報に報告します。

--retriever は測定用です

--retriever=bm25|exact|fused はアームを選択します（デフォルトは bm25）。このフラグは、登録済みの比較試験で、ハーネスを分岐させずに同梱コードの経路から各アームの結果を生成できるようにするためのものです。デフォルトは、まさにこの方法で決定しました。このフラグは調整用のつまみではありません。

エビデンス

このツールのパフォーマンスに関わるすべてのデフォルト設定は、登録済みの機械的な判定を伴う研究に基づいており、以下のすべての主張には適用範囲が明記されています。対象は、141 文書からなるバイリンガルの運用ドキュメントコーパス、新たに用意された 115 問のブラインドセット、そしてこのツールの k=8 契約です。ベイクオフ （doi:10.5281/zenodo.21969901、 doi:10.5281/zenodo.21960138 の付随研究）：

• BM25 は質問の 93.0% で正解文書を特定しました。一方、強化された完全一致検索では 71.3% でした（McNemar p < 1e-5）。これが bm25 をデフォルトにしている理由です。
• 融合方式は BM25 単独を 7.8 pp 下回りました（p = 0.0225）。事前に固定した「融合によって位置特定の性能が低下することはない」という予測を満たせなかったため、事前登録済みのアブレーション規則に従い、デフォルトの経路から除外しました （docs/build/D3-REVISION-2026-08-16.md）。
• 既製の SQLite FTS5 対照群（89.6%）とこの実装との間に、統計的に有意な差はありませんでした。向上をもたらすのは BM25 そのものです。
• より優れた位置特定方式により、後続の回答精度は +5.2 pp 向上しました。そのほぼすべてが位置特定によるものです。

ここでの主張は、対象コーパスの種類を超えて一般化できるとは述べていません。再実行に必要な研究、コーパスマニフェスト、質問セット、判定者は、上記 DOI で公開されています。

エビデンスの適用範囲

これらのデフォルト設定の根拠となった研究はすべて Markdown ドキュメントを使用しており、ソースコードを使用したものはありません。この違いは重要です。課題の説明から変更対象のファイルを探す作業は、語句の重なりが少ないタスクであり、公開済みの比較では BM25 の埋め込み検索に対する順位は低くなっています。SWE-bench Lite では、BM25 が正しいファイルを上位 5 件に含めた割合は 61.7% で、コード埋め込み検索では 84.7% でした （Chen ら、LocAgent、Table 4）。したがって：

• ドキュメント（ランブック、ADR、仕様書など）で回答できる質問には、locate を使用してから、返された範囲を読み取ってください。
• 課題や動作の説明からコードを探す場合は、コードを対象とした研究が行われるまでは、使用中のハーネスに標準搭載された検索機能か、コードを認識するロケーターを優先してください。
• 実稼働中のエージェント内で、このツールをハーネス標準のツールと比較する事前登録済みの比較試験が、コードの位置特定を対象とする層を設けて草案作成されています。まだ実施されていません。実施後は、結果にかかわらずこのセクションで報告します。

さらに、すべてのコミットでテストスイートが検証するのは、インデックスは対象リポジトリに何も書き込まず、プロセスの実行中はメモリ上に保持されること、同一のコーパスとクエリでは実行やインデックスの再構築を行ってもバイト単位で同一のヒットリストが生成されること、シークレットを含むパスはトークン化の後ではなく前に除外されること、そして - で始まる検索パターンはリテラルの -- の後に渡され、検索エンジンのフラグとして解析されることが決してないことです。

MCP

mentu-navigator-mcp は次を公開します：

• navigator：推奨される、コンパクトで自動ルーティング対応のエントリーポイント
• locate：retriever と demotions を使用した BM25 順位付け済みの範囲
• read_range：locate が引き継ぐ、情報開示のステップ
• navigator_map
• navigator_query
• navigator_handles
• navigator_symbol_context
• navigator_change_impact

MCP クライアントの設定：

{
  "mcpServers": {
    "mentu-navigator": {
      "command": "npx",
      "args": ["-y", "-p", "mentu-navigator", "mentu-navigator-mcp"]
    }
  }
}

または、インストール済みのバイナリ mentu-navigator-mcp を直接起動します。

エージェントのセットアップ

mentu-nav setup --target all
mentu-nav doctor --human

セットアップでは、同梱のスキルを複製せずに Codex と Claude にリンクします。既存のパスは置き換えません。リポジトリのナビゲーション自体は引き続き読み取り専用です。

導入

実行可能ファイルは引き続き一元管理されます。各リポジトリで導入するのは短い運用契約のみで、実装をコピーすることはありません。docs/adoption.md を参照してください。