130 lines
3.2 KiB
Markdown
130 lines
3.2 KiB
Markdown
# Memory System
|
|
|
|
Memory in BeadBoard is operational policy, not journal notes.
|
|
|
|
## Core Rule
|
|
|
|
- Reusable rule -> canonical memory bead (`type=decision`)
|
|
- One-off context -> task notes on active bead
|
|
|
|
Canonical memory is active when it is closed and labeled canonical.
|
|
|
|
## Domain Anchors (Use These IDs)
|
|
|
|
- Architecture: `beadboard-76p`
|
|
- Workflow Protocol: `beadboard-nq9`
|
|
- Agent Operations: `beadboard-5r1`
|
|
- UI/UX: `beadboard-fld`
|
|
- Reliability and Errors: `beadboard-8st`
|
|
|
|
## Canonical Memory Contract
|
|
|
|
Required labels:
|
|
- `memory`
|
|
- `mem-canonical`
|
|
- `mem-hard` or `mem-soft`
|
|
- `memory-<domain>`
|
|
|
|
Required description sections:
|
|
- `Scope:`
|
|
- `Out of Scope:`
|
|
- `Rule:`
|
|
- `Rationale:`
|
|
- `Failure Mode:`
|
|
|
|
Required acceptance format:
|
|
- Given/When/Then invariant
|
|
- Verification commands
|
|
|
|
## WHEN to Query Memory
|
|
|
|
Query memory at:
|
|
1. Session start
|
|
2. Before claiming new work
|
|
3. When entering a new domain (arch/workflow/agent/ui/reliability)
|
|
|
|
## Injection Playbook (Steps 1-7)
|
|
|
|
Step 1: Select primary domain
|
|
|
|
```bash
|
|
# choose one:
|
|
# memory-arch | memory-workflow | memory-ux | memory-agent | memory-reliability
|
|
```
|
|
|
|
Step 2: Query canonical memory for that domain
|
|
|
|
```bash
|
|
bd query "label=memory AND label=mem-canonical AND label=<domain> AND status=closed" --sort updated --reverse
|
|
```
|
|
|
|
Step 2b: Validate provenance before trusting it
|
|
|
|
```bash
|
|
bd show <memory-id>
|
|
bd dep list <memory-id>
|
|
```
|
|
|
|
Step 3: Query hard constraints subset
|
|
|
|
```bash
|
|
bd query "label=memory AND label=mem-canonical AND label=mem-hard AND label=<domain> AND status=closed" --sort updated --reverse
|
|
```
|
|
|
|
Step 4: Attach memory to active work
|
|
|
|
```bash
|
|
bd dep relate <active-task-id> <memory-id>
|
|
```
|
|
|
|
Step 5: Optional hard-contract bead (for non-negotiable rules)
|
|
|
|
```bash
|
|
bd create --title "[MEMORY-CONTRACT] <hard-rule>" --type task --label "memory-contract,mem-hard,<domain>" --description "Contract for <active-task-id>"
|
|
bd dep relate <contract-id> <canonical-memory-id>
|
|
bd dep add <active-task-id> <contract-id>
|
|
```
|
|
|
|
Step 6: Record acknowledgement on active task
|
|
|
|
```bash
|
|
bd update <active-task-id> --notes "Memory injection: related <memory-id list>; hard contracts <contract-id list>."
|
|
```
|
|
|
|
Step 7: Preserve provenance evidence in notes
|
|
|
|
```bash
|
|
bd update <active-task-id> --append-notes "Memory provenance verified via bd show/dep list for <memory-id list>."
|
|
```
|
|
|
|
## Ratification Rule
|
|
|
|
"Ratified by closing" means:
|
|
- A decision bead is only an active canonical memory after it is closed.
|
|
- Open decision beads are drafts/proposals, not mandatory policy.
|
|
|
|
## Noise Budget and Promotion Policy
|
|
|
|
Noise budget:
|
|
- Per active task: 3-7 related memory nodes
|
|
- Per active task: 0-2 blocker contracts
|
|
- Per canonical memory: 1 primary anchor domain
|
|
- Per canonical memory: 2-5 source-bead provenance links
|
|
|
|
Promotion policy:
|
|
1. Incident repeats 2+ times -> candidate `mem-soft`
|
|
2. Workaround survives release window -> candidate `mem-hard` or stable `mem-soft`
|
|
3. Obsolete memory -> supersede, do not rewrite history
|
|
|
|
Supersession command:
|
|
|
|
```bash
|
|
bd supersede <old-memory-id> --with <new-memory-id>
|
|
```
|
|
|
|
## Anti-Patterns
|
|
|
|
- Writing policy in markdown without canonical bead
|
|
- Using blocker edges to index memory (use `bd dep relate`)
|
|
- Creating duplicate canonical memory for same rule
|
|
- Skipping provenance check before applying a rule
|