# How Maguyva Works

Canonical source: https://maguyva.ai/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).

Connect a GitHub repository and Maguyva turns it into several searchable views your agent can use on demand. Instead of dumping entire files into context, the model gets grounded access to symbols, structure, docs, dependencies, and ranked code fragments.

When you connect a repository, Maguyva runs cloud ingestion pipelines over code, docs, manifests, symbols, and dependency metadata. The goal is to build durable code memory once instead of making every agent run rediscover the repo from scratch.

Those pipelines produce several specialist data layers: exact text search, semantic retrieval, symbol and reference lookups, structural views, and dependency graph analysis. Different questions route to different layers.

Maguyva offers 5 retrieval capabilities: semantic, AST, symbol, dependency, text. Within intelligent_search, four search modalities are available: semantic, text, structural, and graph. Default auto/balanced routes confident definition questions to structural search, reference or impact questions to graph, and exact-match questions to text. Other questions use semantic meaning and indexed text. Use mode=hybrid or auto with quality=thorough to request all four search modalities; an explicit mode takes precedence over quality. A language_filter omits graph from auto/hybrid and is rejected with explicit graph mode. Results from multiple modalities are fused and ranked for relevance to the query.

The private repository views sit alongside public reference data for supported languages and text-based technologies. Your agent reaches the whole system through MCP tools, which you can lean on heavily while planning and validation or use as spot checks during editing.

### 1. Repository Ingestion

- **Code Structure Analysis**: Parses files into symbols, references, and architectural boundaries
- **Dependency Resolution**: Maps how files, modules, and symbols depend on each other
- **Documentation Integration**: Pulls in repository docs and related reference material alongside the code

### Routing and Ranking

- **Relevance Scoring**: Selects retrieval evidence according to the search mode and quality preset, then ranks matches for query relevance
- **Noise Reduction**: Reduces duplicate matches and limits chunks per file so one file does not fill the result window
- **Context Prioritization**: Keeps results bounded and relevant by default. Importance boosting is opt-in with boost_by_importance=true for architecture tours, not the default ranking policy

### Stored Representations

- **Semantic Retrieval**: Finds conceptually similar code and docs even when the exact words differ
- **Symbol and Structural Views**: Supports exact symbol lookup, references, and AST-shaped questions
- **Dependency Graph Analysis**: Follows callers, imports, and impact radius across the codebase

### Security Features

- **Transport Security**: Connections to the service use HTTPS/TLS
- **Managed Storage**: Indexed data is stored on managed infrastructure with storage-level encryption at rest
- **Namespace Isolation**: Repository data is scoped by workspace and namespace through the pipeline and database query paths
- **Access Controls**: Repository access is constrained by organization and namespace boundaries

### What to Expect

- **Better Planning Accuracy**: Agents can validate an approach against the actual repository before they start coding
- **Safer Refactors**: Blast-radius and dependency checks reduce avoidable breakage
- **Lower Token Waste**: Only relevant fragments are returned instead of whole files
- **Faster Repo Understanding**: The model gets grounded answers quickly instead of rediscovering project structure every run

### Automatic Updates

- **Repository Sync**: Refreshes from GitHub sync jobs as code changes
- **Incremental Processing**: Only processes changed files for efficiency
- **Branch-Aware Context**: Maintains separate indexes per git branch so agents see the right context for each branch

Maguyva is delivered as a cloud-hosted MCP server. Your agent calls the tools for the lens it needs instead of relying on the model to remember your architecture from scratch. The four surfaces above are grouped views onto the concrete tools: Semantic Search covers `semantic_search` and `intelligent_search`; Symbol Lookup covers `find_symbol` and `get_task_context`; Structural Search covers `structural_search` and `text_pattern_search`; Dependency Graph covers `dependency_search` and `analyze_dependencies` — alongside `get_file`, `repository_context`, and `ask_maguyva` as supporting utilities. See the full [MCP API reference](https://maguyva.ai/docs/mcp-api) for all 11 tools.

Performance varies by codebase size and query complexity. Maguyva focuses on delivering the most relevant context rather than dumping entire files. See [compatibility](https://maguyva.ai/docs/compatibility) for supported languages and clients.

Results vary depending on your codebase size, complexity, and the types of queries your AI agent handles.

Connect your GitHub repositories through the Maguyva portal. Indexes refresh through GitHub sync jobs as code changes. The portal also provides API usage visibility.