4. Memory Management — Cleanup, Rotation, Prioritization

Descripción

MEMORY.md es un archivo de texto plano que tu subagent lee al iniciar y actualiza durante la ejecución. Suena simple — y lo es, mecánicamente. Pero el detalle que transforma memoria útil en memoria contraproducente está en un número: 200 líneas. Claude Code inyecta automáticamente las primeras 200 líneas de MEMORY.md en el system prompt del subagent. Lo que esté después de la línea 200 existe en el archivo pero no se carga automáticamente — el agente tendría que leerlo explícitamente, lo cual no hará a menos que se lo instruyas.

Esto significa que MEMORY.md no es un log donde acumulas todo. Es un recurso curado donde el contenido más importante debe estar en las primeras 200 líneas. Un MEMORY.md sin curación crece con cada sesión: primero tiene 50 líneas útiles, luego 150, luego 300 — y en ese momento las 200 líneas auto-inyectadas incluyen información obsoleta sobre decisiones que ya cambiaron, patrones que ya se refactorizaron, y convenciones que el equipo abandonó hace dos sprints. El agente actúa sobre información incorrecta porque no tienes un sistema de curación.

En esta cápsula aprenderás a gestionar el ciclo de vida completo de la memoria de un subagent: qué mantener arriba, qué archivar, qué eliminar, y cómo instruir al propio agente para que participe en su curación. Un agente con memoria bien curada es más efectivo que uno con memoria infinita — porque la señal no se pierde en el ruido.

El Problema de las 200 Líneas

Cómo funciona la inyección automática

Cuando un subagent con memory: project se invoca, Claude Code hace esto antes de ejecutar cualquier instrucción:

1. Busca .claude/agent-memory/{name}/MEMORY.md
2. Lee las primeras 200 líneas
3. Las inyecta al inicio del contexto del subagent
4. Ejecuta el system prompt del subagent con ese contexto

Lo que no hace:

❌ No lee más allá de la línea 200
❌ No prioriza contenido dentro de esas 200 líneas
❌ No detecta si el contenido es obsoleto
❌ No archiva automáticamente contenido viejo

El crecimiento descontrolado

Sin curación, un MEMORY.md típico evoluciona así:

Semana 1 (30 líneas):
- Convenciones de naming: snake_case
- Framework: FastAPI con SQLAlchemy
- Tests: pytest con fixtures compartidas

Semana 4 (120 líneas):
- Todo lo anterior +
- 15 patrones descubiertos
- 8 decisiones arquitecturales
- 5 issues recurrentes con solución

Semana 8 (350 líneas):                    ← PROBLEMA
- Las primeras 200 líneas incluyen:
  - Convenciones (aún válidas)
  - Decisiones de semana 1 (algunas ya cambiaron)
  - Patrones de semana 2 (algunos refactorizados)
- Las líneas 201-350 incluyen:
  - Decisiones recientes más relevantes    ← NO SE INYECTAN
  - Patrones actuales del proyecto         ← NO SE INYECTAN

Resultado: el agente toma decisiones basadas en contexto de hace 2 meses, ignorando las decisiones más recientes que están más allá de la línea 200.

La regla fundamental

Lo que está después de la línea 200 no existe para el agente — a menos que lo lea explícitamente.

Tu trabajo como curator es asegurar que las 200 líneas auto-inyectadas contengan la información más relevante y actual. Todo lo demás debe archivarse o eliminarse.

Anatomía de un MEMORY.md Bien Curado

Categorías recomendadas

Un MEMORY.md estructurado por categorías es más fácil de curar que uno cronológico. Estas son las 4 categorías que cubren el 90% de los casos:

# Agent Memory: code-reviewer

## Architecture Decisions
- API follows REST conventions with /api/v1/ prefix
- Repository pattern: all DB access goes through src/repositories/
- DTOs separate from domain models — never expose ORM models in responses
- Background tasks use Celery, not FastAPI BackgroundTasks

## Coding Conventions
- Python: snake_case functions, PascalCase classes, UPPER_CASE constants
- Imports: stdlib → third-party → local (isort enforced)
- Type hints required on all public function signatures
- Docstrings: Google style, required on public functions
- Error responses: always use ProblemDetail (RFC 7807)

## Known Patterns
- Auth: JWT with refresh tokens, stored in httponly cookies
- Pagination: cursor-based on all list endpoints (no offset)
- Validation: Pydantic v2 models in src/schemas/
- Logging: structured JSON via structlog, correlation IDs on all requests

## Recurring Issues
- N+1 queries in product listings — use selectinload()
- Missing error handling on external API calls (payment gateway)
- Test fixtures create too much data — use factory_boy minimal fixtures

Por qué categorías y no cronología

Un formato cronológico ("Session 2026-03-01: aprendí que..., Session 2026-03-05: descubrí que...") tiene dos problemas:

1. Duplicación: La misma convención aparece en múltiples entradas de sesión
2. Prioridad temporal: Las entradas más viejas están arriba, las nuevas abajo — exactamente al revés de lo que quieres

El formato por categorías agrupa información relacionada y permite actualizar una entrada sin duplicarla. Si la convención de naming cambia de snake_case a camelCase, actualizas una línea en "Coding Conventions" en lugar de tener dos entradas contradictorias en sesiones diferentes.

Priority ordering: lo más importante arriba

Dentro del archivo, ordena las categorías de mayor a menor impacto:

1. Architecture Decisions     ← máximo impacto, cambia raramente
2. Coding Conventions         ← alto impacto, estable
3. Known Patterns             ← medio impacto, evoluciona
4. Recurring Issues           ← variable, cambia frecuentemente

Dentro de cada categoría, el item más importante va primero. Si el límite de 200 líneas corta en "Recurring Issues", pierdes los issues menos frecuentes — aceptable. Si cortara en "Architecture Decisions", perderías decisiones fundamentales — inaceptable.

Estrategias de Curación

Qué mantener

Mantén en MEMORY.md información que cumpla estos tres criterios:

1. Vigente — Refleja el estado actual del proyecto (no decisiones revertidas)
2. Accionable — El agente puede usar esta información para tomar mejores decisiones
3. No obvia — La información no se puede inferir leyendo CLAUDE.md o el código

✅ MANTENER: "Pagination is cursor-based, never use offset — performance degrades on tables > 1M rows"
   → Vigente, accionable (el agente sabe qué patrón usar), no obvia (el porqué del cursor)

❌ ELIMINAR: "The project uses Python"
   → Obvia — el agente lo descubre leyendo pyproject.toml

❌ ELIMINAR: "In session 2026-02-15, we decided to use FastAPI"
   → El proyecto ya usa FastAPI — es un hecho, no una decisión pendiente

Qué archivar

Archiva información que ya no es inmediatamente accionable pero podría ser útil como referencia histórica:

Archivar:
- Decisiones revertidas (para entender por qué se probó X y no funcionó)
- Patrones de versiones anteriores del framework
- Issues resueltos que podrían recurrir en refactors grandes

El archivo va a un archivo separado en el directorio de memoria:

.claude/agent-memory/code-reviewer/
├── MEMORY.md          ← activo, primeras 200 líneas auto-inyectadas
└── ARCHIVE.md         ← referencia histórica, no auto-inyectado

Qué eliminar

Elimina sin archivar:

- Notas de debugging de una sesión específica ("probé X, no funcionó, luego probé Y")
- Información redundante con CLAUDE.md
- Información que el agente redescubre trivialmente (stack tecnológico, estructura de directorios)
- Anotaciones temporales ("TODO: revisar esto mañana")

Instrucciones de Auto-Curación en el System Prompt

El problema de la curación manual

Curar MEMORY.md manualmente funciona para un agente. Para tres o cinco agentes con ejecuciones diarias, se vuelve un overhead significativo. La solución es instruir al subagent para que curé su propia memoria.

Instrucciones de curación en el system prompt

Agrega una sección de Memory Management al final del system prompt de tu subagent:

---
name: code-reviewer
description: Reviews code changes with persistent memory of project patterns
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit
model: haiku
maxTurns: 15
memory: project
---

## Role
[... tu system prompt existente ...]

## Memory Management

At the END of each session, update your MEMORY.md following these rules:

### What to update
- Add new patterns discovered in this session
- Add new architectural decisions observed
- Update entries that are no longer accurate
- Remove entries about issues that have been fixed

### Organization rules
- Use EXACTLY these categories: Architecture Decisions, Coding Conventions, Known Patterns, Recurring Issues
- Keep the most important items at the TOP of each category
- Each entry must be a single line starting with "- "
- No timestamps, no session references, no narrative text

### Size constraint
- MEMORY.md must stay under 180 lines (buffer for the 200-line limit)
- If approaching 180 lines, remove the least relevant entries from Recurring Issues first
- NEVER exceed 200 lines total

### What NOT to store
- Information already in CLAUDE.md (don't duplicate)
- Temporary debugging notes
- Information obvious from reading the code
- Session-specific observations that won't matter next time

Verificar que la curación funciona

Después de varias sesiones, verifica el tamaño:

wc -l .claude/agent-memory/code-reviewer/MEMORY.md

Si supera 180 líneas, refuerza con "CRITICAL: Never exceed 180 lines" en el system prompt o ejecuta una curación manual como checkpoint.

Si quieres que el agente archive en lugar de eliminar, agrega: "When removing an entry, append it to ARCHIVE.md in the same directory with the date."

Rotación de Memoria

Cuándo rotar

La rotación es el proceso de mover contenido de MEMORY.md a archivos de referencia. Rota cuando:

• MEMORY.md se acerca a 180 líneas y todo el contenido es relevante
• Una categoría domina el archivo (ej: 80 líneas de Recurring Issues)
• El proyecto pasa por un milestone y el contexto cambia significativamente

Estructura de rotación

.claude/agent-memory/code-reviewer/
├── MEMORY.md              ← activo (≤ 180 líneas)
├── ARCHIVE.md             ← entries eliminados con fecha
├── patterns-v1.md         ← patrones de Phase 1 del proyecto
└── decisions-log.md       ← historial de decisiones arquitecturales

Instrucciones de rotación en el system prompt

### Rotation rules
- If a category exceeds 30 entries, move the oldest 15 to ARCHIVE.md
- When a major refactoring happens, move affected patterns to
  a versioned file (patterns-v1.md, patterns-v2.md)
- Architecture Decisions are NEVER rotated — they stay in MEMORY.md
  unless explicitly reverted

Los archivos rotados no se inyectan automáticamente. El agente puede acceder a ellos si lo instruyes en el system prompt: "If you encounter a familiar issue not in MEMORY.md, check ARCHIVE.md."

Detección de Memoria Obsoleta

Señales de memoria stale

La memoria se vuelve contraproducente cuando:

1. Decisiones revertidas — MEMORY.md dice "usamos offset pagination" pero el proyecto migró a cursor-based
2. Patrones deprecados — El agente recomienda un pattern que ya no aplica porque el framework se actualizó
3. Issues resueltos — "N+1 en product listings" se registra como Recurring Issue pero el fix ya está en producción
4. Convenciones abandonadas — "Google-style docstrings" cuando el equipo cambió a NumPy-style

Detección automática via system prompt

### Stale detection
Before applying any memory entry, verify it's still accurate:
- If MEMORY.md says a convention exists, check 2-3 files to confirm
- If MEMORY.md says an issue is recurring, check if it's been fixed
- If you find a stale entry, update or remove it immediately
- Add a note in your session output: "Updated stale memory: [what changed]"

Audit periódico

Cada 2-4 semanas, revisa MEMORY.md preguntándote por cada entrada: ¿sigue siendo cierto? ¿el agente actúa sobre esto? ¿cambiaría algo si lo elimino? Si las 3 respuestas son "no", elimina la entrada.

Para un audit automatizado, pídele a Claude Code:

Lee .claude/agent-memory/code-reviewer/MEMORY.md y el código actual
en src/. Identifica entries que ya no son precisos porque el código
cambió. Lista cada entry stale con lo que dice vs lo que el código
muestra actualmente.

Curación Agresiva vs Permisiva

Dos filosofías

La curación agresiva prioriza precisión sobre completitud. La permisiva prioriza completitud sobre brevedad. Ambas tienen tradeoffs reales.

Curación agresiva

## Memory Management (aggressive)

Keep MEMORY.md under 100 lines. Only store:
- Active architectural decisions (max 10)
- Current coding conventions (max 10)
- Top 5 most impactful patterns
- Top 3 most frequent issues

Remove everything else. When in doubt, remove.

Curación permisiva

## Memory Management (permissive)

Keep MEMORY.md under 190 lines. Store:
- All architectural decisions with context
- All coding conventions observed
- All patterns discovered
- Issues seen more than once

Only remove entries confirmed as incorrect.

Cuándo usar cada una

La recomendación por defecto

Para la mayoría de proyectos, empieza con curación agresiva (100 líneas) y relaja si sientes que el agente pierde contexto que necesita. Es más fácil agregar que eliminar — un MEMORY.md de 190 líneas lleno de ruido requiere un audit completo, pero uno de 80 líneas solo necesita que agregues lo que falta.

Manual vs Automatizado: Enfoques de Curación

Curación híbrida: la recomendación

Combina auto-curación del agente con supervisión humana:

Automatizada:  cada sesión (el agente lo hace solo)
Manual rápida:  cada 1-2 semanas (5 min, verificar que la auto-curación funciona)
Audit completo: cada 4-6 semanas (15 min por agente)
Después de refactor: inmediatamente (curación manual forzada)

Ejemplo: Semana 1 vs Semana 8

Sin curación (semana 8, 210+ líneas)

## Architecture Decisions
- REST API with /api/v1/ prefix
- [Session 2026-02-01] Decided to use offset pagination     ← STALE
- [Session 2026-02-22] Switched to cursor pagination         ← contradice la anterior
- ...50 more entries, timestamps, narrativas de sesión...

Contenido contradictorio, entradas stale, timestamps innecesarios. Las decisiones recientes están más allá de la línea 200 — el agente no las ve.

Con curación (semana 8, 28 líneas)

## Architecture Decisions
- REST API with /api/v1/ prefix
- Repository pattern for all DB access
- Redis caching on read-heavy endpoints (products, categories)
- SQLAlchemy 2.0 async for all DB operations
- Cursor-based pagination on all list endpoints

## Coding Conventions
- snake_case for functions, PascalCase for classes
- Pydantic v2 models in src/schemas/ (never expose ORM models)
- Structured logging with structlog, correlation IDs required

## Known Patterns
- JWT auth: access token (15min) + refresh token (7d), httponly cookies
- Validation: request/response models separate (CreateProduct vs ProductResponse)

## Recurring Issues
- Payment gateway timeouts: wrap in retry with exponential backoff
- Test fixtures too heavy: use factory_boy with minimal data

Conciso, actualizado, sin contradicciones. Cada entry es accionable.

Troubleshooting

"MEMORY.md crece sin control"

Causa: Las instrucciones de curación en el system prompt son demasiado permisivas o no existen.

Solución: Agrega un límite explícito y una regla de priorización:

CRITICAL: MEMORY.md must NEVER exceed 180 lines.
If it approaches 180 lines, remove entries in this order:
1. Recurring Issues that haven't appeared in 3+ sessions
2. Known Patterns available in CLAUDE.md
3. Coding Conventions obvious from reading the code
NEVER remove Architecture Decisions unless they've been reverted.

"El agente ignora su propia memoria"

Causa: MEMORY.md tiene demasiadas líneas y la información relevante está más allá de la línea 200, o el contenido es tan genérico que no produce decisiones diferentes.

Solución: Verifica el tamaño y la calidad:

wc -l .claude/agent-memory/code-reviewer/MEMORY.md
head -200 .claude/agent-memory/code-reviewer/MEMORY.md

Si tiene más de 200 líneas, cura. Si el contenido es genérico ("use good naming"), reemplázalo con información específica ("functions use verb_noun pattern: get_user, create_order").

"El agente borra memoria que debería mantener"

Causa: Las instrucciones de curación son demasiado agresivas, o el agente no distingue entre información fundamental y secundaria.

Solución: Marca entradas críticas como permanentes:

## Architecture Decisions [PERMANENT — never remove without explicit instruction]
- Repository pattern for all DB access
- Cursor-based pagination on all list endpoints

El tag [PERMANENT] instruye al agente a no tocar esas entradas durante la curación automática.

"Dos subagents tienen memoria contradictoria"

Causa: Cada agente descubrió la misma información en sesiones diferentes y la registró de forma distinta.

Solución: Designa un agente como "source of truth" para cada categoría: reviewer para Patterns e Issues, implementer para Conventions y Architecture. Cada agente lee la memoria del otro como referencia pero solo escribe en sus propias categorías.

"No sé qué scope usar"

Regla rápida:

Ejercicios

Ejercicio 1: Curar un MEMORY.md inflado (Fácil)

Este MEMORY.md tiene 25 entradas pero el proyecto solo necesita 12 líneas. Identifica qué eliminar, qué mantener, y por qué.

# Agent Memory: code-reviewer

## Architecture Decisions
- The project uses Python 3.12
- REST API with FastAPI
- Repository pattern for DB access
- We considered Django but chose FastAPI
- SQLAlchemy 2.0 for ORM
- Database is PostgreSQL
- [2026-01-15] Set up the project structure
- Background tasks with Celery

## Coding Conventions
- snake_case for functions
- Use type hints
- PascalCase for classes
- Imports should be organized
- We use Black for formatting

## Known Patterns
- JWT authentication
- Pydantic for validation

## Recurring Issues
- Sometimes tests are slow
- Need to add more tests
- The CI pipeline takes 10 minutes
- Found a bug in the payment module last week
- Memory usage is high on production

# Agent Memory: code-reviewer

## Architecture Decisions
- Repository pattern: all DB access through src/repositories/
- Background tasks: Celery for jobs > 30s, FastAPI BackgroundTasks for < 30s
- SQLAlchemy 2.0 async with connection pooling

## Coding Conventions
- snake_case functions, PascalCase classes, UPPER_CASE constants
- Type hints required on all public function signatures

## Known Patterns
- JWT auth with refresh tokens, access token TTL 15min
- Pydantic v2 models in src/schemas/ for all request/response validation

## Recurring Issues
- Tests slow when using real DB — use fixtures with factory_boy
- CI pipeline: 10min — parallelize test suites to reduce
- Memory usage in production: paginate all list endpoints, limit query results

Ejercicio 2: Escribir instrucciones de auto-curación (Fácil)

Dado este subagent tester, escribe la sección Memory Management para su system prompt. El tester tiene scope local y su memoria debería enfocarse en test performance y failure patterns.

---
name: code-tester
description: Runs tests and reports results
tools: Bash, Read, Glob
disallowedTools: Write, Edit
model: haiku
maxTurns: 12
memory: local
---

## Memory Management

At the END of each session, update your MEMORY.md:

### Categories (use exactly these)
- **Test Performance:** Slow tests (> 2s), test suite total time trends
- **Failure Patterns:** Tests that fail repeatedly, common root causes
- **Coverage Trends:** Module coverage percentages, uncovered areas
- **Environment Notes:** Machine-specific config, virtualenv paths, known setup issues

### Rules
- Keep under 120 lines (aggressive — test data changes frequently)
- Only record patterns seen in 2+ sessions
- Remove entries about tests that have been deleted
- Remove entries about failures that have been permanently fixed
- Track test suite execution time trend: add current time each session,
  keep only last 5 measurements

### What NOT to store
- Individual test results (only patterns)
- Full error messages (only root cause summary)
- Temporary workarounds that lasted one session

Ejercicio 3: Diseñar una estrategia de rotación (Medio)

Tu reviewer lleva 3 meses en un proyecto. MEMORY.md tiene 175 líneas, todas relevantes. El proyecto va a empezar Phase 2 con un refactor significativo. Diseña una estrategia de rotación: ¿qué mueves, a dónde, qué mantienes?

cp .claude/agent-memory/code-reviewer/MEMORY.md \
   .claude/agent-memory/code-reviewer/phase-1-memory.md

### Phase awareness
- Phase 1 patterns archived in phase-1-memory.md
- If an issue seems related to Phase 1 code, check phase-1-memory.md
- Patterns discovered in Phase 2 take priority over Phase 1 entries
- Remove Phase 1 references from MEMORY.md if the code was refactored

Ejercicio 4: Detectar y corregir memoria stale (Medio)

Analiza este MEMORY.md y el estado actual del código. Identifica las entradas stale y escribe el MEMORY.md corregido.

MEMORY.md actual:

## Architecture Decisions
- Offset pagination on all endpoints
- SQLAlchemy 1.4 with sync sessions
- Monolithic architecture, single service

## Coding Conventions
- No type hints (team decided against them)
- print() for debugging, no logging library

## Known Patterns
- Auth: session-based with Flask-Login
- Validation: manual if/else checks in route handlers

Estado actual del código (pyproject.toml):

[project]
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.110",
    "sqlalchemy>=2.0",
    "pydantic>=2.0",
    "structlog>=24.0",
    "python-jose[cryptography]>=3.3",
]

## Architecture Decisions
- Cursor-based pagination (verify current implementation)
- SQLAlchemy 2.0 async sessions
- FastAPI application (migrated from Flask)

## Coding Conventions
- Type hints: required (Pydantic v2 enforces them on models)
- Structured logging via structlog (no print statements)

## Known Patterns
- Auth: JWT tokens via python-jose (migrated from session-based)
- Validation: Pydantic v2 models (migrated from manual checks)

## Recurring Issues
- [needs discovery] — previous issues likely resolved during migration

Ejercicio 5: Memory budget para un equipo de 3 subagents (Difícil)

Tienes 3 subagents con scope project (reviewer, implementer, tester). Define un "memory budget" — cuántas líneas máximas para cada agente y cada categoría, justificando las asignaciones. Budget disponible: 180 líneas por agente.

Resumen

• MEMORY.md tiene un límite práctico de 200 líneas — solo las primeras 200 se inyectan automáticamente en el contexto del subagent
• Organiza la memoria en 4 categorías: Architecture Decisions, Coding Conventions, Known Patterns, Recurring Issues
• Mantén el contenido más importante arriba — Architecture Decisions primero, Recurring Issues al final
• Curación = mantener, archivar, o eliminar — cada entry debe ser vigente, accionable, y no obvia
• Instruye al subagent para auto-curarse al final de cada sesión con reglas explícitas en el system prompt
• Rotación: mueve contenido a archivos secundarios (ARCHIVE.md, phase-X.md) cuando MEMORY.md se llena pero la información es valiosa
• Detecta memoria stale verificando entradas contra el código actual — decisiones revertidas y patrones deprecados confunden al agente
• Curación agresiva (~100 líneas) para proyectos activos, permisiva (~180 líneas) para proyectos estables
• El enfoque híbrido (auto-curación + revisión manual periódica) es el más robusto para la mayoría de equipos
• La memoria bien curada es prerequisito para el Módulo 3 — agentes paralelos necesitan memoria compartida sin ruido para coordinarse

Recursos Adicionales

1. Subagents — Persistent Memory (Anthropic Docs) — Documentación oficial del campo memory, scopes, y MEMORY.md
2. Create Custom Subagents — Referencia completa de frontmatter YAML incluyendo memory
3. Claude Code Best Practices — Buenas prácticas de gestión de contexto que aplican a curación de memoria
4. Prompt Engineering: Be Clear and Direct — Técnicas de claridad para instrucciones de auto-curación en system prompts
5. CLAUDE.md Documentation — Cómo CLAUDE.md complementa (no duplica) la memoria del agente
6. Claude Code Tips and Tricks — Tips sobre gestión de contexto y memory
7. Prompt Caching (Anthropic) — Cómo funciona el caching de contexto y por qué memorias más pequeñas son más eficientes
8. Claude Models — Contexto sobre ventanas de contexto y cómo el tamaño de memoria impacta el rendimiento

Siguiente cápsula: En la cápsula 05 construirás una jerarquía de memoria completa para los 3 subagents del Módulo 1. Configurarás scope project para el reviewer e implementer, local para el tester, agregarás instrucciones de curación a cada system prompt, y verificarás que la memoria persiste entre sesiones. Es el proyecto culminante del módulo — si tus 3 agentes recuerdan y curan su contexto, has dominado memory management.