Recuperación de código para agentes de IA: Por qué fallan los embeddings vectoriales y triunfan los gráficos LLM por archivo

Un experimento de un año para construir un sistema de indexación de código para herramientas de codificación de IA arrojó resultados claros: los embeddings vectoriales en fragmentos de código y el análisis AST de Tree-sitter tienen fallos críticos, mientras que el análisis por archivo con LLM almacenado en un grafo Neo4j con búsqueda semántica de texto completo funciona mejor. Los hallazgos se alinean con trabajos recientes como RepoGraph (ICLR 2025) y Code-Craft.

Enfoques probados

• Embeddings vectoriales en fragmentos de código – descartados por completo. Una función llamada process() en un servicio de pagos y otra en un pipeline de imágenes generan vectores similares, a pesar de no tener nada que ver entre sí. Los vectores ignoran los grafos de llamadas, herencia, importaciones — todas las relaciones estructurales. La precisión de recuperación fue inaceptable.
• Análisis AST de Tree-sitter – preciso y rápido, pero solo estructural. Puede indicar que existe una función y a qué llama, pero no puede responder a la pregunta "esta función maneja reintentos de webhook para pagos fallidos de Stripe". Se queda corto cuando los desarrolladores formulan preguntas en lenguaje de negocio.
• Análisis por archivo con LLM → grafo – funciona. Cada archivo recibe una llamada LLM que genera purpose, summary y businessContext, almacenados como nodos en Neo4j con aristas a clases, funciones, palabras clave e importaciones. La recuperación utiliza búsqueda de texto completo en esos campos semánticos en lugar de similitud vectorial. El diff con SHA-256 limita el reindexado a archivos modificados, haciendo que el costo inicial sea manejable.

Benchmarks de la literatura

RepoGraph (ICLR 2025) mostró una mejora del +32.8% en SWE-bench con enfoques basados en grafos. Code-Craft logró una precisión de recuperación top-1 del +82% utilizando resúmenes ascendentes de LLM a partir de grafos de código.

Comparación con herramientas existentes

El equipo publicó una comparación detallada en comparison.md. Diferencias clave:

• Bytebell: LLM por archivo → propósito + resumen + contexto de negocio + entidades; almacenamiento Neo4j + MongoDB; reindexado consciente de diferencias SHA-256.
• PageIndex: árbol de razonamiento TOC para PDFs/documentos largos; sin semántica específica de código.
• GitNexus: AST de Tree-sitter + detección de comunidades; semántica opcional por símbolo; usa LadybugDB.
• GraphRAG: entidades LLM por fragmento + agrupación en comunidades para texto general, no código.
• Sourcegraph/Cody: índice de búsqueda LSIF/SCIP; sin semántica por nodo; despliegue autogestionado o SaaS.
• Augment: índice semántico propietario con embeddings; solo SaaS; indexación continua gestionada.

Código abierto

El sistema es de código abierto en github.com/ByteBell/bytebell-oss.