Cuando un agente de IA como Claude Code necesita entender tu proyecto, explora archivo por archivo y llena su ventana de contexto de código irrelevante, gastando tokens, tiempo y precisión. Codebase Memory MCP es un servidor MCP gratuito y de código abierto que indexa todo tu proyecto en un grafo de conocimiento, de modo que el agente consulta la estructura de tu código en lugar de leérselo entero. En proyectos grandes esto reduce el gasto de tokens de forma drástica. En este artículo explico por qué el contexto es el verdadero cuello de botella de la IA que programa, cómo funciona esta herramienta por dentro y cuándo merece la pena de verdad.

Soy Joaquín Ruiz, y llevo más de veinte años programando y varios probando herramientas de IA a fondo para desarrolladores. Este es el análisis conceptual; si quieres verme medirlo con datos reales, tienes el vídeo al final.

Por qué el contexto es el cuello de botella de la IA para programar

Cuando hablamos de que un modelo de lenguaje «programa», solemos fijarnos en su capacidad de razonar. Pero el límite práctico rara vez es el razonamiento: es el contexto. Todo modelo tiene una ventana de contexto finita, y cada token que gasta describiéndose el proyecto es un token que no gasta resolviendo tu problema.

El problema es cómo un agente obtiene ese contexto. Sin un mapa del código, la única estrategia que le queda es la fuerza bruta: hace grep, abre un archivo, abre otro, se lee un módulo entero por si acaso. No sabe dónde está la respuesta, así que mete ficheros completos en su contexto a ver si suena la flauta. Y esto tiene tres costes que se acumulan:

Coste económico. Si usas la API, pagas por token. La exploración a ciegas puede multiplicar por diez o por veinte el gasto de una consulta que debería ser trivial.

Coste de latencia. Cada lectura de fichero es una ida y vuelta. Cuantos más ficheros abre el agente, más tardas en tener la respuesta.

Coste de calidad. Este es el menos obvio y el más importante. A medida que la ventana de contexto se llena de código irrelevante, la atención del modelo se diluye. Es el fenómeno del «lost in the middle»: la información importante se pierde entre el ruido, y el agente empieza a equivocarse, a escoger el punto de entrada erróneo o a alucinar relaciones que no existen. Más contexto no siempre es mejor contexto.

Dicho de otra forma: el gasto de tokens no es solo una factura, es un techo de rendimiento. Y aquí es donde entra la idea de darle al agente un mapa en lugar de obligarle a explorar a pie.

Qué es Codebase Memory MCP

Codebase Memory MCP es un servidor MCP de código abierto (licencia MIT), desarrollado por DeusData, que indexa el código de un proyecto en un grafo de conocimiento persistente para que un agente de IA pueda consultar su estructura sin leer los ficheros uno a uno. Funciona con Claude Code, Codex, Cursor, Gemini CLI, Zed y otros agentes, y se instala con un solo comando.

Un apunte para evitar confusiones: MCP significa Model Context Protocol, el estándar abierto que permite conectar herramientas externas a un agente de IA. «Codebase Memory MCP» es una herramienta concreta dentro de ese ecosistema, y no debe confundirse con otros servidores de «memoria» genéricos. Aquí «memoria» se refiere específicamente a un mapa estructural de tu código, no a recordar conversaciones.

Y algo que su público técnico agradece: es un único binario estático escrito en C, sin dependencias. Nada de Docker, nada de runtime, nada de claves de API. Lo descargas, lo instalas y funciona.

Cómo funciona por dentro: de tu código a un grafo de conocimiento

La herramienta se construye en tres capas, y entenderlas ayuda a ver por qué es tan eficiente.

Capa 1: el parseo. Coge tu código y lo analiza con tree-sitter, la misma tecnología que usan los editores modernos para entender la sintaxis. Genera el árbol de sintaxis abstracto (AST) de cada archivo. Lo hace en 158 lenguajes, con las gramáticas compiladas dentro del propio binario.

Capa 2: la resolución de tipos. Aquí está lo interesante. Tree-sitter te da la estructura, pero no entiende el código: no sabe que una llamada a un método resuelve a una clase declarada tres módulos más allá. Para eso, Codebase Memory monta encima una capa que sus autores llaman Hybrid LSP: una implementación propia, en C, de los algoritmos de resolución de tipos de los language servers reales (como pyright o gopls), sin levantar ningún proceso aparte. El resultado es un grafo tan preciso como el «Ir a definición» de tu IDE.

Capa 3: el grafo. Todo eso se guarda como un grafo de conocimiento en una base de datos SQLite persistente. Los nodos son funciones, clases, ficheros y rutas HTTP; las aristas son las llamadas, los imports, las implementaciones y las dependencias entre servicios. El indexado es RAM-first: trabaja en memoria comprimida y hace un único volcado a disco al final, lo que le permite indexar proyectos enormes en minutos.

El detalle de diseño más elegante: no lleva ningún modelo de lenguaje dentro. Codebase Memory solo construye y consulta el grafo. No traduce tu pregunta en lenguaje natural a una consulta; de eso se encarga el agente que ya tienes. Tú le preguntas a Claude Code «¿quién llama a esta función?», y Claude decide llamar a la herramienta adecuada del MCP. Es decir: no pagas otro modelo ni configuras nada extra. El agente que ya usas hace de traductor.

Por qué un grafo ahorra tokens: la geometría del ahorro

Este es el concepto clave, y conviene entenderlo bien porque explica tanto las cifras espectaculares como sus límites.

Una consulta al grafo reemplaza decenas de ciclos de grep y lectura de ficheros. En lugar de abrir diez archivos para averiguar quién llama a una función, el agente lanza una única consulta estructural y recibe la respuesta directa. Y aquí está lo importante: la respuesta escala con el tamaño de la respuesta, no con el tamaño del proyecto. Buscar un símbolo en un repositorio de 7.000 líneas o en uno de un millón te devuelve más o menos la misma cantidad de texto.

Esto significa que el ahorro no es una constante mágica: es proporcional a lo que te ahorras de no leer. En un proyecto pequeño, leer cuatro ficheros es baratísimo, así que el grafo tiene poco que ahorrar. En un monorepo donde el agente tendría que abrir treinta archivos para responder lo mismo, el grafo de una sola consulta arrasa. El ahorro de tokens no es magia, es geometría. Cuanto más grande y enrevesado es tu código, más brutal es la diferencia.

Los números, con honestidad

Aquí es donde separo el marketing de la realidad, que es lo que hago en el canal.

El proyecto presume de un 99% menos de tokens. Esa cifra concreta (unos 412.000 tokens explorando archivo a archivo frente a unos 3.400 vía grafo) procede de un único proyecto de prueba que eligieron sus propios autores: es su mejor caso, no una media. Hay además un preprint en arXiv que lo evalúa sobre 31 repositorios, pero conviene saber dos cosas: es un preprint sin revisión por pares y está firmado por los propios autores del sistema. No es una validación independiente, es el equipo evaluándose con su propio banco de pruebas. Datos útiles, pero hay que leerlos con perspectiva.

¿Qué pasa cuando lo mides tú? En mi banco de pruebas habitual (TaskFlow, una API REST en Flask), midiendo con /context antes y después de la misma consulta de arquitectura, el resultado fue en torno a un 40% menos de tokens y aproximadamente la mitad de tiempo (37 segundos frente a 1 minuto y 12). No es el 99% del folleto, pero es un dato real, medido y reproducible. Y encaja perfectamente con la geometría del ahorro: TaskFlow es pequeño, así que el ahorro es modesto; en un proyecto grande sería mucho mayor. Tienes la prueba completa, paso a paso, en el vídeo.

¿Cuándo usar Codebase Memory MCP y cuándo no?

No es una herramienta para todo. Esta es la regla práctica:

Úsalo cuando: trabajas con proyectos medianos, grandes o legacy; haces preguntas de estructura (quién llama a qué, qué se rompe si cambias algo, cuál es el radio de impacto de un refactor, dónde está el código muerto); o quieres un overview de arquitectura de un codebase que ya no te cabe en la cabeza.

No lo necesitas cuando: el proyecto es pequeño y te lo sabes de memoria; o lo que quieres es buscar texto suelto (para eso grep sigue siendo perfecto) o leer un fichero concreto (para eso está la lectura directa). No sustituye a esas herramientas: las complementa para un tipo de pregunta que ellas no responden bien.

Cómo instalarlo

En macOS o Linux es un único comando:

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

El instalador autodetecta los agentes que tengas y configura la entrada del servidor MCP por ti. En Windows, la vía recomendada es WSL. Tienes la instalación y la visualización 3D del grafo explicadas en detalle en el vídeo.

Preguntas frecuentes

Conclusión

El verdadero coste de la IA que programa no está en el modelo, está en cómo alimenta su contexto. Herramientas como Codebase Memory MCP atacan ese problema por la raíz: le dan al agente un mapa estructural en lugar de obligarle a explorar a ciegas. No es magia ni sirve para todo proyecto, pero en codebases grandes es un cambio real en gasto, velocidad y precisión. Y, como siempre digo, no te fíes del número del folleto: mídelo tú con /context en tu propio proyecto.

Si quieres verme instalarlo y medir la diferencia en directo, con la prueba CON y SIN el MCP, tienes el vídeo completo aquí: https://www.youtube.com/watch?v=5_5yik4Y0cw

Y si te interesa entender desde los cimientos cómo una máquina convierte tu código en algo que un modelo puede razonar —embeddings, grafos, contexto—, lo explico a fondo en mi libro El motor de la inteligencia artificial: https://amzn.eu/d/05gIeN2w

Escrito por Joaquín Ruiz, experto en inteligencia artificial afincado en Zaragoza, autor de tres libros de IA, profesor universitario y creador del canal @jokioki (IA para desarrolladores). Puedes ver más sobre mi trabajo en /experto-ia-zaragoza/.