beadboard/skills/beadboard-driver/references/memory-system.md

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

# choose one:
# memory-arch | memory-workflow | memory-ux | memory-agent | memory-reliability

Step 2: Query canonical memory for that domain

bd query "label=memory AND label=mem-canonical AND label=<domain> AND status=closed" --sort updated --reverse

Step 2b: Validate provenance before trusting it

bd show <memory-id>
bd dep list <memory-id>

Step 3: Query hard constraints subset

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

bd dep relate <active-task-id> <memory-id>

Step 5: Optional hard-contract bead (for non-negotiable rules)

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

bd update <active-task-id> --notes "Memory injection: related <memory-id list>; hard contracts <contract-id list>."

Step 7: Preserve provenance evidence in notes

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:

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