From 801389e87ce86aa5128f3dff96ea7990b7cbf2d8 Mon Sep 17 00:00:00 2001 From: ZenchantLive Date: Tue, 3 Mar 2026 18:56:37 -0800 Subject: [PATCH] docs(driver-v5): expand memory protocol reference (maf.2) --- .../references/memory-system.md | 150 ++++++++++-------- 1 file changed, 85 insertions(+), 65 deletions(-) diff --git a/skills/beadboard-driver/references/memory-system.md b/skills/beadboard-driver/references/memory-system.md index df85536..4e9997f 100644 --- a/skills/beadboard-driver/references/memory-system.md +++ b/skills/beadboard-driver/references/memory-system.md @@ -1,110 +1,130 @@ # Memory System -## Purpose +Memory in BeadBoard is operational policy, not journal notes. -Use BeadBoard memory to preserve reusable operating rules across sessions. +## Core Rule -Memory is tracked in `bd` decision beads, not markdown notes. Task notes are for local execution context; canonical memory is for reusable rules. +- Reusable rule -> canonical memory bead (`type=decision`) +- One-off context -> task notes on active bead -## Execution Context +Canonical memory is active when it is closed and labeled canonical. -- 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. +## Domain Anchors (Use These IDs) -## 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. +- Architecture: `beadboard-76p` +- Workflow Protocol: `beadboard-nq9` +- Agent Operations: `beadboard-5r1` +- UI/UX: `beadboard-fld` +- Reliability and Errors: `beadboard-8st` ## Canonical Memory Contract -Create canonical memory only when the rule is reusable. - Required labels: - +- `memory` - `mem-canonical` - `mem-hard` or `mem-soft` -- `memory` -- domain label such as `memory-agent`, `memory-arch`, `memory-workflow`, `memory-reliability`, `memory-ui` +- `memory-` Required description sections: - - `Scope:` - `Out of Scope:` - `Rule:` - `Rationale:` - `Failure Mode:` -Required acceptance style: - +Required acceptance format: - Given/When/Then invariant - Verification commands -## Workflow +## WHEN to Query Memory -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 memory at: +1. Session start +2. Before claiming new work +3. When entering a new domain (arch/workflow/agent/ui/reliability) -## Query and Validation Commands +## 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= AND status=closed" --sort updated --reverse +``` + +Step 2b: Validate provenance before trusting it ```bash -bd query "type=decision label:mem-canonical" bd show bd dep list ``` -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 +Step 3: Query hard constraints subset ```bash -bd create --title="[MEMORY][][HARD|SOFT] " \ - --description="Scope: ...\nOut of Scope: ...\nRule: ...\nRationale: ...\nFailure Mode: ..." \ - --type=decision --priority=1 \ - --label="mem-canonical,mem-hard,memory,memory-" - -bd dep relate -bd dep relate +bd query "label=memory AND label=mem-canonical AND label=mem-hard AND label= AND status=closed" --sort updated --reverse ``` -Use `mem-soft` when the rule is guidance and `mem-hard` when it is non-negotiable. +Step 4: Attach memory to active work -## Evolve Memory Safely +```bash +bd dep relate +``` -Use supersession when changing canonical rules: +Step 5: Optional hard-contract bead (for non-negotiable rules) + +```bash +bd create --title "[MEMORY-CONTRACT] " --type task --label "memory-contract,mem-hard," --description "Contract for " +bd dep relate +bd dep add +``` + +Step 6: Record acknowledgement on active task + +```bash +bd update --notes "Memory injection: related ; hard contracts ." +``` + +Step 7: Preserve provenance evidence in notes + +```bash +bd update --append-notes "Memory provenance verified via bd show/dep list for ." +``` + +## 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 --with ``` -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. +- 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