Anderson Ponce
Cada vez que un agente de IA necesita entender una codebase, hace lo mismo que haría un desarrollador nuevo el primer día: busca archivos, los lee, y arma un mapa mental desde cero. La diferencia es que el agente lo hace en cada sesión, gastando tool calls y tokens en volver a descubrir lo que ya existía.
Un grafo de conocimiento semántico pre-indexado resuelve exactamente ese problema: en vez de escanear archivos crudos, el agente consulta una estructura ya procesada.
Qué es y cómo funciona
La idea es simple: parsear el código una vez con Tree-sitter, extraer símbolos (funciones, clases, métodos, variables exportadas) y las relaciones entre ellos (llamadas, imports, herencia), y guardar todo en una base local — típicamente SQLite con búsqueda de texto completo. El agente ya no necesita leer archivos para saber “quién llama a esta función” o “dónde se define esta clase”: lo pregunta directo.
Corre 100% local. Sin nube, sin mandar código a ningún servidor externo — una condición no negociable para cualquier proyecto con código propietario o de cliente.
Sobre esa base se exponen herramientas puntuales:
- Buscar símbolos por nombre en una sola llamada.
- Listar quién llama a una función, y a qué llama esa función.
- Calcular el radio de impacto de un cambio — qué se rompe si se modifica X.
- Mapear la estructura completa de archivos indexados sin leerlos uno por uno.
Un file watcher nativo mantiene el índice sincronizado con debounce, así que no hace falta reindexar manualmente cada vez que se edita un archivo.
Antes y después, con números reales
La diferencia no es teórica. Con un flujo tradicional, una pregunta como “¿dónde se define este servicio?” implica varios tool calls encadenados — buscar candidatos, leer archivos, filtrar por nombre — antes de llegar a una respuesta. Con el grafo, la misma pregunta es una sola consulta directa al índice.
| Escenario | Sin grafo | Con grafo |
|---|---|---|
| “¿Qué hace esta función y quién la usa?” | 5–8 tool calls, ~2.000–4.000 tokens | 2 tool calls, ~400–600 tokens |
| “Si cambio esta clase, ¿qué se rompe?” | Estimación parcial, sin garantías | Lista exacta de símbolos afectados |
| Onboarding a un proyecto nuevo | 10–20 lecturas para mapear módulos | 1 consulta estructural |
Medido en benchmarks sobre codebases reales (de 110 a más de 10.000 archivos, seis lenguajes distintos): −47% de tokens consumidos, −58% de tool calls, +22% de velocidad de ejecución.
Con una sesión típica de 200.000 tokens, un 47% menos representa unos 94.000 tokens ahorrados por sesión. En 20 sesiones al mes, eso es cerca de 2 millones de tokens menos — con el impacto directo que eso tiene en el costo de usar el agente todos los días.
Lo que no resuelve
Vale la pena ser honesto con los límites:
- No reemplaza la comprensión semántica del agente — le da el mapa, no la interpretación de la lógica de negocio.
- Para lógica compleja, el agente igual necesita leer el cuerpo de ciertas funciones.
- El índice inicial toma tiempo proporcional al tamaño del proyecto — una sola vez, pero no es instantáneo.
- Si el proyecto usa un lenguaje sin soporte de parsing, la herramienta simplemente no aplica.
Para proyectos chicos, la diferencia no se nota. Para codebases grandes que un agente recorre todos los días, la diferencia es directamente el costo mensual de usarlo.