Recuperação de código para agentes de IA: Por que embeddings vetoriais falham e gráficos LLM por arquivo vencem

Um experimento de um ano construindo um sistema de indexação de código para ferramentas de codificação com IA produziu resultados claros: embeddings vetoriais em chunks de código e análise AST do Tree-sitter têm falhas críticas, enquanto análise LLM por arquivo armazenada em um grafo Neo4j com busca semântica de texto completo funciona melhor. Os achados ecoam artigos recentes como RepoGraph (ICLR 2025) e Code-Craft.

Abordagens testadas

• Embeddings vetoriais em chunks de código – descartados completamente. Uma função chamada process() em um serviço de pagamentos e outra em um pipeline de imagem são incorporadas em vetores similares, apesar de não terem nada a ver uma com a outra. Vetores achatam grafos de chamada, herança, importações — todas as relações estruturais. A precisão da recuperação foi inaceitável.
• Análise AST do Tree-sitter – precisa e rápida, mas apenas estrutural. Pode dizer que uma função existe e o que ela chama, mas não consegue responder à pergunta "esta função lida com retentativas de webhook para pagamentos Stripe com falha." Fica aquém quando desenvolvedores formulam perguntas em linguagem de negócios.
• Análise LLM por arquivo → grafo – funciona. Cada arquivo recebe uma chamada LLM gerando purpose, summary e businessContext, armazenados como nós no Neo4j com arestas para classes, funções, palavras-chave e importações. A recuperação usa busca de texto completo nesses campos semânticos em vez de similaridade vetorial. Diferenciação SHA-256 limita o reindexamento a arquivos alterados, tornando o custo inicial gerenciável.

Benchmarks da literatura

RepoGraph (ICLR 2025) mostrou melhoria de +32,8% no SWE-bench com abordagens de grafo. Code-Craft alcançou precisão de recuperação top-1 de +82% usando resumos LLM bottom-up a partir de grafos de código.

Comparação com ferramentas existentes

A equipe publicou uma comparação lado a lado em comparison.md. Principais diferenças:

• Bytebell: LLM por arquivo → purpose + summary + businessContext + entidades; armazenamento Neo4j + MongoDB; reindexação ciente de diff SHA-256.
• PageIndex: árvore de raciocínio TOC para PDFs/documentos longos; sem semântica específica de código.
• GitNexus: AST Tree-sitter + detecção de comunidades; semântica opcional por símbolo; usa LadybugDB.
• GraphRAG: entidades LLM por chunk + agrupamento de comunidades para texto geral, não código.
• Sourcegraph/Cody: índice de busca LSIF/SCIP; sem semântica por nó; implantação self-hosted ou SaaS.
• Augment: índice semântico proprietário com embeddings; apenas SaaS; indexação contínua gerenciada.

Código aberto

O sistema é open source em github.com/ByteBell/bytebell-oss.