Memoria: decisiones, lecciones y cerebro

Una sesión nueva de un asistente de IA empieza de cero: no recuerda por qué elegiste una biblioteca la semana pasada ni qué salió mal el martes. El pack Memory lo arregla con simples archivos Markdown en tu proyecto, un protocolo que dice a cada agente cuándo leerlos y escribirlos, y un agente, Zecher, que los mantiene ordenados. Esta página explica dónde vive la memoria, cómo se detecta y se enlaza un cerebro existente, qué comandos la tocan y qué queda garantizado como nunca sobrescrito. Es para quien trabaja en el mismo proyecto a lo largo de varias sesiones, o en varios proyectos que deberían compartir lo que aprenden.

Dos niveles: memoria de proyecto y cerebro#

La regla de oro: la información que afecta a un proyecto va a la memoria del proyecto; la que afecta a dos o más proyectos es candidata al cerebro. El paso de una a otra nunca es automático. Zecher propone, tú apruebas.

Cómo se detecta un cerebro existente#

Cuando el pack Memory está instalado, BMAD+ busca un cerebro antes de crear nada. Gana la primera coincidencia.

El resultado se escribe en .agents/memory/.brain-link para que cada agente y cada comando encuentre el mismo cerebro. Un cerebro encontrado se enlaza, nunca se copia ni se reescribe: sin duplicación ni sobrescritura. Un cerebro de cartera o claude-memory conserva sus propias convenciones; BMAD+ no crea identity.yaml ni projects/ dentro de él y añade una entrada de índice del proyecto solo cuando el cerebro enlazado es el global de BMAD+. Se indica a los agentes que lean primero el punto de entrada propio de un cerebro de cartera (README.md, AGENTS.md o HOT.md) y sigan su organización.

{
  "linked_brain": "/work/demo/home/.bmad-plus/brain",
  "brain_type": "bmad-global",
  "linked_at": "2026-10-19T02:13:36.733Z"
}

Los archivos y cuándo los tocan los agentes#

### YYYY-MM-DD — <short title>
- **Context**: why the decision was needed
- **Decision**: what was chosen
- **Rationale**: why
- **Consequences**: what this unlocks / forecloses
- **Status**: active / superseded / rolled-back

El protocolo de lectura y escritura#

1. Inicio de sesión (lectura): identity.yaml del cerebro, luego context.md, decisions.md y lessons.md del proyecto, y el último traspaso de sessions/ si se retoma. Un archivo ausente se omite en silencio: la memoria siempre es opcional.
2. Durante la sesión (escritura por disparador): decisiones, lecciones, patrones y contexto como en la tabla anterior.
3. Final de sesión (persistencia): un traspaso en sessions/, un context.md actualizado, un vistazo a las lecciones pendientes y una comprobación transversal que solo propone promociones.

Los cuatro límites de conducta#

Las instrucciones generadas de cada agente llevan cuatro reglas de conducta, adaptadas de un proyecto comunitario inspirado en los consejos de Andrej Karpathy (ver la página de confianza para el crédito). Unen los archivos de memoria con el comportamiento diario.

Zecher, el agente de memoria#

Zecher (el nombre significa «recuerdo» en hebreo) es un agente de utilidad: tú u otro agente lo llamáis cuando la memoria necesita atención. No es un orquestador. Sus reglas: nunca borrar memoria (archivar, consolidar, jamás destruir), preguntar siempre antes de promover al cerebro, fechas ISO 8601 (YYYY-MM-DD, nunca «la semana pasada»), entradas concisas legibles en diez segundos y referencias cruzadas entre una lección y la decisión a la que atañe.

Los comandos: memory, scan y mem#

$ npx bmad-plus mem write --agent atelier --cli claude-code --task "Design read for the Orbit landing page: one job, the loyalty card sign-up" --outcome success --ci pass
mem write: event 912e91734848 appended (2026-10-19T02:13:48.840Z)
  agent=atelier cli=claude-code model=- outcome=success
  task: Design read for the Orbit landing page: one job, the loyalty card sign-up
$ npx bmad-plus mem recall "loyalty card sign-up"
mem recall: 2 match(es) for "loyalty card sign-up" (scope: project)
  1. [0.707] event journal.ndjson#912e91734848
     atelier claude-code Design read for the Orbit landing page: one job, the loyalty card sign-up success {"ci":"pass"}
  2. [0.522] note decisions.md § 2026-10-18 — The landing page has one job, the loyalty card sign-up
     2026-10-18 — The landing page has one job, the loyalty card sign-up - **Context**: design read for the Orbit landing pa…
$ npx bmad-plus mem outcomes
mem outcomes: no observations.
$ npx bmad-plus memory export
◆  📦 Brain exported to: /work/demo/app/bmad-brain-export-2026-10-19.md
# Antes de la consulta se añadió a mano a decisions.md una entrada de decisión con el formato de arriba. Sin una tarea Nexus aceptada no hay observación, así que la ordenación por evidencias no aporta nada a la ordenación simple.

Lo que nunca se sobrescribe#

• Instalar y actualizar nunca sobrescriben decisions.md, lessons.md ni patterns.md, nunca borran sessions/ y conservan tus cambios en context.md e identity.yaml. Los archivos que faltan se crean desde plantillas; los existentes se dejan como están.
• Un cerebro detectado se enlaza, no se copia ni se reescribe. Los archivos del cerebro global solo se crean si faltan; una instalación antigua interrumpida podía dejar un «medio cerebro» y el código actual lo completa de forma idempotente sin tocar lo existente.
• Desinstalar quita los archivos de los que BMAD+ es propietario y conserva .agents/memory/, _bmad/config.yaml y lo que es tuyo o está modificado (ver el bloque siguiente).
• Un fallo al inicializar la memoria no es fatal: si la carpeta personal es de solo lectura (contenedor, CI), la instalación continúa y avisa.
• Los escritores compartidos usan .bmad/memory/writer.lock. Tras una interrupción, inspecciona al propietario y los archivos antes de cualquier recuperación manual; no quites el bloqueo de un escritor vivo, y las evidencias de resultados corruptas nunca se reinician automáticamente.

$ npx bmad-plus uninstall --yes
●  BMAD+ v0.23.0 (installed 2026-10-19)
●  Selected packs: core, memory
◇  ✅ BMAD+ removed (60 items)
└  Project memory, settings, and unknown or modified files have been preserved.
$ find . -path ./.git -prune -o -print | sort
./.agents/memory/.brain-link
./.agents/memory/context.md
./.agents/memory/decisions.md
./.agents/memory/lessons.md
./.agents/memory/patterns.md
./.agents/memory/sessions
./.bmad/memory/journal.ndjson
./_bmad/config.yaml
./bmad-brain-export-2026-10-19.md
# Las carpetas que solo contenían directorios vacíos y los archivos propios del proyecto (README.md, docs) se omiten de este extracto. El cerebro global de la carpeta personal no se tocó.

Zecher, ¿dónde estábamos? Reconstruye el estado de este proyecto a partir de context.md, el último traspaso de sesión, la entrada del cerebro y los últimos commits. Dime qué se decidió, qué está sin terminar y qué lecciones valen para la próxima tarea. Di con claridad cuáles de estas fuentes no encontraste, sin adivinar.

Zecher, consolida la memoria. Primero solo audita: lista los duplicados y las decisiones activas de más de 90 días, y propón qué fusionar, archivar o promover al cerebro global. No apliques nada hasta que apruebe cada cambio, archiva en vez de borrar y escribe las fechas como YYYY-MM-DD.