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 Code olvida porque la información antigua sale de la ventana de contexto deslizante o se pierde cuando el Auto-Compaction la comprime. La solución: escribe reglas persistentes en CLAUDE.md, usa /compact o /clear estratégicamente, y nunca dejes que decisiones importantes existan solo en la conversación.

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 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 depende del modelo que estés usando. La ventana estándar es de aproximadamente 200,000 tokens, aunque algunos modelos soportan hasta 1 millón. De cualquier forma, el trabajo real de desarrollo la llena más rápido de lo esperado.

Qué consume contexto:

• Archivos CLAUDE.md (2,000–5,000 tokens cada uno)
• 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. En sesiones de refactorización donde tocas muchos archivos, el uso puede subir sorprendentemente rápido.

"Olvidar" ocurre de dos formas:

1. 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
2. Resumido por Auto-Compaction — cuando la ventana de contexto se llena (aproximadamente al 80–85% de capacidad), la compresión automática se activa y resume el historial. 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 Capas de Memoria

Claude Code tiene múltiples capas de memoria con una jerarquía de prioridad clara. Las ubicaciones más específicas tienen precedencia sobre las más generales, como describe la documentación oficial de memoria.

La mayoría de desarrolladores individuales usan Project CLAUDE.md, User CLAUDE.md y Auto Memory.

Project CLAUDE.md es la piedra angular de la gestión de contexto. Las reglas escritas aquí se cargan al inicio de cada sesión y tienen precedencia sobre tu User CLAUDE.md personal. A la inversa, las reglas que no están aquí corren riesgo de ser olvidadas.

Un error que cometí al principio con 32blog fue poner reglas específicas del proyecto en ~/.claude/CLAUDE.md (el archivo de nivel usuario). Esas reglas eran sobrescritas por el Project CLAUDE.md y eran efectivamente invisibles. Mueve las reglas del proyecto a la raíz del proyecto.

Para proyectos en equipo, .claude/rules/*.md es muy útil. Puedes definir el alcance de las reglas a tipos de archivo específicos con frontmatter paths — por ejemplo, frontend.md se carga solo cuando Claude toca archivos src/components/**/*.tsx. Esto mantiene el contexto ligero.

Para patrones de cómo estructurar tu CLAUDE.md, 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. Los detalles están en la documentación oficial.

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. A medida que acumulas feedback — cosas como "no agregues Co-Authored-By a los commits" o "siempre verifica antes de proponer cambios" — dejas de repetir las mismas correcciones.

MEMORY.md tiene un límite de 200 líneas. Solo las primeras 200 líneas se cargan al inicio de sesión. El contenido más allá de la línea 200 se ignora silenciosamente. Claude mantiene MEMORY.md como un índice conciso y mueve las notas detalladas a archivos separados (como debugging.md o api-conventions.md) que se leen bajo demanda.

# 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.

> /compact

Un punto importante que la documentación aclara: CLAUDE.md sobrevive completamente a la compactación. Después de /compact, Claude relee tu CLAUDE.md desde disco y lo reinyecta fresco en la sesión. Si una instrucción desapareció después de compactar, fue dada solo en la conversación — no estaba escrita en CLAUDE.md.

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.

> /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 la ventana de contexto se llena — aproximadamente al 80–85% de capacidad. 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 — Claude relee los archivos desde disco después de la compactación.

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. El campo trigger indica si fue manual (/compact) o automático.

{
  "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

1. Ejecuta /context para verificar si queda contexto de una sesión anterior
2. Verifica que CLAUDE.md coincida con la tarea de hoy
3. 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

# 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 subagentes y Agent Teams para distribuir contexto

Para trabajo a gran escala, los subagentes permiten delegar tareas que corren en su propia ventana de contexto. Cada subagente tiene contexto independiente, manteniendo tu sesión principal ligera. Agent Teams llevan esto más lejos — múltiples agentes trabajando en paralelo, cada uno con el presupuesto completo de contexto.

Por ejemplo, asignar "refactorización del frontend" y "adición de tests de API" a agentes separados les da contexto independiente en lugar de competir por espacio en una sola sesión.

Preguntas Frecuentes

¿CLAUDE.md sobrevive a /compact?

Sí. Después de /compact, Claude relee tu CLAUDE.md desde disco y lo inyecta fresco en la sesión. Solo el historial de conversación se comprime — los archivos CLAUDE.md y Auto Memory no se ven afectados.

¿Cuál es la diferencia entre CLAUDE.md y Auto Memory?

CLAUDE.md contiene reglas que tú defines: estándares de código, workflows, decisiones de arquitectura. Auto Memory contiene cosas que Claude aprende de tus correcciones y preferencias. Usa CLAUDE.md para reglas prescriptivas y Auto Memory para conocimiento acumulado.

¿Cómo verifico mi uso de contexto?

Ejecuta /context en tu sesión de Claude Code. Muestra un desglose del consumo de tokens entre prompt del sistema, herramientas, archivos de memoria, historial de conversación y espacio libre.

¿Puedo desactivar el Auto-Compaction?

El Auto-Compaction es una función integrada de Claude Code y no se puede desactivar directamente. La mejor defensa es la gestión proactiva del contexto: ejecutar /compact manualmente antes de alcanzar la capacidad, dividir sesiones por tarea, y escribir decisiones importantes en archivos en lugar de mantenerlas en la conversación.

¿Qué pasa cuando MEMORY.md supera las 200 líneas?

Solo las primeras 200 líneas se cargan al inicio de sesión. El contenido más allá se ignora silenciosamente. Claude gestiona esto manteniendo MEMORY.md como un índice conciso y moviendo notas detalladas a archivos separados que se leen bajo demanda.

¿/clear borra mi Auto Memory?

No. /clear solo borra el historial de conversación. Los archivos de Auto Memory en ~/.claude/projects/<project>/memory/ permanecen intactos y se recargan al inicio de la siguiente sesión.

¿Puedo compartir reglas de CLAUDE.md entre proyectos?

Sí. Coloca reglas compartidas en ~/.claude/CLAUDE.md (nivel usuario) para reglas personales que apliquen en todos los proyectos. Para reglas compartidas entre equipos, usa enlaces simbólicos en .claude/rules/ apuntando a un directorio compartido.

¿Los subagentes pueden tener su propia memoria?

Sí. Los subagentes pueden mantener su propio Auto Memory. Consulta la documentación de memoria de subagentes para los detalles de configuración.

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.

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.

Para más guías de Claude Code, consulta la colección completa de artículos.

Artículos relacionados:

• Gestión de Contexto en Claude Code: Patrones de Diseño para CLAUDE.md
• Cómo Reduje el Consumo de Tokens de Claude Code en un 50%
• Cómo Solucionar "context window exceeded" en Claude Code
• Guía Completa de Solución de Problemas de Claude Code