Memoria en Claude Code: tres capas, qué muere y qué persiste

Clasificar la memoria de Claude Code por dónde vive cada dato (¿es un archivo que escribe una persona, un servidor MCP, un plugin?) deja de funcionar en cuanto aparece Auto Memory: técnicamente también es un archivo (MEMORY.md y archivos de tema), pero nadie lo escribe a mano y no sigue las reglas de CLAUDE.md. El eje que sí aguanta el cambio no es solo cuánto dura la información, porque reglas estables y memoria persistente duran meses las dos: es quién escribe cada pieza, para qué sirve y quién gobierna cuándo se corrige o se descarta.

Con ese eje, la memoria se organiza en tres capas. La capa que acumula conocimiento entre sesiones tiene hoy dos implementaciones distintas y complementarias, y confundirla con la capa de reglas (o confundir esas dos implementaciones entre sí) es la fuente más común de configuraciones redundantes o contradictorias.

El modelo: autoría, propósito y gobernanza, no solo duración

Mezclar capas (meter una decisión puntual en CLAUDE.md, o tratar el estado de una tarea en curso como si fuera conocimiento acumulado) es lo que produce un archivo de reglas de 400 líneas o una base de memoria que contradice al agente seis meses después.

Esa última distinción importa porque "efímero" no significa "sin rastro": Claude Code guarda el transcript de cada sesión localmente y lo puede rehidratar por completo con /resume o --continue, incluidos historial de herramientas y resultados. Lo que muere de verdad al cerrar es el contexto activo si nadie lo comprime a capa 2 antes de hacerlo; la sesión registrada persiste en disco y puede reabrirse, pero reabrir una sesión entera para recuperar un solo dato es justo el coste que la capa 2 existe para evitar. Cómo gestiona Claude Code esa ventana activa en detalle (compactación, cambios de modelo de contexto) es un tema propio; ver el cambio de modelo de contexto en Claude Code.

La pregunta que separa capa 1 de capa 2 es simple: si hay que justificar la afirmación con una historia (en la migración del martes decidimos X porque Y), es una decisión y va a memoria persistente, no a CLAUDE.md. Si es una afirmación que se sostiene sola (Python 3.12, sin ORM), es una regla estable.

Por qué la capa persistente tiene dos implementaciones, no una

La capa persistente que acaba de aparecer en la tabla no corresponde a un solo mecanismo, y ninguna de sus dos implementaciones es CLAUDE.md: eso vive en capa 1, y su papel aquí es dictar el protocolo, no acumular el conocimiento. Según la documentación oficial de Claude Code sobre memoria, el agente acumula ese conocimiento con Auto Memory, que Claude rellena solo a partir de correcciones y preferencias observadas sin que nadie lo instale, o con un servidor MCP externo como Engram, que hay que instalar y registrar aparte. Ninguno de los dos sustituye al otro; cada uno resuelve una necesidad distinta dentro de la misma capa.

• Auto Memory nativo: viene activado por defecto, no requiere instalar nada, y el propio agente decide qué vale la pena anotar. La contrapartida es que no hay búsqueda estructurada por tema ni control fino sobre el criterio de guardado: es Claude quien decide, no un protocolo que el equipo defina.
• MCP externo (Engram): exige instalar un binario y registrar el servidor, pero a cambio expone herramientas de búsqueda explícitas (mem_search, mem_context) y funciona igual en cualquier cliente MCP, no solo en Claude Code. La contrapartida simétrica: si CLAUDE.md no le dice al agente cuándo guardar y cuándo buscar, las herramientas quedan sin usar.

No son alternativas excluyentes. Un proyecto personal puede vivir bien solo con Auto Memory; un repo trabajado desde varios agentes (Claude Code y Codex sobre el mismo código, por ejemplo) necesita la capa MCP porque es la única que no depende de qué CLI abriste hoy.

Setup nativo: Auto Memory sin instalar nada

Auto Memory carga solo las primeras 200 líneas o 25KB de MEMORY.md (lo que se alcance antes) al inicio de cada sesión; el resto queda fuera hasta que Claude lo mueve a un archivo de tema aparte que se lee bajo demanda. Esta es la mecánica exacta según la documentación oficial:

• Vive en ~/.claude/projects/<project>/memory/, una carpeta por repositorio git, compartida entre todos los worktrees de ese repo.
• MEMORY.md actúa como índice; archivos de tema como debugging.md o api-conventions.md no se cargan al arrancar, Claude los lee con sus herramientas normales cuando hacen falta.
• Para inspeccionar o editar lo guardado, el comando /memory abre el índice y la carpeta completa; para confirmar qué se cargó realmente en la sesión activa, /context.
• Se desactiva desde el toggle de /memory, con autoMemoryEnabled: false en el settings.json del proyecto, o globalmente con la variable de entorno CLAUDE_CODE_DISABLE_AUTO_MEMORY.

Auto Memory solo basta cuando el trabajo es de una persona sobre un único agente y no hace falta recuperar una decisión concreta con una búsqueda precisa. En cuanto se necesita esa precisión, o el mismo repo lo tocan varios CLIs, hace falta la segunda pieza.

Setup MCP: Engram paso a paso

Esa segunda pieza es Engram, y conviene aclarar primero qué es realmente frente a lo que se afirmaba en versiones anteriores de este artículo: un binario en Go con SQLite y FTS5 para búsqueda de texto completo, sin dependencias de Python, Node ni Docker, que expone memoria persistente por MCP vía stdio a cualquier cliente compatible (Claude Code, Codex, Gemini CLI, Cursor). No se instala con pip ni exige un intérprete de Python concreto, como se decía antes.

Pasos verificados en la documentación de setup para Claude Code:

# 1. Instalar el binario (macOS/Homebrew; hay binarios para Linux y Windows)
brew install gentleman-programming/tap/engram

# 2. Registrar el plugin: instala el servidor MCP, hooks y el skill de memoria de una vez
claude plugin marketplace add Gentleman-Programming/engram
claude plugin install engram

La alternativa sin plugin, registrando solo el servidor MCP, va en .mcp.json en la raíz del proyecto si quieres compartirlo con el equipo por control de versiones (ese es el formato oficial de Claude Code para MCP de proyecto; settings.json es para permisos, hooks, variables de entorno y modelos, no para servidores MCP):

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp"]
    }
  }
}

Para uso solo personal en ese repo, el equivalente es claude mcp add --scope local engram -- engram mcp (o --scope user para tenerlo disponible en todos tus proyectos); ambos casos se guardan en ~/.claude.json, no en .mcp.json ni en settings.json.

Al abrir sesión deberían aparecer las herramientas mem_save, mem_search, mem_context y mem_session_summary. Cuántas más depende de cómo lo instalaste: 15 si entraste por el plugin (perfil agent, pensado para uso conversacional) o 19 si registraste el servidor a mano sin plugin (el set completo por defecto, con utilidades de administración adicionales). Sin un protocolo explícito en CLAUDE.md, el agente no las usa por iniciativa propia:

## Engram Memory
- Guarda con mem_save tras: bugfix con causa raíz, decisión de arquitectura, descubrimiento, convención nueva.
- Busca con mem_search de forma reactiva ("acordate", "qué hicimos") y proactiva si la tarea actual se solapa con trabajo previo.
- mem_session_summary es obligatorio antes de cerrar sesión.

La prueba de ida y vuelta sigue siendo la validación real: tomar una decisión técnica, guardarla con mem_save, cerrar sesión, y al día siguiente preguntar por ella sin dar contexto adicional. El agente debe resolverlo con mem_search o mem_context, no reconstruyendo la respuesta desde cero.

Qué no persistir jamás: por qué el vertedero degrada al agente

La pregunta operativa antes de guardar cualquier cosa es una sola: ¿esto cambiaría la próxima respuesta del agente? Si la respuesta es no, no se guarda, sin excepción por si acaso.

• Sí merece persistir: una decisión de arquitectura con la alternativa descartada y el motivo; un bug con causa raíz ya identificada; una restricción de entorno descubierta a la fuerza (PM2 corre como usuario ubuntu, nunca con sudo); una preferencia que se validó tras un conflicto explícito entre dos formas de hacer algo.
• No merece persistir: el resumen de qué archivos se tocaron (ya está en git log); los pasos de debugging que llevaron al fix (ya están en el commit o el PR); el estado temporal de una tarea todavía en curso, que pertenece al contexto activo y no debe adelantarse a la capa persistente antes de que la tarea cierre.
• Transcripción indiscriminada frente a resumen operativo: volcar la conversación turno por turno no merece persistir. El resumen estructurado que guarda mem_session_summary al cerrar sesión (objetivo, trabajo hecho, próximos pasos, archivos tocados) sí, porque es exactamente la compresión de contexto activo a capa persistente que el protocolo de cierre exige, no una transcripción sin filtrar.

Esta disciplina no es una preferencia editorial aislada: es una decisión de diseño que el propio ecosistema de herramientas de memoria discute abiertamente. claude-mem, la alternativa más establecida a Engram, resuelve la captura con cinco hooks de ciclo de sesión que registran prácticamente todo y lo comprimen después con un modelo aparte. Engram declara explícitamente que evita ese camino: la compresión posterior añade llamadas extra a un modelo (coste y latencia), y las herramientas sin comprimir contaminan la búsqueda hasta que el proceso de compresión las alcanza. La alternativa de Engram es guardar de forma selectiva, en el momento de la decisión, según el protocolo que el propio CLAUDE.md define.

Ninguna herramienta resuelve el criterio por ti. Capturar todo y comprimir después traslada el juicio editorial a un post-proceso automático que no conoce el contexto real de la decisión; guardar selectivo por protocolo lo deja donde debería estar, en la cabeza de quien (o del agente que) toma la decisión en el instante en que ocurre. El protocolo de cierre de sesión es el mismo en cualquier caso: comprimir el contexto activo en una o dos entradas de capa persistente (con mem_session_summary o editando MEMORY.md a mano) y dejar que el resto se pierda. No hay vertedero neutral: cada entrada guardada por si acaso compite por atención con las que sí importan la próxima vez que alguien busque.