Grafi di conoscenza invece di gigabyte di embedding per l'analisi del codice nei monorepo

Una situazione comune: fornisci un grande monorepo a un assistente AI, e inizia a confondere chiamate di funzione di servizi vicini, perdere connessioni tra moduli e inventare argomenti inesistenti. La ricerca vettoriale classica è piuttosto brava a trovare frammenti di testo simili. Tuttavia, le rappresentazioni vettoriali faticano a comprendere la rigida struttura del codice, dove una singola variabile rinominata o un import implicito cambia la logica dell'intera applicazione.

Lo sviluppatore Vitaliy ha creato il progetto code-graph-rag per risolvere questo problema in modo sistematico. Invece di basarsi esclusivamente sugli embedding vettoriali, lo strumento costruisce un grafo di conoscenza del codebase.

Come funziona internamente

Il sistema si basa su tre componenti principali: il parser Tree-sitter, il database a grafi Memgraph e il database vettoriale Qdrant.

Ecco come funziona:

1. Tree-sitter analizza i file del codice sorgente in alberi di sintassi astratta (AST).
2. L'analizzatore estrae i nodi: funzioni, classi, metodi, moduli e le relazioni tra di essi.
3. I dati vengono scritti in Memgraph con uno schema unificato e indipendente dal linguaggio.
4. Su questa struttura, un'utilità CLI cgr traduce le domande in linguaggio naturale in query Cypher precise verso il database a grafi.

Di conseguenza, quando chiedi "dove viene usata la funzione X e dove fluiscono i suoi dati successivamente?", il sistema non cerca di indovinare la risposta basandosi sulla vicinanza vettoriale nello spazio. Esegue una query mirata sul grafo e restituisce il percorso effettivo delle chiamate.

Исходный код -> Tree-sitter -> AST-анализ -> Граф знаний Memgraph
                                                  |
Запрос пользователя -> AI-модель (Cypher) -> Запрос Cypher -> Результаты

Cosa può fare lo strumento

Il progetto supporta 13 linguaggi, tra cui Python, TypeScript, Go, Rust, Java, C++, C# e PHP. Il supporto per Scala è ancora in sviluppo, mentre Ruby utilizza il pattern matching ast-grep per il parsing.

Ecco i principali compiti cgr risolve:

• Navigazione e domande sul codice. Puoi interrogare le sorgenti delle funzioni non solo per nome, ma anche per significato o ruolo nell'architettura.
• Rilevamento del codice morto. L'utilità attraversa il grafo delle relazioni dai punti di ingresso dell'applicazione e trova funzioni o moduli irraggiungibili attraverso qualsiasi catena di chiamate.
• Ricerca e sostituzione strutturale. Invece delle classiche espressioni regolari, utilizza ast-grep. Lo strumento cerca pattern nell'albero di sintassi e riscrive attentamente il codice preservando la struttura.
• Tracciamento del flusso dei dati. La funzionalità FLOWS_TO traccia come un valore di variabile passa attraverso una catena di assegnazioni, chiamate di funzione e termina in operazioni di I/O. Attualmente il tracciamento funziona per C#, Java, C e Go.

Un bonus extra è il supporto per il Model Context Protocol (MCP). Questo significa che code-graph-rag può essere eseguito come server MCP e connesso direttamente a Claude Code o qualsiasi altro client abilitato MCP. Gli agenti AI potranno interrogare autonomamente la struttura esatta del progetto e suggerire modifiche come diff pronti all'uso.

Avvio rapido e requisiti di sistema

Lo strumento è distribuito come pacchetto Python code-graph-rag. Per la funzionalità completa, dovrai installare Docker (richiesto per i container Memgraph e Qdrant), oltre alle utilità di sistema cmake e ripgrep.

Il modo più semplice per installare l'utilità CLI è tramite uv o pipx:

uv tool install "code-graph-rag[treesitter-full,semantic]"

Dopo l'installazione, devi configurare l'ambiente locale e avviare l'indicizzazione del repository:

# Запуск контейнеров базы данных
cgr daemon up

# Индексация кодовой базы в новый граф
cgr start --repo-path /path/to/repo --update-graph --clean

# Интерактивный режим работы
cgr start --repo-path /path/to/repo

Se prevedi di utilizzare l'utilità come parte di CI/CD o di connetterla a un agente tramite MCP, la documentazione contiene una sezione dettagliata sulla configurazione e l'esportazione del grafo.

Vale la pena adottarlo?

Il progetto sembra promettente per i team che lavorano con monorepo multilingua. Gli assistenti AI regolari spesso non riescono quando il codebase supera le centomila righe e le connessioni da servizio a servizio si basano su chiamate di funzione attraverso cartelle diverse. L'approccio a grafi risolve radicalmente questo problema, mescolando la topologia rigorosa del codice con la flessibilità dei modelli linguistici.

Certo, dovresti considerare la curva di apprendimento. Dovrai eseguire un container Docker con Memgraph, allocare risorse per la costruzione del grafo durante la scansione iniziale e configurare le chiavi API LLM. Ma se sei stanco delle allucinazioni delle reti neurali durante il refactoring di un progetto complesso, dedicare mezz'ora a familiarizzare con code-graph-rag vale sicuramente la pena.