| name | bd-first-memory-migration |
| description | Consolidate fragmented agent-memory layers into one bd-canonical store, then GC/retire the rest. Triggers: "memory migration", "consolidate agent memory", "beads-first memory". |
| skill_api_version | 1 |
| practices | ["wiki-knowledge-surface","pragmatic-programmer"] |
| hexagonal_role | driving-adapter |
| consumes | ["repo-context"] |
| produces | ["migration-report","bd-memories"] |
| metadata | {"tier":"knowledge"} |
bd-first-memory-migration
Make bd the 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
scripts/audit-scan --target <box>
scripts/classify --manifest out/manifest.json
scripts/import --manifest out/manifest.json --dry-run
scripts/recall --query "<topic>" --max-tokens 400
scripts/gen-memory-md
scripts/gc --dry-run
scripts/retire --dry-run
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 .agents knowledge (the authored keepers this skill salvages)
