Si alguna vez usaste Claude Code, Cursor o cualquier agente de IA para programar en un repositorio grande, conocés el problema: el agente no «sabe» tu código, lo va descubriendo a fuerza de grep y read. Cada pregunta como «¿quién llama a esta función?» termina en decenas de búsquedas de texto, archivo por archivo, gastando un montón de tokens solo para entender la estructura del proyecto antes de poder hacer algo útil.
codebase-memory-mcp ataca exactamente ese problema. Es un servidor MCP (Model Context Protocol) que indexa tu repositorio completo en un grafo de conocimiento persistente — funciones, clases, llamadas, rutas HTTP, dependencias — y lo deja disponible para que cualquier agente compatible con MCP lo consulte en milisegundos, en lugar de releer archivos cada vez.
Qué problema resuelve
La forma tradicional en que un agente de IA «explora» un código es básicamente fuerza bruta: lee archivos, busca patrones de texto, infiere relaciones. Funciona, pero es lento y consume una cantidad enorme de contexto. El proyecto cita un benchmark propio: cinco consultas estructurales típicas (¿qué llama a esta función?, ¿qué rutas expone este módulo?, etc.) consumieron alrededor de 3.400 tokens vía codebase-memory-mcp, contra unos 412.000 tokens haciendo el mismo trabajo a mano con grep y lectura de archivos. Es una reducción de más del 99%.
La idea no es nueva en espíritu —existen otras herramientas de «code graph»— pero la implementación tiene varias decisiones técnicas interesantes que vale la pena mirar de cerca.
Cómo está construido
Lo primero que llama la atención es que está escrito casi enteramente en C (87%) y C++ (11%), sin runtime de Node, Python ni JVM de por medio. El resultado es un binario estático único, sin dependencias, que corre en macOS, Linux y Windows. Se instala con un script de una línea y listo: no hay que levantar Docker, no hay que configurar una API key, no hay que instalar nada adicional.
El parsing de código se apoya en tree-sitter, con gramáticas para 155 lenguajes compiladas directamente dentro del binario. Para Go, C, C++ y la familia TypeScript/JavaScript/JSX/TSX, suma además una capa de resolución de tipos al estilo LSP —una reimplementación propia de los algoritmos que usa tsserver— que permite inferencia de tipos de retorno, binding de parámetros, sustitución de genéricos y dispatch de componentes JSX.
Sobre esa base construye un grafo con nodos como Function, Class, Method, Interface, Route o Resource, conectados por relaciones como CALLS, IMPORTS, IMPLEMENTS, HTTP_CALLS o DATA_FLOWS. Ese grafo se puede consultar con un subconjunto de Cypher (el lenguaje de consultas de Neo4j), con búsqueda semántica vectorial usando embeddings de código incrustados en el propio binario, o con búsqueda de texto completo vía SQLite FTS5.
Un dato que cambia la escala del proyecto
El número que mejor ilustra el rendimiento es este: indexa el kernel de Linux completo —28 millones de líneas, 75.000 archivos— en 3 minutos, generando 2,1 millones de nodos y 4,9 millones de aristas. Las consultas sobre ese grafo, una vez construido, responden en menos de 1 milisegundo. Para un repositorio promedio, la indexación inicial se mide en milisegundos.
Esto lo logra con un pipeline que prioriza la RAM: compresión LZ4, una base SQLite en memoria durante todo el proceso, y un único volcado a disco al final. La memoria se libera apenas termina de indexar.
Integración con agentes
El comando de instalación detecta automáticamente qué agentes de código tenés instalados —Claude Code, Codex CLI, Gemini CLI, Cursor, Aider, Zed, OpenCode y varios más— y configura solo las entradas MCP, los archivos de instrucciones y los hooks correspondientes para cada uno. Para Claude Code en particular, instala un hook que intercepta las llamadas a Grep y Glob (nunca a Read, para no romper el flujo de «leer antes de editar») e inyecta contexto estructurado del grafo cuando el término de búsqueda coincide con algún símbolo indexado.
El servidor expone 14 herramientas MCP distintas, divididas en dos grupos: indexación (index_repository, list_projects, index_status) y consulta (search_graph, trace_call_path, detect_changes, query_graph, get_architecture, entre otras). El flujo típico es simple: el agente recibe una pregunta en lenguaje natural, la traduce a una llamada a una de estas herramientas, y codebase-memory-mcp le devuelve resultados estructurados que el agente presenta en texto plano. El proyecto no incluye ningún modelo de lenguaje propio —deliberadamente—, porque asume que el agente con el que ya estás hablando hace ese trabajo de traducción.
Detalles que muestran cuidado en el diseño
Hay un par de decisiones que valen la pena mencionar porque no son obvias a primera vista:
- Artefacto de grafo compartido por equipo: se puede commitear un archivo comprimido con zstd (
.codebase-memory/graph.db.zst) junto al código fuente, para que cuando un compañero clone el repo no tenga que reindexar todo desde cero, solo aplicar el diff incremental. - Indexación de infraestructura como código: Dockerfiles, manifiestos de Kubernetes y overlays de Kustomize se indexan también como nodos del grafo, con sus referencias cruzadas.
- Vinculación cross-servicio: detecta rutas HTTP, gRPC, GraphQL y tRPC, y las conecta con sus call sites correspondientes usando un score de confianza, algo útil en arquitecturas de microservicios donde el código vive repartido en varios repositorios.
- Detección de código muerto: identifica funciones sin ningún llamador, excluyendo los entry points, en unos 150 milisegundos sobre el grafo completo.
Seguridad y procedencia
Para un binario que se descarga y ejecuta directamente sobre tu código fuente, el proyecto documenta bastante bien su cadena de confianza: cada release pasa por escaneo en VirusTotal con más de 70 motores, generación de procedencia criptográfica bajo SLSA Nivel 3, firmas keyless con Sigstore/cosign, checksums SHA-256, y análisis estático con CodeQL que bloquea el pipeline si queda alguna alerta abierta. Todo el procesamiento ocurre localmente: el código no sale de la máquina en ningún momento.
¿Para quién tiene sentido?
Si trabajás con repositorios chicos o medianos, probablemente no notes una diferencia dramática —los agentes ya se manejan razonablemente bien ahí. Donde esta herramienta se vuelve interesante es en monorepos grandes, codebases legacy con miles de archivos, o cualquier escenario donde cada consulta del agente hoy implica minutos de exploración a ciegas. También es relevante si trabajás con varios lenguajes a la vez (PHP, Node, Python como en mi caso), porque el soporte multi-lenguaje evita tener que cambiar de herramienta según el stack.
Vale la pena aclarar que esto no reemplaza al agente: es una capa de memoria estructural debajo de él. Quien sigue interpretando el código y decidiendo qué hacer con esa información es Claude Code, Codex o el agente que estés usando. codebase-memory-mcp solo le ahorra el trabajo sucio de tener que reconstruir el mapa del territorio cada vez que se le pregunta algo.
Instalación rápida
Para quien quiera probarlo, la instalación en macOS o Linux es una sola línea:
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bashDespués de reiniciar el agente, basta con pedirle «indexá este proyecto» para que arranque. El código completo, junto con el paper que describe el diseño y los benchmarks, está disponible en el repositorio de GitHub.
