Cuando un agente de IA explora un repositorio grande archivo por archivo —abrir, leer, grep, abrir el siguiente— el coste no es solo tiempo, es contexto: cada búsqueda exploratoria consume tokens que deberían ir a razonar sobre el problema, no a redescubrir dónde vive cada función. codebase-memory-mcp ataca ese problema desde la raíz: en lugar de que el agente lea código para entender su estructura, indexa el repositorio una vez en un grafo de conocimiento persistente y deja que el agente haga preguntas estructurales directamente sobre ese grafo.
El problema: explorar código cuesta más tokens de los que parece
El propio proyecto lo cuantifica con un dato que resume bien el problema: cinco consultas estructurales típicas consumieron cerca de 3.400 tokens usando codebase-memory-mcp, frente a unos 412.000 tokens haciendo el mismo trabajo con grep archivo por archivo. No es una optimización marginal, es una reducción de dos órdenes de magnitud en el coste de la fase que casi siempre precede a cualquier tarea real de ingeniería: entender dónde está algo y qué depende de qué.
Cómo funciona: de archivos a grafo
El pipeline de indexado extrae el AST de cada archivo con tree-sitter (más de 150 lenguajes soportados), refina las llamadas con resolución de tipos al estilo LSP para los lenguajes principales, resuelve paquetes y módulos, y detecta rutas HTTP, gRPC, GraphQL y tRPC. Todo eso se persiste en SQLite con nodos como Function, Class, Module o Route, y relaciones como CALLS, IMPORTS, IMPLEMENTS o DATA_FLOWS. El resultado es un grafo que un agente puede consultar con un subconjunto de Cypher, en lugar de tener que reconstruir esa estructura leyendo archivos.
Sobre ese grafo se exponen herramientas MCP concretas: search_graph para localizar funciones o clases por nombre o etiqueta, trace_path para recorrer cadenas de llamadas o flujo de datos, get_code_snippet para leer el código exacto de un símbolo sin abrir el archivo entero, get_architecture para obtener de un vistazo lenguajes, paquetes, rutas y hotspots del proyecto, y detect_changespara mapear un diff de git a los símbolos que realmente afecta. Es la diferencia entre pedirle a un agente que "busque" y darle un mapa ya construido.
Por qué esto no es solo velocidad
El ahorro de tokens es la parte más fácil de medir, pero no es la más importante. Un grafo estructural permite preguntas que un grep nunca puede responder bien: qué funciones tienen fan-out alto y son candidatas a refactor, qué código está muerto, qué símbolos toca de verdad un cambio antes de tocarlo, o cómo fluyen los datos entre dos servicios distintos. Son exactamente las preguntas que un ingeniero senior se hace antes de aceptar un PR o antes de tocar un módulo compartido entre squads, y que hasta ahora un agente solo podía aproximar leyendo mucho código y arriesgándose a perder contexto por el camino.
Encaje con el resto del ecosistema MCP
Lo que hace interesante a este proyecto no es solo la técnica de indexado, sino que resuelve un problema real de MCP (Model Context Protocol): dar a un agente acceso a fuentes de contexto ya existentes, con una interfaz de herramientas acotada, en lugar de copiar contexto a mano en cada conversación. El instalador detecta automáticamente más de 40 clientes —Claude Code, Cursor, VS Code, Windsurf, entre otros— y configura el servidor MCP correspondiente en cada uno, lo cual reduce a una línea de comando lo que de otra forma sería una integración manual por herramienta.
Además, el snapshot del grafo (.codebase-memory/graph.db.zst) se puede versionar en el propio repositorio comprimido con zstd, con ratios típicos de 8-13:1. Eso significa que un compañero de equipo que clona el repo no reindexará todo desde cero: descomprime el snapshot y solo indexa de forma incremental lo que ha cambiado. Es la misma lógica que aplico con las Skills a medida que documenté en el artículo sobre agentes IA en Android: convertir un proceso caro y ad-hoc en algo reutilizable y compartido por el equipo.
Un agente que entiende la estructura del código antes de leerlo hace menos preguntas de más calidad.
Lectura para equipos que ya usan agentes en el ciclo real
Si un equipo ya delega en un agente tareas de revisión, documentación o detección de deuda técnica, la exploración de código es el cuello de botella que menos se ve pero más contexto consume. Herramientas como codebase-memory-mcp no sustituyen el criterio del agente ni el del ingeniero que revisa después, pero cambian la base sobre la que se razona: de "buscar y esperar encontrar" a "consultar una estructura ya conocida". Es exactamente el tipo de mejora de infraestructura que, con el tiempo, hace que delegar más trabajo en un agente sea seguro en lugar de arriesgado.