# bmad-plus mem

> Recordar decisiones y eventos, anotar el trabajo de un agente, reforzar un patrón con señales de recompensa, vincular una lección a trabajo de Nexus aceptado. Opciones, salida, errores.

Canonical: https://bmad-plus.rochetta.fr/es/docs/reference/cli-mem/
Language: es
BMAD+ version: 0.23.1
Documentation reviewed: 2026-10-19
Author: Laurent Rochetta
License: MIT

Documentación de BMAD+ › [Referencia](https://bmad-plus.rochetta.fr/es/docs/reference/) › bmad-plus mem

El pack Memory guarda lo que un proyecto ha aprendido en archivos Markdown: decisiones, lecciones y patrones. `bmad-plus mem` es la pequeña caja de herramientas determinista que permite a cualquier asistente usar esos archivos de la misma manera, ya se ejecute en Claude Code, Gemini CLI, Codex CLI, Cursor, OpenCode, Aider o Antigravity. Tiene cinco acciones: `recall` encuentra notas y eventos relevantes, `write` añade un evento a un diario, `reinforce` sube o baja la puntuación de un patrón, `observe` vincula una lección a un trabajo verificado de forma independiente y aceptado, y `outcomes` lista esos vínculos. No hace preguntas en la terminal ni llama nunca a un modelo, así que un agente puede ejecutarla y analizar el resultado. Esta página es para quien quiere que un agente recuerde con evidencias y para quien audita esa memoria.

<a id="synopsis"></a>
## Sinopsis

**En la terminal de tu proyecto**

```sh
npx bmad-plus mem recall <query...> [--scope project|portfolio] [--portfolio <path>] [--limit <n>] [--ranking lexical|evidence] [--context-scope <paths>] [--json]
npx bmad-plus mem write --agent <name> [--cli <name>] [--model <id>] [--task <text>] [--outcome <outcome>] [--eval <0-1>] [--accept <bool>] [--ci <result>] [--json]
npx bmad-plus mem reinforce --pattern <id> [--eval <0-1>] [--accept <bool>] [--ci <result>] [--evidence <ids>] [--json]
npx bmad-plus mem observe --input <file> [--json]
npx bmad-plus mem outcomes [--json]
```

**Argumentos y opciones de mem**

| Opción | Argumento | Por defecto | Qué hace |
| --- | --- | --- | --- |
| `<action>` | `recall`, `write`, `reinforce`, `observe`, `outcomes` | obligatorio | La acción que se ejecuta. |
| `[query...]` | palabras | ninguno | El texto de búsqueda de `recall`. Varias palabras se unen con espacios. |
| `-d, --directory <path>` | ruta | carpeta actual | Carpeta del proyecto que contiene `.agents/memory/` y `.bmad/memory/`. |
| `--scope <scope>` | `project` o `portfolio` | `project` | Solo `recall`. `portfolio` busca también en la carpeta de memoria de un cerebro de portafolio. |
| `--portfolio <path>` | ruta | ninguno | Carpeta del cerebro de portafolio; con `--scope portfolio` se busca en su subcarpeta `memory/`. |
| `--limit <n>` | número | `8` | `recall`: cuántos resultados conservar. |
| `--ranking <mode>` | `lexical` o `evidence` | `lexical` | `recall`: `evidence` favorece las notas respaldadas por un resultado aceptado. Solo ámbito de proyecto. |
| `--context-scope <paths>` | rutas relativas separadas por comas | ninguno | Obligatorio con `--ranking evidence`: las rutas del proyecto sobre las que versa la pregunta. |
| `--input <file>` | ruta relativa al proyecto | ninguno | `observe`: archivo JSON que describe el resultado. |
| `--agent <name>` | texto | ninguno | `write`: el agente que produjo el evento. Obligatorio. |
| `--cli <name>` | texto | ninguno | `write`: el asistente que lo conducía (por ejemplo `claude-code`, `gemini-cli`, `codex-cli`, `cursor`, `opencode`, `aider`, `antigravity`). Se guarda tal cual. |
| `--model <id>` | texto | ninguno | `write`: identificador del modelo, se guarda tal cual. |
| `--task <text>` | texto | vacío | `write`: lo que se intentó. |
| `--outcome <outcome>` | `success`, `failure`, `partial`, `abandoned` | ninguno | `write`: resultado del intento. |
| `--pattern <id>` | texto | ninguno | `reinforce`: el título del patrón en `patterns.md`. Obligatorio. |
| `--eval <score>` | número de 0 a 1 | ninguno | Señal de recompensa: puntuación de una suite de evaluación. |
| `--accept <bool>` | `true`, `false` (o `yes`, `no`), o un número de 0 a 1 | ninguno | Señal de recompensa: si la persona aceptó el resultado. |
| `--ci <result>` | `pass`, `fail`, o un número de 0 a 1 | ninguno | Señal de recompensa: resultado de la integración continua. |
| `--evidence <ids>` | ids de eventos separados por comas | ninguno | `reinforce`: eventos del diario que respaldan el refuerzo; se copian a una propuesta de promoción. |
| `--json` | ninguno | desactivado | Imprime JSON en lugar de texto. Los errores pasan a ser `{"error": "..."}`. |

<a id="reads-writes"></a>
## Qué lee y qué escribe

**Archivos que usa mem**

| Archivo | Función | Lo escribe |
| --- | --- | --- |
| `.bmad/memory/journal.ndjson` | Diario de eventos de solo adición, un objeto JSON por línea. | `write` |
| `.bmad/memory/pattern-scores.json` | Puntuación de cada patrón reforzado (una valoración Elo y una distribución Beta). | `reinforce` |
| `.bmad/memory/promotions.ndjson` | Propuestas de promoción. Siempre con estado `PROPOSED`. | `reinforce` |
| `.bmad/memory/outcomes.ndjson` | Recibos que vinculan una sección de memoria con trabajo de Nexus aceptado. | `observe` |
| `.bmad/memory/writer.lock` | Bloqueo de corta duración que pone en fila a quienes escriben. | toda acción que escribe |
| `decisions.md`, `lessons.md`, `patterns.md` en `.agents/memory/` y `.bmad/memory/` | Notas humanas, divididas en secciones en cada título `### `. Solo lectura. | tú y tus agentes |

Cada almacén está limitado a 2 MiB, el de resultados a 1000 recibos, y las rutas deben quedarse dentro del proyecto sin seguir enlaces simbólicos. Una línea dañada del diario se omite al leer, nunca es fatal.

<a id="actions"></a>
## Las cinco acciones

<a id="recall"></a>
### recall

Busca en los eventos del diario y en las secciones `### ` de `decisions.md`, `lessons.md` y `patterns.md`, tanto en `.agents/memory/` como en `.bmad/memory/`. El ranking es léxico: palabras de la consulta halladas en una entrada, con rendimientos decrecientes para las repeticiones, un bonus por la parte de la consulta cubierta y una normalización por longitud. Los eventos del diario pierden la mitad de su peso cada 30 días. No hace falta ningún servicio de búsqueda ni Python. Con `--scope portfolio --portfolio <path>` también se busca en la carpeta `memory/` de un cerebro de portafolio. Con `--ranking evidence` (solo ámbito de proyecto, y entonces `--context-scope` es obligatorio) una nota con un recibo de resultado aceptado válido para las rutas dadas ve su puntuación multiplicada por 1,25; una nota cuyos recibos están todos obsoletos, sustituidos o contradichos se descarta en lugar de volver en silencio; las notas sin ningún recibo se quedan, marcadas `unverified`.

<a id="write"></a>
### write

Añade un evento a `.bmad/memory/journal.ndjson` con la hora de la llamada, el agente y, si se dan, el asistente, el modelo, la tarea, el resultado y las señales de recompensa pasadas. El id del evento se deriva de la hora, el agente y la tarea, así que es reproducible. Nada del evento es una medición hecha por BMAD+: las señales son lo que declara quien llama.

<a id="reinforce"></a>
### reinforce

Reduce las señales a una recompensa entre 0 y 1: `--eval` pesa 0,5, `--accept` 0,3 y `--ci` 0,2, y las señales omitidas se ignoran renormalizando los pesos, de modo que una llamada solo con CI da igualmente una recompensa utilizable. La recompensa mueve la valoración Elo del patrón (empieza en 1200, factor K de 32) y su distribución Beta (empieza en 1 y 1, con olvido para que la evidencia antigua se desvanezca). Cuando la media Beta llega a 0,7 con al menos 3 actualizaciones, se escribe en `promotions.ndjson` una promoción de `candidate` a `validated`, siempre con estado `PROPOSED`. Aplicarla exige una aprobación humana o de Shield que este comando nunca puede registrar. El resultado indica `evidenceStatus: self-reported` y `rankingEligible: false`: un refuerzo es la afirmación de quien llama, no evidencia aceptada.

<a id="observe"></a>
### observe y outcomes

`observe` es la única manera de que una lección obtenga evidencia. Lee un archivo JSON y solo escribe un recibo si la tarea de Nexus que nombra está aceptada, su último intento completado, su verificación independiente superada y su evidencia aún vigente, y solo si la sección de memoria que nombra existe exactamente una vez. El recibo guarda la huella de esa sección y la tarea, e indica `lessonCausality: unmeasured`: BMAD+ no afirma que la lección causara el éxito. `outcomes` vuelve a comprobar cada recibo con los archivos de hoy e imprime `accepted-current` o la razón por la que ya no cuenta: `superseded`, `contradictory`, `stale-memory-section` (el texto de la sección cambió), `stale-outcome-source` (la tarea de Nexus cambió) o `unavailable-or-ineligible-source`.

**Archivo de entrada de observe**

```json
{
  "runId": "<nexus run id>",
  "taskId": "<accepted task id>",
  "memory": { "file": ".agents/memory/lessons.md", "heading": "<exact ### heading>" },
  "scope": ["src/auth"],
  "interpretation": "Why this accepted work supports the lesson.",
  "supersedes": [],
  "contradicts": []
}
```

`memory.file` debe ser `decisions.md`, `lessons.md` o `patterns.md` bajo `.agents/memory/` o `.bmad/memory/`. `scope` lista de 1 a 30 rutas relativas y debe quedarse dentro del alcance de la tarea aceptada. `supersedes` y `contradicts` nombran ids de recibos anteriores que se solapan con el mismo alcance; un id no puede estar en ambos. Un intento de tarea solo puede producir un recibo.

<a id="exit-codes"></a>
## Códigos de salida

**Códigos de salida de mem**

| Código | Significado |
| --- | --- |
| 0 | La acción se ejecutó. Un `recall` sin resultados sigue siendo 0. |
| 1 | Acción desconocida, opción obligatoria ausente, valor inválido, almacén bloqueado o cualquier otro fallo. Con `--json` el error sale por la salida estándar como `{"error": "..."}`; si no, por el flujo de error como `mem <action>: <message>`. |

<a id="real-output"></a>
## Leer la salida

**recall (puntuaciones y nota ilustrativas)** (Simulado)

```text
$ npx bmad-plus mem recall auth strategy
mem recall: 1 match(es) for "auth strategy" (scope: project)
  1. [0.412] note decisions.md § Auth strategy
     Use short-lived sessions with server-side revocation.
```

Transcripción ilustrativa, no capturada de una ejecución real. Fuente: tools/cli/commands/memory-journal-cmd.js (plantillas de mensajes de runRecall); las puntuaciones y el texto son inventados

**write y luego reinforce (calculado con las fórmulas, ids ilustrativos)** (Simulado)

```text
$ npx bmad-plus mem write --agent forge --cli claude-code --task "Add login rate limit" --outcome success --ci pass
mem write: event 3f9a1c7b02de appended (2026-10-18T09:30:00.000Z)
  agent=forge cli=claude-code model=- outcome=success
  task: Add login rate limit
$ npx bmad-plus mem reinforce --pattern "Rate limit on auth routes" --accept true --ci pass
mem reinforce: pattern "Rate limit on auth routes"
  reward   1.000 (from {"acceptance":true,"ci":"pass"})
  elo      1200.0 -> 1216.0
  mean     0.667 (alpha=2.00, beta=1.00, updates=1)
  promotion: none proposed (needs mean >= 0.7 and >= 3 updates)
```

Transcripción ilustrativa, no capturada de una ejecución real. Fuente: tools/cli/commands/memory-journal-cmd.js (runWrite, runReinforce) y lib/memory-journal.js (computeReward, updatePatternScore); el id y la hora del evento son inventados

<a id="errors"></a>
## Errores y qué hacer

**Mensajes que imprime mem**

| Mensaje | Causa | Qué hacer |
| --- | --- | --- |
| `mem: unknown action '<x>' — expected recall \| write \| reinforce \| observe \| outcomes` | La primera palabra no es una de las cinco acciones. | Corrige el nombre de la acción. |
| `mem recall: recall: query must be a non-empty string` | Se llamó a `recall` sin palabras que buscar. | Añade las palabras de búsqueda tras `recall`. |
| `mem recall: Evidence ranking supports project-local lexical recall only.` | `--ranking evidence` combinado con `--scope portfolio`. | Usa el ámbito de proyecto para el ranking por evidencias. |
| `mem recall: An explicit non-empty project scope is required.` | `--ranking evidence` sin `--context-scope`. | Pasa `--context-scope src/auth,src/session` (de 1 a 30 rutas relativas). |
| `mem write: appendEvent: event.agent is required` | `write` sin `--agent`. | Pasa `--agent <name>`. |
| `mem write: appendEvent: event.outcome must be one of success\|failure\|partial\|abandoned` | `--outcome` inválido. | Usa uno de los cuatro valores. |
| `mem reinforce: mem reinforce: --pattern <id> is required (the pattern heading in patterns.md)` | `reinforce` sin `--pattern`. | Pasa el título `### ` exacto del patrón. |
| `mem observe: Outcome source is not an accepted task with current independently verified evidence.` | La tarea de Nexus no está aceptada, su verificación no se superó o su evidencia está obsoleta. | Termina antes `nexus verify` y `nexus accept`, y vuelve a observar. |
| `mem observe: Memory heading must identify exactly one section.` | El título no existe o aparece dos veces en el archivo. | Usa el texto exacto y único del título `### `. |
| `mem observe: Duplicate outcome: this task attempt already supplied a receipt.` | Ya existe un recibo para este run, esta tarea y este intento. | Nada que hacer; usa `supersedes` en un intento posterior si la lección cambió. |
| `mem observe: Outcome scope exceeds the accepted task scope.` | Una ruta de `scope` queda fuera del alcance declarado de la tarea. | Reduce `scope` a las rutas que posee la tarea. |
| `... Memory writer lock is occupied. Inspect writer.lock and its owner; do not remove a live lock.` | Otro proceso tiene `.bmad/memory/writer.lock` más de unos dos segundos, o una caída lo dejó. | Espera al otro escritor. Borra el archivo solo si estás seguro de que no hay ningún proceso `mem` en marcha. |
| `... Memory store is full; archive it explicitly before adding records.` | Un almacén llegó a 2 MiB. | Archiva o recorta el archivo a mano y reintenta. |

<a id="examples"></a>
## Ejemplos

<a id="example-cli-mem-recall"></a>
### Recordar una decisión pasada

Antes de tocar la autenticación quieres que el agente compruebe lo que el proyecto ya decidió.

**En tu asistente de IA**

```text
Ejecuta `bmad-plus mem recall auth strategy --json` y cita las tres mejores coincidencias con su archivo de origen y su sección.
```

**Lo que deberías obtener** El comando imprime un objeto JSON con `query`, `scope`, `ranking`, `count` y un array `results` ordenado por puntuación. Cada resultado es una `note` (con `source` como `decisions.md`, `ref` igual al título `### ` y el texto de la sección) o un `event` del diario. Sin coincidencias, `count` es 0 y el código de salida sigue siendo 0.

<a id="example-cli-mem-journal"></a>
### Anotar un resultado y reforzar un patrón

Un cambio fue aceptado y la CI está en verde. Quieres que la memoria lo registre y empuje el patrón que lo guio.

**En tu asistente de IA**

```text
Escribe un evento de diario para el agente forge, tarea «Add login rate limit», resultado success, CI pass, y luego refuerza el patrón «Rate limit on auth routes» con aceptación true y CI pass.
```

**Lo que deberías obtener** `mem write` añade una línea a `.bmad/memory/journal.ndjson` e imprime su id. `mem reinforce` calcula una recompensa de 1,000 (aceptación 0,3 y CI 0,2, renormalizados), lleva el Elo del patrón de 1200,0 a 1216,0 en su primera actualización y muestra una media de 0,667. No se propone ninguna promoción hasta que la media llegue a 0,7 con al menos 3 actualizaciones, y una propuesta solo se guarda como `PROPOSED`.

<a id="example-cli-mem-observe"></a>
### Vincular una lección a trabajo aceptado

Una tarea de Nexus que añade un límite de peticiones ha sido verificada y aceptada. Quieres que la lección correspondiente lleve esa evidencia.

**En tu asistente de IA**

```text
Escribe el archivo de resultado de la tarea de Nexus aceptada T-12 del run <run id>, vinculado a la lección «Rate limit on auth routes» en .agents/memory/lessons.md con alcance src/auth, y luego ejecuta `bmad-plus mem observe --input` sobre él y `bmad-plus mem outcomes`.
```

**Lo que deberías obtener** `mem observe` imprime `mem observe: <receipt id> recorded; lesson causality remains unmeasured.` y añade el recibo a `.bmad/memory/outcomes.ndjson`. Después `mem outcomes` imprime `<receipt id>: accepted-current`. Si la tarea no está aceptada, la sección falta o es ambigua, o el alcance sale del de la tarea, `observe` se niega con el mensaje de la tabla de errores y no escribe nada.

**Véase también**

- [memory: informe de salud y exportación](https://bmad-plus.rochetta.fr/es/docs/reference/cli-memory/)
- [nexus: de dónde vienen las tareas aceptadas](https://bmad-plus.rochetta.fr/es/docs/reference/cli-nexus/)
- [scan: indexar tus proyectos](https://bmad-plus.rochetta.fr/es/docs/reference/cli-scan/)
- [Estructura del proyecto](https://bmad-plus.rochetta.fr/es/docs/reference/project-layout/)
- [Solución de problemas](https://bmad-plus.rochetta.fr/es/docs/faq/troubleshooting/)

[Documentación de BMAD+](https://bmad-plus.rochetta.fr/es/docs/) · [Referencia](https://bmad-plus.rochetta.fr/es/docs/reference/)

[Código en GitHub](https://github.com/lrochetta/BMAD-PLUS)