docs: finalize bd-native memory fabric plan and phase-1 evidence
This commit is contained in:
ZenchantLive
parent
641db8b172
commit
9eb805cfa1
2 changed files with 261 additions and 0 deletions
108
docs/plans/2026-03-01-beads-native-memory.md
Normal file
108
docs/plans/2026-03-01-beads-native-memory.md
Normal file
|
|
@ -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,<domain>`
|
||||||
|
- Link style: `bd dep relate <anchor> <memory-node>`
|
||||||
|
|
||||||
|
2. Canonical Memory Nodes (closed decisions)
|
||||||
|
- Purpose: immutable ratified rules/patterns
|
||||||
|
- Type: `decision`
|
||||||
|
- Labels: `memory,mem-canonical,mem-hard|mem-soft,<domain>`
|
||||||
|
- 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=<domain> 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 <active-id> <memory-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Data Contract for Canonical Memory
|
||||||
|
|
||||||
|
Title:
|
||||||
|
- `[MEMORY][<DOMAIN>][HARD|SOFT] <atomic rule sentence>`
|
||||||
|
|
||||||
|
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
|
||||||
153
docs/plans/2026-03-02-bd-memory-fabric-design.md
Normal file
153
docs/plans/2026-03-02-bd-memory-fabric-design.md
Normal file
|
|
@ -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 <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.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue