Por qué los subagentes de Claude Code no comparten memoria — y cómo solucionarlo (2026)

El aislamiento es la funcionalidad por la que está pagando

Comience con el propósito de los subagentes. La documentación de Claude Code describe el caso de uso como una tarea secundaria que, de otro modo, inundaría su conversación principal con resultados de búsqueda, registros o contenidos de archivos a los que no volverá a hacer referencia: "el subagente hace ese trabajo en su propio contexto y devuelve solo el resumen". Cada uno "se ejecuta en su propia ventana de contexto con una instrucción del sistema personalizada, acceso a herramientas específicas y permisos independientes".

Es un buen trato y no debería querer deshacerlo. Diez mil líneas de salida de pruebas se quedan donde pertenecen, y su conversación principal recibe tres frases. Pero observe lo que implica esa misma frase: lo que sea que el subagente haya entendido en el camino —el contenedor de errores, la peculiaridad de nomenclatura, el hecho de que dos módulos no coincidan— existe solo en una ventana de contexto que ahora ha desaparecido. Lo que regresó fue el resumen, y el resumen es lo que el subagente consideró que valía la pena decir.

La memoria de la conversación principal no cruza el límite

Claude Code tiene memoria automática, activada por defecto, donde Claude escribe sus propias notas a medida que trabaja: comandos de compilación, ideas de depuración, preferencias que descubre. Estas viven por repositorio en ~/.claude/projects/<project>/memory/, con un índice MEMORY.md que se carga al inicio de cada conversación.

Cada conversación, es decir, excepto la de un subagente. La documentación lo establece directamente: "La memoria automática de la conversación principal no se carga en los subagentes". La única excepción es una bifurcación (fork), que hereda directamente la conversación principal y la instrucción del sistema. Por lo tanto, lo que su sesión principal aprendió sobre este repositorio el martes pasado no está disponible para el subagente que envíe hoy.

La memoria de cada subagente es su propio directorio

Los subagentes pueden guardar sus propias notas, y vale la pena habilitar esto. Agregue un campo memory a la definición de un subagente y este obtendrá un directorio persistente que sobrevive a las conversaciones, que la documentación describe como un lugar para "acumular conocimiento a lo largo del tiempo, como patrones de código base, ideas de depuración y decisiones arquitectónicas". Hay tres ámbitos disponibles: user escribe en ~/.claude/agent-memory/<name-of-agent>/, project escribe en .claude/agent-memory/<name-of-agent>/ y se puede compartir a través del control de versiones, y local escribe en .claude/agent-memory-local/<name-of-agent>/ y se queda fuera de git.

Lea esas rutas con cuidado, porque la respuesta a nuestra pregunta está en el nombre del directorio. La memoria está delimitada por el nombre del agente. El conocimiento acumulado del revisor está en la carpeta del revisor; el redactor de pruebas tiene su propia carpeta; y no hay una carpeta compartida que ambos lean. Dos características útiles también vienen con esta función e implican sus propios límites: la instrucción del sistema del subagente incluye las primeras 200 líneas o 25 KB de su MEMORY.md, lo que ocurra primero, y todo el mecanismo es parte de la memoria automática; desactive la memoria automática con autoMemoryEnabled o CLAUDE_CODE_DISABLE_AUTO_MEMORY y el campo memory no tendrá ningún efecto.

Dos subagentes integrados también omiten su CLAUDE.md

Hay otra brecha que sorprende a la gente, y está documentada: "Explore y Plan omiten sus archivos CLAUDE.md y el estado de git de la sesión principal para mantener la investigación rápida y económica. Todos los demás subagentes integrados y personalizados cargan ambos".

Explore es el subagente que va y lee su código base. Es el que más desearía que conociera sus convenciones, y es deliberadamente el que no lo hace. Es una decisión de rendimiento razonable, y significa que la investigación que alimenta su conversación principal fue realizada por algo que no había leído sus estándares.

Y nada de esto sale de la máquina

La memoria automática es local de la máquina. La documentación es inequívoca: todos los árboles de trabajo (worktrees) y subdirectorios de un repositorio comparten un directorio, y "Los archivos no se comparten entre máquinas o entornos en la nube". Lo mismo ocurre con los directorios por agente, a menos que confirme (commit) los que tienen ámbito de project.

Así que el conocimiento acumulado de su equipo de agentes vive en una sola computadora portátil, en carpetas por agente, invisible para sus otras herramientas y para sus compañeros de equipo, a menos que decida registrar partes de él deliberadamente. Lo cual está bien para los comandos de compilación. No está bien para la razón por la cual un módulo está fuera de los límites.

Poner todo en `CLAUDE.md`. El primer paso correcto, y de hecho llega a todos los subagentes excepto a Explore y Plan. El límite es el tamaño: la documentación recomienda apuntar a menos de 200 líneas por archivo porque los archivos más largos consumen más contexto y reducen el cumplimiento de las instrucciones. Un CLAUDE.md lo suficientemente grande como para contener lo que cuatro subagentes han aprendido es un CLAUDE.md que nadie sigue.

Escribir instrucciones de subagente más largas. Funciona para instrucciones permanentes, no funciona para descubrimientos. Puede informarle al redactor de pruebas sobre el contenedor de errores una vez que lo conozca, pero el punto era que el revisor lo sabía y usted no.

Decirle al subagente que escriba un archivo. "Guarda lo que aprendiste en notes/review-findings.md". Es efectivo, y básicamente es crear manualmente la función de memoria. Está bien hasta que tiene cuatro agentes, cuatro archivos y ninguna convención sobre quién lee cuál.

Usar bifurcaciones (forks) en su lugar. Una bifurcación hereda la conversación principal y la instrucción del sistema, lo que realmente resuelve el problema de "no sabe lo que discutimos", a costa del ahorro de contexto que deseaba. Es la herramienta adecuada para continuar su propio pensamiento, pero la herramienta incorrecta para aislar una tarea ruidosa.

Habilitar la memoria por agente y esperar que sea suficiente. Habilítela; el ámbito project es la recomendación documentada porque hace que ese conocimiento se pueda compartir a través del control de versiones. Solo no espere que sea un cerebro compartido. Es un cuaderno por agente, y la documentación lo describe exactamente así.

Ejecutar menos subagentes. La gente termina aquí después de la tercera contradicción. Funciona, y es una verdadera pérdida: está pagando contexto para evitar una brecha de coordinación.

El aislamiento debe mantenerse. Lo que debe cambiar es que el "contexto aislado" y el "conocimiento aislado" son actualmente lo mismo, y no tiene por qué ser así.

La estructura que funciona es un almacén compartido que la conversación principal y cada subagente puedan leer y escribir, situado junto a la memoria por agente en lugar de reemplazarla. Los descubrimientos que importan más allá de una sola tarea —el contenedor de errores, la decisión, el ayudante obsoleto— van allí, y cada agente lee la misma versión. La memoria por agente sigue guardando lo que es genuinamente local para el oficio de ese agente.

MemoryLake es una capa de memoria para eso: un almacén único donde viven sus decisiones, convenciones y documentos de origen, accesible a través de MCP desde Claude Code y sus subagentes, desde Codex y desde ChatGPT a través de la API. No es otro cuaderno por agente: es un único registro con varios lectores.

Paso 1: Crear una clave API

Genere una clave y realice su primera solicitud en unos 30 segundos. Manténgala en su entorno o en un gestor de secretos en lugar de pegarla en una sesión.

Paso 2: Subir sus primeras memorias

Suelte los documentos, imágenes y archivos que sus agentes siguen redescubriendo: las convenciones, las decisiones de arquitectura, los informes de incidentes detrás de sus reglas, los contratos de API, la lista de "no tocar esto" con los motivos adjuntos. Suba las fuentes en lugar de un resumen; un resumen es lo que un subagente ya le entrega, y la compresión es el problema que está resolviendo.

Paso 3: Conectar su IA y agentes

Dé acceso a la memoria a Claude, Codex, OpenClaw y otros agentes de IA a través de MCP o la API. Claude Code la lee a través de MCP junto con sus archivos CLAUDE.md, y puede delimitar el acceso por subagente: la documentación señala que declarar un servidor MCP en línea en el campo mcpServers de un subagente mantiene las descripciones de sus herramientas completamente fuera del contexto de la conversación principal; el subagente obtiene las herramientas, el padre no. Así es como le da al revisor y al redactor de pruebas la misma memoria sin gastar el contexto del padre en ello.

La primera diferencia es que un descubrimiento sobrevive a la tarea que lo produjo. El revisor nota el contenedor de errores, lo escribe en el almacén compartido y el redactor de pruebas lo lee una hora más tarde, sin que usted tenga que ser el bus de mensajes entre dos agentes que no pueden verse.

La segunda es que su CLAUDE.md puede mantenerse lo suficientemente corto como para ser efectivo. En lugar de hacer crecer un archivo hacia el tamaño donde disminuye el cumplimiento de las instrucciones, las reglas permanentes se quedan en el archivo y los detalles acumulados se trasladan a la recuperación de información. Esta es la misma razón por la que un agente que vuelve a leer su código base en cada sesión es costoso: el conocimiento existe, simplemente no está donde el agente busca.

La tercera es que el conocimiento sobrevive a la computadora portátil. La memoria automática y la memoria por agente son locales de la máquina por diseño; un almacén compartido es donde las partes que su equipo necesita —las decisiones, los motivos, las convenciones— dejan de ser los archivos locales de un desarrollador. Esa es la diferencia entre que un colega pueda preguntar "por qué esto está fuera de los límites" y tener que preguntarle a usted.

Y no entra en conflicto con lo que Claude Code hace de forma nativa. La memoria automática sigue escribiendo comandos de compilación y notas de depuración por repositorio. La memoria por agente sigue acumulando el conocimiento del oficio de cada subagente. Ninguna de las dos tiene que convertirse en un sistema de registro, que es el rol para el que están menos preparadas, y es la misma división del trabajo que hace que varios agentes en una sola memoria sea algo viable.

Active la memoria por agente, en el ámbito de proyecto

memory: project es la recomendación documentada, y la razón es buena: el directorio se registra en el control de versiones, por lo que el conocimiento acumulado de un subagente puede ser revisado por su equipo en lugar de quedar atrapado en su directorio de inicio. Use local solo para notas que realmente no deban confirmarse.

Solicite lecturas y escrituras de memoria de forma explícita

La documentación sugiere exactamente esto: indique al subagente que consulte su memoria antes de comenzar ("revisa tu memoria para ver patrones que hayas visto antes") y que la actualice al terminar ("guarda lo que aprendiste"). Mejor aún, coloque esas instrucciones en el propio cuerpo de markdown del subagente para que se mantenga a sí mismo sin que usted tenga que recuerdarlo.

Mantenga MEMORY.md como un índice, no como un almacén

Solo se cargan las primeras 200 líneas o 25 KB de MEMORY.md; el contenido posterior no se carga al inicio de la sesión. Mantenga una línea por entrada y mueva los detalles a archivos temáticos, que Claude lee bajo demanda. Un índice de memoria que se desborda silenciosamente es peor que uno corto, porque creerá que está en el contexto.

Asuma que Explore no ha leído sus convenciones

Dado que Explore y Plan omiten CLAUDE.md por diseño, no trate sus hallazgos como si conocieran las convenciones. Si el resultado de una investigación va a impulsar una edición, vuelva a enunciar la regla relevante cuando actúe en consecuencia, o dele a Explore una memoria compartida que pueda consultar, que es la versión más duradera de la misma solución.

No confunda ninguno de los dos tipos de memoria con la aplicación de reglas

La documentación de Claude Code dice que los archivos de instrucciones y la memoria automática son "contexto, no una configuración obligatoria", sin garantía de cumplimiento estricto. Cualquier cosa que deba ser cierta siempre —nunca tocar archivos generados, ejecutar siempre el linter— pertenece a un hook o a una verificación de CI. La memoria es para saber; los hooks son para garantizar. Cualquiera que le venda la memoria como cumplimiento normativo le está vendiendo humo.

Escriba el motivo, no solo el hallazgo

"Pagos utiliza un contenedor de errores personalizado" es un hecho que será cuestionado. "Pagos utiliza un contenedor de errores personalizado porque el cliente ascendente absorbe los códigos de estado; consulte el incidente de marzo" es un hecho que sobrevive a ser cuestionado por el próximo agente y el próximo ingeniero.

Los subagentes de Claude Code no comparten memoria porque no comparten contexto, y ese aislamiento es la funcionalidad clave: cada uno trabaja en su propia ventana y devuelve solo un resumen. La situación de la memoria es más matizada que "no tienen ninguna". Pueden tener memoria persistente, por agente, en un directorio con el nombre del agente, en el ámbito de usuario, proyecto o local. Lo que no existe es una superficie compartida: la memoria automática de la conversación principal no se carga en los subagentes, los directorios por agente no se leen entre sí, Explore y Plan omiten su CLAUDE.md por completo y todo esto se queda en una sola máquina.

Así que mantenga el aislamiento y solucione el intercambio. Habilite la memoria por agente en el ámbito de proyecto, mantenga MEMORY.md como un índice, trate a Explore como ciego a las convenciones y coloque el conocimiento que importa a más de un agente en un almacén único que todos lean. De este modo, el segundo agente comenzará a partir de lo que aprendió el primero, y usted dejará de ser la capa de integración entre sus propios subagentes.