codebase-memory-mcp: dale a tu agente memoria estructural de tu repositorio
En resumen: codebase-memory-mcp indexa tu repositorio en un grafo de conocimiento persistente para que tu agente de codificación responda preguntas estructurales desde el grafo, en lugar de buscar y leer archivos hasta encontrar la respuesta. El proyecto mide cinco consultas estructurales en aproximadamente 3.400 tokens mediante el grafo, frente a unos 412.000 usando exploración archivo por archivo: una reducción del 99,2%. Está escrito en C, se distribuye como un único binario nativo sin entorno de ejecución ni clave API, cubre más de 160 lenguajes y funciona completamente en tu máquina. A 1 de septiembre de 2026 acumula 41.536 estrellas y usa licencia MIT. Si vas a instalar una herramienta de la ola de agentes de 2026, empieza por esta.
Esta es una inmersión práctica en una de las cinco herramientas de agente de IA de código abierto que vale la pena instalar en 2026.
El problema: buscar el código en cada sesión
Pregúntale a tu agente dónde se llama una función y observa el proceso:
- Ejecuta
grep. - Lee tres archivos.
- Busca de nuevo con otro patrón.
- Lee cuatro archivos más.
- Responde correctamente después de consumir decenas de miles de tokens.
Haz una pregunta de seguimiento y el ciclo comienza otra vez.
Este patrón consume rápidamente el límite de uso de una sesión larga. También reduce la calidad de las respuestas: una ventana de contexto llena de código fuente deja menos espacio para razonar, y el agente olvida lo que leyó al terminar la sesión.
codebase-memory-mcp ataca ambos problemas indexando el repositorio una sola vez y respondiendo después las preguntas estructurales desde un grafo persistente.
Qué hace
La herramienta analiza tu repositorio y construye un grafo de conocimiento con:
- Funciones y clases.
- Cadenas de llamadas.
- Rutas HTTP.
- Enlaces entre servicios.
- Relaciones entre archivos y componentes.
El análisis sintáctico usa tree-sitter y cubre más de 160 lenguajes. Una capa LSP híbrida añade resolución semántica de tipos para el grupo principal que el README destaca: Python, TypeScript, JavaScript —incluidos JSX y TSX—, PHP, C#, Go, C, C++, Java, Kotlin, Rust y Perl.
La diferencia es importante: el análisis AST puede decirte que se invoca un método save; la resolución de tipos puede decirte a qué clase pertenece.
El resultado se expone mediante 15 herramientas MCP para:
- Buscar símbolos y referencias.
- Rastrear cadenas de llamadas.
- Obtener una visión general de la arquitectura.
- Analizar el impacto de un cambio.
- Verificar la cobertura del índice.
- Ejecutar consultas Cypher.
- Detectar código muerto.
- Vincular llamadas HTTP entre servicios.
- Gestionar ADR.
Cualquier cliente compatible con el Protocolo de Contexto del Modelo puede utilizarlo. El proyecto enumera 45 interfaces de agente compatibles, entre ellas Claude Code, Codex, Cursor, Windsurf, OpenCode, Gemini CLI, Aider y Kilocode.
Qué dicen las cifras
Hay dos mediciones independientes.
Medición del proyecto
Cinco consultas estructurales consumieron aproximadamente:
- 3.400 tokens mediante el grafo.
- 412.000 tokens explorando archivos con grep.
Eso equivale a una reducción del 99,2%, o aproximadamente 120 veces menos tokens para obtener las mismas respuestas.
Medición académica
La prepublicación Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP evalúa la herramienta en 31 repositorios reales y reporta:
- 83% de calidad de respuesta.
- 10 veces menos tokens.
- 2,1 veces menos llamadas a herramientas frente a la exploración archivo por archivo.
La diferencia entre 120x y 10x es importante. La primera cifra corresponde a cinco consultas estructurales, el mejor caso de uso para un grafo. La segunda combina tareas más amplias en 31 repositorios y se acerca más a lo que verás en el uso diario.
Usa 10x como cifra de planificación. Cualquier resultado mejor será una ventaja.
Velocidad y arquitectura
Indexar el kernel de Linux —28 millones de líneas en 75.000 archivos— tarda unos tres minutos. Un repositorio promedio se indexa en milisegundos y las consultas estructurales responden en menos de un milisegundo.
La tubería utiliza:
- Un diseño orientado a RAM.
- Compresión LZ4.
- SQLite en memoria.
- Coincidencia de patrones Aho-Corasick fusionada.
- Liberación de memoria después de indexar.
La implementación en C, en lugar de TypeScript o Python, explica buena parte de estas cifras y permite distribuir la herramienta sin instalar un runtime.
Instalación
macOS y Linux
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
Windows
El proyecto recomienda revisar el script antes de ejecutarlo:
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
notepad install.ps1 # léelo primero
Unblock-File .\install.ps1
.\install.ps1
El instalador admite:
-
--skip-config: instala solo el binario, sin configurar agentes. -
--dir=<path>: instala en una ubicación personalizada.
También detecta automáticamente los agentes de codificación instalados y escribe las entradas MCP documentadas. Cuando el cliente lo permite, añade instrucciones, habilidades y hooks de ciclo de vida.
En macOS elimina los atributos de cuarentena y firma el binario ad hoc, por lo que no necesitas ejecutar manualmente xattr ni codesign.
Después de instalarlo, reinicia tu agente y pídele que indexe el proyecto.
Configuración recomendada
Configura estas opciones desde el primer día:
# indexar automáticamente los proyectos nuevos al conectarse
codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_index_limit 50000
# visualizar el grafo desde el binario
codebase-memory-mcp --ui=true --port=9749
La interfaz en localhost:9749 renderiza el grafo de conocimiento en 3D. Es útil para detectar estructuras inesperadas y comprobar que el índice cubrió lo que esperabas.
Si trabajas con muchos repositorios, puedes evitar que una sesión registre su proyecto en el observador en segundo plano:
codebase-memory-mcp config set auto_watch false
Para desactivar completamente el hilo de sondeo:
codebase-memory-mcp config set watcher_enabled false
watcher_enabled se lee una sola vez cuando inicia el demonio. Detén y reinicia el demonio después de cambiarlo.
Dos verificaciones antes de ejecutarlo
Ambos puntos están documentados por el proyecto, pero conviene revisarlos.
1. Positivo falso de Microsoft Defender
Microsoft Defender puede marcar un binario de lanzamiento como:
Trojan:Script/Wacatac.B!ml
El proyecto lo documenta como un falso positivo conocido y señala que normalmente 61 de aproximadamente 62 motores lo consideran limpio. También indica que la misma familia de detección afecta a GitHub CLI, llama.cpp, Godot y la propia cadena de herramientas Go de Microsoft.
Cada lanzamiento se analiza en VirusTotal antes de publicarse y las notas de lanzamiento enlazan los resultados. El problema parece estar relacionado con heurísticas aplicadas a binarios nativos pequeños y sin firmar.
2. Acceso al código y a la configuración
La herramienta lee tu base de código y escribe en los archivos de configuración de tu agente. Ese es su propósito y el proyecto lo declara explícitamente.
Las mitigaciones disponibles son:
- Código fuente completo bajo licencia MIT.
- OpenSSF Scorecard.
- Procedencia SLSA 3 para los lanzamientos.
- Procesamiento completamente local.
- Sin solicitudes de red iniciadas por el proceso.
- Sin búsqueda de actualizaciones en segundo plano.
- Sin comunicación externa declarada por el proyecto.
Las actualizaciones se ejecutan desde el script de instalación junto al binario, no desde el proceso en ejecución. El README explica esta decisión de diseño con detalle.
La respuesta práctica es sencilla: lee el script de instalación antes de pasarlo a Bash y verifica la afirmación de que el procesamiento es local si tu modelo de seguridad lo requiere. Las estrellas indican popularidad, no sustituyen una auditoría.
Por qué conviene instalarlo primero
Las demás herramientas de la ola actual de agentes modifican tu flujo de trabajo:
- Los perfiles cambian cómo formulas las preguntas.
- Los worktrees paralelos cambian cómo organizas el trabajo.
- El acceso web cambia qué tareas puedes delegar.
codebase-memory-mcp no exige aprender un flujo nuevo. Lo instalas, indexas el proyecto y tu agente deja de consumir contexto en ciclos repetidos de grep.
En una refactorización larga, la diferencia entre alcanzar el límite a las 14:00 y terminar el día puede ser enorme.
También mejora la calidad. Un agente que gasta 400.000 tokens leyendo archivos tiene menos espacio para razonar y puede perder de vista lo que leyó al principio de la sesión. Responder desde un grafo mantiene libre la ventana de contexto. La misma dinámica afecta a lo que las herramientas devuelven al agente, como se explica en ventanas de contexto de respuesta de herramientas de agente.
Las herramientas que realmente usarás
No necesitas memorizar las 15 herramientas MCP: el agente elige cuál utilizar. Lo importante es saber qué preguntas ahora son baratas.
Análisis de impacto
Antes de cambiar la firma de una función, pregunta qué puede romperse.
El grafo rastrea sus invocadores en todo el repositorio en menos de un milisegundo. A diferencia de grep, puede manejar relaciones indirectas y despacho dinámico con mucha más información estructural.
Convierte “creo que es seguro” en una lista concreta de dependencias.
Rastreo de cadenas de llamadas
Responde cómo llega la ejecución a un fragmento específico de código. Es especialmente útil en repositorios desconocidos y evita leer hacia arriba a través de varios archivos buscando el punto de entrada.
Visión general de la arquitectura
Proporciona un mapa estructural sin obligar al agente a leer todo el árbol. Es una forma rápida de orientarse durante la incorporación a una base de código desconocida y combina bien con una persona o agente dedicado a la exploración de solo lectura.
Detección de código muerto
Encuentra código que no recibe llamadas. Ejecútala antes de un sprint de limpieza para basar la eliminación en datos, no en suposiciones.
Vinculación HTTP entre servicios
Rastrea una llamada de un servicio hasta el handler correspondiente en otro. En un repositorio de microservicios, esto puede marcar la diferencia entre entender un repositorio y entender el sistema completo.
También es el punto en el que aparece una limitación importante: conocer dónde está un endpoint no equivale a conocer el contrato que debe cumplir.
Consultas Cypher
Son la vía de escape. Si las herramientas predeterminadas no cubren una pregunta específica, puedes consultar directamente el grafo.
El cambio práctico está en las preguntas que haces:
- “¿Qué llama a esta función?” antes de cada refactorización.
- “¿Qué se rompe si cambio esta firma?”
- “¿Cuál es la ruta de solicitud de este endpoint?” antes de depurar.
- “¿Qué servicios dependen de esta ruta?”
La herramienta cambia la economía de la curiosidad: preguntas que antes costaban 50.000 tokens y varios minutos pasan a ser prácticamente gratuitas.
Lo que el grafo sabe y lo que no sabe
El grafo se construye a partir de tu código. Por tanto, sabe qué existe en el código y cómo se relacionan sus elementos.
Puede saber que existe la ruta /v1/invoices/{id} y qué función la atiende. No puede inferir de forma fiable que:
- El endpoint devuelve
409cuando se reutiliza una clave de idempotencia. - Esa respuesta usa un sobre de error diferente.
-
statustiene exactamente cinco valores válidos. - El cursor es opaco y no un desplazamiento numérico.
- Un campo está obsoleto y desaparecerá el próximo trimestre.
Esos detalles forman parte de un contrato, no necesariamente de la implementación del handler.
Sin una especificación, el agente puede escribir un cliente contra una forma inferida, probarlo contra un mock inventado y llegar a staging con todo “en verde”, aunque el contrato real sea diferente.
Grafo para el “dónde”, especificación para el “qué”
Por eso Apidog y una herramienta como codebase-memory-mcp se complementan:
- El grafo responde “dónde”. Qué handler atiende una ruta, cuál es la cadena de llamadas y qué dependencias se ven afectadas.
- La especificación responde “qué”. Esquemas reales, códigos de estado, sobres de error y reglas que el agente puede leer en lugar de reconstruir.
- Los mocks se generan desde la especificación. Esto incluye ramas de error que el agente probablemente no inventaría.
- Las pruebas de contrato fallan en CI. Así detectan cuándo la implementación y el acuerdo divergen.
La idea es la misma en ambos casos: indexar una vez la información en un formato diseñado para la pregunta.
Si tus agentes escriben clientes de API contra formas que nadie documentó, consulta cómo usar tu especificación OpenAPI como herramientas para el agente, revisa lo que sucede cuando los cambios de API rompen los agentes de IA y considera descargar Apidog.
También pueden interesarte:
- Diseño de esquemas de herramientas de API para agentes
- ¿Sigues necesitando una herramienta de API en la era de los agentes de IA?
La memoria del código no es memoria del trabajo
El segundo límite es organizativo.
El índice vive en un directorio de caché de una máquina y bajo una cuenta. Se comparte entre sesiones locales de Claude Code, Codex y OpenCode mediante un demonio de coordinación, pero se detiene en el borde de esa máquina.
Más importante todavía: el grafo es memoria de la base de código, no memoria del trabajo.
Puede decirte que el helper de reintentos llama al cliente de pagos. No puede decirte:
- Por qué cambió el backoff en julio.
- Quién tomó la decisión.
- Qué alternativa se descartó.
- Si alguien revisó el cambio.
Esa historia puede haber quedado en una sesión de terminal que ya terminó.
Los equipos experimentan una brecha incómoda: el agente recuerda el código mejor que cualquier persona del equipo, pero no recuerda las decisiones que produjeron ese código.
Sharkly cubre esa otra mitad convirtiendo la tarea en el registro duradero:
- El trabajo vive como tareas. La salida del agente llega como comentarios a los que puedes responder. El progreso y las llamadas a herramientas quedan asociados a la tarea.
- El agente es una configuración guardada. Instrucciones, entorno, habilidades, repositorios y configuración se reutilizan en lugar de reconstruirse en cada máquina.
- La ejecución usa tu infraestructura. Puedes conectar un ordenador portátil, un servidor o un contenedor y reutilizar el Runtime instalado allí.
- El trabajo del repositorio usa un worktree por tarea. Así las tareas paralelas sobre el mismo repositorio no colisionan.
- El Backlog no inicia ejecuciones. Puedes preparar el trabajo antes de lanzar un agente.
- La estructura es familiar. Espacios, proyectos, sprints y tareas, con sincronización con Jira.
La combinación es memoria de código más memoria de trabajo: una herramienta recuerda el repositorio y la otra recuerda lo que el equipo y los agentes hicieron en él.
Preguntas frecuentes
¿Funciona con Cursor, Codex y OpenCode o solo con Claude Code?
Funciona con cualquier cliente MCP. El proyecto lista 45 interfaces compatibles y el instalador detecta automáticamente las que tienes instaladas.
Si estás comparando clientes de agente para trabajo con APIs, revisa nuestro análisis de clientes de API en Cursor y Copilot.
¿Mi código sale de mi máquina?
No según el proyecto. El procesamiento es completamente local y codebase-memory-mcp afirma que no realiza solicitudes de red por sí mismo ni busca actualizaciones en segundo plano. El código fuente tiene licencia MIT, por lo que puedes verificarlo directamente.
¿Es realista una reducción del 99% de tokens?
El 99,2% corresponde a cinco consultas estructurales: el caso más favorable para un grafo.
La prepublicación evaluada en 31 repositorios reporta 10 veces menos tokens y 2,1 veces menos llamadas a herramientas. Planifica alrededor de 10x; las cargas de trabajo con muchas preguntas estructurales pueden superar esa cifra.
¿Qué tamaño de repositorio puede manejar?
El caso límite declarado es el kernel de Linux: 28 millones de líneas y 75.000 archivos indexados en tres minutos.
El límite predeterminado de autoindexación es configurable y puede establecerse en 50.000 archivos. Los repositorios de aplicaciones habituales se indexan en milisegundos.
¿Por qué Microsoft Defender lo marca?
Es un falso positivo conocido asociado a binarios nativos pequeños y sin firmar. El proyecto indica que 61 de aproximadamente 62 motores lo consideran limpio y enlaza los resultados de VirusTotal para cada lanzamiento.
La misma familia de detección también afecta a GitHub CLI y a la cadena de herramientas Go de Microsoft.
¿Esto reemplaza la lectura del código?
Para preguntas estructurales, puede reemplazar gran parte de la exploración manual. Para comportamiento, casos límite e intención, no.
Y para saber qué devuelve una API necesitas una especificación, no solo un grafo ni una lectura parcial del código. Consulta ¿todavía necesitas una herramienta de API en la era de los agentes de IA?.
Conclusión
codebase-memory-mcp es una de las herramientas menos llamativas de la ola de agentes de 2026 y, precisamente por eso, una de las que ofrece mejor retorno: no cambia tu flujo de trabajo, no exige nuevos hábitos, se distribuye como un único binario nativo y reduce en un orden de magnitud los tokens que tu agente gasta respondiendo preguntas estructurales.
El beneficio aumenta cuando varios agentes trabajan en paralelo, como ocurre con Orca.
Instálalo, indexa tu proyecto, configura auto_index y abre una vez el visor de grafos para comprobar qué ha construido.
Después, mantén claros sus dos límites:
- El grafo sabe dónde está tu código, pero no qué promete tu API. Esa brecha se cierra con una especificación, mocks y pruebas de contrato.
- El grafo recuerda el repositorio, pero no el trabajo ni las decisiones que lo modificaron. Esa brecha se cierra haciendo que la tarea sea el registro duradero.
Un recuerdo perfecto del código es una base sólida. No es lo mismo que saber qué es verdad o qué se decidió.
Top comments (0)