Por Qué Claude Code Olvida y Cómo Solucionarlo

"Te acabo de decir esa regla hace cinco minutos" — si has usado Claude Code para cualquier trabajo de desarrollo serio, has tenido este pensamiento.

Claude sigue tus instrucciones perfectamente al inicio de una sesión. Una hora después, está escribiendo código como si tu CLAUDE.md no existiera. Esto no es un bug. Es una consecuencia predecible de cómo funcionan las ventanas de contexto, y es completamente prevenible.

Este artículo explica la mecánica detrás de por qué Claude Code "olvida," cómo usar las 6 capas de memoria efectivamente, cuándo usar /compact vs /clear, y cómo evitar la trampa del Auto-Compaction que silenciosamente degrada la calidad de tu sesión.

Por Qué Claude Code Olvida Tus Instrucciones

La ventana de contexto de Claude Code es de aproximadamente 200,000 tokens. Suena enorme, pero el trabajo real de desarrollo la llena más rápido de lo esperado.

Qué consume contexto:

CLAUDE.md (2,000–5,000 tokens)
MEMORY.md de Auto Memory (hasta 200 líneas)
Lectura de código fuente (~5,000 tokens por archivo de 500 líneas)
Historial de conversación (se acumula con cada intercambio)
Resultados de herramientas (lecturas de archivos, resultados de búsqueda, salida de comandos)

Leer 10 archivos y tener una conversación de 30 minutos puede consumir fácilmente más de 100,000 tokens.

"Olvidar" ocurre de dos formas:

Expulsado de la ventana de contexto — la información antigua sale de la ventana y Claude ya no puede referenciarla. Tus reglas de CLAUDE.md no se olvidan literalmente — quedan enterradas bajo contenido de conversación más reciente y dejan de recibir atención
Resumido por Auto-Compaction — alrededor de 167,000 tokens, la compresión automática se activa y resume el historial de conversación. El resumen preserva decisiones pero a menudo pierde el razonamiento detrás de ellas, causando que Claude tome una dirección diferente

En ambos casos, es un problema de ubicación, no de existencia. Coloca la información correcta en el lugar correcto y no será olvidada.

Entendiendo las 6 Capas de Memoria

Claude Code tiene 6 capas de memoria con una jerarquía de prioridad clara. Las capas superiores tienen precedencia.

Prioridad	Capa	Escrita por	Se carga cuando
1	Enterprise Policy	Admin de la org	Siempre
2	User CLAUDE.md	Tú (`~/.claude/CLAUDE.md`)	Cada sesión
3	Project CLAUDE.md	Equipo (raíz del proyecto)	Cada sesión
4	Subdirectory CLAUDE.md	Equipo (subdirectorio)	Trabajando en ese directorio
5	.claude/rules/*.md	Equipo (archivos de reglas)	Cuando el patrón glob coincide
6	Auto Memory	Claude mismo	Primeras 200 líneas de MEMORY.md

La mayoría de desarrolladores individuales usan las capas 2, 3 y 6.

Project CLAUDE.md (capa 3) es la piedra angular de la gestión de contexto. Las reglas escritas aquí se cargan al inicio de cada sesión. A la inversa, las reglas que no están aquí corren riesgo de ser olvidadas.

Para proyectos en equipo, la capa 5 (.claude/rules/*.md) es poderosa. Los patrones glob permiten aplicar diferentes reglas a diferentes archivos — por ejemplo, frontend.md se carga solo al tocar código del frontend.

Para patrones de cómo estructurar tu CLAUDE.md efectivamente, consulta "Gestión de Contexto en Claude Code: Patrones de Diseño para CLAUDE.md."

Cómo Funciona Auto Memory y Cuándo Usarlo

Auto Memory permite a Claude registrar automáticamente lo que aprende durante las sesiones. Los archivos se guardan en ~/.claude/projects/<project>/memory/, con MEMORY.md como índice.

Qué registra Auto Memory:

Comandos de build y convenciones de testing
Conocimientos de debugging
Decisiones de arquitectura
Preferencias de estilo de código
Tus patrones de trabajo

Qué NO registra Auto Memory:

El contenido del código en sí (leer el codebase es más confiable)
Estado de trabajo temporal ("actualmente editando este archivo")
Información derivable del historial de git

Consejos prácticos

Da feedback explícito y se registra. Dile a Claude "no uses mocks en los tests" y Auto Memory lo guarda como feedback que persiste entre sesiones.

MEMORY.md tiene un límite de 200 líneas. Solo las primeras 200 líneas se cargan al inicio de sesión. Más allá, recibirás una advertencia. Limpia las entradas antiguas regularmente.

bash

# Ver y gestionar Auto Memory
> /memory

Cómo dividir responsabilidades entre CLAUDE.md y Auto Memory:

CLAUDE.md → Reglas que tú defines. "Usa TypeScript strict mode." "Escribe tests con Vitest."
Auto Memory → Cosas que Claude aprende. "Este usuario es un ingeniero senior." "El esquema de BD fue cambiado en la última sesión."

Escribir lo mismo en ambos desperdicia tokens. Reglas en CLAUDE.md. Aprendizaje en Auto Memory.

/compact vs /clear — Elegir el Correcto

Cuando las sesiones se alargan, dos comandos gestionan el contexto. Elegir mal significa perder información que necesitabas.

/compact — Comprimir la conversación

Resume el historial de conversación, reduciendo drásticamente el uso de tokens. Las decisiones clave se preservan, pero el contexto detallado de intercambios individuales se pierde.

bash

> /compact

Cuándo usarlo:

Quieres continuar la misma tarea pero el contexto se está volviendo pesado
/context muestra uso por encima del 70%
La velocidad de respuesta de Claude está bajando

Cuándo NO usarlo:

La tarea terminó y vas a cambiar a otro trabajo (/clear es mejor)

/clear — Resetear el contexto completamente

Borra todo el historial de conversación. CLAUDE.md y Auto Memory se recargan frescos.

bash

> /clear

Cuándo usarlo:

Una tarea está completa y cambias a la siguiente
Claude está claramente atascado en contexto desactualizado
Algo se siente raro (resetear es la solución más rápida)

Regla de decisión

"¿Sigo con la misma tarea?" → Sí → /compact / No → /clear

En caso de duda, /clear es más seguro. Con CLAUDE.md y Auto Memory en su lugar, la mayoría del contexto es recuperable.

La Trampa del Auto-Compaction y Cómo Evitarla

El Auto-Compaction se activa automáticamente cuando el contexto alcanza aproximadamente 167,000 tokens. A diferencia del /compact manual, se dispara sin aviso.

Por qué es un problema

El Auto-Compaction resume conversaciones, pero el resumen puede eliminar el razonamiento detrás de las decisiones. Por ejemplo:

"Usamos Supabase Auth porque necesitamos integración con RLS" → después de la compactación, solo sobrevive "Usar Supabase Auth"
Sin el razonamiento, Claude puede sugerir alternativas que contradicen tu arquitectura

Cómo defenderse

1. Escribe las decisiones importantes en archivos

No dejes que las decisiones existan solo en la conversación. Escríbelas en docs/decisions.md o CLAUDE.md. El contenido de archivos no es afectado por la compresión de contexto.

2. Divide las sesiones por tarea

Una tarea = una sesión como regla general. Flujos de autenticación, cambios de esquema de BD y refactorizaciones grandes con restricciones precisas se benefician especialmente del aislamiento de sesiones.

3. Usa PreCompact Hooks para respaldo automático

Un Hook PreCompact ejecuta un script justo antes de que se active la compresión. Puedes auto-guardar estado crítico en un archivo.

json

{
  "hooks": {
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          {
            "type": "command",
            "command": "bash scripts/save-session-state.sh"
          }
        ]
      }
    ]
  }
}

Técnicas Prácticas para Sesiones Largas Estables

Poniendo todo junto — aquí está la rutina que mantiene las sesiones estables en trabajo de desarrollo real.

Rutina de inicio de sesión

Ejecuta /context para verificar si queda contexto de una sesión anterior
Verifica que CLAUDE.md coincida con la tarea de hoy
Si existe un session-handoff.md de la vez anterior, haz referencia a él

Monitoreo durante la sesión

Verifica /context cada 30 minutos. Uso por encima del 70% → considera /compact
Ejecuta /clear después de cada tarea completada. No arrastres contexto a trabajo no relacionado
Escribe decisiones en archivos conforme ocurren. No las dejes solo en la conversación

Traspaso de sesión

markdown

# session-handoff.md

## Completado
- Migrado src/auth/login.ts de JWT a Supabase Auth
- Todos los tests existentes pasando

## Próxima Sesión
- Migrar src/auth/register.ts (mismo enfoque que login.ts)
- Actualizar verificación de auth en middleware.ts

## Restricciones
- Supabase RLS se mantiene habilitado
- NEXT_PUBLIC_SUPABASE_URL ya configurado en .env.local

Incluso con Auto Memory, escribe "qué hacer después" en session-handoff.md manualmente. Auto Memory registra lo que Claude juzga como importante, que puede no incluir tu plan de trabajo específico.

Usa Agent Teams para distribuir contexto

Para trabajo a gran escala, Agent Teams te permite paralelizar tareas entre múltiples agentes. Cada agente tiene su propia ventana de contexto independiente, así que evitas completamente el problema de desbordamiento en una sola sesión.

Por ejemplo, asignar "refactorización del frontend" y "adición de tests de API" a agentes separados le da a cada uno el presupuesto completo de 200,000 tokens.

Conclusión

Que Claude Code "olvide" no es un bug — es una restricción de las ventanas de contexto. Con las estrategias correctas, puedes mantener calidad consistente incluso en sesiones largas.

Estrategia	Cómo
Mantener reglas persistentes	Escríbelas en CLAUDE.md. Nunca dejes decisiones solo en la conversación
Acumular aprendizaje	Deja que Auto Memory lo maneje. Da feedback explícito cuando importa
Gestionar contexto activamente	Verifica `/context` cada 30 min. `/compact` por encima del 70%
Aislar tareas	`/clear` después de cada tarea. No contamines contexto entre trabajos
Defenderse del Auto-Compaction	Escribe decisiones en archivos. Usa PreCompact Hooks para respaldo
Traspasar entre sesiones	Actualiza session-handoff.md. No dependas solo de Auto Memory

Si Claude parece haber olvidado tus reglas, revisa tu CLAUDE.md primero. Optimizar la ubicación de la información — no el volumen — es lo que cambia la experiencia.