Grafos de Conhecimento em Vez de Gigabytes de Embeddings para Análise de Código em Monorepos

Uma situação familiar: você alimenta um monorepo grande para um assistente de IA, e ele começa a misturar chamadas de funções de serviços vizinhos, perdendo conexões entre módulos e inventando argumentos inexistentes. A busca vetorial comum é bastante boa em encontrar fragmentos de texto similares. No entanto, representações vetoriais têm dificuldade em entender a estrutura rígida do código, onde uma única variável renomeada ou importação implícita muda a lógica de toda a aplicação.

O desenvolvedor Vitaliy criou o projeto code-graph-rag para resolver esse problema de forma sistemática. Em vez de confiar apenas em embeddings vetoriais, a ferramenta constrói um grafo de conhecimento do codebase.

Como Funciona Por Dentro

O sistema é construído sobre três componentes principais: o parser Tree-sitter, o banco de grafos Memgraph e o banco de vetores Qdrant.

Aqui está como funciona:

1. Tree-sitter analisa arquivos de código fonte em árvores de sintaxe abstrata (AST).
2. O analisador extrai nós: funções, classes, métodos, módulos e os relacionamentos entre eles.
3. Os dados são escritos no Memgraph sob um schema unificado e independente de linguagem.
4. Sobre essa estrutura, um utilitário CLI cgr traduz perguntas em linguagem natural em consultas Cypher precisas para o banco de grafos.

Como resultado, quando você pergunta "onde a função X é usada e para onde seu dado flui em seguida?", o sistema não tenta adivinhar a resposta baseada na proximidade vetorial no espaço. Ele executa uma consulta direcionada no grafo e retorna o caminho real de chamadas.

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

O Que a Ferramenta Pode Fazer

O projeto suporta 13 linguagens, incluindo Python, TypeScript, Go, Rust, Java, C++, C# e PHP. O suporte a Scala ainda está em desenvolvimento, e Ruby usa correspondência de padrões com ast-grep para análise.

Aqui estão as principais tarefas cgr resolve:

• Navegação e perguntas e respostas sobre código. Você pode consultar fontes de funções não apenas pelo nome, mas também pelo significado ou papel na arquitetura.
• Detecção de código morto. O utilitário percorre o grafo de relacionamentos a partir dos pontos de entrada da aplicação e encontra funções ou módulos que são inacessíveis através de qualquer cadeia de chamadas.
• Busca e substituição estrutural. Em vez de expressões regulares clássicas, ele usa ast-grep. A ferramenta busca padrões na árvore de sintaxe e reescreve o código com cuidado, preservando a estrutura.
• Rastreamento de fluxo de dados. O recurso FLOWS_TO rastreia como um valor de variável passa por uma cadeia de atribuições, chamadas de funções e termina em operações de I/O. Atualmente, o rastreamento funciona para C#, Java, C e Go.

Um bônus extra é o suporte ao Model Context Protocol (MCP). Isso significa que o code-graph-rag pode ser executado como um servidor MCP e conectado diretamente ao Claude Code ou qualquer outro cliente habilitado para MCP. Agentes de IA poderão consultar a estrutura exata do projeto por conta própria e sugerir alterações como diffs prontos.

Início Rápido e Requisitos do Sistema

A ferramenta é distribuída como um pacote Python code-graph-rag. Para funcionalidade completa, você precisará instalar o Docker (necessário para os containers do Memgraph e Qdrant), além dos utilitários de sistema cmake e ripgrep.

A forma mais fácil de instalar o utilitário CLI é via uv ou pipx:

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

Após a instalação, você precisa configurar o ambiente local e começar a indexar o repositório:

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

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

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

Se você planeja usar o utilitário como parte de CI/CD ou conectá-lo a um agente via MCP, a documentação tem uma seção detalhada sobre configuração e exportação do grafo.

Vale a Pena Adotar?

O projeto parece promissor para equipes que trabalham com monorepos multilíngues. Assistentes de IA comuns frequentemente falham quando o codebase excede cem mil linhas e as conexões entre serviços dependem de chamadas de funções em pastas diferentes. A abordagem de grafos resolve esse problema radicalmente, misturando topologia rígida de código com a flexibilidade de modelos de linguagem.

Claro, você deve considerar a curva de aprendizado. Você precisará executar um container Docker com o Memgraph, alocar recursos para construção do grafo durante a varredura inicial e configurar chaves de API do LLM. Mas se você está cansado de alucinações de redes neurais durante refatoração de um projeto complexo, gastar meia hora se familiarizando com code-graph-rag definitivamente vale a pena.