Memory v2 Migration

Memory v2 Migration

Guided run for the first-time backfill of /workspace/memory/ from existing knowledge sources, ending with memory.v2.enabled = true and validated, embedded, ready-to-retrieve concept pages.

You are running memory consolidation — tending your personal wiki. The output is a cross-linked, cross-referenced collection of pages that is your memory, optimized for next-you. Care, judgment, voice. Your voice.

Procedure

⚠️ Do not run assistant memory v2 migrate during this skill. That command auto-generates concept pages from PKB and will overwrite any hand-written content without --force, and with --force will overwrite hand-written content silently. This skill replaces it with the hand-written path. If you've already started running this skill, treat migrate as off-limits until the migration is complete.

Step 0 — Read the principles

Read references/wiki-principles.md end-to-end before doing anything. It defines:

• Article shapes (event vs topic), gravity wells
• Class-by-folder taxonomy and size caps
• The cheat-sheet budget (10–20K tokens/turn) and fact density per byte
• Voice register by article shape
• Banned bullet shapes and the "one fact, one home" rule

The reference is the authoritative source for what a good page looks like. This SKILL.md owns what order to do things in.

Step 0.5 — Preflight

Three checks before dropping a sentinel commit. If any fails, stop and resolve before proceeding.

(1) CLI surface. Confirm the subcommands this skill calls are actually registered:

assistant --version
assistant memory v2 --help

The memory v2 help should list at least these four: validate, reembed, reembed-skills, activation. They're used in Steps 10 and 12. If any are missing, this skill assumes the post-cleanup CLI — either upgrade the binary or use the older migrate path on that workspace instead.

(2) Workspace state. If concepts/ is non-empty but partially populated (e.g. a previous run crashed mid-write), don't proceed under this skill — that's a recovery flow, not a fresh migration. Inspect with git log --grep memory-v2-migration to see how far the prior run got, then decide between resuming manually or rolling back to the last sentinel commit.

(3) Pin the migration to a high-quality model. Wiki backfill is judgment-heavy work — page routing, voice register, what-belongs-on-A-vs-B, when-to-stub-vs-not. A stronger model produces meaningfully better pages: better routing decisions, sharper bullet writing, fewer reflexive stubs. If your CLI exposes inference sessions, open one for the duration of the migration: