Memoria multiagente Claude Code: gobierna qué se promueve

TL;DR: La memoria persistente entre agentes en Claude Code acelera handoffs, pero arrastra supuestos viejos y errores si no decides qué se promueve y qué queda temporal. En esta guía verás cuándo conviene activar memoria compartida, qué criterios usar para promover observaciones y qué riesgos aparecen cuando dos o más agentes leen del mismo almacén.

El problema: contexto compartido no es lo mismo que contexto correcto

Llevo varios meses usando Claude Code con plugins de memoria persistente para no reexplicar el proyecto en cada sesión. Funciona bien cuando trabajas solo. El día que añadí un segundo agente para revisar PRs, la cosa se torció: el revisor citaba decisiones de arquitectura que ya habíamos descartado dos semanas antes.

El problema no era el modelo. Era que la memoria guardaba todo como si fuera verdad permanente, sin distinguir entre una decisión final y una idea desechada a mitad de discusión.

Si estás moviendo tu flujo de prompts sueltos a un sistema con memoria reutilizable (Claude Code, claude-mem, MCPs tipo Engram), la pregunta clave deja de ser "¿cómo guardo contexto?" y pasa a ser "¿qué se promueve a memoria y qué debe quedarse temporal?".

¿Qué es la memoria persistente multiagente?

La memoria persistente multiagente es una capa de almacenamiento compartida entre varios agentes de IA que sobrevive a la sesión, captura decisiones y contexto, y los inyecta selectivamente cuando otro agente retoma el trabajo.

En la práctica se implementa de tres maneras distintas:

Archivos locales tipo CLAUDE.md o MEMORY.md versionados en el repo.
Plugins MCP con base de datos local (Engram, claude-mem) que indexan observaciones por tipo y proyecto.
Servicios externos como Mem0 o Letta con API propia y permisos por agente.

Cada opción tiene un coste distinto y una superficie de error distinta. La parte interesante no es la tecnología: es la política de qué guardar.

Por qué importa antes de añadir un segundo agente

Cuando trabajas con un solo agente, la memoria persistente es casi siempre ganancia neta: te ahorra reexplicar el stack, las convenciones y las decisiones. El propio agente que escribió la memoria es el que la lee.

Con dos o más agentes (por ejemplo, uno que implementa y otro que revisa), aparecen tres problemas que no existían:

Sesgo heredado: el agente B confía en lo que escribió A sin verificar que sigue siendo cierto.
Decisiones obsoletas como verdades: ideas descartadas quedan registradas como "decisión" y se citan meses después.
Permisos opacos: un agente con scope reducido lee observaciones generadas por otro con scope mayor.

El patrón es el mismo problema que vivimos en bases de datos compartidas hace 20 años, solo que ahora el lector es probabilístico y no te lanza un error si interpreta mal.

Criterio práctico: qué promover a memoria

Después de bastantes iteraciones, el filtro que mejor me funciona es preguntar tres cosas antes de guardar algo:

Pregunta	Si la respuesta es...	Acción
¿Es verificable releyendo el código?	Sí	No guardar. Que el agente lo lea cuando lo necesite.
¿Sigue siendo cierto dentro de 3 meses?	Probablemente no	Marcar como temporal con fecha de caducidad.
¿Lo aplicaría otro agente sin contexto extra?	Sí	Promover a memoria persistente con el porqué.

Regla simple: guarda decisiones y restricciones, no estado. El código ya es el estado.

Tipos de memoria que sí merecen persistencia

Decisiones de arquitectura con el motivo (por qué FastAPI y no Django, no qué endpoints existen).
Convenciones del proyecto que no están en linters (formato de commits, naming de tests).
Restricciones del entorno (la VPS solo tiene 4 GB de RAM, la API tiene rate limit de 60 req/min).
Preferencias del usuario validadas (rechazos repetidos, patrones aceptados).

Tipos que mejor dejar fuera

Listado de archivos o rutas (el agente las descubre con fd o rg).
Resúmenes de commits o PRs recientes (git log ya existe).
Estado en curso de una tarea (eso va en plan o todo, no en memoria).
Recetas de debugging puntuales (el fix está en el commit; la memoria envejece mal).

Estructura mínima de un registro de memoria

Para que un segundo agente pueda usar una observación sin contaminarse, cada registro necesita al menos cuatro campos. Esto es lo que uso con claude-mem y plugins similares:

---
name: feedback-tests-integracion
type: feedback
created: 2026-05-13
expires: never
scope: backend-api
---
Los tests de migraciones deben hitear PostgreSQL real, no mocks.

**Why:** En 2025-Q4 una migración pasó tests mockados y rompió producción.
**How to apply:** Solo en tests con prefijo `test_migration_*`. El resto pueden mockar.

Los campos scope y expires son los que cambian todo cuando entra un segundo agente. Sin scope, un agente de frontend recibe restricciones de backend que no le aplican. Sin expires, las decisiones temporales se vuelven permanentes por inercia.

Gobernanza entre agentes: tres patrones que funcionan

Patrón 1: memoria por scope, no global

Cada agente lee solo el subconjunto de memoria que le aplica. Si tienes un agente implementador y uno revisor, no comparten todo: el revisor lee convenciones y restricciones, no las preferencias de estilo del implementador.

En Claude Code esto se traduce en tener varios CLAUDE.md por subdirectorio o usar el campo scope de tu plugin de memoria.

Patrón 2: promoción explícita, no automática

Muchos plugins capturan todo lo que pasa y lo guardan. Cómodo, pero peligroso. El patrón que mejor envejece es promoción explícita: el agente propone guardar algo, el humano confirma. La fricción es el feature, no el bug.

Si tu plugin no soporta esto, una alternativa barata: dejar que el agente escriba en un archivo candidatos.md y revisarlo al final del día antes de moverlo a MEMORY.md.

Patrón 3: caducidad por defecto

Todo registro nuevo tiene caducidad de 30 días salvo que lo marques como expires: never. Suena radical, pero fuerza a renovar lo que sigue siendo útil y a tirar lo que no. Las decisiones reales no envejecen mal porque las renuevas al usarlas.

En producción

Cuando llevas esto a un equipo o a un flujo serio, aparecen consideraciones que no ves en el tutorial:

Coste de tokens: cada observación cargada en el contexto cuesta. Una memoria de 500 entradas mal filtradas puede consumir 8.000 tokens por turno sin que el agente las necesite. Mide cuánta memoria entra realmente en el system prompt.
Versionado: si la memoria vive en archivos del repo, va a Git y tiene historial. Si vive en una base local, necesitas un backup. Yo prefiero la primera opción cuando se puede, por lo mismo que defendí en su día la separación de responsabilidades: el código y las decisiones que lo gobiernan deberían viajar juntos.
Permisos: si un agente tiene acceso de escritura a memoria global, cualquier prompt injection puede plantar observaciones falsas. Trata la memoria como input no confiable y revísala periódicamente.
Rollback: ten un mecanismo para "olvidar" una observación cuando descubres que está mal. git revert funciona si la memoria está en archivos.

El presupuesto de tokens es donde más fácil se descontrola: en un proyecto medio con tres agentes y memoria mal podada, he visto fácil 15-20€ extra al mes solo en contexto repetido.

Errores comunes y depuración

Error: el agente cita una decisión que ya cambiamos → Causa: registro sin fecha o sin supersedes. → Solución: cuando una decisión reemplaza a otra, marca la anterior como obsoleta en lugar de borrarla; deja la traza.
Error: dos agentes guardan la misma observación con palabras distintas → Causa: no hay deduplicación semántica. → Solución: revisa periódicamente con un agente dedicado a fusionar duplicados, o usa un plugin que detecte candidatos al guardar.
Error: el agente revisor aplica reglas que no le tocan → Causa: scope global por defecto. → Solución: marca scope explícito en cada observación y filtra en el cargador.
Error: la memoria crece sin parar → Causa: ningún proceso poda. → Solución: revisión mensual con un slash command que liste observaciones no usadas en N días.

Preguntas frecuentes

¿Necesito un plugin MCP o me basta con CLAUDE.md?

Para proyectos pequeños o de una persona, un buen CLAUDE.md versionado en el repo cubre el 80% de los casos. El plugin MCP empieza a compensar cuando tienes varios agentes, varios proyectos o quieres búsqueda semántica sobre el histórico.

¿Qué pasa si dos agentes escriben memoria a la vez?

Depende del backend. Los plugins serios usan transacciones; los que escriben en archivo plano pueden corromper datos. Si trabajas con paralelismo real, verifica que tu plugin de memoria soporta escritura concurrente antes de confiarle decisiones importantes.

¿Cuánta memoria es demasiada?

No hay número mágico, pero si tu memoria consume más del 10% del contexto del modelo en cada turno, estás cargando demasiado. Mide y poda. Es preferible que el agente lea código que cargar mil observaciones por si acaso.

Cierre

La memoria persistente multiagente no es un upgrade gratuito sobre la sesión única. Resuelve el problema de reexplicar contexto, pero introduce uno nuevo: decidir qué merece sobrevivir a la sesión y qué debe morir con ella. La regla que mejor envejece es promoción explícita, scope por agente y caducidad por defecto.

Si ya tienes un flujo con varios agentes y memoria compartida, esta semana prueba a auditar tus últimas 50 observaciones con las tres preguntas del filtro: cuántas son verificables releyendo el código, cuántas seguirán siendo ciertas en tres meses y cuántas aplicaría otro agente sin contexto extra. Las respuestas suelen sorprender.

¿Cómo gestionas tú la memoria entre agentes? Cuéntamelo en Twitter @sergiomarquezp_. En el próximo post entraremos en cómo aplicar este mismo criterio cuando la memoria viene de un MCP externo con permisos finos.