Grafo semantico del codice: base tecnica per agenti AI affidabili

Se hai letto la guida all’installazione di tokensave su Windows, sai già che si tratta di uno strumento di code intelligence che espone un grafo semantico del codice agli agenti AI tramite il protocollo MCP. Ma cosa significa esattamente “grafo semantico del codice”? E perché è così importante per chi lavora con agenti AI sul codice?

Questo è il primo di tre articoli dedicati all’architettura interna di tokensave (versione 7.4.0, disponibile su crates.io). Partiamo dai fondamentali.

Che cos’è un grafo semantico del codice?

Un grafo è una struttura matematica composta da nodi (vertici) e archi (spigoli) che collegano coppie di nodi. Quando lo applichiamo al codice sorgente, i nodi rappresentano entità del codice — funzioni, classi, metodi, strutture dati — e gli archi rappresentano le relazioni tra queste entità.

Il termine semantico distingue questo approccio da rappresentazioni più elementari (come l’albero sintattico o il semplice elenco di file). Il grafo non si limita a dire “questo file esiste” o “questo token appare in quella posizione”: cattura il significato strutturale del codice, rispondendo a domande come:

• Chi chiama questa funzione?
• Quale tipo implementa questa interfaccia?
• Quali file dipendono da questo modulo?
• Qual è l’impatto di modificare questa classe?

Questa rappresentazione è particolarmente preziosa per gli agenti AI: invece di leggere decine di file raw per rispondere a una domanda sul codice (con un costo elevato in token), possono interrogare direttamente il grafo e ottenere risposte istantanee.

L’intuizione alla base di tokensave

Il documento di design ufficiale spiega chiaramente la core insight del progetto:

“AI coding agents waste tokens reading raw files when a pre-built graph can answer most questions instantly.”

Se un agente vuole sapere chi chiama la funzione authenticate_user, senza un grafo deve leggere potenzialmente centinaia di file alla ricerca di chiamate. Con il grafo, la risposta è una singola query SQL in millisecondi.

L’architettura a pipeline

tokensave struttura il lavoro come una pipeline a più stadi: i file sorgente entrano nella pipeline, vengono trasformati in nodi e archi, e il risultato viene persistito in un database SQLite interrogabile via CLI o server MCP.

flowchart TD
    A[Source Files] --> B["Tree-sitter Parsing\nparsing del codice sorgente in AST"]
    B --> C["Language Extractors\nuno per linguaggio — 50+ supportati"]
    C --> D["Nodes + Edges + Refs\nsimboli, relazioni, riferimenti non risolti"]
    D --> E["Reference Resolver\nrisoluzione dei riferimenti cross-file"]
    E --> F[("SQLite Database\npersistenza del grafo")]
    F --> G[Graph Traversal]
    F --> H[Graph Queries]
    F --> I[Context Builder]
    G --> J[MCP Server]
    H --> J
    I --> J
    J --> K["Claude / Copilot / Cursor..."]
    G --> L[CLI]
    H --> L
    I --> L
    L --> M[Terminale]

La pipeline si divide in due macro-fasi:

• Costruzione del grafo: parsing con tree-sitter, estrazione dei simboli, risoluzione dei riferimenti cross-file e persistenza in SQLite. È la fase offline, eseguita da tokensave sync.
• Interrogazione del grafo: traversate, query statiche, server MCP e context builder per gli agenti AI. È la fase online, attiva durante il lavoro dell’agente.

Conclusioni

tokensave rappresenta un approccio innovativo per ottimizzare l’interazione degli agenti AI con il codice sorgente. La costruzione di un grafo semantico permette di rispondere rapidamente a domande complesse senza dover leggere ogni singolo file, riducendo significativamente il consumo di token e migliorando l’efficienza complessiva.

Nei prossimi articoli esploreremo più in dettaglio il funzionamento interno di ciascuna fase della pipeline, con esempi pratici e approfondimenti tecnici.

Riferimenti

• Sorgente tokensave 7.4.0: crates.io/crates/tokensave
• Repository ufficiale: github.com/aovestdipaperino/tokensave
• tree-sitter: tree-sitter.github.io
• Model Context Protocol: modelcontextprotocol.io