Cómo funciona Graph Indexer

Graph Indexer analiza tu repositorio con tree-sitter compilado a WebAssembly, extrae definiciones, referencias, imports y evidencias de tipos, enlaza cada referencia con la definición a la que realmente apunta y lo guarda todo en un índice SQLite local en .graph-indexer/index.db. Antes de cada respuesta se resincroniza con los archivos del disco y después ordena los resultados con búsqueda léxica y centralidad en el grafo. No interviene ningún embedding, modelo, red ni compilación nativa.

¿Cuál es el pipeline de Graph Indexer?

Graph Indexer ejecuta cinco etapas, todas deterministas y locales:

1. Parsear cada archivo con una gramática tree-sitter (16 gramáticas incluidas como WebAssembly).
2. Extraer definiciones, referencias, imports y evidencias de tipos con una consulta por lenguaje.
3. Enlazar cada referencia con una definición mediante ámbitos, imports y tipos de receptor inferidos.
4. Guardar los hechos en SQLite (node:sqlite) dentro de .graph-indexer/.
5. Consultar con búsqueda léxica, recorrido del grafo y PageRank, tras resincronizar el índice.

¿Cómo analiza el código Graph Indexer?

Graph Indexer analiza el código con web-tree-sitter 0.25 y 16 gramáticas tree-sitter que viajan como WebAssembly dentro del paquete npm: JavaScript, TypeScript, TSX, Python, Go, Java, Kotlin, Scala, C#, Rust, C, C++, Ruby, PHP, Bash y CSS (incluidos SCSS y Less). Las versiones de las gramáticas están fijadas y verificadas con SHA-256 en un manifiesto, así que no se instala ni se descarga nada en tiempo de ejecución y no hay paso de compilación nativa. Consulta los lenguajes soportados.

Para cada lenguaje, una consulta tree-sitter extrae las definiciones (funciones, métodos, clases, interfaces, campos, etc.), las referencias (llamadas, instanciaciones, usos como tipo, herencia, decoradores, valores y lecturas), los imports y las evidencias de tipos que luego se usan para el enlace.

¿Cómo enlaza Graph Indexer las referencias con las definiciones?

Graph Indexer enlaza una referencia resolviéndola contra ámbitos, imports y el tipo inferido del receptor, de modo que una llamada a UserService.find se distingue de cualquier otro método llamado find. Este paso de enlace es lo que lo separa de una búsqueda por nombre, que no puede distinguirlos.

Inferencia del tipo del receptor

En repo.find(id), el tipo de repo decide qué find se quiere decir. Graph Indexer lo infiere a partir de anotaciones, inicializadores, expresiones new y casts, tipos de retorno declarados e inferidos, campos y dependencias inyectadas por constructor, colecciones (xs[i], for x of xs, forEach, list.get(0)), mapas (Map<K,V>, dict, HashMap, map[K]V de Go), tipos opcionales y envoltorios (Foo | undefined, Optional[Foo], Promise<Foo>, Arc<Mutex<Foo>>), closures y cadenas de acceso. Los miembros de primitivos y colecciones nunca se adivinan, y los enlaces contradictorios no producen tipo: el diseño prioriza la precisión sobre la exhaustividad.

La escalera de resolución

Cada referencia recorre una escalera desde el significado más local al más global, y el resultado lleva una etiqueta de confianza:

1. ámbito léxico
2. el tipo contenedor y sus clases base (con linearización C3 para el orden de resolución de métodos)
3. el mismo archivo
4. un import explícito, incluidos archivos barrel, rutas de tsconfig según el tsconfig más cercano, workspaces, módulos de Go, paquetes de Python, crates de Rust e includes de C
5. el mismo paquete
6. nombres globales

Las referencias enlazadas en lo alto de la escalera se etiquetan como exact (confianza de 0,9 o más) o high (0,7 o más). Una coincidencia solo por nombre se etiqueta como likely (0,4 o más) o possible. Las herramientas imprimen estas etiquetas y los pies informan de las llamadas con el mismo nombre que no se pudieron enlazar, para que el agente sepa cuándo comprobar con búsqueda de texto.

¿Dónde guarda Graph Indexer el índice?

Graph Indexer guarda el índice en una base de datos SQLite en <repo>/.graph-indexer/index.db, con el módulo node:sqlite integrado en Node.js 22.5 y posteriores. La base funciona en modo WAL, con tablas de texto completo FTS5 sobre símbolos y archivos. Los hechos pertenecen a cada archivo, de modo que editar uno solo reemplaza únicamente los hechos de ese archivo y los ids de símbolo se mantienen estables entre ediciones. Cuando el extractor cambia entre versiones, una huella dispara la reconstrucción automática.

npx graph-indexer init añade la carpeta al .gitignore. Contiene extractos de tu código, así que trátala como el propio repositorio; borrarla es seguro porque se reconstruye en el siguiente arranque. Solo se indexa el árbol de trabajo.

¿Cómo se mantiene al día Graph Indexer?

Graph Indexer se resincroniza con los archivos del disco antes de cada respuesta, incluidas las ediciones que el agente hizo hace un segundo. Un observador de archivos (fs.watch) más barridos periódicos de stat detectan los cambios (un barrido cada 30 segundos con el observador; un barrido de stat de como mucho 3 segundos sin él), un paso ensureFresh() se ejecuta antes de cada llamada a una herramienta y los archivos se revalidan antes de mostrar los números de línea. El servidor MCP construye el primer índice en segundo plano al arrancar.

El servidor MCP mantiene el índice abierto mientras corre el agente. Con hooks y sin servidor, se lanza bajo demanda un proceso residente que termina tras 30 minutos de inactividad (GRAPH_INDEXER_RESIDENT=0 lo desactiva). Escucha en un socket Unix (una tubería con nombre en Windows) con modo 0600 dentro de .graph-indexer/, nunca en TCP.

¿Cómo ordena Graph Indexer los resultados de búsqueda?

Graph Indexer ordena los resultados con canales léxicos y señales del grafo, y no usa embeddings. search_code combina cuatro canales: nombres de símbolos, BM25F sobre un índice FTS5 con pesos por campo (nombre 10, nombre cualificado 6, firma 3, documentación 2, ruta 2,5, cuerpo 1), un tesauro de conceptos y BM25 a nivel de archivo. Se suman priores interpretables y la centralidad PageRank del grafo de referencias, y los resultados se diversifican a un máximo de tres por archivo. Los pesos se ajustaron solo con una partición de ajuste.

outline usa el mismo PageRank, personalizado según un texto focus, para construir un mapa ordenado de un directorio o repositorio dentro de un presupuesto de tokens. El impacto de cambios y las comprobaciones de edición parten de símbolos, archivos o git diff, siguen el grafo para hallar dependientes, encuentran tests por el grafo y por nombres, y añaden el historial de cambios conjuntos de git.

En 377 consultas de búsqueda de símbolos sobre 9 repositorios en 8 lenguajes, el primer resultado fue correcto el 70,3 % de las veces (rango recíproco medio de 0,760). Todos los números y métodos están en los benchmarks.

¿Qué velocidad tiene Graph Indexer?

Graph Indexer indexa el repositorio nestjs (1.641 archivos, 96.000 líneas) en 3,7 segundos con una base de datos de 12,3 MB. El monorepo de Twenty CRM (28.512 archivos, 2,33 millones de líneas, unos 170.000 símbolos y 555.000 referencias) tarda 51 segundos y ocupa 304 MB. Resincronizar un repositorio sin cambios tarda 0,2 segundos en nestjs y 1,8 segundos en Twenty.

Con el índice caliente, las herramientas de grafo responden en 1–4 ms, search_code en unos 30 ms y outline en unos 18 ms. Con el proceso residente, las llamadas de hooks pasan de 280–570 ms a 70–120 ms, y las de CLI, de unos 370 ms a 110–210 ms. Una respuesta de herramienta ocupa normalmente de 400 a 1.500 tokens, y Graph Indexer añade unos 1.200 tokens a cada sesión de Claude Code. Fuente: BENCHMARKS.md.

¿Cuáles son los límites conocidos de Graph Indexer?

Graph Indexer no es un comprobador de tipos y lo dice en sus respuestas. Sus límites publicados:

• Los literales de objeto con tipado contextual, la instanciación de genéricos, la reflexión, any y la inyección de dependencias por token de texto solo se ven en parte.
• Solo se indexa el árbol de trabajo.
• La precisión de las referencias se verificó contra los compiladores o comprobadores de tipos de TypeScript, Go y Java. Java es el lenguaje más débil de los medidos (exhaustividad del 86,1 % al 98,9 % en tres repositorios).
• La proporción de referencias enlazadas a una definición varía según el repositorio, del 43 % al 94 %.
• En tareas reales de resolución de incidencias, el benchmark con agentes no mostró un ahorro medible, y las muestras de agentes son pequeñas.

Graph Indexer en sí no hace llamadas de red ni envía telemetría. El agente sigue enviando a su proveedor de modelo lo que lee. La referencia de herramientas está en la página de herramientas.