Claude Code: Memoria, MCPs y Mapa de Repo para Menos Tokens

{ "title": "Claude Code: Memoria, MCPs y Mapa de Repo para Menos Tokens", "urlSlug": "setup-claude-code-memoria-mcps-mapa-repo", "seoTitle": "Setup Claude Code: memoria, MCPs y mapa de repo (2026)", "metaDescription": "Cómo montar Claude Code con memoria operativa, MCPs y mapa del repositorio para gastar menos tokens, evitar alucinaciones y no reexplicar contexto cada sesión.", "tags": ["claude-code-setup", "claude-code-memoria", "mcp-claude-code", "repo-map", "context-engineering", "ai-agents"], "readTimeMinutes": 9, "suggestedAngleType": "authority_case_study", "contentResume": "Guía práctica para montar Claude Code con memoria persistente, MCPs y un mapa del repo que reduce tokens y alucinaciones en proyectos reales.", "contentShort": "La diferencia entre un Claude Code que acierta y uno que alucina ya no está en el prompt. Está en tres piezas que trabajan juntas: memoria operativa (lo que recuerda entre sesiones), MCPs (las herramientas a las que accede) y un mapa del repositorio (cómo entiende tu código sin leerlo entero). Montadas bien, bajan tokens, reducen errores tontos y te ahorran reexplicar el proyecto cada lunes.", "content": "\n\n

TL;DR: El setup eficiente de Claude Code ya no depende del prompt perfecto, sino de tres piezas combinadas: memoria operativa que sobrevive entre sesiones, MCPs para acceder a herramientas externas sin copiar-pegar, y un mapa del repositorio que permite razonar sobre el código sin cargarlo entero. Juntas, bajan el consumo de tokens, reducen alucinaciones y eliminan la necesidad de reexplicar el proyecto cada sesión.

\n\n

El problema: reexplicar el proyecto cada lunes

\n\n

Llevo meses usando Claude Code en proyectos reales y el patrón se repite. Lunes por la mañana, abres el repo, lanzas Claude y empiezas a pegar contexto: qué hace el módulo, qué decidiste la semana pasada, dónde vive la lógica de negocio. Quince minutos después, la sesión está calentita y el token count ya se ha comido medio presupuesto del día.

\n\n

El problema no es el modelo. Es el setup. Cuando tratas Claude Code como un chat, cada sesión empieza de cero. Cuando lo tratas como infraestructura, el contexto se recupera solo. La diferencia entre ambos modos se mide en euros al mes y en bugs que no deberían existir.

\n\n

Los datos de comunidad son claros: los usuarios avanzados están dejando de pulir prompts para construir sistemas que combinan memoria, herramientas externas y representaciones del código. No es hype, es ingeniería de contexto.

\n\n

¿Qué es la memoria operativa en Claude Code?

\n\n

La memoria operativa es todo lo que Claude Code puede recuperar entre sesiones sin que se lo pegues tú. Incluye decisiones de arquitectura, convenciones de código, bugs resueltos y gotchas del proyecto. A diferencia del CLAUDE.md, que se carga siempre entero, la memoria operativa se consulta bajo demanda.

\n\n

En la práctica se materializa en plugins como claude-mem o engram, que capturan observaciones durante la sesión, las almacenan en SQLite con búsqueda FTS5, y las inyectan cuando son relevantes. El punto clave: menos contexto pegado a mano, más contexto recuperable.

\n\n

Si quieres profundizar en la parte de CLAUDE.md vs memoria persistente, escribí antes sobre plugins de memoria en Claude Code que salvan sesiones.

\n\n

¿Qué aporta un MCP bien configurado?

\n\n

Un Model Context Protocol (MCP) es un servidor que expone herramientas a Claude Code mediante un estándar abierto. En vez de copiar credenciales de Postgres al chat, configuras un MCP de base de datos y Claude consulta directamente. En vez de pegar issues de GitHub, el MCP de GitHub las lee.

\n\n

El error común es acumular MCPs pensando que más es mejor. No lo es. Cada MCP añadido carga definiciones de herramientas en cada turno, y eso se traduce en tokens fijos que pagas sin usar. La regla que aplico: solo MCPs que uso al menos una vez a la semana.

\n\n

Si te interesa el coste real de los MCPs, ya lo desgloso en MCP en Claude Code y los 18.000 tokens ocultos por turno.

\n\n

¿Qué es un mapa del repositorio?

\n\n

Un mapa del repositorio es una representación compacta de tu código que Claude puede consultar sin leer cada archivo. Puede ser un grafo de conocimiento (funciones, clases, dependencias), un árbol de símbolos extraído con tree-sitter o un índice vectorial de chunks relevantes.

\n\n

La pieza que cambia el juego: skills como /graphify construyen un grafo del codebase que reduce tokens hasta 71 veces comparado con cargar archivos enteros. Cuando Claude pregunta \"¿dónde se usa esta función?\", no escanea el proyecto. Consulta el grafo.

\n\n

Esto conecta con el principio de separación de responsabilidades: un repo con módulos bien definidos genera un mapa más útil que uno con archivos de 2.000 líneas mezclando todo.

\n\n

Implementación paso a paso

\n\n

Este es el orden que sigo cuando configuro un proyecto nuevo. No es la única forma, pero es la que menos fricción me ha dado en los últimos tres meses.

\n\n

1. Instalar un plugin de memoria persistente

\n\n

El objetivo: que Claude recuerde decisiones entre sesiones sin que tengas que reexplicarlas.

\n\n

# Instala un plugin de memoria que capture observaciones durante la sesion\nnpm install -g claude-mem\nclaude-mem init --project mi-proyecto

\n\n

Después de instalarlo, pide a Claude que guarde decisiones explícitamente: \"Guarda que la autenticación usa JWT con refresh tokens en Redis\". La próxima sesión lo recuperará al detectar keywords como \"auth\" o \"login\".

\n\n

2. Configurar MCPs mínimos viables

\n\n

Empieza con dos: filesystem (para operaciones de archivo nativas) y uno específico del stack (GitHub si trabajas con issues, Postgres si tocas la base, etc).

\n\n

{\n  \"mcpServers\": {\n    \"filesystem\": { \"command\": \"mcp-filesystem\", \"args\": [\"./src\"] },\n    \"github\": { \"command\": \"mcp-github\", \"env\": { \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\" } }\n  }\n}

\n\n

Revisa los tokens que consume cada MCP con claude --mcp-debug. Si uno pasa de 3.000 tokens por turno y lo usas una vez al mes, fuera.

\n\n

3. Generar el mapa del repositorio

\n\n

Instala una skill o herramienta que construya un grafo del código. El formato típico es JSON con nodos (funciones, clases, archivos) y aristas (imports, llamadas).

\n\n

# Genera un mapa compacto del codebase que Claude consulta bajo demanda\nclaude skill install graphify\nclaude /graphify --output .claude/repo-map.json

\n\n

Regenera el mapa cuando haya cambios estructurales, no en cada commit. Un cron semanal o un hook de CI suele ser suficiente.

\n\n

Comparativa: setup mínimo vs setup completo

\n\n\n\n\n\n\n\n\n\n\n

Aspecto	Setup mínimo (solo CLAUDE.md)	Setup completo (3 piezas)
Tokens por sesión media	15.000-25.000	4.000-8.000
Tiempo de setup inicial	10 minutos	45 minutos
Recuperación de contexto entre sesiones	Manual	Automática
Alucinación en refactors grandes	Alta	Media-baja
Coste mensual estimado	30-50€	15-25€

\n\n

Los números son aproximados y dependen del tamaño del proyecto. En un repo pequeño (menos de 50 archivos) el setup completo es overkill. A partir de proyectos medianos (200+ archivos), la diferencia es brutal.

\n\n

Aplicación práctica: un caso real

\n\n

En un proyecto de RAG con FastAPI y Pinecone, el CLAUDE.md había crecido hasta 800 líneas. Cada sesión cargaba la descripción completa de la arquitectura, las convenciones y los endpoints. Resultado: 20k tokens de contexto antes de escribir una línea de código.

\n\n

Tras migrar a memoria operativa + MCP de Pinecone + mapa del repo, el CLAUDE.md quedó en 80 líneas (solo lo crítico). Las convenciones viven en memoria, los detalles de Pinecone los consulta el MCP, y la estructura del código está en el grafo. Tokens medios por sesión: 6k. Coste mensual: a la mitad.

\n\n

El patrón se parece mucho al que describo en procesamiento de PDFs para IA con chunking: no cargas todo, cargas lo que necesitas cuando lo necesitas.

\n\n

En Producción

\n\n

Lo que funciona en un proyecto personal puede romperse en equipo. Estas son las consideraciones que más dolor me han ahorrado.

\n\n

Rendimiento: el mapa del repo regenerado en cada commit puede tardar minutos en repos grandes. Usa un scheduler o genera solo al detectar cambios en la estructura (nuevos archivos, cambios de imports), no en cambios de línea.

\n\n

Manejo de errores: si un MCP cae, Claude Code sigue funcionando pero sin esa herramienta. Configura timeouts agresivos (10-15 segundos) para que un MCP lento no bloquee la sesión entera.

\n\n

Costes: el ahorro viene del mapa del repo y la memoria selectiva, no de los MCPs. Cada MCP añadido es coste fijo por turno. Mide antes de añadir, no después.

\n\n

Escalabilidad en equipo: la memoria operativa es personal por defecto. Si trabajas en equipo, plantea qué comparte el proyecto (convenciones, decisiones de arquitectura) vs qué es individual (atajos de trabajo, notas personales). El CLAUDE.md versionado sigue siendo útil para lo compartido.

\n\n

Errores comunes y depuración

\n\n

Error: Claude ignora la memoria guardada. Causa: el plugin no está activo en la sesión o las keywords no coinciden. Solución: verifica con mem_search que la observación existe, y usa títulos descriptivos al guardar.

\n\n

Error: tokens por turno disparados tras añadir MCPs. Causa: cada MCP carga sus tool definitions en cada turno. Solución: elimina los que no usas o cambia a configuraciones con carga perezosa si el cliente lo soporta.

\n\n

Error: el mapa del repo da información desactualizada. Causa: no se regeneró tras refactor grande. Solución: añade un hook post-merge o regenera manualmente tras cambios estructurales. Si esto ocurre seguido, revisa el harness unificado con patrones multi-agente para orquestar la regeneración automática.

\n\n

Preguntas frecuentes

\n\n

¿Necesito las tres piezas desde el primer día?

\n

No. Empieza por la memoria operativa, que es la que más fricción elimina. Añade MCPs cuando tengas una herramienta externa que uses a diario. El mapa del repo solo merece la pena en proyectos medianos o grandes.

\n\n

¿La memoria operativa funciona entre equipos o es personal?

\n

Por defecto es personal y vive en tu máquina. Algunos plugins permiten sincronizar observaciones de proyecto mediante Git o un backend compartido. Para decisiones de arquitectura que todo el equipo necesita, CLAUDE.md versionado sigue siendo la opción más simple.

\n\n

¿Qué pasa si cambio de Claude Code a otro agente?

\n

El CLAUDE.md es portable (Codex CLI y Cursor lo leen). Las memorias guardadas en plugins específicos no lo son, aunque estándares como Engram empiezan a funcionar cross-harness. El mapa del repo, al ser JSON, se puede reutilizar casi siempre.

\n\n

Cierre

\n\n

La diferencia entre un Claude Code que cuesta 50€ al mes y alucina, y uno que cuesta 20€ y acierta, rara vez está en el prompt. Está en cómo combinas memoria, herramientas y representación del código para que el modelo trabaje con menos ruido. Si hasta ahora has tratado Claude Code como un chat, el salto a tratarlo como infraestructura es el cambio que más ROI da en 2026.

\n\n

¿Has montado algún setup similar o tienes otra combinación que te funcione mejor? Cuéntamelo en Twitter @sergiomarquezp_. En el próximo post entraré en cómo auditar qué parte del contexto está aportando valor real y qué puedes recortar sin perder calidad.

", "faqQA": [ { "q": "¿Necesito las tres piezas (memoria, MCPs, mapa del repo) desde el primer día?", "a": "No. Empieza por la memoria operativa, que elimina más fricción. Añade MCPs cuando tengas una herramienta externa que uses a diario. El mapa del repo solo merece la pena en proyectos medianos o grandes (200+ archivos)." }, { "q": "¿La memoria operativa de Claude Code funciona entre equipos o es personal?", "a": "Por defecto es personal y vive en tu máquina. Algunos plugins permiten sincronizar observaciones de proyecto mediante Git. Para decisiones que todo el equipo necesita, CLAUDE.md versionado sigue siendo la opción más simple." }, { "q": "¿Qué pasa con este setup si cambio de Claude Code a otro agente?", "a": "El CLAUDE.md es portable (Codex CLI y Cursor lo leen). Las memorias guardadas en plugins específicos no siempre lo son. El mapa del repositorio, al ser JSON, se puede reutilizar en la mayoría de casos." } ] }