Grafos de conocimiento en lugar de gigabytes de embeddings para análisis de código en monorepos

Una situación conocida: alimentas un monorepo grande a un asistente de IA, y comienza a mezclar llamadas de funciones de servicios vecinos, pierde conexiones entre módulos e inventa argumentos que no existen. La búsqueda vectorial convencional es bastante buena encontrando fragmentos de texto similares. Sin embargo, las representaciones vectoriales tienen dificultades para entender la estructura rígida del código, donde una sola variable renombrada o una importación implícita cambia la lógica de toda la aplicación.

El desarrollador Vitaliy creó el proyecto code-graph-rag para resolver este problema de forma sistemática. En lugar de depender únicamente de embeddings vectoriales, la herramienta construye un grafo de conocimiento del codebase.

Cómo funciona internamente

El sistema se construye sobre tres componentes principales: el parser Tree-sitter, la base de datos de grafos Memgraph y la base de datos vectorial Qdrant.

Así es como funciona:

1. Tree-sitter analiza los archivos de código fuente en árboles de sintaxis abstracta (AST).
2. El analizador extrae nodos: funciones, clases, métodos, módulos y las relaciones entre ellos.
3. Los datos se escriben en Memgraph bajo un esquema unificado e independiente del lenguaje.
4. Sobre esta estructura, una utilidad CLI cgr traduce preguntas en lenguaje natural a consultas Cypher precisas contra la base de datos de grafos.

Como resultado, cuando preguntas "¿dónde se usa la función X y hacia dónde fluyen sus datos después?", el sistema no intenta adivinar la respuesta basándose en la proximidad vectorial en el espacio. Ejecuta una consulta dirigida contra el grafo y devuelve la ruta de llamadas real.

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

Qué puede hacer la herramienta

El proyecto soporta 13 lenguajes, incluyendo Python, TypeScript, Go, Rust, Java, C++, C# y PHP. El soporte para Scala aún está en desarrollo, y Ruby usa pattern matching con ast-grep para el parsing.

Estas son las tareas principales cgr resuelve:

• Navegación y preguntas y respuestas sobre el código. Puedes consultar los orígenes de funciones no solo por nombre, sino también por significado o rol en la arquitectura.
• Detección de código muerto. La utilidad recorre el grafo de relaciones desde los puntos de entrada de la aplicación y encuentra funciones o módulos que son inalcanzables a través de cualquier cadena de llamadas.
• Búsqueda y reemplazo estructural. En lugar de expresiones regulares clásicas, usa ast-grep. La herramienta busca patrones en el árbol de sintaxis y reescribe el código cuidadosamente mientras preserva la estructura.
• Rastreo de flujo de datos. La funcionalidad FLOWS_TO rastrea cómo un valor de variable pasa a través de una cadena de asignaciones, llamadas a funciones y termina en operaciones de I/O. Actualmente el rastreo funciona para C#, Java, C y Go.

Un extra es el soporte para Model Context Protocol (MCP). Esto significa que code-graph-rag puede ejecutarse como un servidor MCP y conectarse directamente a Claude Code o cualquier otro cliente habilitado para MCP. Los agentes de IA podrán consultar la estructura exacta del proyecto por sí mismos y sugerir cambios como diffs listos para aplicar.

Inicio rápido y requisitos del sistema

La herramienta se distribuye como un paquete de Python code-graph-rag. Para funcionalidad completa, necesitarás instalar Docker (requerido para los contenedores de Memgraph y Qdrant), así como las utilidades del sistema cmake y ripgrep.

La forma más fácil de instalar la utilidad CLI es a través de uv o pipx:

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

Después de la instalación, necesitas configurar el entorno local y comenzar a indexar el repositorio:

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

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

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

Si planeas usar la utilidad como parte de CI/CD o conectarla a un agente vía MCP, la documentación tiene una sección detallada sobre configuración y exportación del grafo.

¿Vale la pena adoptarlo?

El proyecto parece prometedor para equipos que trabajan con monorepos multilingües. Los asistentes de IA convencionales a menudo son insuficientes cuando el codebase supera las cien mil líneas y las conexiones de servicio a servicio dependen de llamadas a funciones a través de diferentes carpetas. El enfoque de grafos resuelve este problema radicalmente, mezclando topología de código estricta con la flexibilidad de los modelos de lenguaje.

Por supuesto, debes considerar la curva de aprendizaje. Necesitarás ejecutar un contenedor Docker con Memgraph, asignar recursos para la construcción del grafo durante el escaneo inicial y configurar las claves de API del LLM. Pero si estás cansado de las alucinaciones de redes neuronales durante el refactoring de un proyecto complejo, dedicar media hora a familiarizarte con code-graph-rag definitivamente vale la pena.