Memoria en subagentes de Claude Code: cuándo usarla y cuándo no

TL;DR Sí en el subagente que lanzas a diario sobre el mismo repo, con dos frases en su cuerpo (consulta la memoria antes, guarda lo aprendido después) y el directorio en git. No en los de un solo uso ni en los de solo lectura: activar la memoria les devuelve Write y Edit aunque se los hubieras quitado.

Un subagente arranca vacío cada vez. Tu revisor, cuando lo lanzas el lunes, no sabe nada de lo que encontró el viernes: las convenciones del repo, el bug que se repite, dónde está cada cosa. Lo redescubre todo, gasta tokens en ello, y lo que aprende muere al devolver el resumen. Es el mismo motivo por el que devuelven resultados incompletos: no heredan nada, ni de tu conversación ni de sus propias ejecuciones anteriores.

El campo memory: del frontmatter le da un directorio propio. Al arrancar, su system prompt lleva las primeras 200 líneas o 25 KB del MEMORY.md que haya ahí, y mientras trabaja puede escribir en él. A la tercera ejecución llega sabiendo cómo funciona tu proyecto. No es la auto memory de tu sesión principal: es una libreta por agente, con su nombre en la ruta, que solo lee ese agente.

Resultado, tras una ejecución de prueba con memory: project en la que le pedí guardar un dato:

.claude/agent-memory/noter/
├── MEMORY.md                        # índice: una línea por entrada
└── project_secret_greeting_word.md  # la entrada, con frontmatter propio

# MEMORY.md
- [Project secret greeting word](project_secret_greeting_word.md) — the word is 'zanahoria'

El subagente decidió solo el formato: un índice de una línea por tema y un fichero por tema con name, description y un bloque de "por qué" y "cómo aplicarlo". Es el mismo esquema que usa la auto memory de la sesión principal, y viene en las instrucciones que el binario le inyecta junto con la ruta.

Cuándo sí

El candidato es el agente que lanzas varias veces por semana sobre el mismo repo y cuyo trabajo mejora con contexto acumulado: el revisor, el que escribe tests, el que conoce tu dominio.

1. La línea, y las dos frases que hacen que la use

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality and best practices
memory: project
---

You are a senior code reviewer for this repository.

Before you start, check your agent memory for conventions and recurring
issues you have already recorded. When you finish, save what you learned:
new patterns, repeated mistakes, where things live.

Sin las dos frases, la memoria existe pero el agente la usa cuando le parece. Con ellas, la consulta al empezar y la actualiza al terminar. La doc recomienda además pedirlo en el prompt de cada tarea ("revisa este PR y mira tu memoria antes"), pero con las frases en el cuerpo del agente no dependes de acordarte.

2. El ámbito

La doc recomienda project, y en el caso del revisor tiene sentido: lo que aprende sobre tu código lo hereda el revisor de tu compañero.

3. Mira git status tras la primera ejecución

Con project, el directorio aparece como untracked y lo comiteas. Con local, en mi prueba también apareció como untracked: el binario lleva una regla para excluir agent-memory-local del repositorio, pero la escribe el componente de tareas programadas, no el subagente, y en una sesión con -p el .git/info/exclude quedó vacío. Si eliges local, comprueba que no acabe en un commit.

Cuándo no

• Agentes de un solo uso. Un agente que busca, resume o hace un refactor mecánico no tiene nada que recordar. Lo que consigues es un arranque en frío más grande, porque el índice viaja en el system prompt de cada ejecución, y el subagente no comparte caché con tu sesión. Más informado sí, más económico no.
• Agentes con herramientas capadas. Activar la memoria les devuelve Read, Write y Edit para gestionar sus ficheros. Un revisor definido con tools: Read, Grep, Glob para que no toque nada deja de ser de solo lectura.
• user para conocimiento de proyecto. Una sola libreta para todos tus repos: lo que aprendió en uno lo aplica en otro donde no encaja.
• project en equipo sin acordarlo. El subagente de cada persona escribe en el repositorio, y esos ficheros entran en cada PR. Decidid quién lo comitea y cuándo, o usad local.
• Sin cuidar el índice. De MEMORY.md solo entran las primeras 200 líneas o 25 KB. Cuando una escritura se pasa, el binario avisa en la propia respuesta de la herramienta ("compact it now: keep one line per entry, move detail into topic files"). Lo que queda pasado el límite no existe para el agente.

Qué le llega de verdad al prompt

Dos ejecuciones sobre el mismo agente de prueba, en sesiones nuevas cada vez:

tools: Glob             + memory: project     →  "zanahoria", cero llamadas a herramientas
tools: Glob             + auto memory apagada →  dos Glob y "unknown"

En la primera, el agente no podía leer ficheros y aun así respondió: el dato estaba en la línea del índice, y esa línea iba dentro de su system prompt. En la segunda, con CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, el campo memory: no hizo nada: ni instrucciones ni herramientas, y el agente buscó a ciegas y se rindió. La memoria de subagentes depende de la auto memory: si la tienes desactivada con autoMemoryEnabled: false o esa variable, la línea del frontmatter es decorativa.

Documentación oficial: Enable persistent memory

Requisitos

• Comprobado en Claude Code v2.1.260, con un subagente en model: sonnet.
• Auto memory activada (es el valor por defecto).