Claude Code: 3 patrones de memoria post-compact

El comando /compact de Claude Code comprime la conversación en curso para liberar espacio en la ventana de contexto. Suena inofensivo hasta que descubres que borra hasta el 90% de lo que estabas construyendo. El código que compartiste, las decisiones que discutieron, el archivo que acabas de leer, las restricciones que le explicaste dos veces. Todo se resume en un párrafo genérico y sigues trabajando con un colaborador que “leyó la sinopsis” pero no vivió la conversación.

En este texto describo 3 patrones de memoria que uso para que el trabajo importante sobreviva al /compact. Los tres son concretos: un archivo, una convención de handoff, y un md de checkpoint. Los tres se pueden aplicar hoy sin instalar nada.

Por qué /compact duele más de lo que parece

Antes de los patrones, vale la pena entender qué pierde el /compact.

Cuando la conversación se acerca al límite del contexto (200k tokens en los modelos actuales), /compact toma toda la historia y le pide al mismo modelo que la resuma en unos pocos miles de tokens. El resumen es competente en promedio, pero deja fuera cosas que dolerán después:

• Fragmentos de código que compartiste se resumen a “el usuario compartió código de X”. Si necesitas que Claude recuerde la firma exacta de una función, se perdió.
• Decisiones tomadas con matiz (“vamos con B pero solo si Y no cambia”) se aplanan a “decidimos B”.
• Restricciones que se dijeron una sola vez (“nunca uses --force”) tienen alta probabilidad de desaparecer del resumen.
• El estado exacto del filesystem (qué archivos abriste, qué probaste, qué falló) se convierte en un párrafo abstracto.

En proyectos donde he medido con mi plugin compact-ops, el warning por sobrepasar el 67% del contexto (umbral que uso para forzar un save preventivo antes de que Claude decida comprimir por su cuenta) aparece prácticamente en cada sesión de trabajo largo. Eso significa que si no tienes un plan, cada 3 horas de trabajo profundo termina en un resumen que pierde la mitad de lo importante.

Los 3 patrones abajo intentan que la parte que importa sobreviva.

Patrón 1: archivo permanente (MEMORY.md)

Qué es: un archivo MEMORY.md en la raíz del proyecto (o en ~/.claude/ para memoria global) que contiene las decisiones, restricciones y contexto que no debes perder entre sesiones. Claude Code lee este archivo automáticamente si está en el CLAUDE.md como referencia, o si le pides read MEMORY.md al iniciar.

Cuándo usarlo: para información que es válida por semanas o meses. No para el bug que estás debugueando ahora.

Estructura mínima:

# MEMORY.md

## Perfil del proyecto
- Stack: TypeScript, Astro, Cloudflare Workers
- Ambiente: producción vive en main; PRs preview en cf pages
- Deploy: automático al hacer merge a main

## Decisiones estables
- Base de datos: SQLite via D1 (no Postgres, decidido por costo en volumen bajo)
- Auth: Clerk (no roll-your-own, decidido después del incidente de sesión de 2026-03)
- Testing: vitest para unit, playwright para e2e

## Restricciones absolutas
- Nunca `git push --force` a main
- Nunca instalar dependencias con `--legacy-peer-deps` sin abrir issue
- Nunca commit sin correr `npm run typecheck` antes

## Convenciones del código
- Componentes en PascalCase, hooks con prefijo use, tests con .test.ts
- Comentarios: solo cuando el "por qué" no es obvio del código

Regla de mantenimiento: cuando tomes una decisión que dolerá si Claude la olvida, agrégala aquí en el mismo momento en que la tomas. No al final del sprint. En el momento. Si esperas, el /compact va a llegar primero y la decisión va a desaparecer del contexto vivo antes de que la escribas.

Esta es la memoria más importante de las tres. Sobrevive al /compact porque no depende del /compact: es un archivo, siempre está ahí, se lee al inicio de la sesión siguiente.

Patrón 2: note handoff (nota de traspaso)

Qué es: al final de una sesión de trabajo importante, escribir 5-10 líneas de “traspaso” a la próxima sesión. Se guarda en notes/handoff-YYYY-MM-DD.md o similar.

Cuándo usarlo: cuando estás por cerrar una sesión y sabes que la próxima va a continuar el mismo hilo (mañana, después del almuerzo, después de una reunión).

Formato:

# Handoff — 2026-09-05 18:30

## Dónde quedé
Estaba implementando el rate limiter en `src/middleware/ratelimit.ts`. Terminé
la lógica base con sliding window de 60s. Falta:
- Test de concurrencia (2 requests simultáneos del mismo IP no deben ambos pasar)
- Integrar con el logger existente en `src/lib/log.ts`

## Decisiones importantes de esta sesión
- Elegimos sliding window sobre token bucket porque el tráfico es bursty y token bucket dejaba pasar spikes
- El límite por IP es 60/min, decidido después de mirar los logs de las últimas 4 semanas

## Lo que probé y no funcionó
- `express-rate-limit` no anda bien con Cloudflare Workers (necesita KV, no memoria)
- Redis serverless costaría USD 15/mes solo para esto, decidí no usarlo

## Próximo paso concreto
Correr `npm test -- ratelimit` y ver si los 3 tests que agregué pasan.
Si sí, abrir PR con base en `main`.

Regla: las decisiones y los “lo que probé y no funcionó” son la parte que más se pierde en el /compact y la más costosa de reconstruir. Escríbelas aunque el resto del handoff quede breve.

Este patrón es más ligero que MEMORY.md pero cubre el hueco de “trabajo en progreso que no encaja en decisiones estables”. Los handoffs viejos se pueden archivar o borrar sin culpa; su función es sobrevivir 24-72 horas, no siempre.

Patrón 3: checkpoint md (checkpoint por sesión)

Qué es: un archivo temporal (checkpoint.md o similar) que Claude actualiza durante la sesión con el estado actual del trabajo. Cuando el /compact se acerca, este archivo es lo que vas a pedirle a Claude que lea primero después de la compresión.

Cuándo usarlo: en sesiones largas de exploración o depuración, donde Claude está acumulando entendimiento que costaría reconstruir.

Cómo se genera:

Al inicio de una tarea larga, pídele a Claude:

Vamos a mantener un checkpoint.md en la raíz. Cada vez que descubramos algo
importante sobre este sistema (arquitectura, edge cases, decisiones), lo
agregas al checkpoint. Cuando lleguemos al 70% de contexto, vas a leer
el checkpoint completo y confirmar que refleja tu estado actual.

Estructura sugerida:

# Checkpoint — debug del race condition en el queue

## Sistema en cuestión
- Queue: BullMQ sobre Redis, workers en Cloudflare Workers
- Sospecha inicial: race entre el `moveToActive` y el `acknowledge`

## Hipótesis descartadas
- No es problema de connection pool (medido, hay slots libres)
- No es TTL del lock (revisado, se renueva bien)

## Hipótesis activa
- Cuando 2 workers hacen `moveToActive` en el mismo tick, el `getNextJob`
  puede devolver el mismo id a los dos. El `lock` de BullMQ debería impedirlo
  pero no siempre lo hace en escenarios de Workers (a investigar)

## Próximo experimento
- Log en el momento del `moveToActive` con el worker id y el job id
- Correr el load test con 5 workers concurrentes y buscar duplicados en el log

La diferencia con el handoff: el checkpoint es un archivo vivo que se actualiza durante la sesión, no una foto al final. Sobrevive al /compact porque cuando la compresión pasa, la primera acción es leer el checkpoint y “rehidratar” el estado mental de Claude con datos concretos (no con el resumen genérico que produjo /compact).

Cómo combinar los tres

Los 3 patrones no son alternativos, son complementarios:

• MEMORY.md — meses. Decisiones estables, restricciones absolutas, convenciones.
• Handoff — días. Estado de trabajo en progreso, decisiones recién tomadas.
• Checkpoint — horas. Estado mental durante una sesión larga de exploración.

En un flujo típico de trabajo profundo:

1. Al iniciar el día, Claude lee MEMORY.md + el handoff más reciente
2. Durante el trabajo, se mantiene checkpoint.md para la tarea activa
3. Cuando aparece el warning de contexto, /compact se ejecuta pero el checkpoint ya está en disco
4. Después del /compact, primera acción: “lee el checkpoint completo”
5. Al cerrar el día, se escribe un handoff nuevo y las decisiones nuevas van a MEMORY.md

Ninguno de los 3 patrones es mágico. Los 3 requieren disciplina: escribir en el momento de la decisión, no después. Si esperas al final del día para actualizar MEMORY.md, el /compact va a llegar primero y vas a estar reconstruyendo de memoria en lugar de escribir lo que sabías fresco.

La forma de saber si los patrones están funcionando es medir cuántas veces por semana Claude te hace una pregunta cuya respuesta ya está en MEMORY.md o en un handoff reciente. Si son más de 2-3 por semana, el problema no es Claude, es que la memoria no está donde debería.

---

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev