Módulo 2: Agent Memory y Scopes

1. Introducción al Módulo — El Problema de la Memoria Efímera

Descripción

Tus subagents del módulo anterior funcionan — el reviewer revisa, el implementer corrige, el tester verifica. Pero tienen un problema fundamental: son amnésicos. Cada vez que invocas al reviewer, empieza de cero. No recuerda que la semana pasada señaló los mismos patrones problemáticos. No sabe que el equipo decidió usar snake_case para todas las funciones. No retiene las decisiones arquitecturales que ya se discutieron. Cada ejecución es como contratar a un consultor nuevo que nunca ha visto tu proyecto.

Memory scopes resuelven esto. Permiten que cada subagent persista contexto entre sesiones con diferentes niveles de alcance: user (todas tus sesiones en cualquier proyecto), project (compartible via git con tu equipo), y local (proyecto-específico pero privado). La diferencia entre un agente sin memoria y uno con memoria bien configurada es la diferencia entre un consultor externo que viene una vez y un miembro del equipo que acumula conocimiento institucional.

En este módulo vas a configurar una jerarquía de memoria que permite a tus subagents recordar patrones del codebase, decisiones de arquitectura, y convenciones del equipo — y verificarás que esa memoria persiste entre sesiones y se comparte de forma controlada.

¿Dónde Estamos en la Guía?

Contexto en el Path

Phase 1: Subagents Avanzados
├── Módulo 1: Custom Subagents                    ← completado
├── Módulo 2: Agent Memory y Scopes               ← ESTÁS AQUÍ
└── Módulo 3: Parallel Sub-Agent Delegation

Phase 2: Agent Teams y Plugins (Módulos 4-6)
Phase 3: Orquestación (Módulos 7-8)

En el Módulo 1 creaste subagents con identidad propia — roles, restricciones, system prompts. Ahora les das memoria. Sin este módulo, tus agentes son herramientas potentes pero olvidadizas. Con él, se convierten en colegas que aprenden de tu proyecto.

¿Hacia dónde vamos?

Este módulo es el segundo pilar de Phase 1. La progresión es deliberada:

Módulo 1: Crear agentes con identidad ← completado
Módulo 2: Dar memoria a esos agentes ← AQUÍ — resolver el problema de la amnesia
Módulo 3: Poner agentes a trabajar en paralelo — necesitan memoria compartida para no tomar decisiones contradictorias

La memoria es prerequisito para la delegación paralela. Agentes paralelos sin contexto compartido generan resultados inconsistentes — el frontend agent usa camelCase mientras el backend agent usa snake_case porque ninguno sabe qué decidió el otro.

El Problema: Agentes que Olvidan Todo

El escenario frustrante

Ejecutas tu reviewer subagent en un proyecto Python:

Sesión 1 (lunes):
reviewer → "Encontré 3 funciones sin type hints en src/api/routes.py"
         → "La convención del proyecto debería ser snake_case, encontré 2 inconsistencias"

Sesión 2 (miércoles):
reviewer → "Encontré 3 funciones sin type hints en src/api/routes.py"  ← mismos issues
         → "No puedo determinar la convención de naming del proyecto"  ← olvidó snake_case

El reviewer detecta los mismos problemas porque no recuerda haberlos señalado. No sabe que el equipo ya decidió la convención de naming. Cada sesión parte desde cero, repitiendo análisis y perdiendo contexto valioso.

El costo real

Sin memoria persistente:

Repetición: Los mismos issues se reportan una y otra vez
Inconsistencia: Cada ejecución puede producir recomendaciones diferentes
Pérdida de contexto: Decisiones arquitecturales se olvidan entre sesiones
Ineficiencia: El agente re-descubre lo que ya sabía

Con memoria persistente:

Acumulación: El agente aprende patrones del codebase con cada ejecución
Consistencia: Aplica las mismas convenciones siempre
Contexto: Recuerda decisiones previas y las respeta
Eficiencia: Se enfoca en issues nuevos, no en redescubrir los conocidos

Lo que se pierde sin memoria

Piensa en todo el contexto valioso que un agente descubre durante una sesión:

Sesión de 20 minutos con el reviewer:

Descubrimientos:
- "src/api/ usa un patrón service → repository → model"
- "Las funciones helper están en src/utils/ organizadas por dominio"
- "El proyecto tiene 3 módulos con >500 líneas que podrían refactorizarse"
- "La convención de naming es snake_case para todo excepto clases"
- "Hay 2 dependencias deprecadas en requirements.txt"
- "Los tests usan pytest con fixtures en conftest.py"

Todo este conocimiento → se pierde al cerrar la sesión

Cada uno de esos descubrimientos tomó tiempo y tokens. Sin memoria, el agente vuelve a descubrirlos — pagando el mismo costo de tiempo y tokens cada vez. Con memoria, los registra una vez y los reutiliza siempre.

El impacto en costos

No es solo un problema de calidad — es un problema de eficiencia medible:

Sin memoria: Cada sesión gasta ~30% de tokens en redescubrir el codebase
Con memoria: Ese 30% se invierte una vez y se reutiliza en cada sesión posterior
En un proyecto con 5 sesiones semanales: La memoria ahorra ~120% de tokens por semana en trabajo redundante

La analogía

Imagina un equipo de desarrollo donde cada mañana todos pierden la memoria del día anterior. Cada standup es una reintroducción completa. Cada PR review empieza desde "¿cuáles son nuestras convenciones?" Eso es lo que pasa con subagents sin memoria — técnicamente capaces, pero institucionalmente ignorantes.

Cómo Funciona la Memoria en Claude Code

El mecanismo: MEMORY.md

Cuando habilitas memoria para un subagent, Claude Code crea un directorio dedicado con un archivo MEMORY.md que el agente puede leer y escribir. Este archivo se inyecta automáticamente en el system prompt del subagent (las primeras 200 líneas), dándole acceso a su conocimiento acumulado al inicio de cada sesión.

Subagent sin memoria:
system_prompt = [tu system prompt]

Subagent con memoria (user scope):
system_prompt = [tu system prompt] + [primeras 200 líneas de ~/.claude/agent-memory/{name}/MEMORY.md]

El subagent puede actualizar MEMORY.md durante la ejecución — agregar patrones descubiertos, decisiones registradas, o insights del codebase. Estos cambios persisten para la siguiente sesión.

Los tres scopes

Scope	Ubicación	Cuándo usar
`user`	`~/.claude/agent-memory/{name}/`	Conocimiento universal: convenciones personales, patrones generales, preferencias
`project`	`.claude/agent-memory/{name}/`	Conocimiento del proyecto: arquitectura, convenciones del equipo, decisiones técnicas. Compartible via git
`local`	`.claude/agent-memory-local/{name}/`	Conocimiento del proyecto pero privado: credenciales, notas personales, experiments

La diferencia clave entre project y local: project se puede commitear a git y compartir con el equipo. Local es gitignored — solo tú lo ves.

Objetivo del Módulo

Al terminar este módulo serás capaz de:

✅ Explicar los tres scopes de memoria (user, project, local) y cuándo usar cada uno
✅ Configurar el campo memory en el frontmatter de un subagent para habilitar persistencia
✅ Instruir al subagent para que actualice su memoria proactivamente con patrones y decisiones
✅ Verificar que el contexto persiste entre sesiones: ejecutar, cerrar, reabrir, y confirmar retención
✅ Diseñar una estrategia de memoria para un proyecto: qué va en user, qué en project, qué en local
✅ Implementar curación de memoria: mantener MEMORY.md relevante, limpio, y dentro del límite de 200 líneas

Objetivo profesional

En tu próximo proyecto, cada subagent que crees tendrá memoria configurada. Tu reviewer recordará los patrones del codebase. Tu implementer recordará las convenciones del equipo. Cuando un nuevo miembro se una al equipo y clone el repo, los subagents con scope project traerán el conocimiento institucional — la arquitectura, las decisiones, las convenciones — sin que nadie tenga que explicar nada.

Roadmap del Módulo

Mapa de cápsulas

#	Cápsula	Qué aprenderás	Tipo
01	Introducción (esta)	El problema de la memoria efímera, los tres scopes, MEMORY.md	Intro
02	Memory Scopes en Profundidad	Configurar user/project/local, el campo memory en frontmatter, instrucciones de curación en system prompts	Técnica
03	Compartir Memoria entre Subagents	Estrategias para que múltiples subagents accedan a contexto compartido, read-only vs read-write, convenciones	Técnica
04	Memory Management	Curación de MEMORY.md, rotación de contenido obsoleto, priorización de contexto relevante, límite de 200 líneas	Técnica
05	Proyecto: Memory Hierarchy	Configurar una jerarquía de memoria completa para un proyecto con 3 subagents y verificar persistencia	Proyecto

Flujo de aprendizaje

Primero entenderás cómo habilitar memoria en un subagent y cómo difieren los tres scopes (cápsula 02). Luego verás cómo múltiples subagents pueden compartir contexto — porque un reviewer y un implementer que no comparten conocimiento producen resultados inconsistentes (cápsula 03). Después aprenderás cómo mantener la memoria útil — porque memoria infinita confunde más que ayuda (cápsula 04). Finalmente, construirás una jerarquía completa para un proyecto real y verificarás que todo persiste (cápsula 05).

La progresión es: habilitar memoria → compartir entre agentes → mantener relevante → construir sistema completo.

Duración estimada del módulo: 1-1.25 horas.

Conexión con el Proyecto

Mini-proyecto de este módulo: Memory Hierarchy

En la cápsula 05 configurarás una jerarquía de memoria para los 3 subagents del Módulo 1:

Reviewer con scope project — recuerda patrones del codebase y los comparte con el equipo via git
Implementer con scope project — recuerda convenciones de código y decisiones arquitecturales
Tester con scope local — recuerda resultados de tests previos y coverage trends (privado, no compartido)

Verificarás la persistencia ejecutando cada subagent, cerrando la sesión, reabriendo, y confirmando que recuerdan lo aprendido.

Conexión con el proyecto final (Módulo 8)

La memoria configurada aquí es crítica para el proyecto integrador. Un sistema de 5 agentes sin memoria compartida es caótico — el backend agent no sabe qué decidió el frontend agent, el tester no sabe qué cambió. Memory scopes son el "cerebro compartido" del sistema multi-agente.

Prerequisitos

Conocimientos necesarios

✅ Módulo 1 completado — Sabes crear subagents custom con frontmatter YAML y system prompts
✅ Git básico — Entiendes commits, .gitignore, y por qué algo se commitea o no
✅ CLAUDE.md funcional — Tienes un proyecto con configuración de Claude Code activa

Verificación rápida

Si puedes responder "sí" a estas preguntas, estás listo:

¿Tienes al menos un subagent custom creado en .claude/agents/?
¿Sabes qué campos van en el frontmatter YAML de un subagent?
¿Entiendes la diferencia entre archivos que se commitean a git y archivos que se gitignoran?
¿Has experimentado la frustración de que un agente "olvide" contexto de sesiones anteriores?

No necesitas

❌ Experiencia con bases de datos o storage systems — la memoria son archivos Markdown simples
❌ Conocimiento de Agent Teams — eso es módulo 4
❌ Scripts de automatización — todo se configura en el frontmatter del subagent
❌ Experiencia con caching o estado persistente — el concepto es más simple de lo que parece

Setup para el Módulo

Lo que necesitas tener listo

1. Subagents del Módulo 1 funcionando:

Deberías tener al menos un subagent custom en tu proyecto. Si completaste el Módulo 1, tienes tres (reviewer, implementer, tester) en .claude/agents/. Verifica:

ls .claude/agents/

Si ves tus archivos .md, estás listo. Si no, crea al menos uno básico:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Grep, Glob, Bash
model: haiku
---

You are a code reviewer. Analyze code changes and provide actionable feedback.

2. Proyecto con historial de git:

La memoria con scope project se commitea a git. Necesitas un proyecto con al menos 3 commits para que el reviewer tenga algo que analizar.

git log --oneline -5

3. Verificar que los directorios de memoria existen (o se pueden crear):

# Estos se crean automáticamente cuando habilitas memoria,
# pero puedes verificar que tienes permisos
mkdir -p .claude/agent-memory
mkdir -p .claude/agent-memory-local
ls ~/.claude/agent-memory/ 2>/dev/null || echo "Se creará automáticamente"

4. Un editor de texto para inspeccionar MEMORY.md:

Durante el módulo verificarás el contenido de MEMORY.md manualmente. Cualquier editor funciona, pero tener uno a mano te permite ver la memoria que tu agente acumula en tiempo real.

Conceptos Clave que Usaremos

Antes de entrar a las cápsulas técnicas, asegúrate de tener claros estos conceptos:

Memory scope: El alcance de la memoria de un subagent. Define dónde se almacena y quién puede acceder. Los tres scopes son user, project, y local.
MEMORY.md: El archivo Markdown donde el subagent almacena su conocimiento acumulado. Se lee automáticamente al inicio de cada sesión (primeras 200 líneas).
Persistencia: La capacidad del subagent de retener información entre sesiones. Sin memoria, cada sesión empieza de cero.
Curación: El proceso de mantener MEMORY.md relevante — eliminar información obsoleta, priorizar lo importante, respetar el límite de 200 líneas.
Memoria compartida: Cuando múltiples subagents pueden acceder al mismo conocimiento, ya sea leyendo la misma memoria o complementando memorias separadas.

La relación entre CLAUDE.md y Agent Memory

Es natural preguntarse: "¿No es CLAUDE.md suficiente para dar contexto?" CLAUDE.md es estático — tú lo escribes y lo actualizas manualmente. Agent memory es dinámica — el agente la construye mientras trabaja. Son complementarios:

CLAUDE.md = Lo que TÚ le dices al agente sobre el proyecto (estático)
MEMORY.md = Lo que el AGENTE aprende del proyecto (dinámico)

CLAUDE.md: "Este proyecto usa FastAPI con PostgreSQL. Sigue PEP 8."
MEMORY.md: "src/api/routes.py tiene 3 funciones sin type hints.
           El equipo prefiere snake_case. La función process_order
           en src/services/ es la más compleja del codebase."

CLAUDE.md define las reglas. MEMORY.md registra lo aprendido dentro de esas reglas.

Límites: Qué NO Se Cubre en Este Módulo

❌ Delegación paralela — Se cubre en el Módulo 3. Aquí los subagents trabajan en secuencia
❌ Agent Teams y task boards — Se cubre en el Módulo 4. Aquí la coordinación es manual
❌ Memory en Agent Teams — Concepto avanzado que se toca cuando llegues a Agent Teams
❌ Bases de datos o storage externo — La memoria de Claude Code usa archivos Markdown, no DBs
❌ SDK headless con memoria — Se cubre en el Módulo 6

Evidencia de Éxito

Al terminar este módulo, sabrás que tuviste éxito si:

✅ Puedes explicar la diferencia entre user, project, y local memory scopes en una frase cada uno
✅ Tu reviewer subagent recuerda patrones del codebase entre sesiones
✅ Al cerrar y reabrir Claude Code, verificas que MEMORY.md contiene el contexto acumulado
✅ Puedes decidir qué scope usar para cada tipo de información (credenciales → local, convenciones → project, preferencias → user)
✅ Tu MEMORY.md está curado — relevante, dentro del límite, y sin información obsoleta
✅ Un colega que clona tu repo obtiene el conocimiento del proyecto via memory scope project

Test rápido de autoevaluación

Si puedes responder estas preguntas al terminar el módulo, vas por buen camino:

¿Dónde se almacena la memoria de un subagent con scope project?
¿Cuántas líneas de MEMORY.md se inyectan automáticamente en el system prompt?
¿Por qué usarías local en vez de project para un tester?
¿Qué pasa si MEMORY.md supera las 200 líneas?
¿Cómo verificas que la memoria persiste entre sesiones?

Nota sobre Compatibilidad

La funcionalidad de agent memory requiere Claude Code versión 2.1.63 o posterior. El campo memory en el frontmatter YAML es funcionalidad estable (GA). Si usas una versión anterior, actualiza antes de comenzar este módulo:

claude --version

# Si necesitas actualizar
npm update -g @anthropic-ai/claude-code

Última verificación de funcionalidad: Marzo 2026

Resumen

Los subagents del Módulo 1 son capaces pero amnésicos — cada sesión empieza de cero
Memory scopes resuelven esto con tres niveles: user (global), project (compartible via git), local (privado)
El mecanismo es MEMORY.md — un archivo que el subagent lee al iniciar y actualiza durante la ejecución
Las primeras 200 líneas de MEMORY.md se inyectan automáticamente en el system prompt
La curación de memoria es un skill: mantener el contexto relevante, limpio y dentro del límite
La memoria configurada aquí es prerequisito para delegación paralela (Módulo 3) y Agent Teams (Módulo 4)

Recursos Adicionales

Subagents — Persistent Memory (Anthropic Docs) — Documentación oficial del campo memory en subagents
Create Custom Subagents — Referencia completa de frontmatter incluyendo memory
CLAUDE.md Best Practices — Buenas prácticas que complementan la memoria del agente
Claude Code Overview — Contexto general de persistencia en Claude Code
Skills Documentation — Skills que se pueden combinar con memoria
Hooks Reference — Hooks que pueden interactuar con el ciclo de memoria

Siguiente cápsula: En la cápsula 02 configurarás memoria real en tus subagents. Verás cómo un solo campo en el frontmatter (memory: project) transforma a un agente amnésico en uno que acumula conocimiento — y verificarás la persistencia con tus propios ojos.

← Anterior5. Proyecto — Pipeline de 3 Subagents Especializados Siguiente →2. Memory Scopes en Profundidad