Memoria en Claude Code: las 3 capas que evitan el vertedero

TL;DR: La memoria útil en Claude Code no consiste en guardar todo lo que ocurre, sino en separar tres capas (decisiones duraderas, reglas estables y contexto efímero) y descartar activamente lo que no cambia la siguiente respuesta. Si lo haces bien, retomas trabajo al día siguiente sin reexplicar el repo ni arrastrar una conversación infinita.

El problema: tu memoria es un trastero, no una biblioteca

Llevo meses observando un patrón en sesiones largas con Claude Code: el agente empieza fino, toma buenas decisiones, y a las 3 horas responde con respuestas más genéricas, repite preguntas que ya tenían respuesta y olvida convenciones que dejaste claras al principio. La reacción habitual es guardar más cosas (todo el historial, todos los archivos tocados, todos los resúmenes). El resultado: peor todavía.

El problema no es que falte memoria. Es que no toda la información tiene el mismo valor operativo. Guardar el contenido entero de cada sesión es como guardar todas las notas adhesivas que has escrito en tu vida: técnicamente tienes la información, pero recuperarla cuesta más que volver a generarla.

El enfoque que mejor me ha funcionado, y que coincide con lo que están empujando los harnesses serios en 2026, es tratar la memoria como un sistema de tres capas con políticas distintas de escritura y recuperación.

Las tres capas de memoria operativa

No son arbitrarias. Cada una responde a una pregunta diferente y vive en un sitio distinto.

Capa	Qué guarda	Vida útil	Dónde vive
Reglas estables	Convenciones, stack, no-hacer	Meses	CLAUDE.md, hooks
Memoria persistente	Decisiones, bugs resueltos, descubrimientos	Semanas-meses	Plugin de memoria (Engram, claude-mem)
Contexto efímero	Estado de la tarea actual	Una sesión	Ventana de contexto

La clave: cada capa tiene una política de descarte distinta. La capa efímera muere al cerrar la sesión y no pasa nada. La persistente se poda cuando algo deja de ser cierto. Las reglas solo cambian cuando el equipo decide explícitamente cambiarlas.

Capa 1: reglas estables

Aquí va lo que siempre es cierto en tu proyecto: lenguaje, framework, convenciones de naming, qué herramientas usar (rg en vez de grep, fd en vez de find), qué nunca hacer sin confirmación. Esta capa tiene que ser corta, declarativa y leerse al principio de cada sesión. Si crece más allá de 200 líneas, ya no es regla estable, es novela.

Una regla estable se justifica por sí sola, sin contexto. Ejemplo válido: "Conventional commits format only". Ejemplo inválido: "En la migración del lunes decidimos usar X porque Y discutió con Z". Eso último pertenece a la capa 2.

Si trabajas con varios proyectos, esta capa se complementa muy bien con un archivo de configuración bien pensado para coding agents, donde el peso real está en la configuración, no en el modelo elegido.

Capa 2: memoria persistente (decisiones y descubrimientos)

Esta es la capa que la mayoría infla mal. La pregunta correcta no es "¿qué pasó?" sino "¿qué cambiaría mi siguiente respuesta saber esto?". Si la respuesta es "nada", no lo guardes.

Lo que sí merece persistir:

• Decisiones de arquitectura: por qué se descartó una opción (no solo cuál se eligió).
• Bugs resueltos con causa raíz: el síntoma se olvida, la causa raíz evita repetir el error.
• Restricciones del entorno: "PM2 corre como ubuntu, nunca sudo", "este endpoint tiene rate limit de 10 req/s".
• Preferencias del usuario validadas en conflicto: "prefiero patches mínimos, no refactor preventivo".

Lo que no merece persistir y mucha gente guarda igualmente: resúmenes de qué archivos se tocaron (eso está en git log), pasos de debugging que terminaron en el fix (el fix está en el código), listas de comandos ejecutados, transcripciones de la conversación.

Capa 3: contexto efímero

Es la ventana de contexto activa: archivos abiertos, salida de tests reciente, el plan de la tarea actual. Esta capa muere y debe morir al cerrar la sesión. Intentar persistirla entera es lo que convierte la memoria en vertedero.

La regla operativa: al terminar una tarea, antes de cerrar, comprime la capa 3 en una o dos entradas para la capa 2 (decisiones tomadas, bugs encontrados) y deja morir el resto. Si tu plugin de memoria captura automáticamente toda la sesión, configúralo para que pase por un filtro de relevancia antes de escribir.

Implementación práctica en 4 pasos

Voy a aterrizarlo en un flujo concreto que uso a diario. Asume Claude Code con un plugin de memoria tipo Engram, pero el patrón es portable a Codex, OpenClaw o Gemini CLI.

Paso 1: define tu CLAUDE.md como contrato, no como diario

Una sección por tipo de regla, máximo 2-3 frases por sección. Si necesitas justificar mucho una regla, probablemente no es regla, es decisión (capa 2).

## Rules
- NEVER add Co-Authored-By to commits
- Use rg/fd/bat, never grep/find/cat
- No auto-commit without explicit confirmation

## Stack
- Python 3.12, FastAPI, Pydantic v2
- Postgres 16, no ORM (raw SQL via asyncpg)

Paso 2: protocolo de guardado proactivo

Configura el agente para que llame al plugin de memoria inmediatamente después de eventos disparadores: decisión tomada, bug arreglado con causa raíz identificada, convención nueva acordada. No esperes al final de la sesión, porque para entonces el contexto ya se ha diluido.

El formato que mejor recupera después es este:

# Plantilla mínima para una entrada de memoria útil
title: "Migración auth: descartado JWT por sesiones server-side"
type: decision
content: |
  What: Se eligió sesiones en Redis sobre JWT.
  Why: Necesidad de revocación inmediata (compliance).
  Where: módulo auth/, ADR-007.
  Learned: JWT funciona si no necesitas revocación rápida.

Ese campo "Why" es lo que hace que la entrada sirva dentro de 3 meses cuando alguien pregunte por qué no se usó JWT. Si te interesa el patrón general detrás de este tipo de decisiones de seguridad, escribí sobre cuándo JWT sí encaja en Spring Boot.

Paso 3: recuperación selectiva, no historial completo

Cuando empiezas una sesión nueva, lo que no quieres es que el agente cargue las últimas 10 sesiones enteras en contexto. Lo que quieres es búsqueda semántica sobre la capa 2 con las keywords de la tarea actual.

En la práctica: al abrir una tarea de "añadir endpoint de pagos", el agente busca en memoria persistente términos como "pagos", "stripe", "webhook" y trae solo las 3-5 entradas más relevantes. Si no hay nada relevante, no inyecta nada. Esto reduce el contexto inicial de ~15k tokens (cargar todo) a ~2k tokens (solo lo que aplica).

Paso 4: poda activa

Una memoria que solo crece se vuelve ruido. Revisa la capa 2 cada 2-4 semanas y borra entradas que ya no son ciertas. Una entrada de tipo decisión queda obsoleta si la decisión cambió. Una entrada de bugfix queda obsoleta si el módulo donde vivía fue reescrito.

Esto no es opcional: sin poda, en 6 meses tu sistema de memoria devuelve resultados contradictorios y el agente empieza a tomar decisiones basadas en restricciones que ya no existen.

En Producción

Los detalles que cambian entre el tutorial y el uso real:

• Coste de tokens: cargar todo el historial en cada sesión te puede salir entre 20€ y 60€ al mes extra en API de Opus, solo por contexto que el modelo nunca usa. La recuperación selectiva lo baja a un par de euros.
• Latencia: cada 10k tokens extra en contexto añaden entre 1 y 3 segundos de tiempo hasta la primera respuesta. Multiplica eso por 50 mensajes al día y notas la diferencia.
• Privacidad: la capa 2 va a almacenamiento persistente (local o cloud). No guardes ahí secretos, tokens, ni fragmentos de código propietario sensible. Si tu plugin va a un servicio gestionado, revisa qué se envía.
• Múltiples proyectos: separa los namespaces de memoria por proyecto. Una decisión válida en el proyecto A puede ser exactamente lo contrario en el proyecto B.
• Equipo: si varios desarrolladores comparten configuración, la capa 1 (CLAUDE.md) va al repo. La capa 2 es personal por defecto, aunque algunos equipos comparten un subconjunto de decisiones (ADRs) en un repo común.

Una práctica que aprendí a las malas: versiona tu CLAUDE.md. Cuando una regla cambia, el commit cuenta el porqué. Si lo tratas como código (lo es), evitas que alguien borre una regla crítica sin contexto. Esto se conecta directo con el principio de separación de responsabilidades: cada capa de memoria responde a una pregunta distinta y se gestiona con un proceso distinto.

Errores Comunes y Depuración

Error: El agente repite preguntas que ya tenían respuesta en sesiones anteriores.
Causa: La memoria persistente existe pero la búsqueda no encuentra la entrada relevante. Suele ser problema de keywords pobres o de que la entrada se guardó sin el campo "Why".
Solución: Revisa las últimas 10 entradas de memoria. Si tienen títulos genéricos ("reunión", "fix bug"), reescríbelas con títulos descriptivos que incluyan el dominio.

Error: El contexto inicial de cada sesión supera los 10k tokens sin haber hecho nada.
Causa: El plugin de memoria está inyectando todo, sin filtro de relevancia.
Solución: Configura un límite duro (top-5 entradas, máximo 2k tokens) en la inyección automática. Permite búsqueda manual para el resto.

Error: El agente toma decisiones basadas en restricciones que ya no existen.
Causa: Falta de poda. Decisiones antiguas se recuperan como si fueran actuales.
Solución: Añade campo de fecha a cada entrada y filtra por antigüedad en la búsqueda. Programa una revisión mensual de la capa 2.

Error: CLAUDE.md creció hasta 600 líneas y el agente lo ignora.
Causa: Pusiste decisiones en la capa de reglas. Las decisiones envejecen, las reglas no.
Solución: Mueve toda decisión contextual a la capa 2. Deja en CLAUDE.md solo afirmaciones permanentes sobre el proyecto.

Preguntas Frecuentes

¿Qué plugin de memoria uso para la capa 2?

En 2026 los más maduros son Engram (mejor para sesiones técnicas con search semántico) y claude-mem (más simple, captura pasiva). Si empiezas, prueba uno durante dos semanas y mide cuántas veces la recuperación te ahorra trabajo real. Si la respuesta es "casi nunca", probablemente el problema está en cómo escribes las entradas, no en el plugin.

¿Debo guardar el contenido de los archivos que tocó el agente?

No. Los archivos están en el repo y git log ya tiene el historial. Guardar copias en memoria duplica fuente de verdad y crea inconsistencias en cuanto el código cambie. Guarda solo la decisión detrás del cambio, no el cambio en sí.

¿Cómo migro si ya tengo meses de memoria desordenada?

No la migres entera. Filtra por las últimas 4-8 semanas, revisa entrada por entrada y conserva solo lo que pase el test "¿esto cambiaría una decisión futura?". Lo demás, archívalo o bórralo. En mi experiencia, queda menos del 20% del volumen original, y el sistema funciona mejor.

Cierre

La memoria útil en Claude Code no es un problema de almacenamiento, es un problema de criterio editorial. Separar reglas, decisiones y contexto efímero te da tres palancas distintas con políticas distintas, y eso es lo que diferencia retomar una tarea al día siguiente en dos minutos de pasar veinte reexplicando el repo.

Lo más difícil no es montar el sistema, es la disciplina de descartar. Cada entrada que guardas "por si acaso" empeora la recuperación de las entradas que sí importan. Si tu primera reacción al ver un bug interesante es "esto hay que guardarlo", pregúntate primero si la causa raíz cambia una decisión futura. Si no, el commit ya lo cuenta.

¿Cómo gestionas la memoria entre sesiones de Claude Code? ¿Qué entradas has terminado borrando porque generaban más ruido que ayuda? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo post toca cómo conectar esta arquitectura de memoria con hooks que la mantengan limpia sin trabajo manual.