153 lines
5.1 KiB
Markdown
153 lines
5.1 KiB
Markdown
# 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 <new-id> on <date>".
|
|
|
|
## 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 <context>, when <action>, then <expected invariant>
|
|
- Verification command(s): <exact command list>
|
|
|
|
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.
|