La diferencia entre un agente que aprende y uno que olvida todo al cerrar la sesión. CLAUDE.md, Auto Memory, Subagent Memory, y sistemas externos.
Imagina que contratas a un neurocirujano de élite para operar en tu hospital. El primer día llega, revisa los protocolos de la institución (CLAUDE.md), lee el historial clínico del paciente actual (contexto de sesión), y consulta su libreta de notas personales donde anotó lo aprendido del último caso similar (MEMORY.md). Durante la operación recuerda de forma instintiva técnicas practicadas miles de veces (memoria procedural). Al terminar, actualiza su libreta con los hallazgos del día.
El problema: Si ese cirujano sufre amnesia cada vez que sale del quirófano, no puede crecer. Cada operación empieza desde cero. Sin memoria persistente, los agentes AI son brillantes dentro de una sesión, amnésicos entre sesiones.
B Según "State of AI Agent Memory 2026" (Mem0.ai, abril 2026):
A Taxonomía adoptada por Anthropic, LangChain, Mem0 y el campo AI agents en general:
Todo lo que el modelo "ve" en una sola llamada. Mensajes, herramientas usadas, resultados en curso. Limitada a la ventana de contexto.
"La semana pasada falló X cuando hacíamos Y." Historial de interacciones y eventos específicos. MEMORY.md es la implementación en Claude Code.
Hechos fijos: "este proyecto usa Python 3.11, FastAPI, PostgreSQL." CLAUDE.md encapsula esta memoria semántica del proyecto.
Cómo hacer las cosas: workflows, comandos, procedimientos. Skills y comandos slash en Claude Code implementan esto.
B Primer benchmark controlado de memoria en coding agents (Markus Sandelin, Medium, enero 2026). Mismo repositorio de 10K líneas, 50 tareas idénticas:
| Condición | Tareas completadas | Errores repetidos | Tiempo promedio |
|---|---|---|---|
| Sin memoria | 34/50 — 68% | 8.2 por sesión | 23 min/tarea |
| Con MEMORY.md | 43/50 — 86% (+18pp) | 1.9 por sesión | 17 min/tarea |
| MEMORY.md + Skills | 47/50 — 94% (+26pp) | 0.4 por sesión | 14 min/tarea |
A 5 capas de memoria con prioridad y scope distintos. Haz clic en cada capa para ver detalles:
/compact para compresión manual con resumen denso./memory abre el selector de archivos de memoria para revisión y edición manual.
user (global, todos los proyectos) · project (este proyecto) · local (esta instalación, en .gitignore).A Archivo Markdown leído automáticamente al iniciar Claude Code en cualquier directorio. No es una instrucción ordinaria — define cómo el agente debe actuar en ese contexto específico.
Orden de carga (todos se concatenan, son aditivos):
1. ~/.claude/CLAUDE.md → configuración global personal
2. /proyecto/CLAUDE.md → contexto del proyecto
3. /proyecto/src/CLAUDE.md → sub-contexto del módulo src
4. /proyecto/src/api/CLAUDE.md → sub-contexto del módulo api
↑
Claude trabaja aquí → carga TODOS los anteriores
# CLAUDE.md — API Gateway Service ## Stack técnico - Python 3.11, FastAPI 0.110, PostgreSQL 15, Redis 7 - Infraestructura: AWS ECS + RDS, Terraform 1.7 - CI/CD: GitHub Actions, deploy auto a staging en merge a main ## Arquitectura (Hexagonal) - /src/domain/ → lógica de negocio pura (sin dependencias externas) - /src/adapters/ → implementaciones de ports (DB, cache, HTTP) - /src/application/ → casos de uso que orquestan el dominio - NUNCA importar desde adapters en domain/ — es la regla #1 ## Comandos frecuentes - make test → suite completa (pytest + cobertura 80%+) - make lint → ruff + mypy --strict - make dev → docker compose up -d + uvicorn reload ## Reglas críticas - NUNCA hardcodear credenciales (usar variables de entorno) - NUNCA modificar migraciones ya aplicadas en producción - Antes de cualquier DELETE masivo: confirmar con el usuario - PRs requieren: tests + cobertura + type hints + docstrings Google ## Equipo - Lead arquitectura: María González — consultar cambios de estructura - Revisor seguridad: Juan Pérez — revisar cualquier auth change
| Zona | Límite recomendado | Razón |
|---|---|---|
| CLAUDE.md raíz del proyecto | 60–100 líneas | Se recarga en toda sesión; cada línea consume tokens |
| CLAUDE.md de módulo | 20–40 líneas | Solo se carga si Claude trabaja en ese directorio |
| CLAUDE.md global (~/.claude/) | 30–50 líneas | Aplica a TODOS los proyectos — máxima abstracción |
A MEMORY.md es escrito autónomamente por Claude Code durante y después de las sesiones, sin intervención humana. Diferencia clave con CLAUDE.md: lo escribe el agente, no el humano.
INICIO DE SESIÓN:
1. Claude lee las primeras 200 líneas de MEMORY.md (o 25KB)
2. Inyecta ese contenido en su system prompt como contexto
3. Habilita Read, Write, Edit para gestionar memoria
DURANTE LA SESIÓN:
4. Claude trabaja normalmente
5. Cuando detecta algo relevante (bug recurrente, patrón nuevo,
preferencia del usuario) → escribe nota en MEMORY.md
AL FINALIZAR (hook Stop):
6. Si MEMORY.md supera 200 líneas → Claude reorganiza y comprime
7. Mueve notas detalladas a archivos secundarios
8. MEMORY.md queda como índice ejecutivo ≤200 líneas
# MEMORY.md — Proyecto API-Gateway # Auto-generado por Claude Code · Última actualización: 2026-05-18 ## Patrones aprendidos - El timeout de Redis debe ser 500ms, no el default 1000ms (causaba timeouts en tests de carga — aprendido 2026-04-12) - Los tests de integración requieren REDIS_URL=redis://localhost:6380 (puerto 6380, hay conflicto con otro servicio en 6379) ## Errores frecuentes a evitar - NO usar asyncio.run() dentro de endpoint FastAPI (ya es async) → RuntimeError: This event loop is already running - La tabla user_sessions tiene índice en (user_id, expires_at) → Las queries de purga DEBEN usar AMBAS columnas ## Preferencias del usuario - Gerardino prefiere analogías antes del código técnico - Al hacer refactoring: mostrar diff compacto, no archivo completo - Commits: Conventional Commits (feat/fix/chore/docs/refactor) ## Estado actual del proyecto - Feature en curso: rate limiting por tenant Branch: feat/rate-limiting (en progreso desde 2026-05-15) - Bloqueador: esperando Redis Cluster en staging (DevOps ETA: semana próxima) ## Archivos detallados - Debugging → memory/debugging.md (14 patrones documentados) - API Contracts → memory/api_contracts.md (23 endpoints) - Seguridad → memory/security.md (LEER SIEMPRE)
A Ejecutar /memory durante cualquier sesión abre el selector de archivos de memoria y permite:
.claude/
MEMORY.md ← índice ejecutivo (≤200 líneas)
memory/
architecture.md ← decisiones de arquitectura y sus razones
debugging.md ← errores frecuentes y soluciones probadas
api_contracts.md ← contratos de API y excepciones conocidas
security.md ← reglas de seguridad específicas del proyecto
team.md ← preferencias del equipo y responsabilidades
A Introducida en Claude Code v2.1.33 (febrero 2026). Da a cada subagente nombrado su propio almacén de conocimiento persistente, separado del agente orquestador.
Motivación: Sin esta feature, todos los subagentes de un sistema multi-agente compartían el mismo MEMORY.md del proyecto, causando colisiones — el subagente de testing mezclaba notas con el de documentación.
---
name: api-specialist
description: Especialista en endpoints REST y OpenAPI
model: claude-sonnet-4-5
memory:
scopes:
- user # ~/.claude/agents/api-specialist/MEMORY.md
- project # .claude/agents/api-specialist/MEMORY.md
max_lines: 150 # límite personalizado (default: 200)
sections: # estructura predefinida
- name: "Patrones de API"
description: "Convenciones de naming, versionado, formatos de respuesta"
- name: "Errores conocidos"
description: "Problemas recurrentes y sus soluciones"
- name: "Estado actual"
description: "En qué está trabajando este agente"
---
Eres un especialista en APIs REST para el proyecto [X].
Lee SIEMPRE tu memoria al inicio. Escribe en ella al finalizar.
| Scope | Ubicación del MEMORY.md | Alcance |
|---|---|---|
user |
~/.claude/agents/{name}/MEMORY.md |
Todas las instancias del agente en TODOS los proyectos del usuario |
project |
.claude/agents/{name}/MEMORY.md |
Todas las instancias del agente en ESTE proyecto (en git) |
local |
.claude/agents/{name}/MEMORY.local.md |
Solo esta instalación local (en .gitignore, no se comparte) |
# Agente security-reviewer con memoria acumulativa cross-proyecto:
memory:
scopes:
- user # Aprende patrones de seguridad en todos los proyectos
- project # Reglas específicas de este proyecto
- local # Credenciales de test locales (no en git)
B Basado en benchmark LOCOMO (ECAI 2025) y "State of AI Agent Memory 2026" (Mem0.ai, abril 2026):
⚠️ Las barras representan utilidad relativa general, no solo accuracy. Zep y LangMem tienen otros casos de uso válidos donde destacan.
El equipo de Developer Experience usó CLAUDE.md para definir sus 200+ convenciones de API, y MEMORY.md para que el agente acumulara conocimiento sobre inconsistencias históricas y excepciones no documentadas.
Clave del éxito: El CLAUDE.md del equipo de APIs tiene exactamente 73 líneas — todo lo accionable, nada de explicaciones. La historia y el razonamiento están en /docs/ADR/ (Architecture Decision Records).
Cognition implementó memoria multi-proyecto para Devin usando Mem0 (para memoria semántica de patrones de código) + archivos CLAUDE.md por cliente (para contexto de proyecto específico).
Resultado: Devin puede onboardear a un nuevo repositorio de un cliente existente 40% más rápido porque ya "conoce" los patrones de código del cliente de proyectos anteriores.
Block (Square + Cash App) usa 100+ skills como forma de memoria procedural. Cada skill encapsula un workflow complejo que el agente ejecuta consistentemente — incluyendo el agente de debug de pagos POS.
Insight: Los skills son memoria procedural codificada — el agente no necesita "recordar" cómo debuggear un pago; lo tiene documentado como procedimiento estándar.
claude-mem captura conversaciones al finalizar cada sesión via lifecycle hooks, las comprime semánticamente con AI, y las almacena en SQLite con búsqueda full-text. En el siguiente inicio, recupera e inyecta el contexto más relevante.
npm install -g claude-mem claude-mem init claude-mem search "timeout redis" claude-mem export --format markdown > dump.md
| Anti-patrón | Síntoma | Solución |
|---|---|---|
| CLAUDE.md como manual | 400+ líneas con explicaciones históricas | Solo instrucciones accionables; historia → /docs/ADR/ |
| MEMORY.md como log de chat | Copia literal de conversaciones — imposible leer | Solo notas concisas de patrones, no transcripciones |
| Credenciales en MEMORY.md | API keys en texto plano en el archivo de memoria | Variables de entorno; MEMORY.md es texto plano en git |
| Nunca limpiar la memoria | Notas de hace 18 meses, muchas ya incorrectas | Memory audit mensual con /memory o claude-mem |
| Misma memoria para todos los agentes | Subagentes de distintos dominios mezclando conocimiento | Subagent Memory con scopes independientes (v2.1.33) |
| Ignorar el límite de 200 líneas | MEMORY.md de 800 líneas; solo se leen 200 | Índice ≤200 líneas + archivos secundarios por dominio |
| Capa | Cuándo NO usarla |
|---|---|
| CLAUDE.md muy largo | Si supera 150 líneas, dividir en submódulos. Más largo = más tokens = más lento y costoso en cada sesión. |
| MEMORY.md sin estructura | Sin secciones definidas, se convierte en un dump inútil en 2 semanas. Siempre definir secciones al inicializar. |
| Auto Memory en proyectos confidenciales | El agente puede escribir información sensible en texto plano. Revisar y filtrar qué se permite persistir. |
| Subagent Memory para agentes temporales | Si el agente no se reutilizará, el overhead de gestionar memoria no vale. Solo para agentes long-lived. |
| Mem0/Zep para proyectos pequeños | Agregan latencia y complejidad innecesaria. CLAUDE.md + MEMORY.md es suficiente para proyectos <10 devs. |
| Full context como estrategia de escala | 72.9% accuracy pero 9.87s y 26K tokens — insostenible a escala. Usar solo como baseline de evaluación. |