docs: add native memory help pack and enforce workflow in AGENTS
This commit is contained in:
parent
9eb805cfa1
commit
6ba2e8b3c4
5 changed files with 203 additions and 31 deletions
14
help/memory/README.txt
Normal file
14
help/memory/README.txt
Normal file
|
|
@ -0,0 +1,14 @@
|
|||
BeadBoard Native Memory System (Index)
|
||||
|
||||
Use this folder when you need to understand, query, or update memory in BeadBoard.
|
||||
Memory source-of-truth is bd + Dolt history, not markdown notes.
|
||||
|
||||
Files:
|
||||
- memory_fabric_workflow.txt: full lifecycle and operating procedure
|
||||
- query_and_injection.txt: task-start retrieval and attachment commands
|
||||
- schema_and_noise_budget.txt: node types, edge rules, and anti-noise limits
|
||||
|
||||
Fast path for agents:
|
||||
1) Read memory_fabric_workflow.txt
|
||||
2) Run query_and_injection.txt command sequence at task start
|
||||
3) Follow schema_and_noise_budget.txt before creating new memory nodes
|
||||
46
help/memory/memory_fabric_workflow.txt
Normal file
46
help/memory/memory_fabric_workflow.txt
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
# Memory Fabric Workflow (bd-native)
|
||||
|
||||
Goal: keep memory durable, queryable, and behavior-changing without graph noise.
|
||||
|
||||
Core model:
|
||||
1. Domain Anchors (open epic)
|
||||
- Purpose: index and discovery root per domain
|
||||
- Labels: memory,memory-anchor,<domain>
|
||||
- Example domains: memory-arch,memory-workflow,memory-ux,memory-agent,memory-reliability
|
||||
|
||||
2. Canonical Memory Nodes (closed decision)
|
||||
- Purpose: ratified reusable rules/patterns
|
||||
- Labels: memory,mem-canonical,mem-hard|mem-soft,<domain>
|
||||
- Lifecycle: create -> ratify -> close
|
||||
|
||||
3. Execution Contracts (open task or decision)
|
||||
- Purpose: temporary enforcement wrapper for hard constraints only
|
||||
- Labels: memory-contract,mem-hard,<domain>
|
||||
- Lifecycle: attach to active work while unresolved, close when satisfied
|
||||
|
||||
Required lifecycle:
|
||||
1) Propose memory node
|
||||
- Create as decision bead using strict template fields (Scope, Out of Scope, Rule, Rationale, Failure Mode)
|
||||
|
||||
2) Ratify memory node
|
||||
- Add acceptance checks and metadata JSON
|
||||
- Close with explicit reason: Ratified canonical memory
|
||||
|
||||
3) Index memory node
|
||||
- Relate canonical node to exactly one primary domain anchor
|
||||
bd dep relate <anchor-id> <memory-id>
|
||||
|
||||
4) Inject memory into execution
|
||||
- At task start, query by domain and attach relevant nodes via relates_to
|
||||
- Promote only mem-hard constraints to blocker contracts
|
||||
|
||||
5) Evolve memory safely
|
||||
- Do not rewrite historical canonical truth
|
||||
- Create a new canonical node and link lineage:
|
||||
bd supersede <old-memory-id> --with <new-memory-id>
|
||||
|
||||
Non-negotiables:
|
||||
- No direct writes to .beads/issues.jsonl
|
||||
- No markdown-only memory source of truth
|
||||
- No blanket blocker links for all memories
|
||||
- Evidence before completion claims
|
||||
40
help/memory/query_and_injection.txt
Normal file
40
help/memory/query_and_injection.txt
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
# Query and Injection Playbook
|
||||
|
||||
Run this sequence at task start.
|
||||
|
||||
Step 1: Determine task domain
|
||||
- Choose one primary domain label:
|
||||
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=<domain> AND status=closed" --sort updated --reverse
|
||||
```
|
||||
|
||||
Step 3: Query hard constraints subset
|
||||
```bash
|
||||
bd query "label=memory AND label=mem-canonical AND label=mem-hard AND label=<domain> AND status=closed" --sort updated --reverse
|
||||
```
|
||||
|
||||
Step 4: Attach context to active work (soft + hard)
|
||||
```bash
|
||||
bd dep relate <active-task-id> <memory-id>
|
||||
```
|
||||
|
||||
Step 5: Enforce hard constraints only (optional contract bead)
|
||||
```bash
|
||||
bd create --title "[MEMORY-CONTRACT] <short hard rule title>" --type task --labels memory-contract,mem-hard,<domain> --description "Contract for active task <active-task-id>" --acceptance "Hard rule is acknowledged and verified in task evidence." --silent
|
||||
bd dep relate <contract-id> <canonical-memory-id>
|
||||
bd dep add <active-task-id> <contract-id>
|
||||
```
|
||||
|
||||
Step 6: Record acknowledgement
|
||||
```bash
|
||||
bd update <active-task-id> --notes "Memory injection: related <memory-id list>; hard contracts <contract-id list>."
|
||||
```
|
||||
|
||||
Expected response patterns:
|
||||
- bd query: list of IDs + labels + titles
|
||||
- bd dep relate: relation confirmation
|
||||
- bd dep add: blocker edge confirmation
|
||||
- bd show/dep list: attached memory visible on task graph
|
||||
55
help/memory/schema_and_noise_budget.txt
Normal file
55
help/memory/schema_and_noise_budget.txt
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
# Memory Schema and Noise Budget
|
||||
|
||||
One memory bead = one atomic reusable rule.
|
||||
If it is not reusable across future tasks, keep it in task notes instead.
|
||||
|
||||
Canonical memory schema:
|
||||
- type: decision
|
||||
- status: closed (after ratification)
|
||||
- labels: memory,mem-canonical,mem-hard|mem-soft,<domain>
|
||||
- title format: [MEMORY][<DOMAIN>][HARD|SOFT] <rule sentence>
|
||||
|
||||
Required description sections:
|
||||
- Scope:
|
||||
- Out of Scope:
|
||||
- Rule:
|
||||
- Rationale:
|
||||
- Failure Mode:
|
||||
|
||||
Required acceptance style:
|
||||
- Given / When / Then invariant
|
||||
- Verification commands
|
||||
|
||||
Required metadata JSON keys:
|
||||
- memory_version
|
||||
- memory_strength
|
||||
- domain
|
||||
- effective_date
|
||||
- owner
|
||||
- supersedes
|
||||
- superseded_by
|
||||
|
||||
Edge rules:
|
||||
1) Anchor <-> Canonical memory
|
||||
- Use: bd dep relate
|
||||
- Never use blocker edge for anchor indexing
|
||||
|
||||
2) Active task <-> Memory
|
||||
- Default: bd dep relate
|
||||
|
||||
3) Active task <- Contract (hard rules only)
|
||||
- Use: bd dep add <active-task> <contract>
|
||||
|
||||
4) Memory versioning
|
||||
- Use: bd supersede <old> --with <new>
|
||||
|
||||
Noise budget limits:
|
||||
- Per active task: 3-7 related memory nodes
|
||||
- Per active task: 0-2 blocker contracts
|
||||
- Per canonical memory: 1 primary anchor domain
|
||||
- Promote incident/workaround memory only after repetition evidence
|
||||
|
||||
Promotion policy:
|
||||
1) Incident repeats 2+ times -> candidate soft canonical memory
|
||||
2) Workaround survives release window -> candidate hard/soft canonical memory
|
||||
3) Obsolete canonical memory -> supersede, do not rewrite history
|
||||
Loading…
Add table
Add a link
Reference in a new issue