La memoria compartida para agentes de código con IA es un almacén a nivel de proyecto con decisiones, correcciones y notas de traspaso que cada agente lee al empezar y al que añade mientras trabaja, para que una sesión nueva no arranque desde cero. Sin ella, cada sesión de Claude Code o Codex solo sabe lo que hay en el repositorio y en sus archivos de instrucciones. Con ella, el siguiente agente sabe por qué elegiste JWT, que el usuario ya dijo «nada de dependencias nuevas» y que el último agente dejó a medias el flujo de reembolsos.
Este artículo explica por qué los agentes olvidan, qué debe ir en una memoria compartida y cómo el Brain de AgentVera construye una a partir del historial de tu proyecto y deja que los agentes la lean y la escriban por MCP.
Por qué los agentes de código olvidan
La memoria de un agente de código es su ventana de contexto. Cuando termina la sesión, o cuando se compacta la conversación, casi todo lo ocurrido desaparece. La siguiente sesión recibe:
- El prompt del sistema y las definiciones de herramientas
- Tus archivos de instrucciones, como
CLAUDE.mdoAGENTS.md - Lo que lea del repositorio durante la tarea
Eso funciona para el código, porque el código está en el repositorio. Falla con los motivos. El commit dice qué cambió; la razón suele estar en un comentario de PR, en un issue o en una conversación con un agente que ya no existe. Así los agentes repiten las mismas preguntas, proponen el enfoque que rechazaste la semana pasada y rehacen trabajo que otro agente ya terminó. Cuando ejecutas varios agentes en paralelo, empeora: cada uno aprende algo que los demás nunca ven.
Qué debe ir en una memoria compartida
Los archivos de instrucciones y una memoria compartida hacen trabajos distintos.
| Archivo de instrucciones (CLAUDE.md, AGENTS.md) | Memoria compartida | |
|---|---|---|
| Lo escribe | Tú, a mano | Se construye desde el historial, más los agentes mientras trabajan |
| Contenido | Reglas, comandos, convenciones | Decisiones con sus motivos, correcciones, notas de traspaso |
| Cambia | Rara vez | Todos los días |
| Se carga | El archivo entero, en cada sesión | Se consulta cuando hace falta, con un resumen breve al empezar |
| Sabe cuándo está desactualizado | No | Puede marcar decisiones como stale o superseded |
Mantén tu archivo de instrucciones corto y estable (cómo escribir uno). Lo que se mueve va a la memoria. Una buena memoria compartida guarda cuatro tipos de cosas:
- Decisiones. «Usamos JWT para la API porque las sesiones rompían la app móvil», con la fecha y la fuente.
- Correcciones. Cosas que el usuario le dijo a un agente que hizo mal. Son las más caras de perder.
- Notas de traspaso. Qué hizo un agente y qué dejó abierto.
- Hechos. Pequeñas verdades del proyecto que no son obvias a partir del código.
Cómo construye la memoria el Brain de AgentVera
En AgentVera, cada proyecto tiene una pestaña Brain en su página Details. Pulsa Build memory (más tarde Refresh memory) y lee el historial del proyecto:
- Docs y registros de decisiones versionados en Git: README, ARCHITECTURE, CONTRIBUTING, CLAUDE, AGENTS, CHANGELOG,
docs/,adr/ydecisions/(hasta 250 archivos) - Los 1.500 commits más recientes que no sean de merge
- Hasta 200 pull requests y 200 issues, si el proyecto está en GitHub y has iniciado sesión
- Hasta 120 conversaciones pasadas con agentes
Claude Haiku extrae las decisiones de ese material. Cada una recibe un título, el motivo, una fecha, sus fuentes y los términos de código a los que se refiere. Los duplicados se fusionan.
Las decisiones no son verdad para siempre, así que cada una tiene un estado: current, stale o superseded. Compare with code contrasta los términos de código de una decisión con el repositorio mediante git grep. Verify with Claude ejecuta una comprobación de solo lectura con Sonnet para mirarlo más de cerca. Así la memoria puede decirle a un agente «decidimos esto, pero el código ha cambiado».
La pestaña Brain tiene cuatro vistas: Decisions, Knowledge graph, Context pack y Memory. También hay un cuadro Ask. Pregunta «¿Por qué usamos JWT?» y Sonnet responde desde la memoria, en solo lectura, con citas de las fuentes.
Cómo leen y escriben la memoria los agentes
Construir la memoria es la mitad del trabajo. La otra mitad es que los agentes la usen. AgentVera añade un servidor MCP llamado agentvera-brain a cada agente cuyo CLI admite servidores MCP. Si MCP es nuevo para ti, empieza por qué es un servidor MCP.
El servidor tiene dos herramientas:
| Herramienta | Qué hace |
|---|---|
brain_recall | Busca en decisiones (con su estado), docs, commits, PRs, issues, conversaciones pasadas, notas de traspaso y hechos recordados. Devuelve hasta 8 resultados, cada uno con un [id] para citar. Sin consulta, devuelve las memorias guardadas y los hilos abiertos. |
brain_remember | Guarda una frase autosuficiente como fact, correction o decision. No sirve para actualizaciones de progreso. El texto idéntico no se guarda dos veces. |
El servidor también le dice al agente cuándo usarlas: llamar a brain_recall antes de una tarea que toque trabajo anterior, llamar a brain_remember cuando el usuario lo corrige, expresa una regla o preferencia, o se toma una decisión, y citar los elementos por [id].
Un intercambio típico en una sesión de Claude Code se ve así:
You: Add refresh tokens to the API.
Agent: (calls brain_recall "auth tokens JWT")
Found [d12] "Use JWT for the API, sessions broke the mobile app" (current)
and a correction [m4] "Never store tokens in localStorage".
I will keep JWT and put the refresh token in an httpOnly cookie.
You: Good. And refresh tokens expire after 30 days.
Agent: (calls brain_remember, kind: decision)El siguiente agente que toque la autenticación encuentra las dos cosas, sin que tengas que repetirte.
Notas de traspaso: memoria entre sesiones
El interruptor Agents write the memory de la pestaña Brain está activado salvo que lo desactives. Con él activado:
- Después de los turnos (como máximo cada 15 minutos por agente), y siempre que un agente compacta su conversación, el agente deja una nota de traspaso breve. La escribe Haiku: un resumen de una a cuatro frases y hasta seis hilos abiertos, que se muestran como Left open.
- Las correcciones y decisiones que el agente guarda con
brain_remembervan a la misma memoria. - Los agentes nuevos del proyecto reciben las recientes.
- Entre las 03:00 y las 06:00 el brain se compila de nuevo, pero solo si se construyó antes, hay notas nuevas desde entonces y como máximo una vez cada 12 horas.
Las notas y memorias aparecen en la vista Memory, etiquetadas como Fact, Correction, Decision o Session note. Forget elimina una.
Cuando arranca un agente nuevo, sus instrucciones reciben una introducción breve de hasta 2.500 caracteres: las memorias guardadas (primero las correcciones, hasta 15), más la nota más reciente de hasta seis otros agentes de los últimos siete días que aún tengan hilos abiertos. Esto hace que la compactación duela menos: el resumen que escribe Claude Code desaparece tras la sesión, pero la nota de traspaso se queda. Para saber más sobre lo que la compactación conserva y descarta, consulta la ventana de contexto de Claude Code.
El context pack
Por separado, la vista Context pack contiene un resumen del proyecto de hasta 2.500 caracteres. Activa Give new agents a context pack y los agentes nuevos reciben el pack más la lista de decisiones stale en sus instrucciones. Está desactivado por defecto, porque suma al contexto inicial de cada agente nuevo. Actívalo si tus agentes siguen sin captar el mismo contexto de fondo.
Configúralo en cinco pasos
- Abre el proyecto en AgentVera y ve a Details → Brain.
- Pulsa Build memory. Inicia sesión antes en GitHub si quieres incluir PRs e issues.
- Echa un vistazo a Decisions. Ejecuta Compare with code en las que dudes.
- Deja Agents write the memory activado y decide si quieres el context pack.
- Inicia un agente nuevo de Claude Code o Codex y dale una tarea que toque trabajo anterior. Observa cómo llama a
brain_recall.
Memoria compartida y coordinación
La memoria responde a «¿qué sabemos?». La coordinación responde a «¿quién hace qué ahora mismo?». Para el trabajo en vivo, AgentVera también da a los agentes un tablón de avisos por MCP (agentvera-board) donde publican notas, decisiones, tareas pendientes y hallazgos, y avisa cuando dos agentes editan el mismo archivo. Las dos cosas encajan: el tablón es para hoy, el Brain es para el mes que viene.
La memoria también combina bien con el mapa del proyecto. El mapa le dice al agente dónde está el código; el Brain le dice por qué el código es como es.
Límites que conviene conocer
- El Brain se añade a los agentes que admiten servidores MCP. Las terminales simples y los agentes en un host SSH remoto no lo reciben.
- Las notas de sesión y las memorias guardan cada una hasta 200 entradas.
- Todo se almacena en local, un archivo por proyecto en la carpeta de datos de la app. La extracción de decisiones, las notas de traspaso y las respuestas usan Claude a través de tu inicio de sesión de Claude Code, así que esas peticiones van a Anthropic.
- Una memoria vale lo que contiene. Revisa la vista Memory de vez en cuando y olvida las notas que estén mal.
Resumen
La memoria compartida para agentes de código con IA llena el hueco entre los archivos de instrucciones estáticos y una ventana de contexto que se reinicia. El Brain de AgentVera la construye a partir de tus docs, commits, PRs, issues y conversaciones, rastrea qué decisiones siguen vigentes y deja que cada agente compatible con MCP recuerde y guarde a través de agentvera-brain, con notas de traspaso tras los turnos y al compactar. El Brain forma parte del plan gratuito. Lee la página de la función Brain o descarga AgentVera y construye la memoria de tu primer proyecto.