codebase-memory-mcp: guía para que tu AI Agent entienda el código

Cuando Claude Code, Codex o Cursor entra por primera vez en un proyecto relativamente complejo, normalmente no empieza a escribir código de inmediato. Primero realiza una gran cantidad de trabajo de “reconocimiento”: busca archivos, lee código fuente, localiza funciones y clases, sigue imports, analiza relaciones entre llamadas y solo después empieza a modificar el proyecto.

En un proyecto pequeño, esto no supone un gran problema. Pero a medida que el repositorio crece, hacer que la IA vuelva a familiarizarse con el proyecto cada vez que recibe una nueva tarea puede generar una gran cantidad de búsquedas repetitivas y consumo adicional de contexto.

La idea de codebase-memory-mcp es bastante directa: analizar primero el repositorio y convertirlo en un grafo de conocimiento estructurado que pueda consultarse de forma persistente, y después exponer ese conocimiento a los AI Coding Agents mediante MCP.

No es un Coding Agent ni se encarga de generar código. Es más útil entenderlo como una capa de comprensión del código para el agente.

Antes de empezar: qué necesitas

La versión oficial actual proporciona binarios nativos para macOS, Linux y Windows. No requiere Docker, Node.js ni Python como runtime, y tampoco necesita una API Key. El proyecto utiliza Tree-sitter para el análisis AST y ofrece resolución de tipos mediante Hybrid LSP para lenguajes como Python, TypeScript/JavaScript, Java, Go, Rust y C/C++.

Si ya utilizas herramientas de AI Coding como Claude Code, Codex CLI, Cursor, Gemini CLI, VS Code o Zed, puedes utilizarlas directamente como clientes MCP. El instalador oficial detecta automáticamente algunos de estos clientes y escribe la configuración correspondiente.

Para la primera prueba, es recomendable utilizar un proyecto real, por ejemplo un proyecto propio de Next.js, React, Python o Node.js, en lugar de un simple Hello World.

Instalar codebase-memory-mcp

En macOS y Linux, la forma más sencilla es utilizar el script oficial de instalación:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

En Windows, puedes utilizar el script oficial de PowerShell:

Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
Unblock-File .\install.ps1
.\install.ps1

El instalador oficial no solo instala el MCP Server. También puede detectar los clientes disponibles y configurar automáticamente los archivos MCP correspondientes, además de añadir Instructions, Skills y determinados Hooks del ciclo de vida.

Una vez terminada la instalación, tendrás que reiniciar tu Coding Agent.

Si prefieres comprobar primero qué archivos modificará el instalador, puedes ejecutar:

codebase-memory-mcp install --dry-run

Este comando muestra los archivos de configuración que se modificarían en el sistema actual, por lo que resulta especialmente útil para revisar el proceso antes de ejecutar la instalación real.

Configurar MCP: puede ser muy sencillo

Si utilizas la instalación automática, normalmente no tendrás que editar manualmente la configuración de MCP.

Con clientes como Codex CLI, Claude Code o Cursor, el instalador oficial intenta detectar el cliente y escribir la configuración correspondiente. Como la ubicación de los archivos de configuración varía entre clientes, es preferible utilizar install --dry-run para comprobar qué ruta utiliza realmente tu entorno, en lugar de copiar una ruta fija encontrada en otro tutorial.

Si necesitas realizar la configuración manualmente, el proyecto también admite la configuración estándar de un MCP Server, por ejemplo:

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

Lo importante aquí es sustituir command por la ruta real del binario en tu equipo.

Después de completar la configuración, reinicia el Agent.

Crear el primer Codebase Memory

Entra en el directorio de tu proyecto real y dile al AI Agent:

Index this project

Este es probablemente el paso más importante de la primera experiencia.

codebase-memory-mcp analizará el repositorio y construirá un grafo de conocimiento estructurado y persistente. La implementación actual no se limita a dividir todo el código fuente en chunks de texto. Analiza archivos, símbolos, funciones, clases, relaciones entre llamadas y otras estructuras del código.

Los resultados del índice se almacenan de forma persistente en un directorio de caché local, por lo que el Agent puede seguir utilizándolos después de reiniciarse.

El proyecto también admite un watcher en segundo plano y mecanismos de indexación automática. Actualmente auto_watch está activado de forma predeterminada, y también puedes utilizar auto_index para que los proyectos nuevos se indexen automáticamente al establecerse la sesión MCP.

Para una primera prueba, ejecutar manualmente:

Index this project

es suficiente.

No empieces haciendo cambios: prueba primero una consulta

Una vez creado el Memory, es recomendable comenzar con una tarea de solo lectura.

Por ejemplo:

Lee el código actual y dime cuáles son los principales módulos del proyecto, sus puntos de entrada y las dependencias generales entre ellos. No modifiques ningún archivo.

Después puedes profundizar:

Localiza las principales funciones relacionadas con el inicio de sesión de usuarios y explica aproximadamente la ruta de llamadas desde el punto de entrada hasta la lógica de autenticación.

En esta fase, lo realmente interesante no es solo lo que responde la IA, sino si el Agent está utilizando las herramientas de consulta estructurada de codebase-memory-mcp.

La versión actual proporciona herramientas MCP como search_graph, trace_path, query_graph, index_status y check_index_coverage.

Por ejemplo, trace_path permite recorrer las relaciones de llamadas de una función, tanto hacia las funciones que la llaman como hacia aquellas que ella misma invoca.

Por tanto, no se limita a responder:

“¿En qué archivos aparece la palabra relacionada con el inicio de sesión?”

Sino que puede acercarse más a:

“¿Quién llama a esta función y qué funciones invoca después?”

Primer Coding Task real

Cuando hayas comprobado que Memory funciona correctamente, puedes empezar con una tarea de desarrollo real.

Por ejemplo, en un sistema de usuarios existente:

Añade una función para eliminar la cuenta desde la página de configuración del usuario. Primero analiza la autenticación, las API y la estructura de la base de datos actuales y determina qué archivos deben modificarse. No añadas nuevas dependencias. Después implementa la funcionalidad y ejecuta las pruebas existentes.

Un flujo normal del Agent podría ser:

Codebase Memory
↓
Localizar el User Model
↓
Localizar API / Service
↓
Seguir las relaciones de llamadas
↓
Determinar el alcance de los cambios
↓
Modificar el código
↓
Ejecutar pruebas
↓
Analizar resultados y corregir

Aquí Codebase Memory no sustituye a Codex ni a Claude Code.

Su función es proporcionar información estructurada sobre el código; el Agent se encarga de interpretar esa información y ejecutar el trabajo de desarrollo.

Ese es precisamente el papel de MCP dentro de esta arquitectura: convertir las capacidades de análisis del repositorio en herramientas que el Agent puede utilizar activamente.

Prueba también la comprensión entre módulos

Una de las mejores formas de evaluar Codebase Memory es utilizar preguntas que atraviesen varios archivos o módulos.

Por ejemplo:

Si quiero modificar el sistema de estados de los pedidos, no cambies todavía ningún código. Dime qué Model, Service, API, componentes frontend y pruebas podrían verse afectados y explica cómo están relacionados.

Con una búsqueda convencional, este tipo de tarea puede terminar convirtiéndose en:

Buscar Order
↓
Abrir archivo
↓
Buscar otro símbolo
↓
Seguir leyendo
↓
Construir manualmente las relaciones

En cambio, el grafo de conocimiento de codebase-memory-mcp puede proporcionar directamente relaciones estructurales mediante las herramientas de búsqueda y trazado de llamadas. Después, el Agent puede convertir esos resultados estructurados en una explicación comprensible.

La documentación oficial describe el proyecto como un backend de análisis estructural. No incorpora un LLM propio; el razonamiento inteligente lo realiza el Agent del MCP Client.

¿Qué ocurre con Memory después de modificar el código?

Este es un detalle que resulta fácil pasar por alto durante la primera instalación.

La versión actual incorpora mecanismos de sincronización automática. Una vez creado el índice, el watcher puede detectar cambios en el código, incluidos cambios relacionados con Git, y volver a indexar la información correspondiente. También puedes utilizar las opciones auto_index y auto_watch.

Puedes consultar el estado del índice mediante:

index_status

Y comprobar si determinadas rutas ya han sido indexadas mediante:

check_index_coverage

Sin embargo, hay que tener presente algo importante:

que exista un índice no significa que la comprensión que tiene la IA del proyecto sea siempre correcta.

El código generado dinámicamente, la reflexión, determinados comportamientos de runtime y las situaciones que el parser no puede analizar completamente pueden provocar información incompleta.

Por eso, Memory debe entenderse como una infraestructura de apoyo para la comprensión del código, no como una fuente absoluta de verdad sobre el comportamiento real de la aplicación.

Problemas más habituales durante la primera instalación

MCP no aparece

Comprueba la ruta de instalación y la configuración del cliente y, después, reinicia el Agent. Si has realizado la configuración manualmente, verifica especialmente que command utilice una ruta absoluta válida.

La documentación oficial también proporciona métodos para comprobar directamente el MCP Server.

No se ha creado el Memory

Comprueba que estás indexando el directorio correcto y consulta index_status. En repositorios especialmente grandes también conviene tener en cuenta los límites de recursos asociados a la indexación.

El Agent no utiliza Memory automáticamente

Que la conexión MCP funcione correctamente no significa que el Agent vaya a utilizar las herramientas en todas las tareas.

Puedes indicarle explícitamente:

Antes de analizar el código, utiliza primero codebase-memory-mcp para consultar la estructura relevante del código y las relaciones de llamadas.

Pero no conviene interpretar esto como una garantía absoluta. La decisión final de utilizar o no una herramienta sigue dependiendo del cliente y de la estrategia de uso de herramientas del propio Agent.

El código ya ha cambiado, pero las consultas parecen incorrectas

Primero comprueba si el índice se ha actualizado correctamente. Si el índice está actualizado, entonces hay que considerar si existe alguna limitación en la capacidad de análisis del código.

¿Qué proyectos son más adecuados?

Si solo tienes un pequeño proyecto Demo con unas pocas decenas de archivos, la búsqueda del IDE, ripgrep y la capacidad del propio Agent para leer archivos probablemente sean suficientes.

Los casos donde merece más la pena probarlo son:

• repositorios medianos y grandes;

• proyectos con múltiples módulos;

• proyectos antiguos;

• arquitecturas con dependencias complejas;

• proyectos que requieren mantenimiento frecuente;

• equipos que utilizan Claude Code, Codex u otros Coding Agents de forma intensiva.

Cuanto más complejo es el proyecto, más tiempo suele dedicar el Agent a comprender el código existente. Por eso, también aumenta el potencial de una capa de Codebase Memory.

El flujo que conviene recordar para empezar

Instalar
↓
Configurar MCP
↓
Entrar en un proyecto real
↓
Index this project
↓
Dejar que el Agent comprenda primero el proyecto
↓
Consultar relaciones del código
↓
Ejecutar una tarea de Coding real
↓
Comprobar que el índice sigue actualizado

No conviene entender codebase-memory-mcp como otro AI Coding Agent.

Una forma más precisa de definirlo sería:

Es una infraestructura de comprensión del código que conecta el repositorio con el AI Agent.

Su función principal no es escribir código por ti, sino permitir que el Agent consulte de forma estructurada archivos, símbolos, relaciones de llamadas y dependencias cuando trabaja con un proyecto complejo. De esta manera, puede reducir parte del coste asociado a las búsquedas repetitivas y a tener que reconstruir continuamente una visión del repositorio.

En proyectos pequeños, esta capa puede no ser necesaria. Pero cuando el código ha alcanzado un nivel de complejidad en el que incluso un desarrollador necesita pasar bastante tiempo buscando dónde se encuentra una determinada funcionalidad, es cuando Codebase Memory empieza a tener un valor mucho más evidente.