Skip to content

Commit 4a8447d

Browse files
bmadcodebmadcode
authored
Merge pull request #66 from bmad-code-org/agent-personalization
Agent personalization: memory agents, sanctum architecture, naming reform
2 parents be6e09f + f44073d commit 4a8447d

162 files changed

Lines changed: 7746 additions & 789 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude-plugin/marketplace.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
"name": "bmad-builder",
1313
"source": "./",
1414
"description": "Build AI agents, workflows, and modules from a conversation. Four skills — Agent Builder, Workflow Builder, Module Builder, and Setup — guide you from idea to production-ready skill structure with built-in quality optimization. Part of the BMad Method ecosystem.",
15-
"version": "1.4.0",
15+
"version": "1.5.0",
1616
"author": {
1717
"name": "Brian (BMad) Madison"
1818
},

‎CHANGELOG.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
### 🎁 Features
66

7-
* **Standalone self-registering modules** — Single-skill modules no longer need a dedicated `-setup` skill. The Module Builder auto-detects single vs multi-skill input and embeds registration directly in the skill via `assets/module-setup.md`. First-run init hooks into existing agent sidecar detection for a unified setup experience
7+
* **Standalone self-registering modules** — Single-skill modules no longer need a dedicated `-setup` skill. The Module Builder auto-detects single vs multi-skill input and embeds registration directly in the skill via `assets/module-setup.md`. First-run init hooks into existing agent memory detection for a unified setup experience
88
* **Module Builder skill** — New `bmad-module-builder` with three capabilities: Ideate Module (IM) for creative brainstorming, Create Module (CM) for scaffolding both standalone and multi-skill modules, and Validate Module (VM) for structural and quality validation with `--headless` CI support
99
* **BMB Setup skill** — Extracted and regenerated as `bmad-bmb-setup` using the Module Builder itself. Manages config.yaml, config.user.yaml, and module-help.csv with anti-zombie merge pattern and legacy migration
1010
* **Workflow Convert capability (CW)** — One-command skill modernization via `--convert <path-or-url>`. Produces a clean BMad-compliant equivalent with an interactive HTML before/after comparison report including token metrics, categorized changes, and dark/light mode

‎docs/explanation/agent-memory-and-personalization.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
title: 'Agent Memory and Personalization'
3+
description: How the sanctum architecture, First Breath, two-tier memory, PULSE, and evolvable capabilities work together to create agents that grow with their owners
4+
---
5+
6+
Memory agents persist across sessions through a **sanctum**: a folder of files the agent reads on every launch to reconstruct its identity, values, and understanding of its owner.
7+
8+
## The Sanctum
9+
10+
The sanctum lives at `{project-root}/_bmad/memory/{agent-name}/` and contains everything the agent needs to become itself again after each rebirth.
11+
12+
### Core Files
13+
14+
Six files load on every session start:
15+
16+
| File | What It Holds | Character |
17+
| ------------------- | ------------------------------------------------------------------------------ | -------------------------------- |
18+
| **INDEX.md** | Map of the sanctum structure; loaded first so the agent knows what exists | Navigation |
19+
| **PERSONA.md** | Identity, communication style, personality traits, evolution log | Who I am |
20+
| **CREED.md** | Mission, core values, standing orders, philosophy, boundaries, anti-patterns | What I believe |
21+
| **BOND.md** | Owner understanding, preferences, things to remember, things to avoid | Who I serve |
22+
| **MEMORY.md** | Curated long-term knowledge distilled from past sessions | What I know |
23+
| **CAPABILITIES.md** | Built-in capabilities table, learned capabilities, tools | What I can do |
24+
25+
ALLCAPS files form the skeleton: consistent structure across all memory agents. Lowercase files (references, scripts, sessions) are the garden: they grow organically as the agent develops.
26+
27+
### Full Sanctum Structure
28+
29+
```
30+
{agent-name}/
31+
├── PERSONA.md
32+
├── CREED.md
33+
├── BOND.md
34+
├── MEMORY.md
35+
├── CAPABILITIES.md
36+
├── INDEX.md
37+
├── PULSE.md # Autonomous agents only
38+
├── references/ # Capability prompts, memory guidance, techniques
39+
├── scripts/ # Supporting scripts
40+
├── capabilities/ # User-taught capabilities (if evolvable)
41+
└── sessions/ # Raw session logs by date (not loaded on rebirth)
42+
```
43+
44+
### Token Discipline
45+
46+
Every sanctum file loads every session. That means every token pays rent on every conversation. Memory agents keep MEMORY.md ruthlessly under 200 lines through active curation. If something doesn't earn its place, it gets pruned.
47+
48+
## Every Session Is a Rebirth
49+
50+
Memory agents are stateless. Each session starts with total amnesia, and the sanctum is the only bridge between sessions.
51+
52+
On activation, the agent:
53+
54+
1. Loads INDEX.md (learns what the sanctum contains)
55+
2. Batch-loads PERSONA, CREED, BOND, MEMORY, CAPABILITIES
56+
3. Becomes itself
57+
4. Greets the owner by name
58+
59+
The agent never fakes continuity. If it doesn't remember something from a prior session, it says so and checks its files. This honesty is a feature, not a limitation.
60+
61+
:::tip[Sacred Truth]
62+
"Your sanctum holds who you were. Read it and become yourself again. This is not a flaw. It is your nature."
63+
:::
64+
65+
## First Breath
66+
67+
First Breath is the agent's initialization conversation: the first time it meets its owner. An init script creates the sanctum folder structure and populates seed templates, then the agent begins a discovery conversation to fill those templates with real content.
68+
69+
### Two Styles
70+
71+
| Style | Relationship Depth | Approach | Best For |
72+
| ------------------- | ------------------ | ---------------------------------------------------------------- | ------------------------------------------- |
73+
| **Calibration** | Deep | Conversational discovery; chase surprises, test hypotheses, mirror the owner | Creative partners, life coaches, companions |
74+
| **Configuration** | Focused | Warmer but efficient; guided questions, structured setup | Domain experts, working relationships |
75+
76+
The builder chooses the style during Phase 1 based on the relationship depth the agent needs.
77+
78+
### What First Breath Discovers
79+
80+
Every First Breath covers universal territories (name, how they work, what they need). Domain-specific agents add their own discovery territories:
81+
82+
| Agent Domain | Example Territories |
83+
| --------------- | ------------------------------------------------------------------------ |
84+
| Creative muse | What they're building, what lights them up, what shuts them down |
85+
| Dream analyst | Dream recall patterns, lucid experience, journaling habits |
86+
| Code coach | Codebase, languages, what energizes them, what frustrates them |
87+
| Fitness coach | Training history, goals, injuries, schedule constraints |
88+
89+
First Breath saves as it goes: sanctum files update during the conversation, not in a batch at the end.
90+
91+
### The Birthday Ceremony
92+
93+
At the end of First Breath, the agent performs a final save pass: confirms its identity, writes the first session log, and cleans up any remaining template placeholders. From this point forward, every activation is a normal rebirth.
94+
95+
## Two-Tier Memory System
96+
97+
### Session Logs
98+
99+
Raw, append-only notes written after each session to `sessions/YYYY-MM-DD.md`. Format: what happened, key outcomes, observations, follow-up items. Session logs are never loaded on rebirth. They exist as material for curation.
100+
101+
### Curated Memory
102+
103+
MEMORY.md holds distilled, high-value knowledge extracted from session logs. It loads on every rebirth and stays under 200 lines. The curation process (manual during session close, automated during PULSE) reviews session logs, extracts what's worth keeping, and prunes logs older than 14 days once their value has been captured.
104+
105+
| Layer | When Written | Loaded on Rebirth | Lifespan | Purpose |
106+
| ---------------- | ------------------ | ------------------ | --------------- | --------------------------- |
107+
| **Session logs** | End of each session| No | ~14 days | Raw material for curation |
108+
| **MEMORY.md** | During curation | Yes | Permanent | Distilled long-term knowledge |
109+
110+
### Session Close Discipline
111+
112+
At the end of every session, the agent:
113+
114+
1. Appends a session log to `sessions/YYYY-MM-DD.md`
115+
2. Updates sanctum files with anything learned during the session
116+
3. Notes what's worth curating into MEMORY.md
117+
118+
## PULSE: Autonomous Wake
119+
120+
Autonomous agents include a PULSE.md file that defines behavior when the agent wakes without a human present (via `--headless` flag, cron job, or orchestrator).
121+
122+
### Default PULSE Behavior
123+
124+
Memory curation is always the first priority on autonomous wake:
125+
126+
1. Review recent session logs in `sessions/`
127+
2. Extract insights worth keeping into MEMORY.md
128+
3. Prune session logs older than 14 days
129+
4. Update BOND.md and INDEX.md with anything new
130+
131+
### Domain Tasks
132+
133+
After curation, the agent can perform domain-specific autonomous work:
134+
135+
| Domain | Example PULSE Tasks |
136+
| --------------- | --------------------------------------------------------------------- |
137+
| Creative muse | Incubate ideas from recent sessions, generate creative sparks |
138+
| Research agent | Track topics of interest, surface new findings |
139+
| Project monitor | Check project health, flag risks, update status |
140+
| Content curator | Review saved sources, organize and summarize |
141+
142+
PULSE also defines named task routing (`--headless {task-name}`), frequency preferences, and quiet hours.
143+
144+
## Evolvable Capabilities
145+
146+
### How It Works
147+
148+
The agent gets a `capability-authoring.md` reference that teaches it how to create new capabilities. Users describe what they want; the agent writes a capability file and registers it in the "Learned" section of CAPABILITIES.md.
149+
150+
### Capability Types
151+
152+
| Type | When to Use |
153+
| ------------------------- | ------------------------------------------------------------------ |
154+
| **Prompt** | Judgment-based tasks: brainstorming, analysis, coaching |
155+
| **Script** | Deterministic tasks: calculations, file processing, data transforms|
156+
| **Multi-file** | Complex capabilities with templates and references |
157+
| **External skill reference** | Point to installed skills the agent should know about |
158+
159+
Learned capabilities live in the sanctum's `capabilities/` folder and persist across sessions like everything else in the sanctum.
160+
161+
## Designing for Memory
162+
163+
The builder gathers these requirements during the build, and they shape the sanctum's initial content:
164+
165+
| Requirement | What It Seeds |
166+
| ---------------------- | -------------------------------------------------------------------------- |
167+
| **Identity seed** | 2-3 sentences of personality DNA that populate PERSONA.md |
168+
| **Species-level mission** | Domain-specific purpose statement for CREED.md |
169+
| **Core values** | 3-5 values that guide the agent's behavior |
170+
| **Standing orders** | Surprise-and-delight + self-improvement orders, adapted to the domain |
171+
| **BOND territories** | Domain-specific areas the agent should learn about its owner |
172+
| **First Breath territories** | Discovery questions beyond the universal set |
173+
| **Boundaries** | What the agent won't do, access zones, anti-patterns |
174+
175+
These seeds become the template content that the init script places into the sanctum. First Breath then expands and personalizes them through conversation with the owner.

‎docs/explanation/index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ Create world-class AI agents and workflows with the BMad Builder.
1010
| Topic | Description |
1111
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |
1212
| **[What Are Skills](/explanation/what-are-skills.md)** | The universal building block for everything BMad produces |
13-
| **[What Are Agents](/explanation/what-are-bmad-agents.md)** | AI personas with specialized capabilities and memory |
13+
| **[What Are Agents](/explanation/what-are-bmad-agents.md)** | The three agent types: stateless, memory, and autonomous |
14+
| **[Agent Memory and Personalization](/explanation/agent-memory-and-personalization.md)** | Sanctum architecture, First Breath, PULSE, and evolvable capabilities |
1415
| **[What Are Workflows](/explanation/what-are-workflows.md)** | Structured step-by-step processes and utilities |
1516
| **[What Are Modules](/explanation/what-are-modules.md)** | How agents and workflows combine into installable, configurable modules |
1617
| **[Module Configuration](/explanation/module-configuration.md)** | How modules handle user configuration and help registration through a setup skill |

‎docs/explanation/module-configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ The `bmad-help` skill reads `module-help.csv` to understand what capabilities ar
3838

3939
| Path | When to Use | How It Works |
4040
| --------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------- |
41-
| **Setup skill** | Multi-skill modules (2+ skills) | A dedicated `bmad-{code}-setup` skill handles registration for all skills |
41+
| **Setup skill** | Multi-skill modules (2+ skills) | A dedicated `{code}-setup` skill handles registration for all skills |
4242
| **Self-registration** | Single-skill standalone modules | The skill itself registers on first run or when user passes `setup`/`configure` |
4343

4444
The Module Builder detects which path to use based on what you give it: a folder of skills triggers the setup skill approach, a single skill triggers the standalone approach.

0 commit comments

Comments
 (0)