# Come funziona Maguyva Canonical source: https://maguyva.ai/it/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). Collega un repository GitHub e Maguyva lo trasforma in diverse viste consultabili che il tuo agente può usare a richiesta. Invece di riversare interi file nel contesto, il modello accede a simboli, struttura, documentazione, dipendenze e frammenti di codice ordinati per pertinenza, con riscontri nel repository reale. Quando colleghi un repository, Maguyva esegue pipeline di acquisizione nel cloud su codice, documentazione, manifest, simboli e metadati delle dipendenze. L'obiettivo è costruire una memoria del codice duratura una sola volta, invece di far riscoprire il repo da zero a ogni run dell'agente. Quelle pipeline producono diversi livelli di dati specializzati: ricerca testuale esatta, recupero semantico, ricerca di simboli e riferimenti, viste strutturali e analisi del grafo delle dipendenze. Domande diverse vengono instradate a livelli diversi. Maguyva offre 5 funzionalità di recupero delle informazioni: semantic, AST, symbol, dependency, text. In intelligent_search sono disponibili quattro modalità di ricerca: semantica, testuale, strutturale e a grafo. L'impostazione predefinita auto/balanced indirizza le query riconosciute con alta confidenza come ricerche di definizioni alla ricerca strutturale, le domande su riferimenti o impatto al grafo e quelle su corrispondenze esatte alla ricerca testuale. Le altre domande utilizzano il significato semantico e il testo indicizzato. Usa mode=hybrid oppure auto con quality=thorough per richiedere tutte e quattro le modalità di ricerca. Una modalità scelta esplicitamente ha la precedenza su quality. language_filter esclude il grafo da auto/hybrid e viene rifiutato quando si sceglie esplicitamente mode=graph. I risultati di più modalità vengono combinati e ordinati in base alla pertinenza rispetto alla query. Le viste private del repository convivono con i dati di riferimento pubblici relativi a languages and text-based technologies supportati. Il tuo agente accede all'intero sistema tramite gli strumenti MCP: puoi usarli intensamente durante la pianificazione e la validazione, oppure per controlli puntuali durante le modifiche. ### 1. Acquisizione del repository - **Analisi della struttura del codice**: Analizza i file in simboli, riferimenti e confini architetturali - **Risoluzione delle dipendenze**: Mappa come file, moduli e simboli dipendono l'uno dall'altro - **Integrazione della documentazione**: Include la documentazione del repository e il materiale di riferimento correlato insieme al codice ### Instradamento e ordinamento dei risultati - **Punteggio di rilevanza**: Seleziona le evidenze in base alla modalità di ricerca e al livello di qualità, poi ordina le corrispondenze per pertinenza rispetto alla query - **Riduzione del rumore**: Riduce le corrispondenze duplicate e limita i frammenti per file, così un solo file non occupa tutta la finestra dei risultati - **Prioritizzazione del contesto**: Mantiene i risultati limitati e pertinenti per impostazione predefinita. Il potenziamento per importanza si attiva con boost_by_importance=true per esplorare l'architettura; non è la politica di ordinamento predefinita ### Rappresentazioni memorizzate - **Recupero semantico**: Trova codice e documentazione concettualmente simili anche quando le parole esatte differiscono - **Viste di simboli e struttura**: Supporta la ricerca esatta dei simboli, i riferimenti e le query basate sulla struttura AST - **Analisi del grafo delle dipendenze**: Segue chiamanti, import e raggio d'impatto in tutto il codice ### Funzionalità di sicurezza - **Sicurezza del trasporto**: Le connessioni al servizio usano HTTPS/TLS - **Archiviazione gestita**: I dati indicizzati sono archiviati su infrastruttura gestita con crittografia a riposo a livello di storage - **Isolamento per namespace**: I dati del repository sono delimitati per workspace e namespace lungo la pipeline e i percorsi di query del database - **Controlli di accesso**: L'accesso al repository è limitato dai confini di organizzazione e namespace ### Cosa aspettarsi - **Maggiore accuratezza nella pianificazione**: Gli agenti possono validare un approccio rispetto al repository reale prima di iniziare a scrivere codice - **Refactoring più sicuri**: I controlli di raggio d'impatto e dipendenze riducono le rotture evitabili - **Meno spreco di token**: Vengono restituiti solo i frammenti rilevanti invece di file interi - **Comprensione più rapida del repo**: Il modello ottiene rapidamente risposte fondate, invece di riscoprire la struttura del progetto a ogni run ### Aggiornamenti automatici - **Sincronizzazione del repository**: Si aggiorna tramite i job di sincronizzazione GitHub man mano che il codice cambia - **Elaborazione incrementale**: Elabora solo i file modificati per maggiore efficienza - **Contesto consapevole del branch**: Mantiene indici separati per branch git, in modo che gli agenti vedano il contesto corretto per ogni branch Maguyva viene fornito come server MCP ospitato nel cloud. Il tuo agente chiama gli strumenti per la vista di cui ha bisogno, invece di affidarsi al modello per ricordare la tua architettura da zero. Le quattro superfici sopra sono viste raggruppate sugli strumenti concreti: Ricerca semantica copre `semantic_search` e `intelligent_search`; Ricerca di simboli copre `find_symbol` e `get_task_context`; Ricerca strutturale copre `structural_search` e `text_pattern_search`; Grafo delle dipendenze copre `dependency_search` e `analyze_dependencies` — insieme a `get_file`, `repository_context` e `ask_maguyva` come utility di supporto. Consulta il [riferimento API MCP](https://maguyva.ai/docs/mcp-api) completo per tutti gli 11 strumenti. Le prestazioni variano in base alla dimensione del codice e alla complessità della query. Maguyva si concentra sul fornire il contesto più rilevante invece di riversare interi file. Consulta [compatibilità](https://maguyva.ai/docs/compatibility) per i linguaggi e i client supportati. I risultati variano in base alla dimensione e alla complessità del tuo codice e ai tipi di query gestite dal tuo agente IA. Collega i tuoi repository GitHub tramite il portale Maguyva. Gli indici si aggiornano tramite processi di sincronizzazione GitHub quando il codice cambia. Il portale permette anche di consultare l'utilizzo dell'API.