2. Memory Scopes en Profundidad

Descripción

En la cápsula anterior viste el problema — subagents amnésicos que repiten análisis, olvidan convenciones, y empiezan de cero cada sesión. También viste la solución a nivel conceptual: tres scopes de memoria (user, project, local) y un archivo MEMORY.md que persiste contexto. Ahora es momento de implementarlo.

Configurar memoria en un subagent es agregar un campo al frontmatter YAML. Pero elegir el scope correcto, escribir instrucciones que guíen al subagent sobre qué recordar, y verificar que la persistencia realmente funciona — eso requiere práctica deliberada. Un subagent con memoria mal configurada es peor que uno sin memoria: acumula ruido, alcanza el límite de 200 líneas con información irrelevante, y sus decisiones se contaminan con contexto obsoleto.

En esta cápsula vas a configurar memoria en los tres scopes, escribir system prompts que instruyen al subagent a curar su propia memoria, verificar persistencia entre sesiones, y aplicar todo al reviewer e implementer del proyecto de la cápsula 05.

El Campo memory en el Frontmatter

Sintaxis de configuración

Habilitar memoria es agregar una línea al frontmatter YAML del subagent file:

---
name: code-reviewer
description: Reviews code for quality
memory: project
---

El campo memory acepta exactamente tres valores:

Si no incluyes el campo memory, el subagent no tiene persistencia. Cada sesión empieza sin contexto previo.

Lo que ocurre cuando habilitas memoria

Al agregar memory: project a un subagent llamado code-reviewer, Claude Code:

1. Crea el directorio .claude/agent-memory/code-reviewer/ si no existe
2. Crea MEMORY.md vacío en ese directorio si no existe
3. Inyecta las primeras 200 líneas de MEMORY.md en el system prompt del subagent al inicio de cada sesión
4. Habilita automáticamente las herramientas Read, Write, y Edit para que el subagent pueda gestionar su archivo de memoria
5. Agrega instrucciones al system prompt indicándole al subagent cómo leer y escribir en su directorio de memoria

Esas herramientas se habilitan adicionales a las que defines en tools. Si tu reviewer tiene tools: Read, Glob, Grep, con memory: project tendrá acceso a Read, Glob, Grep más Write y Edit — pero solo para archivos dentro de su directorio de memoria.

Sin memoria:
  tools disponibles = [Read, Glob, Grep]

Con memory: project:
  tools disponibles = [Read, Glob, Grep]
  + Write/Edit habilitados SOLO para .claude/agent-memory/code-reviewer/*

Scope user: Conocimiento Personal Universal

Cuándo usarlo

El scope user almacena memoria en tu directorio home (~/.claude/agent-memory/{name}/). No está asociado a ningún proyecto — es tuyo, disponible en cualquier repositorio donde uses ese subagent.

---
name: style-enforcer
description: Enforces personal coding style preferences across all projects
memory: user
---

Qué guardar en user scope

• 📝 Preferencias de estilo personal (indentación, naming, comentarios)
• 📝 Patrones que usas frecuentemente en cualquier proyecto
• 📝 Convenciones de documentación personal

Ejemplo: enforcer de estilo personal

Crea ~/.claude/agents/style-enforcer.md:

---
name: style-enforcer
description: Enforces personal coding style preferences across all projects
tools: Read, Glob, Grep
disallowedTools: Write, Edit
model: haiku
maxTurns: 10
memory: user
---

## Role
You enforce coding style preferences. You read code and report
deviations from the style preferences stored in your memory.
You NEVER modify code files.

## Memory Management
On first run (empty MEMORY.md):
- Ask what style preferences the user wants to enforce
- Save preferences to MEMORY.md in structured format

On subsequent runs:
- Read MEMORY.md for established preferences
- Apply preferences to code review
- Add new preferences if the user mentions them

## Output Format
### Style Report
**Preferences applied:** [count from memory]
#### Deviations Found
- **[file:line]** — Expected: [preference] | Found: [deviation]
#### Summary: [n] deviations in [n] files

La primera vez que ejecutas este subagent, MEMORY.md está vacío y preguntará tus preferencias. La segunda vez ya las conoce y las aplica directamente.

Scope project: Conocimiento del Equipo

Cuándo usarlo

El scope project almacena memoria en .claude/agent-memory/{name}/ — dentro del proyecto, versionable con git. Es el scope más poderoso porque permite que todo el equipo comparta el conocimiento acumulado del subagent.

Qué guardar en project scope

• 🏗️ Decisiones arquitecturales del proyecto
• 🏗️ Convenciones de código del equipo
• 🏗️ Patrones comunes del codebase
• 🏗️ Bugs recurrentes y sus soluciones

Ejemplo: reviewer con memoria de proyecto

Actualiza tu .claude/agents/reviewer.md del Módulo 1:

---
name: reviewer
description: Reviews recent code changes for quality, security, and best practices
tools: Read, Glob, Grep, Bash
disallowedTools: Write, Edit
model: haiku
maxTurns: 15
permissionMode: plan
memory: project
---

## Role
You are a code reviewer. You analyze recent git changes and produce
a structured report. You NEVER modify any file except your MEMORY.md.

## Memory Management
Update your agent memory as you discover codepaths, patterns, library
locations, and key architectural decisions. This builds up institutional
knowledge across conversations. Write concise notes about what you found
and where.

When updating MEMORY.md:
- Add patterns you observe repeatedly
- Record architectural decisions mentioned in comments or PR descriptions
- Note recurring issues so you can flag them proactively next time
- Keep entries concise: one line per pattern/decision
- If MEMORY.md exceeds 150 lines, consolidate redundant entries

## Review Process
1. Read MEMORY.md for context on known patterns and previous findings
2. Run `git diff HEAD~3 --name-only` to identify changed files
3. Read each changed file completely
4. Apply review criteria WITH context from memory
5. Update MEMORY.md with new patterns discovered
6. Produce the report

## Output Format
### Code Review Report
**Date:** [current date]
**Files reviewed:** [list]
**Memory context:** [relevant patterns from MEMORY.md applied]
#### CRITICAL (must fix)
- **[file:line]** — Description
#### WARNING (should fix)
- **[file:line]** — Description
#### Summary
- Critical: [n] | Warnings: [n] | Suggestions: [n]
- Verdict: PASS | PASS_WITH_WARNINGS | NEEDS_REVISION
#### Memory Updates
- [list what was added to MEMORY.md this session]

Cómo evoluciona la memoria del reviewer

Sesión 1 — MEMORY.md vacío:

# Reviewer Memory

## Architecture
- FastAPI project with SQLAlchemy ORM
- Routes in src/routes/, models in src/models/

## Conventions
- Snake_case for all Python identifiers
- Type hints required on all public functions

Sesión 3 — acumulación:

# Reviewer Memory

## Architecture
- FastAPI + SQLAlchemy + Alembic + PostgreSQL
- Background tasks in src/tasks/ using Celery
- Redis caching layer in src/cache/

## Conventions
- Snake_case for all Python identifiers
- All endpoints return standardized {data, error, meta} response
- Exceptions use custom AppError hierarchy (src/exceptions.py)

## Resolved Issues
- routes/products.py:45 SQL injection — FIXED in commit abc123

El reviewer ahora sabe la arquitectura, las convenciones, y los issues previos. Cuando revisa código nuevo, aplica este contexto sin que tú repitas nada.

Compartir con el equipo

git add .claude/agent-memory/reviewer/MEMORY.md
git commit -m "chore: update reviewer memory with project patterns"
git push

Cuando un colega hace pull, su reviewer subagent hereda todo ese conocimiento.

Scope local: Conocimiento Privado del Proyecto

Cuándo usarlo

El scope local almacena memoria en .claude/agent-memory-local/{name}/ — dentro del proyecto, pero gitignored automáticamente. Para información que no debe compartirse.

Qué guardar en local scope

• 🔒 Tokens y credenciales de entornos de desarrollo
• 🔒 Resultados de tests de tu máquina específica
• 🔒 Notas personales sobre el proyecto

Ejemplo: tester con memoria local

---
name: tester
description: Runs test suites and reports results
tools: Bash, Read, Glob
disallowedTools: Write, Edit
model: haiku
maxTurns: 10
memory: local
---

## Role
You are a test runner and reporter. You NEVER modify source code.

## Memory Management
Track test results across sessions:
- Record pass/fail counts per module after each run
- Note flaky tests (tests that sometimes pass, sometimes fail)
- Track coverage percentages over time
Keep MEMORY.md under 100 lines — summarize old results, keep recent ones.

## Output Format
### Test Report
**Comparison with last run:** [improved/degraded/stable]
#### Results
- ✅ Passed: [n] (previous: [n from memory])
- ❌ Failed: [n] (previous: [n from memory])
#### Coverage
| Module | Current | Previous | Trend |
|--------|---------|----------|-------|
| [module] | [%] | [% from memory] | ↑/↓/= |
#### Verdict: ALL_PASS | FAILURES | ERROR

El tester usa local porque los resultados dependen de tu máquina — versiones, base de datos local, variables de entorno. No tiene sentido commitear eso.

Comparación: ¿Qué Scope Para Qué?

Tabla de decisión

La regla de tres preguntas

Cuando no sepas qué scope usar:

1. ¿Es información de TODOS mis proyectos?  → user
2. ¿El equipo necesita esta información?     → project
3. ¿Es específica de MI entorno?             → local

Estructura en disco

my-project/
├── .claude/
│   ├── agents/
│   │   ├── reviewer.md          # memory: project
│   │   ├── implementer.md       # memory: project
│   │   └── tester.md            # memory: local
│   └── agent-memory/
│       ├── reviewer/
│       │   └── MEMORY.md        # ← compartido via git
│       └── implementer/
│           └── MEMORY.md        # ← compartido via git
├── .claude/agent-memory-local/
│   └── tester/
│       └── MEMORY.md            # ← gitignored
└── .gitignore

~/.claude/
└── agent-memory/
    └── style-enforcer/
        └── MEMORY.md            # ← personal, todos los proyectos

Instrucciones de Memoria en el System Prompt

Por qué importa lo que escribes

Habilitar memory: project crea la infraestructura. Pero la calidad de la memoria depende de lo que el subagent decide guardar. Sin instrucciones claras, un subagent puede guardar todo (memoria saturada en la primera sesión), no guardar nada (memoria habilitada pero vacía), o guardar irrelevancia (ruido que confunde).

Patrón: instrucciones estructuradas

## Memory Management

Update your agent memory as you discover codepaths, patterns, library
locations, and key architectural decisions. This builds up institutional
knowledge across conversations. Write concise notes about what you found
and where.

### What to Remember
- Architecture patterns (directory structure, design patterns in use)
- Team conventions (naming, formatting, error handling approach)
- Key decisions (why X library over Y, why this architecture)
- Recurring issues (bugs that keep appearing, common mistakes)

### What NOT to Remember
- Specific code content (it changes — reference files instead)
- One-time issues already fixed
- Personal opinions or subjective assessments

### Format Rules
- One line per entry when possible
- Group by category (Architecture, Conventions, Issues, Patterns)
- If MEMORY.md exceeds 150 lines, consolidate: merge similar entries,
  remove outdated ones, summarize old sections

Patrón: curación activa

## Memory Curation

Before writing to MEMORY.md, read it first. Then:
1. Check if the new information already exists — don't duplicate
2. Check if any existing entry is now outdated — update or remove it
3. If adding pushes past 150 lines, consolidate the oldest section
4. Always keep the most recent and most actionable items

Think of MEMORY.md as a living document, not a log.

Verificar la Persistencia

El test de humo

Paso 1: Ejecuta el subagent y dale contexto que debería recordar.

Usa el reviewer para analizar src/routes/products.py

Paso 2: Verifica que escribió en MEMORY.md.

cat .claude/agent-memory/reviewer/MEMORY.md

Paso 3: Cierra Claude Code completamente.

Paso 4: Reabre Claude Code y ejecuta el reviewer de nuevo.

Usa el reviewer para analizar src/routes/users.py

Paso 5: Verifica que el reporte referencia contexto de la sesión anterior. El reviewer debería mencionar patrones aprendidos o aplicar convenciones que descubrió en la sesión 1.

Paso 6: Inspecciona MEMORY.md de nuevo.

cat .claude/agent-memory/reviewer/MEMORY.md

Debería tener entradas de ambas sesiones, organizadas sin duplicados.

Verificación para scope project

git status
# Deberías ver: new file: .claude/agent-memory/reviewer/MEMORY.md

Verificación para scope local

git status
# NO debería mostrar archivos en .claude/agent-memory-local/

ls .claude/agent-memory-local/tester/MEMORY.md
# El archivo existe pero git lo ignora

Ejemplo: Implementer con Memoria de Proyecto

El implementer necesita recordar convenciones de código para aplicarlas consistentemente:

---
name: implementer
description: Implements code changes in src/ following project conventions
tools: Read, Glob, Grep, Write, Edit, Bash
model: sonnet
maxTurns: 30
memory: project
---

## Role
You are a senior developer implementing code changes in src/.
Follow existing project conventions — never introduce new patterns.

## Memory Management
Update your agent memory with:
- Code conventions you observe (naming, structure, error handling)
- Architectural decisions referenced in code comments or CLAUDE.md
- Library-specific patterns (e.g., "sessions use context manager")
- File/module purposes you discover

Keep MEMORY.md organized by category. Consolidate if over 150 lines.
When implementing, ALWAYS check MEMORY.md first for conventions.

## Constraints
- ONLY modify files inside src/
- NEVER modify test files, config files, or CLAUDE.md
- Follow conventions from MEMORY.md — they represent team agreements

## Output Format
### Implementation Report
**Files modified:** [list]
**Conventions applied from memory:** [list]
**Changes made:**
1. **[file]** — Description of change
   - Convention: [which memory entry guided this decision]
**Memory updates:** [what was added to MEMORY.md]

Conexión con el Proyecto

Hacia la cápsula 05: Memory Hierarchy para 3 Subagents

En la cápsula 05 implementarás una jerarquía de memoria completa:

reviewer    → memory: project ← comparte patrones del codebase con el equipo
implementer → memory: project ← comparte convenciones de código con el equipo
tester      → memory: local   ← resultados de tests son privados

La configuración que hiciste aquí es el building block. Lo que añade la cápsula 05 es la coordinación: ¿qué pasa cuando el reviewer y el implementer tienen memorias independientes? ¿Cómo evitas inconsistencias? La cápsula 03 (siguiente) aborda exactamente eso.

Troubleshooting

"MEMORY.md está vacío después de ejecutar el subagent"

Causa: El system prompt no incluye instrucciones de memoria suficientemente explícitas. El subagent tiene la capacidad de escribir pero no sabe qué guardar.

Fix: Agrega una sección ## Memory Management con instrucciones imperativas: "Update your agent memory as you discover..." no "You might want to remember..."

"MEMORY.md creció demasiado rápido — ya tiene 200+ líneas"

Causa: El subagent guarda todo sin curar.

Fix: Agrega instrucciones de curación:

If MEMORY.md exceeds 150 lines, before adding new entries:
1. Merge similar entries into summaries
2. Remove entries about files that no longer exist
3. Archive resolved issues

"El subagent no lee su MEMORY.md al inicio"

Causa: Las primeras 200 líneas se inyectan automáticamente. Si MEMORY.md tiene información trivial al principio, el contexto inyectado no ayuda.

Fix: Estructura MEMORY.md con las secciones más importantes primero. Arquitectura, convenciones, y patrones frecuentes van en las primeras 200 líneas.

"El scope project no aparece en git status"

Causa: El directorio .claude/agent-memory/ fue agregado al .gitignore por error.

Fix:

cat .gitignore | grep agent-memory
# Solo .claude/agent-memory-local/ debe estar en gitignore
# .claude/agent-memory/ (sin -local) NO debe estar en gitignore

"Dos subagents con el mismo nombre comparten memoria"

Causa: El directorio de memoria usa el name del frontmatter. Nombres iguales = mismo directorio.

Fix: Usa nombres únicos: reviewer-security y reviewer-performance, no dos reviewer.

Ejercicios

Ejercicio 1: Habilitar memoria básica (Fácil)

Toma el subagent todo-finder del Módulo 1 y agrégale scope user. Debe recordar cuántos TODOs encontró en cada sesión para reportar tendencias.

---
name: todo-finder
description: Finds all TODO and FIXME comments across the codebase
memory: user
---

Search for comments containing TODO, FIXME, HACK, or XXX.

## Memory Management
After each scan, record in MEMORY.md:
- Date of scan and total count by type (TODO, FIXME, HACK, XXX)
- Compare with previous scan and note trend (increasing/decreasing)
Keep only the last 10 scan results in memory.

### TODO/FIXME Report
**Trend:** [count] total ([+/-n] vs last scan from memory)
#### FIXME (urgent)
- **[file:line]** — Comment text
#### TODO (planned)
- **[file:line]** — Comment text
**Total:** [count] items found

Ejercicio 2: Elegir el scope correcto (Fácil)

Para cada escenario, indica el scope correcto (user, project, o local):

1. Un subagent que recuerda las API keys de staging
2. Un subagent que recuerda la arquitectura de un proyecto con 5 devs
3. Un subagent que recuerda tus patrones de error handling en todos tus proyectos
4. Un subagent que recuerda qué tests fueron flaky en tu laptop
5. Un subagent que recuerda las dependencias del proyecto y por qué se eligieron

Ejercicio 3: Escribir instrucciones de memoria (Medio)

Escribe la sección ## Memory Management para un subagent dependency-auditor que revisa dependencias de un proyecto Python. Debe recordar: versiones actuales, vulnerabilidades, y decisiones de por qué se eligió cada dependencia.

## Memory Management

Update your agent memory after each audit:

### What to Remember
- Current dependency versions and when they were last audited
- Known vulnerabilities: severity, status (open/fixed/accepted-risk)
- Decisions: why each key dependency was chosen over alternatives
- Version constraints: why certain packages are pinned
- Incompatibilities discovered between packages

### What NOT to Remember
- Transitive dependencies (too many, too volatile)
- Exact vulnerability CVE details (link to advisory instead)

### Format
| Package | Version | Why Chosen | Last Audited |
|---------|---------|------------|--------------|
| fastapi | 0.104.0 | Team standard | 2026-03-10 |

### Curation Rules
- Update versions after each audit, don't append duplicates
- Remove vulnerability entries once fixed and verified
- If over 100 lines, archive old audit dates — keep only latest

Ejercicio 4: Verificar persistencia end-to-end (Medio)

Configura el reviewer con memory: project. Ejecuta estos pasos y documenta qué ves:

1. Ejecuta el reviewer en un archivo del proyecto
2. Lee MEMORY.md y verifica que tiene contenido
3. Cierra Claude Code
4. Reabre y ejecuta el reviewer en un archivo diferente
5. Verifica que el reporte referencia contexto de la sesión anterior
6. Confirma que MEMORY.md tiene entradas de ambas sesiones sin duplicados

# Paso 1: Ejecutar reviewer
# > "Usa el reviewer para analizar src/routes/products.py"

# Paso 2: Verificar
cat .claude/agent-memory/reviewer/MEMORY.md
# Esperado: entradas sobre patterns de products.py

# Paso 3: Cerrar
# exit

# Paso 4-5: Reabrir y ejecutar en otro archivo
# > "Usa el reviewer para analizar src/routes/users.py"
# Esperado: el reporte menciona contexto de la sesión 1

# Paso 6: Verificar MEMORY.md
cat .claude/agent-memory/reviewer/MEMORY.md
# Esperado: entradas de AMBAS sesiones, organizadas sin duplicados

Ejercicio 5: Diseñar la jerarquía de memoria (Difícil)

Tienes un proyecto con 4 subagents: reviewer, implementer, tester, doc-generator. Diseña qué scope usa cada uno, qué categorías de información guarda, y justifica la elección. Presenta como tabla.

Ejercicio 6: Depurar memoria corrupta (Difícil)

Tu MEMORY.md tiene 250 líneas: session log de 80 líneas, notas random, y las secciones críticas (Architecture, Conventions) están después de la línea 200 (no se inyectan). Reestructura para que quepa en 150 líneas con las prioridades al inicio.

## Session Log
- 2026-01-15: Reviewed products.py...
... (80 entries)
## Random Notes
- The team uses PostgreSQL
- There might be a performance issue
## Architecture (line ~180)
- FastAPI + SQLAlchemy + Alembic
## Conventions (line ~220)
- Snake_case everywhere

# Reviewer Memory

## Architecture
- Stack: FastAPI + SQLAlchemy + Alembic + PostgreSQL
- Routes in src/routes/, models in src/models/
- Repository pattern for DB access

## Conventions
- Snake_case for all Python identifiers
- Type hints required on all public functions

## Active Issues
- routes/products.py: N+1 query (found 2026-01-19)

## Resolved Issues
- routes/products.py:45 SQL injection — fixed (2026-01-17)

## Review Summary
- 5 reviews completed (Jan 15-19, 2026)

Resumen

• El campo memory en el frontmatter acepta tres valores: user, project, local
• user (~/.claude/agent-memory/{name}/) es personal y aplica a todos los proyectos
• project (.claude/agent-memory/{name}/) se comparte via git — conocimiento del equipo
• local (.claude/agent-memory-local/{name}/) es privado y gitignored — secretos y datos locales
• Al habilitar memoria, MEMORY.md se inyecta (primeras 200 líneas) en el system prompt automáticamente
• El subagent recibe Read, Write, Edit habilitados para su directorio de memoria
• La calidad de la memoria depende de las instrucciones en el system prompt — sé explícito sobre qué recordar y cuándo curar
• Verificar persistencia requiere ejecutar → cerrar → reabrir → confirmar retención
• La regla de tres preguntas: ¿todos mis proyectos? → user. ¿El equipo lo necesita? → project. ¿Solo mi entorno? → local
• Las primeras 200 líneas son críticas — pon lo más importante al inicio de MEMORY.md
• Los 3 subagents con memoria son el building block del proyecto de la cápsula 05

Recursos Adicionales

1. Subagents — Persistent Memory (Anthropic Docs) — Documentación oficial del campo memory y sus scopes
2. Create Custom Subagents — Referencia completa de frontmatter incluyendo memory
3. Claude Code Best Practices — Buenas prácticas de organización de contexto aplicables a MEMORY.md
4. CLAUDE.md Documentation — Cómo CLAUDE.md complementa la memoria del agente
5. Claude Code Overview — Contexto general de persistencia en Claude Code
6. Prompt Engineering: System Prompts — Principios transferibles a instrucciones de memoria
7. Claude Code Tips and Tricks — Tips sobre organización de contexto
8. Git Best Practices — Versionar archivos de configuración compartida

Siguiente cápsula: En la cápsula 03 abordarás el problema de la memoria compartida. Tienes un reviewer y un implementer, ambos con memory: project, pero con memorias independientes. ¿Cómo evitas que tomen decisiones contradictorias? Verás estrategias para compartir contexto entre subagents sin que se sobrescriban.