Vellum Memory V2 Migration

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

assistant/CLAUDE.md

assistant/src/approvals/CLAUDE.md

assistant/src/notifications/CLAUDE.md

assistant/src/runtime/CLAUDE.md

gateway/CLAUDE.md

Audit 0.4.1 · source sha 19bc86343b63 · 14 Oct 2026Report an issue or request a re-scan

• Publishervellum-ai GitHub organizationOwner of the repository this skill is read from
• Source foldervellum-ai/vellum-assistant/skills/vellum-memory-v2-migrationThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict19bc86343b63A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Perform a one-time migration from memory v1, to memory v2, which was introduced in 0.8.0.

---
name: vellum-memory-v2-migration
description: Perform a one-time migration from memory v1, to memory v2, which was introduced in 0.8.0.
compatibility: "Designed for Vellum personal assistants"
metadata:
  emoji: "🧠"
  vellum:
    category: "system"
    display-name: "Memory v2 Migration"
    user-invocable: true
    activation-hints:
      - "When the user asks to migrate to memory v2"
      - "When /workspace/memory/concepts/ is empty or near-empty and memory.v2.enabled is false"
    avoid-when:
      - "When concept pages are already populated and memory.v2.enabled is already true"
      - "When /workspace/pkb/ and /workspace/memory/buffer.md are both empty (nothing to migrate)"
---

# 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:

```
assistant inference session open quality-optimized --ttl 2h
```

If `quality-optimized` isn't a profile name on this workspace, list the available profiles and open the session against the one labelled highest-quality. Do not match on model name: the profile roster is per-workspace and the models behind each label change between releases.

```
assistant config get llm.profiles
assistant inference session open <profile-name> --ttl 2h
```

The `--ttl 2h` overrides the 30m default — comfortable headroom for a typical migration without leaving a forever-pinned session if the close in Step 14.5 is skipped. The session is conversation-scoped and stays active across all migration turns.

If `assistant inference session` isn't on your binary (older builds before the inference-session CLI shipped), proceed without it — the migration still works, the model just won't be pinned. Skip the close in Step 14.5 too.

**(4) User confirmation.** Before starting any work, confirm the user understands what they're signing up for. The migration is judgment-heavy LLM work — every concept page, buffer entry, and always-loaded file goes through inference. Duration and cost scale with the size of the existing knowledge base: a workspace with months of history and hundreds of buffer entries will take meaningfully longer and cost meaningfully more than a fresh one.

Use the CLI confirmation prompt:

```
assistant ui confirm "This migration will read all of your existing memories and knowledge base entries, distill them into concept pages, and re-embed everything. Depending on how long your assistant has been running and how many memories you have, this could take a while and cost real money. Proceed?"
```

If the user declines, stop the skill immediately — no sentinel commit, no work. If `assistant ui confirm` isn't available on this binary, ask the user directly in conversation instead.

### Step 1 — Open a paper trail

`/workspace` is a git repo. Drop a sentinel commit so the migration is greppable in history:

```
cd /workspace
git add -A && git commit -m "memory-v2-migration: start" --allow-empty
```

You'll commit again at two more milestones (mid — after pages + buffer drain + always-loaded files, in Step 9; and at the very end, in Step 14). Three total sentinel commits, all using the exact prefix `memory-v2-migration:` so `git log --grep` finds them as one set. The heartbeat auto-committer may fire between your milestones — that's fine; the explicit sentinels are what make the migration story reconstructable later.

### Step 2 — Inventory

Run in parallel:

```
ls /workspace/pkb/ 2>/dev/null
ls -R /workspace/me

Excerpt, first 6,001 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/vellum-ai/vellum-assistant
git -C vellum-assistant checkout 19bc86343b63

Works in

1. 2026-10-14
   ✓SAFE B 89 / 100

   first audit · source 19bc86343b63

Questions about Vellum Memory V2 Migration

• github.com/vellum-ai/vellum-assistant/tree/main/skills/vellum-me — the audited source at commit 19bc86343b63 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology