beadboard/docs/plans/2026-03-02-bd-memory-fabric-design.md

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 <anchor> <memory-node> 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 <active-work> <contract>
  • contract relates to canonical node: bd dep relate <contract> <memory-node>

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,<domain>.

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=<domain> AND status=closed"
  • bd dep relate <active-id> <memory-id> 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 <old> <new>.
• 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 <anchor-id> 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][<DOMAIN>][HARD|SOFT] <Rule sentence>

Description template:

• Scope:
• Out of Scope:
• Rule:
• Rationale:
• Failure Mode:

Acceptance template:

• Given , when , then
• Verification command(s):

Metadata JSON template:

{
  "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.