bmad-plus 0.6.0 → 0.7.0

package/src/bmad-plus/module.yaml

@@ -160,6 +160,17 @@ packs:
     agents:
       - animated-website-agent
 
+  memory:
+    name: "Memory — Persistent Brain"
+    icon: "🧠"
+    description: "Cross-session memory + project scanner + Karpathy guardrails"
+    required: false
+    packDir: pack-memory
+    packSrcDir: packs
+    agents:
+      - zecher
+    cohabitation_warning: "Memory can detect and link to existing brain directories (_brain/, ~/.claude/memory/). It will NEVER overwrite existing memory files."
+
 install_packs:
   prompt:
     - "Quels packs additionnels souhaites-tu installer ?"
@@ -181,6 +192,8 @@ install_packs:
       label: "🗂️ Universal Backup — Backup ZIP intelligent"
     - value: "animated"
       label: "🎬 Animated Website — Luxury scroll-driven site from video"
+    - value: "memory"
+      label: "🧠 Memory — Cerveau persistant + scanner de projets + guardrails Karpathy"
     - value: "all"
       label: "🤖 Tout installer"
     - value: "none"

package/src/bmad-plus/packs/pack-memory/README.md

@@ -0,0 +1,106 @@
+# Pack Memory — Persistent Brain for BMAD+
+
+> 🧠 Give your AI agents a memory that persists across sessions, projects, and time.
+
+## What is Pack Memory?
+
+Pack Memory adds a **persistent brain** to BMAD+. Every decision logged, every lesson learned, every pattern discovered — they all survive between sessions. Your agents get smarter over time.
+
+### Two Levels of Memory
+
+| Level | Location | Scope |
+|-------|----------|-------|
+| **Project Memory** | `.agents/memory/` | Decisions, lessons, patterns for ONE project |
+| **Global Brain** | `~/.bmad-plus/brain/` | Cross-project knowledge, user preferences, project index |
+
+### The Golden Rule
+
+> If info applies to **1 project** → project memory. If **2+ projects** → global brain.
+
+## Features
+
+### 🧠 Persistent Memory
+- `decisions.md` — ADR-style architectural decisions with rationale
+- `lessons.md` — Things that burned you, logged immediately, never repeated
+- `patterns.md` — Validated solutions that work, ready to reuse
+- `context.md` — Living project state, auto-updated by agents
+- `sessions/` — Session handoffs for seamless context transfer
+
+### 🔍 Project Scanner
+- Scan any directory (or entire disk) to discover projects
+- Auto-detect tech stack from project markers
+- Interactive validation — you confirm each project before indexing
+- Build a complete portfolio index in your global brain
+
+### 🛡️ Karpathy Guardrails
+Four behavioral principles (from Andrej Karpathy, 132K ⭐) woven into every agent:
+1. **Think Before Coding** — Surface assumptions, don't guess
+2. **Simplicity First** — Minimum code, nothing speculative
+3. **Surgical Changes** — Touch only what you must
+4. **Goal-Driven Execution** — Define success criteria, verify
+
+### 🤖 Zecher Agent (זכר)
+Dedicated memory agent that can:
+- Consolidate and deduplicate memory entries
+- Scan and index projects interactively
+- Reconstruct context when starting a cold session
+- Run memory health checks
+
+## Installation
+
+```bash
+npx bmad-plus install
+# Select "🧠 Memory — Persistent Brain" in the pack menu
+```
+
+### Brain Detection
+
+If you already have a brain directory (`_brain/`, `~/.claude/memory/`, etc.), BMAD+ will:
+- ✅ **Detect it** automatically
+- ✅ **Link to it** — no duplication
+- ❌ **Never overwrite** your existing memory
+
+## Quick Start
+
+After installation:
+
+```
+# Scan your projects
+"Zecher, scan projects in D:\travail\DEV"
+
+# Start remembering
+"Atlas, create a PRD for..."    ← decisions auto-logged
+"Forge, implement story S1"     ← patterns auto-detected
+
+# Recall context
+"Zecher, where were we?"        ← instant context reconstruction
+
+# Maintain memory
+"Zecher, health check"          ← verify integrity
+"Zecher, consolidate memory"    ← deduplicate & archive
+```
+
+## File Structure
+
+```
+pack-memory/
+├── README.md                     ← This file
+├── memory-orchestrator.md        ← Pack entry point
+├── zecher-agent.md               ← Memory Agent (Zecher)
+├── shared/
+│   ├── karpathy-guardrails.md    ← Behavioral guardrails
+│   └── memory-protocol.md       ← Read/write protocol
+└── templates/
+    ├── decisions.md
+    ├── lessons.md
+    ├── patterns.md
+    ├── context.md
+    ├── session-handoff.md
+    └── identity.yaml
+```
+
+## Credits
+
+- Memory architecture inspired by Laurent Rochetta's `_brain/` methodology
+- Behavioral guardrails adapted from [Andrej Karpathy](https://github.com/multica-ai/andrej-karpathy-skills) (MIT License)
+- BMAD+ by [Laurent Rochetta](https://github.com/lrochetta/BMAD-PLUS)

package/src/bmad-plus/packs/pack-memory/memory-orchestrator.md

@@ -0,0 +1,79 @@
+# Pack Memory — Orchestrator
+
+> Manages the persistent memory system for BMAD+ projects.
+
+## Overview
+
+Pack Memory provides a two-level persistent brain for BMAD+:
+- **Project memory** (`.agents/memory/`) — decisions, lessons, patterns specific to one project
+- **Global brain** (`~/.bmad-plus/brain/`) — cross-project knowledge that grows over time
+
+## Agent
+
+| Agent | Hebrew | Role |
+|-------|--------|------|
+| **Zecher** | זכר (remembrance) | Memory archivist — consolidation, scanning, recall |
+
+## Activation
+
+Pack Memory activates automatically when installed:
+- At session start: agents load project memory + global identity
+- During session: agents write decisions/lessons/patterns on trigger
+- At session end: session handoff is persisted
+
+Manual activation via Zecher:
+- `"Zecher, scan projects in D:\travail\DEV"` — discover and index all projects
+- `"Zecher, consolidate memory"` — deduplicate, archive stale, promote
+- `"Zecher, where were we?"` — reconstruct context from last session
+- `"Zecher, health check"` — verify memory integrity
+
+## Memory Protocol
+
+See `shared/memory-protocol.md` for the complete read/write protocol.
+
+## Behavioral Guardrails
+
+See `shared/karpathy-guardrails.md` for the 4 Karpathy principles with memory integration.
+
+## Files
+
+```
+pack-memory/
+├── README.md                           ← You are here
+├── memory-orchestrator.md              ← This file
+├── zecher-agent.md                     ← Memory Agent (Zecher)
+├── shared/
+│   ├── karpathy-guardrails.md          ← 4 Karpathy principles + memory hooks
+│   └── memory-protocol.md             ← Complete read/write protocol
+└── templates/
+    ├── decisions.md                    ← ADR template
+    ├── lessons.md                      ← Lessons template
+    ├── patterns.md                     ← Patterns template
+    ├── context.md                      ← Living project context
+    ├── session-handoff.md              ← Session handoff template
+    └── identity.yaml                   ← User preferences (global brain)
+```
+
+## Cohabitation Warning
+
+> ⚠️ If you have an existing brain directory (`_brain/`, `~/.claude/memory/`, etc.),
+> BMAD+ will detect it and **link to it** instead of creating a duplicate.
+> Your existing memory will NOT be overwritten.
+
+## Installation Behavior
+
+When Pack Memory is selected during `npx bmad-plus install`:
+
+1. **Brain detection** — Scans for existing brain directories
+2. **Project memory** — Creates `.agents/memory/` with templates
+3. **Global brain** — Creates `~/.bmad-plus/brain/` if it doesn't exist
+4. **Identity setup** — Generates `identity.yaml` from user's install answers
+5. **Guardrails injection** — Makes `karpathy-guardrails.md` available to all agents
+
+## CLI Commands (planned)
+
+```
+npx bmad-plus scan [path]      — Scan and index projects interactively
+npx bmad-plus memory status    — Show memory health report
+npx bmad-plus memory export    — Export brain as portable archive
+```

package/src/bmad-plus/packs/pack-memory/shared/karpathy-guardrails.md

@@ -0,0 +1,86 @@
+# Karpathy Guardrails — BMAD+ Agent Behavioral Guidelines
+
+> Adapted from [andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) (132K ⭐, MIT License)
+> Enhanced with BMAD+ memory integration
+
+---
+
+## G1 — Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, **ask**.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+- **Check `.agents/memory/decisions.md`** for prior decisions on this topic before deciding again.
+- **Check `.agents/memory/lessons.md`** for known pitfalls before proceeding.
+
+## G2 — Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+- **Check `.agents/memory/patterns.md`** — a pattern that already solved this might exist.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## G3 — Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+**Memory integration**: If you discover something surprising, **log it immediately** in `.agents/memory/lessons.md`.
+
+## G4 — Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+**Memory integration**: Log non-obvious architectural decisions in `.agents/memory/decisions.md` with rationale.
+
+---
+
+## When These Guidelines Are Working
+
+- Fewer unnecessary changes in diffs — only requested changes appear
+- Fewer rewrites due to overcomplication — code is simple the first time
+- Clarifying questions come BEFORE implementation — not after mistakes
+- Clean, minimal PRs — no drive-by refactoring or "improvements"
+- **Persistent learning** — the same mistake never happens twice because it's in lessons.md
+
+---
+
+## Attribution
+
+Behavioral principles by [Andrej Karpathy](https://x.com/karpathy) via [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) (MIT License).
+Memory integration by [Laurent Rochetta](https://github.com/lrochetta/BMAD-PLUS).

package/src/bmad-plus/packs/pack-memory/shared/memory-protocol.md

@@ -0,0 +1,143 @@
+# Memory Protocol — When and How Agents Use Memory
+
+> This protocol defines when BMAD+ agents should read from and write to the persistent memory system.
+
+---
+
+## Memory Locations
+
+### Project Memory (per-project)
+```
+<project>/.agents/memory/
+├── decisions.md        ← Architectural decisions for THIS project
+├── lessons.md          ← Mistakes and surprises in THIS project
+├── patterns.md         ← Validated patterns in THIS project
+├── context.md          ← Living state (auto-updated)
+└── sessions/           ← Session handoffs
+    └── YYYY-MM-DD-<topic>.md
+```
+
+### Global Brain (cross-project)
+```
+~/.bmad-plus/brain/
+├── identity.yaml       ← User preferences (stack, style, rules)
+├── decisions.md        ← Cross-project decisions
+├── lessons.md          ← Cross-project lessons
+├── patterns.md         ← Reusable patterns
+├── stack-preferences.md ← Default tech choices
+└── projects/           ← Index of all BMAD+ projects
+    └── <hash>.yaml     ← Per-project metadata
+```
+
+---
+
+## Protocol: Session Start (READ)
+
+Every agent MUST perform this sequence at the start of a meaningful session:
+
+1. **Read `identity.yaml`** (global) — Know the user's preferences
+2. **Read `context.md`** (project) — Understand current state
+3. **Read `decisions.md`** (project) — Don't re-decide what's already decided
+4. **Read `lessons.md`** (project) — Don't repeat known mistakes
+5. **Optionally read latest `sessions/`** — If resuming work
+
+> If a file doesn't exist, skip it silently. Memory is always optional.
+
+---
+
+## Protocol: During Session (WRITE on trigger)
+
+### Trigger → decisions.md
+**When**: A non-obvious architectural or strategic choice is made.
+**What**: ADR-style entry (Context, Decision, Rationale, Consequences, Status).
+**Rule**: If you'd explain "why" to a colleague, it's a decision worth logging.
+
+### Trigger → lessons.md
+**When**: Something unexpected happens, a bug is caused by a non-obvious issue, or an assumption proved wrong.
+**What**: Context, Impact, Lesson (the rule to follow next time).
+**Rule**: Log IMMEDIATELY — don't wait for session end.
+
+### Trigger → patterns.md
+**When**: A solution works well and could be reused in other contexts.
+**What**: Problem, Shape, Trade-off, Status (candidate → validated).
+**Rule**: Only promote to global patterns.md if used in 2+ projects.
+
+### Trigger → context.md
+**When**: The project state changes meaningfully (new module, stack change, architecture shift).
+**What**: Update the relevant section.
+**Rule**: Keep it concise — this file should be readable in 30 seconds.
+
+---
+
+## Protocol: Session End (PERSIST)
+
+If meaningful work was done:
+
+1. **Write session handoff** → `sessions/YYYY-MM-DD-<topic>.md`
+2. **Update `context.md`** → Reflect new reality
+3. **Review pending lessons** → Any surprise worth logging?
+4. **Cross-project check** → Any lesson/pattern that applies to ALL projects? → Copy to global brain.
+
+---
+
+## The Golden Rule
+
+> **If info applies to 1 project → project memory. If 2+ projects → global brain.**
+
+---
+
+## Merge Safety
+
+When reinstalling BMAD+ or updating:
+- **NEVER overwrite** decisions.md, lessons.md, patterns.md
+- **NEVER delete** sessions/ directory
+- **Safe to overwrite**: context.md template (user regenerates), identity.yaml template only if no user edits
+- **Install manifest** (`.bmad-plus-install.json`) tracks what was installed, brain detection prevents overwrites
+
+---
+
+## Project Scanner Protocol
+
+The `bmad-plus scan` command follows this protocol:
+
+1. **Scan** target directory recursively for project markers (package.json, Cargo.toml, .git, etc.)
+2. **Analyze** each discovered project (detect stack, status, last modified)
+3. **Present** findings to user in interactive table
+4. **User validates** each project (confirm, skip, edit metadata)
+5. **Index** validated projects in `~/.bmad-plus/brain/projects/<hash>.yaml`
+6. **Generate** project-level memory stubs if requested
+
+### Project Detection Markers (priority order)
+```
+package.json          → Node.js / JavaScript
+Cargo.toml            → Rust
+requirements.txt      → Python
+pyproject.toml        → Python
+go.mod                → Go
+composer.json         → PHP
+Gemfile               → Ruby
+*.sln / *.csproj      → .NET
+pom.xml               → Java
+build.gradle          → Java/Kotlin
+.git                  → Any (version controlled)
+AGENTS.md             → Already agent-aware
+.agents/              → Already BMAD+ installed
+```
+
+### Project Metadata (per scan)
+```yaml
+# ~/.bmad-plus/brain/projects/<hash>.yaml
+path: "D:\\travail\\DEV\\my-project"
+name: "my-project"
+hash: "a1b2c3d4"  # SHA256 of absolute path
+stack:
+  primary: "Node.js"
+  framework: "Next.js 15"
+  database: "PostgreSQL"
+status: "active"          # active / paused / archived / unknown
+last_modified: "2026-05-17"
+last_scanned: "2026-05-17"
+bmad_installed: true
+packs_installed: ["core", "memory", "dev-studio"]
+notes: "CRM client project"
+```

package/src/bmad-plus/packs/pack-memory/templates/context.md

@@ -0,0 +1,39 @@
+---
+title: Project Context
+description: Living state of this project — auto-updated by agents
+created: "{{date}}"
+project: "{{project_name}}"
+last_updated: "{{date}}"
+---
+
+# Project Context
+
+> This file is the **living state** of the project. It is read by agents at session start and updated at session end.
+
+## Project Identity
+
+- **Name**: {{project_name}}
+- **Path**: {{project_path}}
+- **Stack**: (to be detected or filled by user)
+- **Status**: active
+- **Created**: {{date}}
+
+## Current Focus
+
+<!-- What matters right now -->
+
+## Recent Changes
+
+<!-- Last 5 significant changes, most recent first -->
+
+## Architecture Notes
+
+<!-- Key architectural decisions and constraints -->
+
+## Known Issues
+
+<!-- Active bugs or tech debt to be aware of -->
+
+## Open Questions
+
+<!-- Things that need human decision -->

package/src/bmad-plus/packs/pack-memory/templates/decisions.md

@@ -0,0 +1,25 @@
+---
+title: Decisions
+description: ADR-style log of architectural and strategic decisions
+created: "{{date}}"
+project: "{{project_name}}"
+---
+
+# Decisions
+
+Architectural and strategic decisions for this project. One entry per decision, short and actionable.
+
+## Format
+
+```
+### 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
+```
+
+---
+
+<!-- Decisions will be appended below by BMAD+ agents -->

package/src/bmad-plus/packs/pack-memory/templates/identity.yaml

@@ -0,0 +1,39 @@
+# BMAD+ User Identity
+# This file stores your preferences across all BMAD+ projects.
+# It is read by agents at session start to personalize their behavior.
+# Location: ~/.bmad-plus/brain/identity.yaml
+
+user_name: "{{user_name}}"
+communication_language: "{{language}}"
+created: "{{date}}"
+
+# How you prefer agents to communicate
+style:
+  verbosity: "concise"           # concise | detailed | minimal
+  code_comments: "essential"     # essential | verbose | none
+  explain_level: "expert"        # beginner | intermediate | expert
+
+# Your default tech preferences
+stack:
+  # Agents will prefer these unless project-specific overrides exist
+  # Fill in as you work — agents will suggest additions
+  # Example:
+  # frontend: "Next.js 15"
+  # backend: "Node.js + Express"
+  # database: "PostgreSQL"
+  # hosting: "Hetzner VPS"
+
+# Known AI tools in your environment
+ai_tools: []
+  # - claude-code
+  # - antigravity
+  # - cursor
+  # - codex-cli
+
+# Anti-regression rules (agents MUST follow)
+rules:
+  - "Never rewrite entire files — surgical edits only"
+  - "Never delete existing code without explicit approval"
+  - "Always read existing file before modifying"
+  - "Dates in ISO 8601 (YYYY-MM-DD), never relative"
+  - "Never commit without explicit permission"

package/src/bmad-plus/packs/pack-memory/templates/lessons.md

@@ -0,0 +1,31 @@
+---
+title: Lessons
+description: Things that burned us — don't repeat
+created: "{{date}}"
+project: "{{project_name}}"
+---
+
+# Lessons
+
+Things that went wrong. Logged immediately. Never repeated.
+
+## Format
+
+```
+### YYYY-MM-DD — <what happened>
+- **Context**: circumstances
+- **Impact**: what went wrong / cost
+- **Lesson**: the rule to follow next time
+```
+
+---
+
+## Meta-lessons (always apply)
+
+- When producing content for a page/UI: read the EXISTING file entirely BEFORE rewriting. Never regenerate from blank.
+- Dates absolute (ISO 8601 `YYYY-MM-DD`), never relative.
+- Never commit without explicit user permission.
+
+---
+
+<!-- Lessons will be appended below by BMAD+ agents -->

package/src/bmad-plus/packs/pack-memory/templates/patterns.md

@@ -0,0 +1,24 @@
+---
+title: Patterns
+description: Reusable patterns observed in this project
+created: "{{date}}"
+project: "{{project_name}}"
+---
+
+# Patterns
+
+Reusable patterns that work well in this project. Each pattern answers: *what problem does this solve, where does it apply, what's the trade-off?*
+
+## Format
+
+```
+### <pattern name>
+- **Problem**: what it solves
+- **Shape**: the core idea in 2-3 sentences
+- **Trade-off**: what it costs
+- **Status**: `candidate` / `validated` / `deprecated`
+```
+
+---
+
+<!-- Patterns will be appended below by BMAD+ agents -->

package/src/bmad-plus/packs/pack-memory/templates/session-handoff.md

@@ -0,0 +1,25 @@
+---
+title: Session Handoff
+description: Context transfer between AI sessions
+date: "{{date}}"
+topic: "{{topic}}"
+agent: "{{agent}}"
+project: "{{project_name}}"
+---
+
+# Session Handoff — {{date}}
+
+## What changed
+<!-- Summary of work done this session -->
+
+## Decisions made
+<!-- Non-obvious decisions with rationale -->
+
+## Open questions
+<!-- Things that need human decision or more research -->
+
+## Next steps
+<!-- What should happen next, in priority order -->
+
+## Files modified
+<!-- List of files changed, with short reason -->