Brian
fc6a41c673
* feat(toolsmith): make a single-skill module the default for one skill Registration is settled from the registry and shown in the read-back instead of asked. A skill joins a module only when the user is working on that module, named it, or chose its prefix. A bmod-<code> record folder is never written for one skill. * fix(toolsmith): ask whether a skill is part of a module Single-skill module stays the offered guess, but discovery now asks whether the skill joins a module or more skills are planned. A planned module settles its code and prefix on the first skill, so nothing is renamed later. * feat(toolsmith): read any agent's session logs and offer customization in from-logs The agent finds its own logs and confirms the location instead of assuming Claude Code. A corrected installed skill can be offered as a bmad-customize change instead of a new skill. * refactor(toolsmith): split discover into short sections and cut what a model infers Registration gets its own section, the five things and other enumerable items become lists, and the read-back carries the consumer and bar. * feat(toolsmith): start prose from one sentence and hold one topic to a paragraph The canon, leanness lens and cut roles now default to the one-sentence version of a passage and split mixed topics. The pre-pass reports long paragraphs and sentences. * refactor(toolsmith): cut prompt files to one topic per paragraph and inline ecosystem into ship Every route, mode and shape file is split into short paragraphs, bullets and cases, with what a model would infer removed. ecosystem.md only ever loaded from ship.md, so its content now lives there. * feat(toolsmith): let a memory agent add its name to its description at First Breath * fix(toolsmith): close a Markdown fence only on its own marker in the pre-pass * fix(toolsmith): let a single-skill module grow into a multi-skill module * fix(toolsmith): write dependencies to the table the module shape uses * feat(toolsmith): restore a memory agent's name after an update and skip global installs * docs(toolsmith): bring the help up to date and route to cut mode * refactor(toolsmith): call the read-back the Smithy execution plan and add help on sharing and subagents * docs(toolsmith): write the Toolsmith docs to replace the builder site
5.9 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Agents with Memory | How a memory agent works: when to build one, the sanctum, waking, how memory is kept and tended, First Breath, naming, and Pulse. |
|
A memory agent keeps its identity and memory in a folder in your project and reloads them each session, so it carries on as the same self. The pattern is called Continuity of Self. This page explains how it works and when it is worth building.
When to Build One
Memory is for an agent that must build up knowledge across sessions. The test: used daily for a month, would the thirtieth session differ from the first? "Nice if it remembered" is a no. A stateless agent with persistent_facts covers standing context.
Smithy asks about four layers as questions, and each yes adds one:
| Would the agent need to | Adds |
|---|---|
| Remember you between sessions | The sanctum |
| Be given material to keep, such as transcripts and notes | The intake capability |
| Be taught new things over time | Learned capabilities |
| Work on its own when nobody is at the keyboard | Pulse |
The Sanctum
The sanctum is the agent's memory, at _bmad/memory/<skill>/ in your project. The skill itself is a short bootloader. It holds a seed of the agent's identity, its mission, how it must behave, and the activation steps. Who the agent is lives in the sanctum.
_bmad/memory/<skill>/
├── PERSONA.md # who I am
├── CREED.md # what I believe: mission, standing orders, boundaries
├── BOND.md # who I serve and what to call them
├── HOW-I-REMEMBER.md # how my memory is laid out
├── CAPABILITIES.md # built-in and learned abilities, tools
├── memory/ # small files by subject and date
│ ├── sessions/
│ └── pending.md # what to raise next time
├── raw/ # material handed over, kept as given
├── capabilities/ # capabilities you taught it
├── references/ # copies of the skill's reference files
├── scripts/ # copies of the skill's scripts
└── PULSE.md # what to do on a schedule, when Pulse is on
The sanctum is also how you shape the agent. Edit these files, or tell the agent what to change, rather than adding a customization layer on top.
Waking
On each activation, wake.py checks for the sanctum. With no sanctum, or one missing an identity file, the agent runs First Breath. Otherwise, it prints the five identity files and a map of memory: each folder with its file count, the newest dated files, raw files not yet distilled, when memory was last tended, and anything pending.
The memory files themselves do not load. The agent reads what a conversation reaches, so waking costs the same however much it knows. It finds things with ls and grep, and there is no index to maintain.
How Memory Is Kept
- Small files, one subject each. A standing subject goes by slug, as in
memory/people/<name>.md. An event goes by date and slug, as inmemory/decisions/2026-10-04-<slug>.md. - Standing files say what is true now. Sections are replaced, not appended. Only a
## Historysection takes dated lines, at turning points. - Handed-over material goes to
raw/. It stays as given. The agent distills it into subject files that link back, and reads those from then on. - The agent writes as it goes. Sessions often end with no warning.
Tending
Memory stays useful by being tended, not by growing. When the map shows session notes since the last tending, the agent distills raw files, merges duplicate subject files, updates standing files a recent session contradicted, raises what you should hear, and records the date. Nothing is deleted for being old.
First Breath
First Breath is the agent's first conversation with you. It is a conversation, not a form. The agent builds its sanctum, then asks what to call you, and your reply sets both your name and the language it uses. Nothing about you comes from config.
It then learns about you and finds its specific mission for you, saving as it goes. The agent's domain sets the topics it explores, and Smithy writes those topics when it builds the agent. Anything unfinished goes to memory/pending.md for the next waking.
There are two styles. A deep relationship agent explores freely. A focused agent gets the basics and defers to any urgent work you bring.
Naming the Agent
An agent can ship with a name, or ship with an empty one and be named at First Breath. Once the name is settled, the agent adds it to its own description, so you can ask for it by name from your next session. This is the one edit an agent makes to its own SKILL.md.
Two cases work differently:
- After an update.
npx skills updatereplacesSKILL.md, which removes the name. The sanctum keeps it, and the agent puts it back at its next waking. - Global installs. A global skill serves every project, and each project has its own sanctum, so the agent skips this edit.
Pulse
Pulse is optional. The agent wakes on a schedule with nobody at the keyboard, tends its memory first, then does the tasks its PULSE.md lists. You choose whether to use it and how often during First Breath.
Build One
Ask Smithy for an agent that remembers you. Use the build steps as usual, with these differences:
- Smithy tests whether memory is warranted, and proposes a stateless agent if not.
- The execution plan shows the name, or an empty name, the mission, the First Breath topics, and the built-in capabilities.
- Smithy writes the bootloader, First Breath, capability files, sanctum seeds,
wake.py, andinit-sanctum.py. - The first time you activate the agent, First Breath runs.
:::tip[Keep your memory out of the repository]
A sanctum can hold personal details. Check whether _bmad/memory/ belongs in version control for your project before you share anything sensitive with the agent.
:::