majiayu000 bd-first-memory-migration
Make
bdthe single source of truth for agent memory. Salvage the keepers, derive the caches, garbage-collect and retire the rest. Three phases, gated between destructive steps.
The problem this solves
Agents accrete multiple uncoordinated memory stores — one per harness (Claude MEMORY.md, an ao/flywheel store, .agents/learnings piles, bd memories). None is canonical, so they drift, bloat, duplicate, and never get garbage-collected. This skill collapses them to one bd-canonical substrate; everything else becomes a derived cache or is retired.
Not a generic dedup tool. It is opinionated: bd wins, decay-ranked recall replaces grep, and stale low-utility memory is evicted to a cold archive (never silently deleted).
When to use / when not
| Use it when | Skip it when |
|---|---|
You have ≥2 memory stores and one is bd (or you'll adopt bd) |
You only have one store and it's healthy |
| A store has stalled (e.g. 99% "provisional", never promoted/evicted) | You need cross-org memory federation (out of scope) |
Disk pile of duplicated extracts (-pend-*, N× copies) |
You want to keep every store independent |
Quick start
# Phase 1 — AUDIT (read-only; produces the KEEP/DROP manifest + reversibility plan)
scripts/audit-scan --target <box> # inventory every layer
scripts/classify --manifest out/manifest.json # keepers vs junk (dry-run)
# ⛔ GATE A: human reviews the manifest before anything is written
# Phase 2 — MIGRATE (salvage -> bd; stand up typed recall; unify writes)
scripts/import --manifest out/manifest.json --dry-run # then drop --dry-run
scripts/recall --query "<topic>" --max-tokens 400 # decay-ranked
scripts/gen-memory-md # regenerate the thin cache
# Phase 3 — GC / RETIRE (after rollback test green)
scripts/gc --dry-run # dedup + evict-to-archive
# ⛔ GATE B: rollback test green before any destructive retire
scripts/retire --dry-run # decommission dead daemons + reclaim disk
The three phases
| Phase | Goal | Destructive? | Gate |
|---|---|---|---|
| 1 — Audit | Inventory all layers; classify keep vs junk; write reversibility plan | No (read-only) | ⛔ Gate A — review KEEP/DROP manifest |
| 2 — Migrate | Salvage keepers → bd (typed + provenance); decay-ranked recall; unified write path; generated MEMORY.md |
Writes to bd only | — |
| 3 — GC/Retire | Utility scoring, scheduled GC/dedup, retire dead stores, reclaim disk | Yes | ⛔ Gate B — rollback test green; ⛔ Gate C — human go/no-go on the real box |
Full per-phase contract: references/PHASES.md. Memory data model + type taxonomy: references/DATA-MODEL.md. Reversibility/rollback contract: references/ROLLBACK.md. Worked examples: references/EXAMPLES.md. Acceptance scenarios: references/audit.feature (Phase 1) · references/migrate.feature (Phase 2).
Anti-patterns
| Don't | Do |
|---|---|
| Hard-delete a store before salvage is verified | Import-ledger confirms every keeper landed in bd first |
| Run destructive retire before rollback is proven | Gate B: rollback test green is a hard precondition |
| Burst bd writes during bulk salvage | Pace writes — bd auto-commits each write to Dolt; bursts OOM a memory-capped server |
| Silently truncate (top-N, sampling) | log() whatever was dropped — silent caps read as "covered everything" |
Hand-edit the generated MEMORY.md |
It is a read-only cache rebuilt from bd; edit the bd memory instead |
| Auto-fire the real destructive retire | Gate C: human go/no-go on the live box (pre-mortem first) |
Guardrails (load-bearing)
- Idempotent + reversible + backup-aware. Every destructive step takes a backup and has a documented rollback (see ROLLBACK.md).
- Dry-run first. Every Phase-2/3 mutate path ships with a working
--dry-run. - Pace bd/Dolt writes. Bulk salvage of thousands of keepers will trip a memory-capped Dolt server if unpaced — sleep between writes, cap concurrency.
- bd canonical, not br. This skill targets
bd; it does not migrate the tracker itself.
See also
skills/beads/SKILL.md— the bd issue/memory substrate this skill writes toskills/harvest/SKILL.md— promoting.agentsknowledge (the authored keepers this skill salvages)