# bmad-plus mem

> Rappeler décisions et événements passés, journaliser le travail d’un agent, renforcer un motif par des signaux de récompense, relier une leçon à un travail Nexus accepté. Options, sortie, erreurs.

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

Documentation BMAD+ › [Référence](https://bmad-plus.rochetta.fr/fr/docs/reference/) › bmad-plus mem

Le pack Memory range ce qu’un projet a appris dans des fichiers Markdown : décisions, leçons et motifs. `bmad-plus mem` est la petite boîte à outils déterministe qui permet à n’importe quel assistant d’utiliser ces fichiers de la même façon, qu’il tourne dans Claude Code, Gemini CLI, Codex CLI, Cursor, OpenCode, Aider ou Antigravity. Elle a cinq actions : `recall` retrouve des notes et événements pertinents, `write` ajoute un événement à un journal, `reinforce` monte ou baisse le score d’un motif, `observe` relie une leçon à un travail vérifié de façon indépendante puis accepté, et `outcomes` liste ces liens. Elle n’a aucune question de terminal et n’appelle jamais de modèle : un agent peut donc la lancer et analyser le résultat. Cette page s’adresse à qui veut qu’un agent se souvienne avec des preuves, et à qui audite cette mémoire.

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

**Dans le terminal de votre projet**

```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]
```

**Arguments et options de mem**

| Option | Argument | Défaut | Effet |
| --- | --- | --- | --- |
| `<action>` | `recall`, `write`, `reinforce`, `observe`, `outcomes` | obligatoire | L’action à exécuter. |
| `[query...]` | mots | aucun | Le texte de recherche de `recall`. Plusieurs mots sont joints par des espaces. |
| `-d, --directory <path>` | chemin | dossier courant | Dossier du projet contenant `.agents/memory/` et `.bmad/memory/`. |
| `--scope <scope>` | `project` ou `portfolio` | `project` | `recall` seulement. `portfolio` cherche aussi dans le dossier mémoire d’un cerveau de portefeuille. |
| `--portfolio <path>` | chemin | aucun | Dossier du cerveau de portefeuille ; son sous-dossier `memory/` est fouillé avec `--scope portfolio`. |
| `--limit <n>` | nombre | `8` | `recall` : combien de résultats garder. |
| `--ranking <mode>` | `lexical` ou `evidence` | `lexical` | `recall` : `evidence` favorise les notes appuyées par un résultat accepté. Portée projet uniquement. |
| `--context-scope <paths>` | chemins relatifs séparés par des virgules | aucun | Obligatoire avec `--ranking evidence` : les chemins du projet sur lesquels porte la question. |
| `--input <file>` | chemin relatif au projet | aucun | `observe` : fichier JSON qui décrit le résultat. |
| `--agent <name>` | texte | aucun | `write` : l’agent qui a produit l’événement. Obligatoire. |
| `--cli <name>` | texte | aucun | `write` : l’assistant qui le pilotait (par exemple `claude-code`, `gemini-cli`, `codex-cli`, `cursor`, `opencode`, `aider`, `antigravity`). Enregistré tel quel. |
| `--model <id>` | texte | aucun | `write` : identifiant du modèle, enregistré tel quel. |
| `--task <text>` | texte | vide | `write` : ce qui a été tenté. |
| `--outcome <outcome>` | `success`, `failure`, `partial`, `abandoned` | aucun | `write` : résultat de la tentative. |
| `--pattern <id>` | texte | aucun | `reinforce` : le titre du motif dans `patterns.md`. Obligatoire. |
| `--eval <score>` | nombre de 0 à 1 | aucun | Signal de récompense : score d’une suite d’évaluation. |
| `--accept <bool>` | `true`, `false` (ou `yes`, `no`), ou un nombre de 0 à 1 | aucun | Signal de récompense : la personne a-t-elle accepté le résultat. |
| `--ci <result>` | `pass`, `fail`, ou un nombre de 0 à 1 | aucun | Signal de récompense : résultat de l’intégration continue. |
| `--evidence <ids>` | identifiants d’événements séparés par des virgules | aucun | `reinforce` : événements du journal qui appuient le renforcement ; recopiés dans une proposition de remontée vers le cerveau global. |
| `--json` | aucun | désactivé | Affiche du JSON au lieu du texte. Les erreurs deviennent `{"error": "..."}`. |

<a id="reads-writes"></a>
## Ce qu’elle lit et écrit

**Fichiers utilisés par mem**

| Fichier | Rôle | Écrit par |
| --- | --- | --- |
| `.bmad/memory/journal.ndjson` | Journal d’événements en ajout seul, un objet JSON par ligne. | `write` |
| `.bmad/memory/pattern-scores.json` | Score de chaque motif renforcé (une cote Elo et une distribution Bêta). | `reinforce` |
| `.bmad/memory/promotions.ndjson` | Propositions de remontée vers le cerveau global. Toujours au statut `PROPOSED`. | `reinforce` |
| `.bmad/memory/outcomes.ndjson` | Reçus qui relient une section de mémoire à un travail Nexus accepté. | `observe` |
| `.bmad/memory/writer.lock` | Verrou de courte durée qui met les écrivains en file. | toute action qui écrit |
| `decisions.md`, `lessons.md`, `patterns.md` dans `.agents/memory/` et `.bmad/memory/` | Notes humaines, découpées en sections à chaque titre `### `. Lecture seule. | vous et vos agents |

Chaque registre est limité à 2 Mio, celui des résultats à 1000 reçus, et les chemins doivent rester dans le projet sans suivre de lien symbolique. Une ligne abîmée du journal est ignorée à la lecture, jamais fatale.

<a id="actions"></a>
## Les cinq actions

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

Cherche dans les événements du journal et dans les sections `### ` de `decisions.md`, `lessons.md` et `patterns.md`, à la fois dans `.agents/memory/` et `.bmad/memory/`. Le classement est lexical : mots de la requête trouvés dans une entrée, avec des rendements décroissants pour les répétitions, un bonus pour la part de la requête couverte et une normalisation par la longueur. Les événements du journal perdent la moitié de leur poids tous les 30 jours. Aucun service de recherche ni Python n’est requis. Avec `--scope portfolio --portfolio <path>`, le dossier `memory/` d’un cerveau de portefeuille est aussi fouillé. Avec `--ranking evidence` (portée projet seulement, et `--context-scope` devient obligatoire), une note qui a un reçu de résultat accepté valide pour les chemins donnés voit son score multiplié par 1,25 ; une note dont tous les reçus sont périmés, remplacés ou contredits est écartée au lieu de retomber silencieusement ; les notes sans reçu restent, marquées `unverified`.

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

Ajoute un événement à `.bmad/memory/journal.ndjson` avec l’heure de l’appel, l’agent, et si fournis l’assistant, le modèle, la tâche, le résultat et les signaux de récompense passés. L’identifiant de l’événement dérive de l’heure, de l’agent et de la tâche : il est reproductible. Rien dans l’événement n’est une mesure faite par BMAD+ : les signaux sont ce que l’appelant déclare.

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

Replie les signaux en une récompense entre 0 et 1 : `--eval` pèse 0,5, `--accept` 0,3 et `--ci` 0,2, et les signaux omis sont ignorés avec les poids renormalisés, si bien qu’un appel avec le seul CI donne quand même une récompense exploitable. La récompense déplace la cote Elo du motif (départ à 1200, facteur K de 32) et sa distribution Bêta (départ à 1 et 1, avec un oubli qui estompe les vieilles preuves). Quand la moyenne Bêta atteint 0,7 sur au moins 3 mises à jour, une promotion de `candidate` à `validated` est écrite dans `promotions.ndjson`, toujours au statut `PROPOSED`. L’appliquer demande une approbation humaine ou de Shield que cette commande ne peut jamais enregistrer. Le résultat indique `evidenceStatus: self-reported` et `rankingEligible: false` : un renforcement est l’affirmation de l’appelant, pas une preuve acceptée.

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

`observe` est le seul moyen pour qu’une leçon obtienne une preuve. Elle lit un fichier JSON et n’écrit un reçu que si la tâche Nexus nommée est acceptée, que sa dernière tentative est terminée, que sa vérification indépendante a réussi et que sa preuve est encore à jour, et seulement si la section de mémoire nommée existe exactement une fois. Le reçu enregistre l’empreinte de cette section et la tâche, et indique `lessonCausality: unmeasured` : BMAD+ ne prétend pas que la leçon a causé le succès. `outcomes` revérifie chaque reçu contre les fichiers d’aujourd’hui et affiche `accepted-current` ou la raison pour laquelle il ne compte plus : `superseded`, `contradictory`, `stale-memory-section` (le texte de la section a changé), `stale-outcome-source` (la tâche Nexus a changé) ou `unavailable-or-ineligible-source`.

**Fichier d’entrée 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` doit être `decisions.md`, `lessons.md` ou `patterns.md` sous `.agents/memory/` ou `.bmad/memory/`. `scope` liste de 1 à 30 chemins relatifs et doit rester dans le périmètre de la tâche acceptée. `supersedes` et `contradicts` nomment des identifiants de reçus antérieurs qui recouvrent le même périmètre ; un identifiant ne peut figurer dans les deux. Une tentative de tâche ne peut produire qu’un seul reçu.

<a id="exit-codes"></a>
## Codes de sortie

**Codes de sortie de mem**

| Code | Signification |
| --- | --- |
| 0 | L’action s’est exécutée. Un `recall` sans résultat reste à 0. |
| 1 | Action inconnue, option obligatoire absente, valeur invalide, registre verrouillé ou toute autre défaillance. Avec `--json`, l’erreur sort sur la sortie standard sous la forme `{"error": "..."}` ; sinon sur le flux d’erreur sous la forme `mem <action>: <message>`. |

<a id="real-output"></a>
## Lire la sortie

**recall (scores et note illustratifs)** (Simulé)

```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.
```

Transcription illustrative, non capturée lors d’une exécution réelle. Source: tools/cli/commands/memory-journal-cmd.js (modèles de messages de runRecall) ; les scores et le texte sont inventés

**write puis reinforce (calculé avec les formules, identifiants illustratifs)** (Simulé)

```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)
```

Transcription illustrative, non capturée lors d’une exécution réelle. Source: tools/cli/commands/memory-journal-cmd.js (runWrite, runReinforce) et lib/memory-journal.js (computeReward, updatePatternScore) ; l’identifiant et l’heure de l’événement sont inventés

<a id="errors"></a>
## Erreurs et conduite à tenir

**Messages affichés par mem**

| Message | Cause | Que faire |
| --- | --- | --- |
| `mem: unknown action '<x>' — expected recall \| write \| reinforce \| observe \| outcomes` | Le premier mot n’est pas l’une des cinq actions. | Corrigez le nom de l’action. |
| `mem recall: recall: query must be a non-empty string` | `recall` a été appelé sans mots à chercher. | Ajoutez les mots de recherche après `recall`. |
| `mem recall: Evidence ranking supports project-local lexical recall only.` | `--ranking evidence` combiné avec `--scope portfolio`. | Utilisez la portée projet pour le classement par preuves. |
| `mem recall: An explicit non-empty project scope is required.` | `--ranking evidence` sans `--context-scope`. | Passez `--context-scope src/auth,src/session` (1 à 30 chemins relatifs). |
| `mem write: appendEvent: event.agent is required` | `write` sans `--agent`. | Passez `--agent <name>`. |
| `mem write: appendEvent: event.outcome must be one of success\|failure\|partial\|abandoned` | `--outcome` invalide. | Utilisez l’une des quatre valeurs. |
| `mem reinforce: mem reinforce: --pattern <id> is required (the pattern heading in patterns.md)` | `reinforce` sans `--pattern`. | Passez le titre `### ` exact du motif. |
| `mem observe: Outcome source is not an accepted task with current independently verified evidence.` | La tâche Nexus n’est pas acceptée, sa vérification n’a pas réussi ou sa preuve est périmée. | Terminez d’abord `nexus verify` et `nexus accept`, puis observez de nouveau. |
| `mem observe: Memory heading must identify exactly one section.` | Le titre est absent ou apparaît deux fois dans le fichier. | Utilisez le texte exact et unique du titre `### `. |
| `mem observe: Duplicate outcome: this task attempt already supplied a receipt.` | Un reçu existe déjà pour cette exécution, cette tâche et cette tentative. | Rien à faire ; utilisez `supersedes` sur une tentative ultérieure si la leçon a changé. |
| `mem observe: Outcome scope exceeds the accepted task scope.` | Un chemin de `scope` sort du périmètre déclaré de la tâche. | Réduisez `scope` aux chemins que la tâche possède. |
| `... Memory writer lock is occupied. Inspect writer.lock and its owner; do not remove a live lock.` | Un autre processus tient `.bmad/memory/writer.lock` depuis plus de deux secondes environ, ou un plantage l’a laissé. | Attendez l’autre écrivain. Ne supprimez le fichier que si vous êtes sûr qu’aucun processus `mem` ne tourne. |
| `... Memory store is full; archive it explicitly before adding records.` | Un registre a atteint 2 Mio. | Archivez ou élaguez le fichier à la main, puis réessayez. |

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

<a id="example-cli-mem-recall"></a>
### Se rappeler une décision passée

Avant de toucher à l’authentification, vous voulez que l’agent vérifie ce que le projet a déjà décidé.

**Dans votre assistant IA**

```text
Lance `bmad-plus mem recall auth strategy --json` et cite les trois meilleurs résultats avec leur fichier source et leur section.
```

**Ce que vous devriez obtenir** La commande affiche un objet JSON avec `query`, `scope`, `ranking`, `count` et un tableau `results` trié par score. Chaque résultat est soit une `note` (avec `source` comme `decisions.md`, `ref` égal au titre `### ` et le texte de la section), soit un `event` du journal. Sans résultat, `count` vaut 0 et le code de sortie reste 0.

<a id="example-cli-mem-journal"></a>
### Journaliser un résultat et renforcer un motif

Un changement a été accepté et la CI est verte. Vous voulez que la mémoire le consigne et pousse le motif qui l’a guidé.

**Dans votre assistant IA**

```text
Écris un événement de journal pour l’agent forge, tâche « Add login rate limit », résultat success, CI pass, puis renforce le motif « Rate limit on auth routes » avec acceptation true et CI pass.
```

**Ce que vous devriez obtenir** `mem write` ajoute une ligne à `.bmad/memory/journal.ndjson` et affiche son identifiant. `mem reinforce` calcule une récompense de 1,000 (acceptation 0,3 et CI 0,2, renormalisés), fait passer l’Elo du motif de 1200,0 à 1216,0 à sa première mise à jour et affiche une moyenne de 0,667. Aucune promotion n’est proposée avant que la moyenne atteigne 0,7 sur au moins 3 mises à jour, et une proposition n’est jamais stockée autrement qu’en `PROPOSED`.

<a id="example-cli-mem-observe"></a>
### Relier une leçon à un travail accepté

Une tâche Nexus qui ajoute une limite de débit a été vérifiée et acceptée. Vous voulez que la leçon correspondante porte cette preuve.

**Dans votre assistant IA**

```text
Écris le fichier de résultat pour la tâche Nexus acceptée T-12 de l’exécution <run id>, rattaché à la leçon « Rate limit on auth routes » dans .agents/memory/lessons.md avec le périmètre src/auth, puis lance `bmad-plus mem observe --input` dessus et `bmad-plus mem outcomes`.
```

**Ce que vous devriez obtenir** `mem observe` affiche `mem observe: <receipt id> recorded; lesson causality remains unmeasured.` et ajoute le reçu à `.bmad/memory/outcomes.ndjson`. `mem outcomes` affiche ensuite `<receipt id>: accepted-current`. Si la tâche n’est pas acceptée, si la section manque ou est ambiguë, ou si le périmètre sort de celui de la tâche, `observe` refuse avec le message du tableau des erreurs et n’écrit rien.

**Voir aussi**

- [memory : rapport de santé et export](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-memory/)
- [nexus : d’où viennent les tâches acceptées](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-nexus/)
- [scan : indexer vos projets](https://bmad-plus.rochetta.fr/fr/docs/reference/cli-scan/)
- [Arborescence du projet](https://bmad-plus.rochetta.fr/fr/docs/reference/project-layout/)
- [Dépannage](https://bmad-plus.rochetta.fr/fr/docs/faq/troubleshooting/)

[Documentation BMAD+](https://bmad-plus.rochetta.fr/fr/docs/) · [Référence](https://bmad-plus.rochetta.fr/fr/docs/reference/)

[Code sur GitHub](https://github.com/lrochetta/BMAD-PLUS)