From 9eb805cfa14c3d99890d018b3eddbe5645351ba5 Mon Sep 17 00:00:00 2001 From: ZenchantLive Date: Sun, 1 Mar 2026 16:41:12 -0800 Subject: [PATCH] docs: finalize bd-native memory fabric plan and phase-1 evidence --- docs/plans/2026-03-01-beads-native-memory.md | 108 +++++++++++++ .../2026-03-02-bd-memory-fabric-design.md | 153 ++++++++++++++++++ 2 files changed, 261 insertions(+) create mode 100644 docs/plans/2026-03-01-beads-native-memory.md create mode 100644 docs/plans/2026-03-02-bd-memory-fabric-design.md diff --git a/docs/plans/2026-03-01-beads-native-memory.md b/docs/plans/2026-03-01-beads-native-memory.md new file mode 100644 index 0000000..b3f1c91 --- /dev/null +++ b/docs/plans/2026-03-01-beads-native-memory.md @@ -0,0 +1,108 @@ +# Native Memory System Implementation Plan + +Goal: establish a durable, low-noise, bd-native memory system with explicit retrieval, lineage, and selective enforcement. + +## Final Architecture (Phase 1) + +Memory uses a layered model: + +1. Domain Anchors (open epics) +- Purpose: stable index roots per domain +- Type: `epic` +- Labels: `memory,memory-anchor,` +- Link style: `bd dep relate ` + +2. Canonical Memory Nodes (closed decisions) +- Purpose: immutable ratified rules/patterns +- Type: `decision` +- Labels: `memory,mem-canonical,mem-hard|mem-soft,` +- Lifecycle: create -> ratify -> close; evolve with `bd supersede` + +3. Execution Contracts (future phase) +- Purpose: temporary blockers for hard constraints only +- Type: `task|decision` +- Labels: `memory-contract,mem-hard` +- Link style: contract blocks active work; contract relates to canonical memory + +## Query Model + +Domain retrieval: +```bash +bd query "label=memory AND label=mem-canonical AND label= AND status=closed" +``` + +Hard constraints only: +```bash +bd query "label=memory AND label=mem-canonical AND label=mem-hard AND status=closed" +``` + +Attach context to active work: +```bash +bd dep relate +``` + +## Data Contract for Canonical Memory + +Title: +- `[MEMORY][][HARD|SOFT] ` + +Description fields: +- Scope +- Out of Scope +- Rule +- Rationale +- Failure Mode + +Acceptance: +- Given/When/Then invariant + concrete verification commands + +Metadata JSON: +```json +{ + "memory_version": 1, + "memory_strength": "hard|soft", + "domain": "memory-...", + "effective_date": "YYYY-MM-DD", + "owner": "team", + "supersedes": null, + "superseded_by": null +} +``` + +## Phase 1 Execution Evidence (2026-03-02) + +Tracking bead: +- `beadboard-yz6` + +Anchors created: +- `beadboard-76p` `[MEMORY-ANCHOR] Architecture` +- `beadboard-fld` `[MEMORY-ANCHOR] UI/UX` +- `beadboard-nq9` `[MEMORY-ANCHOR] Workflow Protocol` +- `beadboard-5r1` `[MEMORY-ANCHOR] Agent Operations` +- `beadboard-8st` `[MEMORY-ANCHOR] Reliability and Errors` + +Canonical memories created and closed: +- `beadboard-116` `[MEMORY][WORKFLOW][HARD] Evidence before completion claims` +- `beadboard-dvp` `[MEMORY][AGENT][SOFT] Parallelize independent work with clear ownership` +- `beadboard-60a` `[MEMORY][ARCH][HARD] Dependencies model execution order, not visual order` +- `beadboard-zas` `[MEMORY][ARCH][HARD] Shared logic for cross-view behavior` +- `beadboard-duo` `[MEMORY][UX][SOFT] User-facing copy must stay simple and explicit` +- `beadboard-6fv` `[MEMORY][RELIABILITY][HARD] Triage stale-state bugs via parity and watcher checks` +- `beadboard-fga` `[MEMORY][RELIABILITY][SOFT] Workarounds require trigger rollback and owner` + +Connectivity verified via `bd dep list` on each anchor and `bd query` for canonical closed memory labels. + +## Next Phase + +1. Add task-start routine in agent protocol: +- query by domain +- relate top relevant memories +- elevate only hard constraints into contract blockers + +2. Add lint/guardrail checks: +- active task in a domain must have at least one memory relation +- applicable hard memories must have a contract blocker before completion + +3. Add pruning policy: +- promote repeated incidents into canonical decisions +- supersede stale workaround memory nodes diff --git a/docs/plans/2026-03-02-bd-memory-fabric-design.md b/docs/plans/2026-03-02-bd-memory-fabric-design.md new file mode 100644 index 0000000..2d3a24e --- /dev/null +++ b/docs/plans/2026-03-02-bd-memory-fabric-design.md @@ -0,0 +1,153 @@ +# BeadBoard Memory Fabric Design + +## Why A/B/C feel insufficient + +- Option A (Vector Node Pattern) is strong for immutable history and retrieval, but weak on enforcement. Agents can skip query steps and still proceed. +- Option B (Active Protocol Roster) is strong for visibility and onboarding, but weak on audit integrity. Directly mutating a single Epic note creates merge noise and weak provenance. +- Option C (Execution Contract Pattern) is strong for hard enforcement, but too rigid. If every memory becomes a blocker, throughput drops and dependency graphs become noisy. + +The core issue: each option optimizes one axis and sacrifices the other two. + +## Recommended Architecture: Option D "Memory Fabric" (Layered) + +Use three memory layers, each mapped to a specific `bd` mechanism: + +1. Canonical Memory Nodes (immutable knowledge) +- Type: `decision` +- Status: `closed` once ratified +- Labels: `memory`, one domain label (`memory-ux`, `memory-arch`, etc.), one strength label (`mem-hard` or `mem-soft`) +- Fields: + - `title`: single rule statement in plain language + - `description`: Scope / Out of Scope / Rule / Rationale / Failure Mode + - `acceptance`: objective checks for compliance + - `metadata`: JSON with `version`, `supersedes`, `effective_date`, `owner` + +2. Active Domain Anchors (discoverability and curation) +- Type: `epic` +- Status: `open` +- Labels: `memory-anchor`, domain label +- Purpose: stable index/root for each domain; minimal mutable notes +- Linking: + - `bd dep relate ` for semantic association + - no blocker semantics by default + +3. Execution Contracts (selective enforcement) +- Type: `task` or `decision` +- Status: `open` while unresolved +- Labels: `memory-contract`, `mem-hard` +- Usage: only for high-risk constraints (security, data integrity, release gates) +- Linking: + - contract blocks active work: `bd dep add ` + - contract relates to canonical node: `bd dep relate ` + +This gives us A retrieval, B visibility, and C enforcement only where needed. + +## Memory Lifecycle + +1. Propose +- Create draft decision bead with labels `memory,draft,`. + +2. Ratify +- Validate wording and acceptance checks. +- Close it as canonical memory. + +3. Index +- Relate the canonical node to its domain anchor Epic. + +4. Inject into work +- For every new feature/task, run domain query and attach context: + - `bd query "label=memory AND label= AND status=closed"` + - `bd dep relate ` for soft guidance + - if `mem-hard`, create/attach execution contract as blocker + +5. Evolve +- Never edit closed canonical rule text. +- Create successor bead and use `bd supersede `. +- Add note to old bead: "Superseded by on ". + +## Query Model + +Primary retrieval queries: + +- Domain memory set: + - `bd query "label=memory AND label=memory-arch AND status=closed" --sort updated --reverse` +- Hard constraints only: + - `bd query "label=memory AND label=mem-hard AND status=closed"` +- Anchor-centric context: + - `bd show ` and inspect related memory nodes + +Recommended ingestion sequence at task start: + +1. Collect matching domain memories +2. Attach all as `relates_to` +3. Promote only `mem-hard` into blocker contracts +4. Record acknowledgement note in active bead + +## Data Contract for Canonical Memory Beads + +Use this strict shape to keep memory machine-readable and human-auditable. + +Title format: +- `[MEMORY][][HARD|SOFT] ` + +Description template: +- Scope: +- Out of Scope: +- Rule: +- Rationale: +- Failure Mode: + +Acceptance template: +- Given , when , then +- Verification command(s): + +Metadata JSON template: +```json +{ + "memory_version": 1, + "memory_strength": "hard", + "domain": "memory-arch", + "effective_date": "2026-03-02", + "owner": "team", + "supersedes": null, + "superseded_by": null +} +``` + +## Governance Rules + +- Do not store memory in markdown notes as source-of-truth. +- Do not use optional fields to bypass schema rigor. +- Every hard memory must include explicit acceptance checks. +- Every supersession must use `bd supersede` + metadata update + note. +- Contracts are temporary enforcement wrappers, not long-lived policy storage. + +## Migration Plan From Current State + +1. Create anchors +- `EPIC: Memory Anchor - Architecture` +- `EPIC: Memory Anchor - UI/UX` +- `EPIC: Memory Anchor - Workflow` + +2. Convert existing protocol statements from `AGENTS.md` into canonical memory decision beads. + +3. Classify each as `mem-soft` or `mem-hard`. + +4. Relate all canonical nodes to anchors. + +5. Add task-start routine: +- query domain memories +- relate them to active bead +- create blockers only for `mem-hard` + +6. Add lint/check script (or CI step): +- fail when active bead has no memory relations for its declared domain +- fail when `mem-hard` memory exists but no corresponding contract/blocker is attached + +## Why this is stronger + +- Auditability: immutable canonical nodes + supersession graph. +- Precision: structured schema and acceptance contracts. +- Performance: contracts only for high-risk rules, not every memory. +- Discoverability: always-on anchors make the graph readable. +- Operational fit: uses existing `bd` commands only.