codebase-memory-mcp
Servidor MCP de inteligencia de codigo que convierte un repositorio en un grafo de conocimiento persistente (Tree-sitter AST, Hybrid LSP, SQLite) con relaciones CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS, flujos de datos y busqueda semantica local. Complementa a los AI Coding Agents en la fase de exploracion.
Indice de contenidos
La forma más precisa de entenderlo no es como “un MCP que permite a la IA recordar el código”.
En realidad, es un servidor MCP de inteligencia de código orientado a agentes de AI Coding.
El proyecto convierte actualmente el repositorio en un grafo de conocimiento persistente que contiene no solo archivos y símbolos de código, sino también relaciones como CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS, llamadas HTTP, llamadas asíncronas, flujos de datos y otras conexiones. También admite relaciones semánticas y detección de código similar.
Por tanto, esta “Memory” se parece más a:
Extraer de antemano las relaciones estructurales que están implícitas en grandes cantidades de código fuente y convertirlas en datos que el agente pueda consultar directamente.
Esto es muy diferente de guardar simplemente un “resumen del proyecto”.
Además, el propio proyecto no es un LLM. Su arquitectura establece una separación clara: codebase-memory-mcp se encarga del análisis y las consultas sobre la estructura del código, mientras que Claude Code, Codex u otro cliente MCP se encarga del razonamiento.
Y esta es una decisión arquitectónica importante.
El verdadero problema que intenta resolver no es la búsqueda, sino el coste de exploración
El proceso tradicional de comprensión de código de un Coding Agent suele ser:
Tarea del usuario ↓ Buscar archivos ↓ Leer código ↓ Volver a buscar ↓ Construir relaciones de llamadas ↓ Seguir leyendo ↓ Empezar a modificar
El problema es que este flujo depende en gran medida de que el propio modelo explore el proyecto paso a paso.
Si la pregunta es:
¿Qué partes del proyecto llaman a ProcessOrder?
el agente puede necesitar realizar varias búsquedas y lecturas de archivos.
El enfoque de Codebase Memory es diferente:
Repositorio ↓ Analizar código ↓ Construir Graph ↓ Persistir información ↓ El agente consulta las relaciones estructurales ↓ Obtiene resultados ↓ Continúa razonando
De esta manera, una parte de las relaciones que antes el modelo tenía que “deducir” mediante múltiples búsquedas se convierte en una infraestructura que puede consultar directamente.
Este es probablemente uno de los aspectos más interesantes del proyecto:
A veces, el cuello de botella del AI Coding no es la generación de código, sino que el agente no sabe qué código debería analizar.
¿Por qué no es lo mismo que un RAG convencional?
Si tratamos todo el repositorio como documentos normales para un sistema RAG, normalmente obtenemos algo parecido a:
Código ↓ Chunks ↓ Embeddings ↓ Búsqueda vectorial ↓ Código relevante
Este enfoque puede responder a preguntas como:
¿Qué código está relacionado semánticamente con el inicio de sesión de usuarios?
Pero la parte realmente compleja del código suele estar en las relaciones.
Por ejemplo:
LoginController ↓ AuthService ↓ SessionRepository ↓ Database
O:
PaymentService ↓ OrderService ↓ Refund ↓ Notification
Encontrar “código relacionado” y comprender “cómo está conectado ese código” son dos problemas diferentes.
El enfoque actual de codebase-memory-mcp está claramente más orientado al segundo. Primero utiliza Tree-sitter AST para analizar estructuralmente el código y, además, proporciona resolución semántica mediante Hybrid LSP para lenguajes como Python, TypeScript/JavaScript, PHP, C#, Go, C/C++, Java, Kotlin, Rust y Perl.
Al mismo tiempo, incorpora búsqueda semántica local. Según la documentación actual, el proyecto integra el embedding nomic-embed-code directamente en el binario y combina búsqueda semántica, AST, flujos de datos, proximidad entre módulos y otras señales para recuperar código.
Por eso, en realidad no estamos ante un simple:
RAG + MCP
sino ante algo más cercano a:
AST + análisis de símbolos + resolución de tipos + Code Graph + búsqueda semántica + MCP.
¿Por qué resulta interesante su enfoque técnico?
El punto central es que extrae las “relaciones del código” del contexto temporal del modelo.
El grafo actual del proyecto no se limita a las llamadas entre funciones. También incluye relaciones como IMPORTS, INHERITS, IMPLEMENTS, DATA_FLOWS, llamadas HTTP entre servicios y relaciones como SEMANTICALLY_RELATED y SIMILAR_TO.
Esto permite que el agente formule preguntas que las búsquedas de texto tradicionales no resuelven bien:
¿Quién llama a esta función?
¿Qué partes podrían verse afectadas si modifico este módulo?
¿Por qué funciones pasa un determinado dato desde que entra en el sistema?
¿Qué funciones podrían ser implementaciones duplicadas?
¿Qué interfaz conecta estos dos servicios?
Aquí está la verdadera diferencia conceptual entre Codebase Memory y la búsqueda de código convencional.
ripgrep destaca por encontrar texto.
Un Code Graph destaca por representar relaciones.
Y MCP convierte esas relaciones en herramientas que el agente puede utilizar activamente.
¿Qué aporta realmente MCP en este caso?
Si solo construyéramos un grafo de código, seguiría siendo principalmente una herramienta para desarrolladores.
MCP cambia la forma de utilizarlo:
AI Agent ↓ Descubre una herramienta MCP ↓ Consulta el Code Graph ↓ Obtiene resultados estructurados ↓ Los combina con el código fuente para razonar ↓ Ejecuta la tarea de Coding
Esto permite que Codebase Memory no tenga que convertirse en un IDE completo de AI Coding.
Puede funcionar como un “plugin cognitivo” para el agente.
Actualmente, el proyecto proporciona herramientas MCP para búsqueda estructural, rutas de llamadas, análisis de arquitectura, análisis de impacto, comprobación de cobertura, consultas Cypher y detección de código muerto, entre otras funciones.
Por eso encaja especialmente bien en el ecosistema de AI Coding: no compite con el agente, sino que complementa una de las partes potencialmente más costosas de su trabajo: explorar el código existente.
Pero Memory no significa “comprensión real”
Este es también uno de los puntos que conviene tener más presentes al evaluar el proyecto.
En el trabajo de investigación asociado al proyecto, se comparó Codebase-Memory con un agente basado en exploración de archivos utilizando 31 repositorios reales. El estudio reportó una calidad de respuesta del 83 % para Codebase-Memory frente al 92 % del agente de exploración de archivos. Al mismo tiempo, el consumo de tokens se redujo aproximadamente 10 veces y el número de llamadas a herramientas unas 2,1 veces.
Este resultado es más interesante que limitarse a afirmar que el proyecto “ahorra tokens”.
Indica que:
un grafo de código estructurado puede reducir considerablemente el coste de exploración, pero no constituye un sustituto perfecto.
Cuando una pregunta exige comprender una lógica de negocio muy específica, saber que dos funciones tienen una relación CALLS no sustituye la lectura del código fuente real.
Por eso, un flujo de trabajo más razonable sería:
Codebase Memory ↓ Ayuda al agente a localizar rápidamente ↓ Lee el código fuente relevante ↓ Comprende la lógica de negocio ↓ Modifica y ejecuta pruebas
Memory funciona como una capa de navegación, no como una respuesta universal.
Su mayor limitación también procede de la comprensión estática del código
Las relaciones del código no siempre pueden deducirse correctamente de forma estática.
Los lenguajes dinámicos, la reflexión, el código generado durante la ejecución, las macros complejas, los servicios externos y los comportamientos ocultos en archivos de configuración pueden provocar diferencias entre el Graph estático y el comportamiento real de la aplicación.
El proyecto utiliza Hybrid LSP y distintos mecanismos de análisis para reducir este problema, pero las capacidades de análisis no son idénticas para todos los lenguajes. En aquellos que todavía no cuentan con una capa semántica especializada, el proyecto tiene que apoyarse en mecanismos de análisis más básicos o en rutas de análisis textual.
Además, la propia Memory necesita mantenimiento.
El proyecto incorpora actualmente un watcher en segundo plano capaz de detectar cambios en los archivos y volver a indexarlos, mientras utiliza SQLite para mantener el índice de forma persistente.
Esto evita tener que reconstruir el Graph desde cero cada vez que se inicia el sistema, pero no elimina un problema fundamental:
El índice siempre puede quedarse por detrás del estado real del código.
Por eso, un agente maduro debería combinar el Graph, el código fuente, los cambios de Git y las pruebas.
Los repositorios grandes son donde realmente merece la pena analizarlo
En un proyecto pequeño con unas pocas decenas de archivos, el agente puede utilizar ripgrep, la búsqueda del IDE y su propio contexto, y probablemente sea suficiente.
En ese caso, añadir:
Indexer + Graph + Watcher + MCP
puede limitarse a añadir complejidad.
Pero en proyectos grandes la situación cambia.
Cuando una tarea afecta a decenas de archivos, varios módulos, múltiples servicios o incluso varios repositorios, encontrar primero el código relevante puede convertirse por sí mismo en uno de los principales costes del trabajo.
Esto resulta especialmente interesante en:
- repositorios antiguos;
- proyectos con múltiples módulos;
- arquitecturas de microservicios;
- proyectos mantenidos durante muchos años;
- sistemas con dependencias complejas;
- equipos que utilizan agentes de AI Coding con mucha frecuencia.
En estos escenarios es más probable que Codebase Memory aporte valor.
Porque cuanto más complejo es el proyecto:
mayor es la proporción de la tarea de Coding que consiste en comprender el código existente.
No es un sustituto de Code Search
La relación más precisa sería:
| Tecnología | Problema principal que resuelve |
|---|---|
| grep / ripgrep | Búsqueda precisa de texto |
| IDE Search | Localización de archivos y símbolos |
| RAG convencional | Recuperación semántica de documentos |
| Code RAG | Recuperación semántica de código |
| Code Graph | Estructura y relaciones del código |
| codebase-memory-mcp | Proporciona estas capacidades de conocimiento del código al agente mediante MCP |
Por eso, una arquitectura de AI Coding más completa probablemente no tenga que elegir solo una de estas tecnologías, sino combinarlas:
Code Search + Semantic Search + Code Graph + Codebase Memory + Git + Tests + AI Agent
El valor de codebase-memory-mcp está precisamente en que intenta convertirse en una infraestructura de conocimiento del código dentro de este conjunto.
Evaluación en escala de 5 puntos
| Dimensión | Puntuación | Evaluación |
| --- | ---: | --- |
| Enfoque técnico | 4,6/5 | Combina AST, resolución de tipos, Code Graph y MCP con una dirección técnica clara |
| Valor para AI Coding | 4,4/5 | Especialmente útil durante la fase de exploración de repositorios complejos |
| Comprensión del código | 4,5/5 | Las relaciones estructurales y las cadenas de llamadas son una fortaleza, aunque no sustituyen la lectura del código |
| Valor dentro del ecosistema MCP | 4,5/5 | Convierte el grafo de conocimiento del código en capacidades accesibles para los agentes |
| Potencial de aplicación | 4,5/5 | El potencial es especialmente interesante en proyectos grandes y mantenidos durante largos periodos |
| Facilidad de uso / complejidad | 4,1/5 | La integración es bastante profunda, pero la indexación y el mantenimiento añaden complejidad al sistema |
| Valoración general | 4,4/5 | Está más cerca de una infraestructura de AI Coding que de un simple plugin MCP |
Conclusión
El problema que realmente intenta resolver codebase-memory-mcp puede resumirse en una frase:
Permitir que un agente de IA no tenga que empezar desde cero para entender un repositorio cada vez que recibe una tarea.
Su mayor diferencia frente a una herramienta convencional de búsqueda de código tampoco consiste simplemente en “buscar más rápido”, sino en extraer previamente las relaciones estructurales del código para que el agente pueda consultarlas directamente.
En repositorios grandes, esta capacidad resulta especialmente interesante porque una parte cada vez mayor del coste de un agente proviene de explorar y comprender sistemas existentes, no simplemente de generar unas pocas líneas de código.
Pero no es una “memoria permanente” de la IA, ni significa que el modelo vaya a comprender automáticamente la lógica de negocio después de construir un Graph. El análisis estático tiene límites, el índice necesita mantenimiento y los proyectos complejos también incorporan una capa adicional de infraestructura.
Por eso, considero más apropiado entender codebase-memory-mcp como una AI Coding Code Intelligence Layer:
No hace que el modelo sea más inteligente; hace que, antes de empezar a razonar, pueda obtener mucho más rápido un mapa estructural correcto del código que tiene delante.
Y probablemente ahí está el verdadero valor de Codebase Memory en la era del AI Coding.
Lo que hace codebase-memory-mcp
- Grafo de conocimiento persistente del codigo almacenado en SQLite
- Analisis estructural con Tree-sitter AST
- Resolucion semantica hibrida mediante Hybrid LSP (Python, TS/JS, PHP, C#, Go, C/C++, Java, Kotlin, Rust, Perl)
- Relaciones CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS, DATA_FLOWS, HTTP y SEMANTICALLY_RELATED
- Busqueda semantica local con nomic-embed-code integrado en el binario
- Herramientas MCP: busqueda estructural, rutas de llamadas, analisis de impacto, cobertura, Cypher y codigo muerto
- Watcher en segundo plano que detecta cambios y reindexa
- Calidad de respuesta del 83 % frente al 92 % de exploracion de archivos, con ~10x menos tokens