Los agentes de programación con inteligencia artificial han mejorado mucho en generación de código, refactorización y análisis de proyectos, pero siguen teniendo un problema muy básico: encontrar contexto útil dentro de repositorios grandes. Leer archivo por archivo, lanzar búsquedas repetidas con grep o cargar fragmentos de código sin una visión estructural funciona en proyectos pequeños. En un monorepo, una base heredada o un sistema con miles de ficheros, ese método empieza a romperse.
codebase-memory-mcp intenta resolver ese problema con una idea cada vez más habitual en herramientas de desarrollo asistidas por IA: convertir el repositorio en un grafo persistente de conocimiento. En vez de tratar el código como una pila de texto, el proyecto lo analiza con Tree-sitter, extrae símbolos, relaciones, llamadas, rutas HTTP, clases, funciones, paquetes y enlaces entre servicios, y expone esa información mediante un servidor MCP para que agentes como Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Aider o VS Code puedan consultarla.
El resultado, según sus responsables, es un backend de inteligencia de código capaz de indexar el kernel de Linux, con 28 millones de líneas y 75.000 archivos, en unos tres minutos, responder consultas estructurales por debajo del milisegundo y reducir de forma drástica el consumo de tokens frente a la exploración tradicional archivo por archivo. La cifra es llamativa, pero lo importante no es solo la velocidad. Es el cambio de modelo: de buscar texto a consultar relaciones.
Del RAG textual al grafo de código
Muchas herramientas para IA y desarrollo han usado estrategias cercanas al RAG tradicional: trocear archivos, generar embeddings, buscar fragmentos parecidos y pasárselos al modelo. Ese enfoque puede ser útil para documentación, manuales o preguntas semánticas generales, pero en código se queda corto cuando la pregunta depende de estructura.
Saber “qué llama a esta función”, “qué endpoints dependen de este servicio”, “qué impacto tiene este cambio” o “dónde está el código muerto” no es solo un problema de similitud textual. Es un problema de relaciones. Una función puede estar lejos del archivo que la invoca. Una ruta HTTP puede enlazar con un servicio interno. Una clase puede heredar comportamiento de otra. Un cambio pequeño puede afectar a un módulo completo si está en una zona muy conectada del grafo.
codebase-memory-mcp plantea una arquitectura más adecuada para esas preguntas. Primero analiza el repositorio con gramáticas Tree-sitter. Después construye un grafo persistente en SQLite con nodos como proyectos, paquetes, carpetas, archivos, módulos, clases, funciones, métodos, interfaces, tipos, rutas o recursos. Las aristas representan relaciones como CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS, HTTP_CALLS, ASYNC_CALLS, EMITS, LISTENS_ON o DATA_FLOWS.
| Enfoque | Cómo trabaja | Ventaja | Límite principal |
|---|---|---|---|
| Búsqueda archivo por archivo | El agente lee y busca en ficheros sucesivos | Simple y compatible con cualquier repo | Consume muchos tokens y puede perder relaciones |
| RAG textual | Divide el código en fragmentos y busca similitud semántica | Útil para localizar conceptos o documentación | No siempre entiende llamadas, dependencias o impacto |
| Repo map | Resume símbolos y estructura básica | Reduce contexto frente a leer todo | Puede quedarse corto en análisis profundo |
| Grafo AST persistente | Indexa símbolos y relaciones del código | Permite consultas estructurales rápidas | Requiere indexación previa y calidad de parsing |
La diferencia práctica es clara. Un agente que pregunta por una función no necesita recorrer decenas de archivos para averiguar quién la llama. Puede consultar el grafo. Si necesita analizar el impacto de un cambio, puede combinar información del diff de Git con relaciones entre símbolos. Si quiere detectar funciones sin llamadas entrantes, puede ejecutar una consulta estructural sobre el grafo, no improvisar una búsqueda textual.
Rendimiento: el kernel de Linux como prueba de escala
El proyecto usa el kernel de Linux como una de sus pruebas más visibles. Según el README, codebase-memory-mcp puede indexar el repositorio completo, con 28 millones de líneas de código y 75.000 archivos, en tres minutos sobre un Apple M3 Pro. En modo rápido, la misma referencia baja a 1 minuto y 12 segundos. La indexación completa generaría 4,81 millones de nodos y 7,72 millones de aristas, mientras que el modo rápido produciría 1,88 millones de nodos.
| Operación | Resultado publicado |
| Indexación completa del kernel Linux | 3 min |
| Tamaño del repositorio usado en la prueba | 28 MLOC / 75.000 archivos |
| Nodos generados en indexación completa | 4,81 millones |
| Aristas generadas en indexación completa | 7,72 millones |
| Indexación rápida del kernel Linux | 1 min 12 s |
| Indexación completa de Django | ~6 s |
| Consulta Cypher estructural | <1 ms |
| Búsqueda por nombre con regex | <10 ms |
| Detección de código muerto | ~150 ms |
| Trazado de llamadas hasta profundidad 5 | <10 ms |
Estas cifras deben leerse como benchmarks del proyecto, no como garantía universal. El rendimiento real dependerá del hardware, el tamaño del repositorio, los lenguajes utilizados, la estructura del código, la configuración de exclusiones, el almacenamiento y el tipo de consulta. Aun así, ayudan a entender el objetivo: que el agente no tenga que gastar contexto en reconstruir una arquitectura que ya puede estar indexada.
La parte de eficiencia en tokens es igual de relevante. El README afirma que cinco consultas estructurales consumieron unos 3.400 tokens mediante codebase-memory-mcp frente a unos 412.000 tokens con exploración basada en grep y lectura de archivos, una reducción del 99,2 %. El preprint asociado, publicado en arXiv bajo el título “Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP”, describe una evaluación sobre 31 repositorios reales en la que el sistema alcanzó un 83 % de calidad de respuesta frente al 92 % de un agente que explora archivos, pero usando diez veces menos tokens y 2,1 veces menos llamadas a herramientas.
Ese matiz importa. No se trata de afirmar que el grafo siempre responde mejor que leer archivos. El propio estudio sugiere un intercambio: algo menos de calidad media en ciertas tareas, pero mucha más eficiencia. Para equipos que usan agentes de IA a diario en repositorios grandes, esa reducción de coste, latencia y ruido puede ser más valiosa que exprimir cada respuesta con lectura completa del código.
Un binario local para entornos sensibles
Otro punto fuerte de codebase-memory-mcp es su orientación local. El proyecto se distribuye como un binario estático para macOS, Linux y Windows, sin Docker, sin dependencias de runtime y sin necesidad de claves API. Los índices se almacenan en SQLite bajo el directorio de caché del usuario y el procesamiento del código se realiza en la propia máquina.
Para empresas con código privado, esta parte es importante. Un servidor MCP de este tipo lee el repositorio y escribe configuración en herramientas de agente, así que no debería ejecutarse sin revisión previa. Sus responsables insisten en que todo el código queda local, que los binarios se publican con checksums SHA-256, firmas y escaneos antivirus, y que el proyecto puede auditarse porque el código fuente está disponible. Aun así, en entornos corporativos conviene pasar por el circuito habitual de seguridad antes de instalar cualquier binario que interactúe con repositorios y configuraciones de agentes.
| Característica | Implicación para equipos técnicos |
| Binario estático | Instalación sencilla y menos dependencias externas |
| Procesamiento local | El código no necesita salir de la máquina |
| SQLite persistente | El grafo sobrevive a reinicios y nuevas sesiones |
| MCP | Se integra con agentes compatibles mediante herramientas estructuradas |
| UI opcional | Permite explorar el grafo en localhost:9749 |
| Soporte multiagente | Configura distintos clientes de IA con un solo comando |
| Artefacto compartido | Permite versionar un snapshot comprimido del grafo en el repo |
La herramienta también incluye una opción interesante para equipos: un artefacto comprimido .codebase-memory/graph.db.zst. La idea es que un repositorio pueda incluir una copia compactada del grafo para que otros desarrolladores no tengan que reindexar desde cero. En proyectos grandes, esto puede ahorrar tiempo de arranque, aunque cada equipo deberá decidir si quiere versionar ese archivo o mantener los índices solo en local.
Qué herramientas ofrece al agente
codebase-memory-mcp no incluye un modelo de lenguaje. Es un backend de análisis estructural. El agente sigue siendo el componente que interpreta la pregunta del usuario y decide qué herramienta invocar. La diferencia es que, en vez de pedir al modelo que busque a ciegas, el servidor MCP le ofrece operaciones como index_repository, search_graph, trace_path, detect_changes, query_graph, get_architecture, search_code, get_code_snippet o manage_adr.
| Herramienta MCP | Uso típico |
index_repository | Indexar un proyecto en el grafo |
search_graph | Buscar símbolos por nombre, tipo, archivo o grado |
trace_path | Ver quién llama a una función y qué llama esa función |
detect_changes | Mapear cambios de Git a símbolos afectados |
query_graph | Ejecutar consultas tipo Cypher de solo lectura |
get_architecture | Obtener una visión general del proyecto |
search_code | Buscar texto dentro de archivos indexados |
get_code_snippet | Recuperar el código de un símbolo concreto |
manage_adr | Gestionar decisiones arquitectónicas persistentes |
Además del análisis de código, el proyecto indexa elementos de infraestructura como Dockerfiles, manifiestos de Kubernetes y overlays de Kustomize. Esto lo acerca a un uso más amplio que el de un simple buscador de funciones: permite relacionar componentes de aplicación, configuración e infraestructura dentro del mismo grafo.
El soporte de lenguajes también es amplio. El repositorio afirma integrar gramáticas Tree-sitter para 158 lenguajes y una capa Hybrid LSP para mejorar la resolución semántica en Python, TypeScript, JavaScript, PHP, C#, Go, C, C++, Java, Kotlin y Rust. El preprint académico describe una versión anterior evaluada con 66 lenguajes, lo que indica que el proyecto ha seguido ampliando cobertura después de la publicación del documento.
Por qué esto importa para el desarrollo con IA
El auge de los agentes de programación ha puesto de moda una idea peligrosa: pensar que basta con dar acceso a un repositorio para que un modelo lo entienda. En realidad, el contexto sigue siendo caro, limitado y frágil. Un LLM puede generar una respuesta convincente a partir de fragmentos incompletos, pero eso no significa que haya entendido las dependencias reales del sistema.
Las herramientas basadas en grafos no eliminan ese riesgo, pero lo reducen en una zona concreta: la recuperación estructural. Cuando el agente necesita saber relaciones, rutas, llamadas o impacto, puede apoyarse en datos extraídos del código en lugar de reconstruirlos mediante lecturas sucesivas. Esto no sustituye a pruebas, revisión humana, análisis estático tradicional ni observabilidad en producción, pero mejora el punto de partida.
codebase-memory-mcp encaja dentro de una tendencia más amplia: los agentes de IA necesitan memoria externa, herramientas especializadas y contexto estructurado. No basta con ampliar ventanas de contexto. En repositorios grandes, meter más texto en el prompt suele aumentar coste y ruido. La alternativa es que el agente haga menos lecturas, pero mejores. Un grafo persistente del código apunta precisamente en esa dirección.
El proyecto todavía debe demostrar adopción sostenida, calidad en más lenguajes, estabilidad en equipos grandes y utilidad real frente a herramientas ya conocidas como indexadores de IDE, LSIF, Sourcegraph, OpenGrok, Semgrep, CodeQL, ctags o los repo maps de asistentes como Aider. Su propuesta, aun así, es muy actual: llevar al flujo MCP una capa de inteligencia estructural que los agentes puedan consultar de forma local y barata.
La conclusión técnica es prudente, pero clara. Para repositorios pequeños, quizá no haga falta una infraestructura de grafo. Para sistemas grandes, monorepos, microservicios o bases de código heredadas, seguir obligando a la IA a leer archivos como si fuera un desarrollador perdido en un árbol de directorios empieza a parecer ineficiente. codebase-memory-mcp no promete que el modelo deje de equivocarse, pero sí le da una forma más inteligente de mirar el código antes de responder.
Preguntas frecuentes
¿Qué es codebase-memory-mcp?
Es un servidor MCP de inteligencia de código que indexa repositorios en un grafo persistente para que agentes de IA puedan consultar funciones, clases, llamadas, rutas, dependencias y cambios de forma estructurada.
¿Sustituye a un buscador vectorial o a un RAG tradicional?
No exactamente. Puede complementarlos, pero su punto fuerte está en consultas estructurales sobre código: llamadas, dependencias, impacto de cambios, rutas HTTP o arquitectura.
¿Funciona en local?
Sí. El proyecto se distribuye como binario estático para macOS, Linux y Windows, usa SQLite para persistencia y no necesita API keys, Docker ni servicios externos para funcionar.
¿Es recomendable usarlo en repositorios privados?
Puede ser interesante porque procesa el código en local, pero cualquier equipo debería auditar el binario, revisar el código fuente y validar sus políticas de seguridad antes de integrarlo en flujos internos.
