110 lines
3 KiB
Markdown
110 lines
3 KiB
Markdown
# Memory System
|
|
|
|
## Purpose
|
|
|
|
Use BeadBoard memory to preserve reusable operating rules across sessions.
|
|
|
|
Memory is tracked in `bd` decision beads, not markdown notes. Task notes are for local execution context; canonical memory is for reusable rules.
|
|
|
|
## Execution Context
|
|
|
|
- Agents usually run in a target project repository, not the BeadBoard repository.
|
|
- Project scope is controlled by the user in the BeadBoard UI.
|
|
- Agents do not select or mutate project scope.
|
|
|
|
## Core Objects
|
|
|
|
- Anchor: domain parent bead (for example architecture, workflow, agent ops, reliability).
|
|
- Canonical memory: `type=decision` bead with memory labels.
|
|
- Provenance links: relations from memory to source evidence beads.
|
|
|
|
## Canonical Memory Contract
|
|
|
|
Create canonical memory only when the rule is reusable.
|
|
|
|
Required labels:
|
|
|
|
- `mem-canonical`
|
|
- `mem-hard` or `mem-soft`
|
|
- `memory`
|
|
- domain label such as `memory-agent`, `memory-arch`, `memory-workflow`, `memory-reliability`, `memory-ui`
|
|
|
|
Required description sections:
|
|
|
|
- `Scope:`
|
|
- `Out of Scope:`
|
|
- `Rule:`
|
|
- `Rationale:`
|
|
- `Failure Mode:`
|
|
|
|
Required acceptance style:
|
|
|
|
- Given/When/Then invariant
|
|
- Verification commands
|
|
|
|
## Workflow
|
|
|
|
1. Query existing memory first.
|
|
2. Validate the memory provenance before relying on it.
|
|
3. Apply existing canonical memory to current task design.
|
|
4. If a new reusable rule appears, create canonical memory.
|
|
5. Link anchor, evidence, and related work with `bd dep relate`.
|
|
6. Ratify by closing the memory bead once complete.
|
|
7. For changes to an existing rule, supersede; do not rewrite history.
|
|
|
|
## Query and Validation Commands
|
|
|
|
```bash
|
|
bd query "type=decision label:mem-canonical"
|
|
bd show <memory-id>
|
|
bd dep list <memory-id>
|
|
```
|
|
|
|
Interpretation checklist:
|
|
|
|
- Is the memory closed and canonical?
|
|
- Are provenance links present (2-5 evidence beads preferred)?
|
|
- Is the domain anchor relationship present?
|
|
|
|
## Create and Index Canonical Memory
|
|
|
|
```bash
|
|
bd create --title="[MEMORY][<DOMAIN>][HARD|SOFT] <rule sentence>" \
|
|
--description="Scope: ...\nOut of Scope: ...\nRule: ...\nRationale: ...\nFailure Mode: ..." \
|
|
--type=decision --priority=1 \
|
|
--label="mem-canonical,mem-hard,memory,memory-<domain>"
|
|
|
|
bd dep relate <anchor-id> <memory-id>
|
|
bd dep relate <memory-id> <source-bead-id>
|
|
```
|
|
|
|
Use `mem-soft` when the rule is guidance and `mem-hard` when it is non-negotiable.
|
|
|
|
## Evolve Memory Safely
|
|
|
|
Use supersession when changing canonical rules:
|
|
|
|
```bash
|
|
bd supersede <old-memory-id> --with <new-memory-id>
|
|
```
|
|
|
|
Do not edit historical memory beads to represent new policy.
|
|
|
|
## Noise Budget
|
|
|
|
Apply memory sparingly per active task:
|
|
|
|
- 3-7 related memory nodes
|
|
- 0-2 blocker contracts
|
|
- 1 primary anchor domain per canonical memory
|
|
- 2-5 source-bead provenance links
|
|
|
|
If the lesson is not reusable, record it in task notes instead of creating memory.
|
|
|
|
## Anti-Patterns
|
|
|
|
- Writing policy in ad-hoc markdown only.
|
|
- Using blocker edges for memory indexing.
|
|
- Creating duplicate canonical memory for the same rule.
|
|
- Creating memory for one-off incidents without recurrence.
|
|
- Claiming memory-backed completion without verification evidence.
|