# Maguyvaの仕組み

Canonical source: https://maguyva.ai/ja/docs/how-it-works

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

GitHubリポジトリを接続すると、Maguyvaはそれを、あなたのエージェントがオンデマンドで使えるいくつもの検索可能なビューへと変換します。ファイル全体をコンテキストに流し込む代わりに、モデルはシンボル、構造、ドキュメント、依存関係、ランク付けされたコードフラグメントへの、根拠のあるアクセスを得ます。

リポジトリを接続すると、Maguyvaはコード、ドキュメント、マニフェスト、シンボル、依存関係メタデータに対してクラウド取り込みパイプラインを実行します。目的は、すべてのエージェントが毎回リポジトリをゼロから再発見する代わりに、永続的なコードの記憶を一度だけ構築することです。

これらのパイプラインは、いくつかの専門データレイヤーを生成します: 正確なテキスト検索、セマンティック検索、シンボルおよび参照のルックアップ、構造ビュー、そして依存関係グラフ解析です。質問の種類によって、扱われるレイヤーが変わります。

Maguyva は 5 の検索機能を提供します: semantic, AST, symbol, dependency, text。intelligent_search では、意味、テキスト、構造、グラフの 4 つの検索モダリティを利用できます。 デフォルトの auto/balanced は、意図を高い確度で判定できる定義の質問を構造検索へ、参照や影響の質問をグラフへ、完全一致の質問をテキスト検索へ振り分けます。それ以外の質問には、意味に基づく検索とインデックス済みテキストを使います。 4 つすべてを要求するには mode=hybrid、または auto と quality=thorough を指定します。明示的に指定した mode は quality より優先されます。 language_filter を指定すると auto/hybrid からグラフが除外され、明示的な mode=graph との併用は拒否されます。 複数のモダリティによる結果は統合され、質問との関連性に応じて順位付けされます。

非公開リポジトリのビューは、対応するlanguages and text-based technologiesの公開リファレンスデータと並んで存在します。あなたのエージェントは、MCPツールを通じてシステム全体にアクセスできます。計画や検証の段階で全面的に頼ることも、編集中のスポットチェックとして使うこともできます。

### 1. リポジトリの取り込み

- **コード構造解析**: ファイルをシンボル、参照、アーキテクチャ境界に分解します
- **依存関係の解決**: ファイル、モジュール、シンボルが互いにどう依存しているかをマッピングします
- **ドキュメント統合**: コードと合わせて、リポジトリのドキュメントや関連する参考資料を取り込みます

### ルーティングとランキング

- **関連度スコアリング**: 検索モードと品質プリセットに応じて検索の根拠を選択し、クエリとの関連性に基づいて一致結果を順位付けします
- **ノイズ除去**: 重複する一致結果を減らし、ファイルごとのチャンク数を制限して、1 つのファイルが結果枠を埋め尽くさないようにします
- **コンテキストの優先順位付け**: デフォルトでは結果を関連性のある範囲に絞ります。重要度によるブーストは、アーキテクチャを概観する際に boost_by_importance=true で明示的に有効にするもので、標準の順位付け方針ではありません

### 保存されるデータ表現

- **セマンティック検索**: 言葉が完全に一致していなくても、概念的に似ているコードやドキュメントを見つけます
- **シンボル・構造ビュー**: 正確なシンボルルックアップ、参照、AST形式の質問に対応します
- **依存関係グラフ解析**: コードベース全体で、呼び出し元、インポート、影響範囲を追跡します

### セキュリティ機能

- **通信のセキュリティ**: 本サービスへの接続にはHTTPS/TLSを使用します
- **マネージドストレージ**: インデックス化されたデータは、保存時にストレージレベルの暗号化が施された管理インフラに保存されます
- **ネームスペースの分離**: リポジトリデータは、パイプラインおよびデータベースクエリの経路を通じて、ワークスペースとネームスペースの単位でスコープされます
- **アクセス制御**: リポジトリへのアクセスは、組織とネームスペースの境界によって制限されます

### 期待できること

- **計画精度の向上**: エージェントは、コーディングを始める前に、実際のリポジトリに対してアプローチを検証できます
- **より安全なリファクタリング**: 影響範囲と依存関係チェックにより、避けられる破壊を減らします
- **トークンの無駄を削減**: ファイル全体ではなく、関連するフラグメントだけが返されます
- **リポジトリ理解の高速化**: モデルは、毎回プロジェクト構造を再発見する代わりに、根拠のある回答をすばやく得られます

### 自動更新

- **リポジトリ同期**: コードの変更に応じて、GitHub同期ジョブから更新します
- **差分処理**: 効率化のため、変更されたファイルのみを処理します
- **ブランチを認識するコンテキスト**: gitブランチごとに別々のインデックスを維持し、エージェントが各ブランチに応じた正しいコンテキストを見られるようにします

Maguyvaはクラウドホスト型のMCPサーバーとして提供されます。エージェントは、モデルがゼロからあなたのアーキテクチャを記憶していることに頼るのではなく、必要な視点に応じたツールを呼び出します。上記の4つのサーフェスは、具体的なツールをグループ化したビューです: セマンティック検索は`semantic_search`と`intelligent_search`、シンボルルックアップは`find_symbol`と`get_task_context`、構造検索は`structural_search`と`text_pattern_search`、依存関係グラフは`dependency_search`と`analyze_dependencies`をカバーし、さらに補助ユーティリティとして`get_file`、`repository_context`、`ask_maguyva`があります。全11ツールについては、完全な[MCP APIリファレンス](https://maguyva.ai/docs/mcp-api)をご覧ください。

パフォーマンスは、コードベースの規模とクエリの複雑さによって変わります。Maguyvaはファイル全体を詰め込むのではなく、最も関連性の高いコンテキストを届けることに重点を置いています。対応言語とクライアントについては[互換性](https://maguyva.ai/docs/compatibility)をご覧ください。

結果は、コードベースの規模、複雑さ、そしてAIエージェントが扱うクエリの種類によって変わります。

Maguyva のポータルから GitHub リポジトリを接続します。コードの変更に応じて、GitHub 同期ジョブがインデックスを更新します。ポータルでは API の使用状況も確認できます。