Saltar al contenido principal

codebase-memory-mcp

Estándar de Wiedii para inteligencia de código con agentes de IA (decisión 2026-07-15) — reemplaza a graphify, que queda deprecado.

Servidor MCP local de inteligencia de código para agentes de IA. Construye un grafo de conocimiento SQLite por repositorio usando tree-sitter (análisis AST determinista) y embeddings locales nomic-embed-code. Todo corre localmente — sin API keys, sin telemetría, sin llamadas a la nube.

Qué expone​

14 herramientas MCP siempre disponibles (sin invocación explícita de skill):

HerramientaPropósito
index_repositoryIndexar un repo manualmente
search_graphBúsqueda estructural (regex, filtros, scoping)
semantic_queryBúsqueda vectorial semántica
search_codeGrep augmentado por grafo
trace_pathTrazar el camino entre dos símbolos
get_architectureVista arquitectónica de un módulo
detect_changesDetectar qué cambió desde el último índice
query_graphConsultas Cypher sobre el grafo
manage_adrGestión de Architecture Decision Records
+ 5 máslist_projects, delete_project, index_status, get_graph_schema, get_code_snippet, ingest_traces

Por qué se eligió sobre graphify​

graphify requiere una invocación explícita (/graphify) y genera artefactos en graphify-out/ dentro del repo. codebase-memory-mcp expone sus capacidades como servidor MCP siempre activo y almacena los índices fuera del repo (~/.cache/codebase-memory-mcp/), lo que simplifica el flujo y evita ruido en el workspace.

Diferencias clave:

Aspectographifycodebase-memory-mcp
Invocaciónskill /graphify explícito14 herramientas MCP siempre disponibles
Almacenamiento del índicegraphify-out/ en el repo~/.cache/codebase-memory-mcp/ (fuera del repo)
Motor semánticoClaude API (subagentes)Embeddings locales nomic-embed-code — sin API calls
Package manageruv tool install graphifyy (PyPI)brew tap + brew install (Homebrew)
Lenguajes20 vía tree-sitter + LLM para docs158 vía tree-sitter (parseo determinístico)
Scope MCPskill opcional por proyectoservidor MCP global (--scope user)

Instalación (Homebrew — verificado)​

El proyecto ofrece una fórmula Homebrew en el repo principal. Es un tap de terceros, así que la instalación requiere agregar el tap y confiar la fórmula antes de instalar (Homebrew 6.0+ Tap Trust — ver gestion-herramientas-brew-mise):

# 1. Agregar el tap
brew tap DeusData/codebase-memory-mcp https://github.com/DeusData/codebase-memory-mcp

# 2. Confiar la fórmula (Tap Trust — taps no oficiales lo exigen desde Homebrew 6.0)
brew trust --formula DeusData/codebase-memory-mcp/codebase-memory-mcp

# 3. Instalar
brew install codebase-memory-mcp

# 4. Auto-configurar Claude Code (--scope user → global, todos los proyectos)
codebase-memory-mcp install

# Actualizaciones futuras
brew upgrade codebase-memory-mcp

Limitación conocida del tap: el tap clona el repo completo (~1.5GB de fuentes C + grammars vendorizados) porque el proyecto no tiene un repo dedicado homebrew-codebase-memory-mcp. Funciona correctamente, pero el brew tap es más pesado de lo ideal. Verificar si crean un tap dedicado en versiones futuras.

Registro MCP global en Claude Code​

codebase-memory-mcp install detecta Claude Code automáticamente y registra el servidor con --scope user, disponible en todos los proyectos sin configuración adicional por repo. El binario queda en /opt/homebrew/bin/codebase-memory-mcp (macOS ARM64).

Para verificar:

claude mcp list
# → codebase-memory  /opt/homebrew/bin/codebase-memory-mcp  user

Indexado por proyecto​

El servidor es global; los índices son por repositorio, almacenados en ~/.cache/codebase-memory-mcp/.

# Indexar manualmente el repo actual
codebase-memory-mcp cli index_repository '{"repo_path": "/ruta/al/repo"}'

# O habilitar auto-indexado al conectar un agente
codebase-memory-mcp config set auto_index true

Variables de entorno opcionales​

VariablePor defectoPropósito
CBM_CACHE_DIR~/.cache/codebase-memory-mcpDónde viven los índices SQLite
CBM_LOG_LEVELinfodebug / info / warn / error / none
CBM_WORKERSautoWorkers paralelos para indexado

Flujo de trabajo: crear → actualizar → usar​

PasoCómo
Crearindex_repository (mode full, una vez) — o cli index_repository. Extracción determinista (tree-sitter/LSP), sin LLM.
Actualizardetect_changes (ve el drift vía git-diff, instantáneo, sin LLM) → index_repository mode fast para aplicar solo lo que cambió.
Usarsearch_graph (BM25 + semántico + regex), trace_path (callers/callees/data-flow), get_code_snippet, query_graph (Cypher), get_architecture (clusters Leiden).

Regla operativa: al empezar a trabajar un repo, index_status; si falta o está stale, index_repository (full la primera vez, fast después) antes de explorar. Tras un chunk de trabajo, re-indexar fast o detect_changes para que el grafo no derive.

Actualización automática en cada commit (lefthook)​

El grafo debe mantenerse al día con el código. El binario tiene modo CLI (codebase-memory-mcp cli <tool> [json]), pensado para un hook post-commit:

# Job post-commit en lefthook.yaml del proyecto (o en wiedii-configs/lefthook/base.yaml si es infra compartida)
codebase-memory-mcp cli index_repository '{"repo_path":".","mode":"fast"}'

A diferencia de graphify (que llamaba a un LLM en cada commit), esta actualización es determinista (tree-sitter/LSP) y sin costo de tokens.

El job codebase-memory-update ya vive en wiedii-configs/lefthook/base.yaml (reemplazo de graphify-update, release 0.3.0) - cualquier repo con el remote de wiedii-configs en su lefthook.yaml lo recibe automaticamente. repo_path va siempre absoluto (con pwd); pasar un punto registra un proyecto separado y bogus en vez de coincidir con el real.

Referencias​