# Como o Maguyva Funciona Canonical source: https://maguyva.ai/pt-br/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). Conecte um repositório GitHub e o Maguyva o transforma em várias visões pesquisáveis que seu agente pode usar sob demanda. Em vez de despejar arquivos inteiros no contexto, o modelo recebe acesso fundamentado a símbolos, estrutura, documentação, dependências e fragmentos de código ordenados por relevância. Quando você conecta um repositório, o Maguyva executa pipelines de ingestão na nuvem sobre código, documentação, manifests, símbolos e metadados de dependência. O objetivo é construir uma memória de código durável uma única vez, em vez de fazer com que cada execução de agente redescubra o repositório do zero. Esses pipelines produzem várias camadas de dados especializadas: busca de texto exata, recuperação semântica, buscas de símbolos e referências, visões estruturais e análise de grafo de dependências. Perguntas diferentes são roteadas para camadas diferentes. Maguyva oferece 5 capacidades de recuperação: semantic, AST, symbol, dependency, text. intelligent_search disponibiliza quatro modalidades de busca: semântica, texto, estrutural e grafo. Por padrão, auto/balanced direciona perguntas sobre definições cuja intenção identifica com confiança para a busca estrutural, perguntas sobre referências ou impacto para o grafo e perguntas de correspondência exata para o texto. As demais perguntas usam o significado semântico e o texto indexado. Use mode=hybrid ou auto com quality=thorough para solicitar as quatro modalidades de busca. Um mode explícito tem prioridade sobre quality. language_filter exclui o grafo de auto/hybrid e é rejeitado com mode=graph explícito. Os resultados de várias modalidades são combinados e ordenados por relevância para a consulta. As visões de repositório privado ficam lado a lado com dados de referência públicos para languages and text-based technologies suportadas. Seu agente acessa todo o sistema através das ferramentas MCP, nas quais você pode se apoiar fortemente durante o planejamento e a validação, ou usar como verificações pontuais durante a edição. ### 1. Ingestão do Repositório - **Análise de Estrutura de Código**: Analisa arquivos em símbolos, referências e limites arquiteturais - **Resolução de Dependências**: Mapeia como arquivos, módulos e símbolos dependem uns dos outros - **Integração de Documentação**: Traz a documentação do repositório e material de referência relacionado junto com o código ### Roteamento e Ordenação por Relevância - **Pontuação de Relevância**: Seleciona evidências de recuperação conforme o modo de busca e a predefinição de qualidade, depois classifica as correspondências pela relevância para a consulta - **Redução de Ruído**: Reduz correspondências duplicadas e limita os trechos por arquivo para que um único arquivo não preencha toda a janela de resultados - **Priorização de Contexto**: Mantém os resultados limitados e relevantes por padrão. A ponderação por importância é ativada explicitamente com boost_by_importance=true para explorar a arquitetura; não é a política padrão de ordenação ### Representações Armazenadas - **Recuperação Semântica**: Encontra código e documentação conceitualmente semelhantes, mesmo quando as palavras exatas são diferentes - **Visões de Símbolos e Estruturais**: Permite a busca de símbolos por nome exato, a consulta de referências e perguntas sobre a estrutura do AST - **Análise de Grafo de Dependências**: Segue chamadores, imports e raio de impacto por toda a base de código ### Recursos de Segurança - **Segurança de Transporte**: As conexões com o serviço usam HTTPS/TLS - **Armazenamento Gerenciado**: Os dados indexados são armazenados em infraestrutura gerenciada, com criptografia em repouso no nível de armazenamento - **Isolamento de Namespace**: Os dados do repositório são escopados por workspace e namespace em todo o pipeline e nas consultas ao banco de dados - **Controles de Acesso**: O acesso ao repositório é restrito por limites de organização e namespace ### O Que Esperar - **Melhor Precisão de Planejamento**: Os agentes podem validar uma abordagem contra o repositório real antes de começar a codificar - **Refatorações Mais Seguras**: Verificações de raio de impacto e dependência reduzem quebras evitáveis - **Menos Desperdício de Tokens**: Apenas fragmentos relevantes são retornados, em vez de arquivos inteiros - **Compreensão Mais Rápida do Repositório**: O modelo recebe respostas fundamentadas rapidamente, em vez de redescobrir a estrutura do projeto a cada execução ### Atualizações Automáticas - **Sincronização de Repositório**: Atualiza a partir de jobs de sincronização do GitHub conforme o código muda - **Processamento Incremental**: Processa apenas arquivos alterados para maior eficiência - **Contexto com Reconhecimento de Branch**: Mantém índices separados por branch do git, para que os agentes vejam o contexto certo para cada branch O Maguyva é entregue como um servidor MCP hospedado na nuvem. Seu agente chama as ferramentas para a lente de que precisa, em vez de depender do modelo para lembrar sua arquitetura do zero. As quatro superfícies acima são visões agrupadas sobre as ferramentas concretas: Busca Semântica cobre `semantic_search` e `intelligent_search`; Busca de Símbolos cobre `find_symbol` e `get_task_context`; Busca Estrutural cobre `structural_search` e `text_pattern_search`; Grafo de Dependências cobre `dependency_search` e `analyze_dependencies` — junto com `get_file`, `repository_context` e `ask_maguyva` como utilitários de apoio. Veja a [referência da API MCP](https://maguyva.ai/docs/mcp-api) completa para todas as 11 ferramentas. O desempenho varia de acordo com o tamanho da base de código e a complexidade da consulta. O Maguyva foca em entregar o contexto mais relevante, em vez de despejar arquivos inteiros. Veja [compatibilidade](https://maguyva.ai/docs/compatibility) para linguagens e clientes suportados. Os resultados variam de acordo com o tamanho e a complexidade da sua base de código, e os tipos de consultas que seu agente de IA processa. Conecte seus repositórios GitHub pelo portal do Maguyva. Os trabalhos de sincronização do GitHub atualizam os índices conforme o código muda. O portal também mostra o uso da API.