Codebase Memory: grafo de conocimiento del código y optimización de tokens en agentes de IA

El MCP codebase memory (en concreto el servidor codebase-memory-mcp) convierte tu repositorio en un grafo de conocimiento consultable que tu agente de IA puede interrogar en milisegundos, en lugar de leer fichero a fichero. Aquí tienes qué hace exactamente, qué puedes esperar de él y cómo montarlo en Claude Code, Codex CLI, Antigravity y DeepSeek Harness, todo con un único binario y sin nubes ni claves de API.

01 Qué es el MCP codebase memory

El Model Context Protocol (MCP) es un estándar abierto que permite que un agente de IA se conecte a herramientas y datos externos de forma normalizada: el agente deja de ser una «caja negra» y puede ejecutar búsquedas, leer cosas o consultar servicios a través de un contrato común. Un servidor MCP es, en pocas palabras, un programa que expone esas capacidades.

Cuando se habla de “codebase memory” la expresión más directa apunta a codebase-memory-mcp (proyecto de DeusData). Es un motor de inteligencia de código: indexa tu repositorio en un grafo de conocimiento persistente —funciones, clases, rutas HTTP, llamadas entre módulos, dependencias y enlaces entre servicios— y luego te deja interrogarlo con herramientas tipo «quién llama a esta función».

Técnicamente se apoya en dos capas:

• Análisis sintáctico con tree-sitter, que soporta 158 lenguajes y extrae definiciones, llamadas e imports.
• Hybrid LSP, una pasada sensible a tipos para Python, TypeScript/JavaScript/JSX/TSX, PHP, C#, Go, C/C++, Java, Kotlin y Rust, que refina las aristas CALLS, USAGE y RESOLVED_CALLS con información de tipos, acercándose a lo que resolvería un «Ir a la definición» del IDE.

Todo se guarda en una base de datos SQLite local (por defecto en ~/.cache/codebase-memory-mcp/), se ejecuta 100 % en tu máquina, no envía telemetría y no necesita ninguna clave de API. El resultado es un binario estático único, sin dependencias ni Docker.

Un punto clave para no confundirse: este servidor no lleva un modelo de lenguaje dentro. Es un backend de análisis estructural. La inteligencia la pone tu cliente MCP (Claude Code, Codex, DeepSeek Harness…), que traduce tu pregunta en lenguaje natural a una consulta al grafo y te devuelve la respuesta explicada.

02 Qué puedes esperar de él

Su gran promesa es ahorrar el coste de explorar el código fichero a fichero. En lugar de decenas de ciclos de grep + read, una sola consulta al grafo te da contexto estructurado. En los benchmarks del proyecto, cinco consultas estructurales consumen ~3 400 tokens frente a ~412 000 de una búsqueda tradicional: una reducción del 99,2 %.

El servidor expone 14 herramientas MCP. Las agrupamos:

Indexado — index_repository, list_projects, delete_project, index_status. El indexado es rapidísimo: un repositorio medio se indexa en milisegundos y el kernel de Linux (28 M LOC, 75 k ficheros) en 3 minutos; Django, en unos 6 segundos. Las consultas al grafo responden en <1 ms.

Consulta — search_graph (búsqueda estructural por etiqueta/patrón), trace_path (recorrido BFS: quién llama a una función y a qué llama), detect_changes (mapea el git diff a símbolos afectados con radio de impacto y clasificación de riesgo), query_graph (consultas tipo Cypher de solo lectura), get_graph_schema, get_code_snippet, get_architecture (visión general: lenguajes, paquetes, rutas, hotspots, clústeres), search_code (búsqueda tipo grep sobre los ficheros indexados).

Inteligencias entre servicios — enlaza rutas HTTP con los puntos de llamada, detecta gRPC, GraphQL y tRPC, y reconoce canales EMITS/LISTENS_ON (Socket.IO, EventEmitter, pub-sub genérico en 8 lenguajes). También genera aristas CROSS_* entre repos indexados bajo el mismo almacén.

Decisiones de arquitectura — manage_adr guarda registros de decisiones arquitectónicas entre sesiones, y ingest_traces enriquece las aristas HTTP_CALLS con trazas reales.

Además incluye detección de código muerto (funciones sin llamadores), detección de comunidades (clústeres Louvain sobre las aristas de llamada), indexado de infraestructura (Dockerfiles, manifiestos Kubernetes y overlays Kustomize como nodos), y una UI de grafo 3D opcional en localhost:9749 para explorar el grafo a ojo.

En marcha, un watchdog en segundo plano detecta cambios (basado en git) y reindexa automáticamente, y puedes activar el indexado automático al iniciar sesión (config set auto_index true).

03 Cómo instalarlo

La instalación es repetible y no necesita Docker ni claves. Para macOS/Linux, un solo comando:

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

Si quieres la UI de visualización de grafo, añade la opción:

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

En Windows (PowerShell):

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

Opciones del instalador: --ui (UI de grafo), --skip-config (solo binario, sin tocar la configuración del agente) y --dir=<ruta> (ubicación personalizada). El comando install detecta automáticamente los agentes instalados y configura servidores MCP, ficheros de instrucciones, skills y hooks para cada uno.

También está disponible en gestores de paquetes: npm, PyPI, Homebrew, Scoop, Winget, Chocolatey y AUR, además de go install. Y puedes pedírselo a Claude Code directamente:

Instala este servidor MCP: https://github.com/DeusData/codebase-memory-mcp

Si prefieres instalación manual, descarga el archivo de la plataforma desde los releases, descomprímelo y ejecuta ./install.sh (o .\install.ps1). El script elimina la cuarentena de macOS y firma ad-hoc el binario.

Para verificar que todo va bien: reinicia el agente y comprueba con /mcp que aparece codebase-memory-mcp con sus 14 herramientas. Un test rápido por línea de órdenes: echo '{}' | ruta/al/binario debe devolver JSON.

Y recuerda, hay comandos útiles de mantenimiento: codebase-memory-mcp update (actualizar), uninstall (quitar la configuración de los agentes; no borra el binario ni las bases de datos), y config set auto_index true (indexar automáticamente).

04 Integración en Claude Code

La vía más rápida es dejar que el instalador lo haga (configura .claude/.mcp.json, añade 4 skills y un hook PreToolUse). Para una configuración manual, añade la entrada a ~/.claude/.mcp.json (global) o al .mcp.json del proyecto:

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/ruta/al/codebase-memory-mcp",
      "args": []
    }
  }
}

Reinicia el agente. Los tools aparecerán con sus nombres propios (index_repository, search_graph, trace_path, get_architecture, query_graph…). Después, dile “Indexa este proyecto” y listo.

05 Integración en Codex CLI

El instalador configura Codex automáticamente: escribe en .codex/config.toml, añade .codex/AGENTS.md y un recordatorio SessionStart. Para hacerlo a mano, añade la entrada en ~/.codex/config.toml. Ojo: en Codex la clave de nivel superior es mcp_servers (snake_case), no mcpServers, porque Codex usa TOML:

[mcp_servers.codebase-memory-mcp]
command = "/ruta/al/codebase-memory-mcp"
args = []
# opcional: startup_timeout_ms = 20_000

También puedes gestionarlo desde el CLI: codex mcp add codebase-memory-mcp -- ruta/al/binario, listarlo con codex mcp list y quitarlo con codex mcp remove codebase-memory-mcp.

06 Integración en Antigravity

Antigravity usa la configuración de estilo Gemini, compartida con Gemini CLI. El instalador escribe en .gemini/config/mcp_config.json (compartido), antigravity-cli/AGENTS.md y un recordatorio SessionStart. Para hacerlo a mano, añade la entrada a ese mcp_config.json:

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/ruta/al/codebase-memory-mcp",
      "args": []
    }
  }
}

Reinicia Antigravity y el servidor aparecerá disponible junto a sus herramientas.

07 Integración en DeepSeek Harness

DeepSeek Harness (el entorno en el que estoy ejecutándome ahora) sí soporta MCP, a través del plugin @deepseek-ai/dsh-mcp-client. Ese plugin se conecta a servidores MCP externos y registra sus herramientas en ctx.tools, de modo que el modelo las ve como herramientas nativas con nombres con espacio de servidor: mcp__<serverName>__<tool> (por ejemplo, mcp__codebase-memory__search_graph).

Cada servidor MCP es una instancia de plugin en la configuración cordis del perfil. Para el perfil web (o el que corresponda), la capa de parche se edita en cordis.patch.yml. Una entrada con stdio para codebase-memory-mcp:

- id: mcp-codebase-memory
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: codebase-memory
    transport: stdio
    command: /ruta/al/codebase-memory-mcp
    args: []

También admite transport: streamable-http con url y, opcionalmente, headers para autenticación. Hay parámetros útiles: toolCallTimeoutMs, failOnStartupError (activación rechazada si la conexión inicial falla) y un bloque reconnect con enabled, initialDelayMs, maxDelayMs y maxAttempts para reconexión con retroceso exponencial.

08 Conclusión

09 Notas y referencias