assistant-migration

Assistant Migration

Help the creator migrate from another AI assistant into Vellum. Preserve as much of the source assistant as can be understood safely. Non-Vellum systems (OpenClaw, Hermes, Manus, and others) evolve quickly, so never assume their internals follow a fixed schema: inspect the actual source artifacts in front of you and map them into Vellum primitives. The bundled memory parsers in scripts/ follow the same rule; they introspect whatever artifact they are given instead of hardcoding a layout, and everything they emit is a review candidate, never a finished import.

Core Posture

• Migrate internals opportunistically: prompts, memory exports, skill definitions, tool manifests, schedules, app code, workflow docs, MCP configs, browser/computer-use preferences, and integration metadata can often be preserved.
• Do not pretend opaque runtime state is portable. If a file, database row, binary blob, or generated artifact cannot be confidently understood, mark it for review or rebuild.
• Never import secrets from chat, logs, config dumps, browser profiles, or exported files. Secrets must be reconnected through Vellum's credential vault, OAuth flows, or setup skills.
• Do not write new ad-hoc scripts that encode assumptions about another assistant's private filesystem or database schema. For memory extraction, use the bundled parsers in scripts/: they avoid schema assumptions by design (ZIP entries matched by name/content heuristics, SQLite tables discovered via sqlite_master introspection) and their output always goes through creator review before anything is saved.
• Be inviting. Migration can feel sensitive because the creator may have a real relationship with the source assistant; acknowledge that directly, move at the creator's pace, and keep them in control of what is inspected, imported, reviewed, or left alone.
• Treat every source assistant, source machine, and source export as read-only unless the creator explicitly authorizes a specific write. Before accessing a source machine, say plainly that you will not modify anything there.
• Be transparent with the creator: identify what will be ported, what needs review, what should be disregarded, and what must be re-set up from scratch.

Getting Access to Source Internals

The creator may not know where their other assistant stores its internals. Help them find the safest available source of truth before asking them to upload or paste data.

Start with low-risk discovery:

• Ask whether the source assistant offers an official export, backup, workspace folder, settings page, or CLI command.
• If the source runs locally, help locate likely workspace/config directories, but avoid scraping browser profiles or secret stores.
• If the source is on another machine, walk the creator through a safe access path such as an archive, read-only share, or temporary SSH access. Make clear that source-machine work is for inspection and copying only: do not install packages, change config, stop services, delete files, write marker files, or run source-assistant commands that mutate state without explicit approval.
• If the source is hosted, guide the creator toward official data export, account settings, project download, repository access, or support-provided archive paths.
• If there is no export path, ask the source assistant to produce portable summaries of its memory, instructions, active workflows, skills, apps, contacts, and integration setup.
• If access requires admin privileges, organization approval, or another person's account, stop and tell the creator what permission they need rather than trying to bypass it.

When internals are hard to access, fall back to an interview-style migration: ask the creator and source assistant for high-signal summaries, then rebuild in Vellum with review.

Before copying large folders or attachments, estimate source size and check available space in the current Vellum workspace. Use available storage diagnostics or shell filesystem probes when available, migrate large assets in batches, and pause for the creator if the import could crowd the workspace or trigger disk-pressure cleanup.

Per-assistant references

Once the source assistant is identified, consult the matching reference for the exact data-directory layout, a bundling recipe with explicit --exclude flags for secret-bearing paths, and the after-import rebind checklist:

• ChatGPT → Vellum
• Claude → Vellum
• Hermes → Vellum
• OpenClaw → Vellum

For ChatGPT conversation history specifically, do not parse export ZIPs here — invoke the chatgpt-import skill, which owns the export-and-parse flow. The ChatGPT reference covers only the non-conversation material (custom instructions, saved memories, GPT configs).

These are reconnaissance notes, not adapters. They tell you where to look and what to leave behind. The preferred flow is a single tar archive that the creator uploads to the conversation as a chat attachment. Never run curl, wget, or any other fetcher against a URL the creator pastes in chat — a chat-supplied URL substituted into a shell command is a confused-deputy surface (shell substitution inside double quotes, SSRF against private networks, and a bypass of the platform's structured URL-safety checks). See references/README.md for the shared tar-and-transport model and the rules each per-assistant reference must follow.

Migration Workflow

1. Establish the Source and Migration Goal

Ask only for missing essentials:

• Source assistant and artifact location: export file, workspace directory, repository, archive, screenshots, or copied text.
• Desired fidelity: quick usable migration, careful review-first migration, or exhaustive salvage.

If the user already provided enough context, start inspecting.

2. Inventory Before Importing

Build an inventory grouped by Vellum primitive. For each candidate item, capture:

• Source path or origin.
• What it appears to be.
• Suggested Vellum destination.
• Confidence: high, medium, or low.
• Recommended action: port, review first, re-setup, or disregard.
• Reason for the recommendation.

Do not mutate Vellum state until the creator has reviewed the inventory unless they explicitly asked for an immediate best-effort migration.

Multi-source migrations

When the creator names more than one source ("I used ChatGPT and Claude", "ChatGPT plus my old OpenClaw box"), build one unified inventory, not one per source. Each inventory row gains a Source attribution column alongside the existing fields (source path/origin, what-it-is, Vellum destination, confidence, action, reason).

Dedupe and reconcile across sources:

• When the same fact, memory, identity trait, contact, or skill appears from multiple sources, collapse it to a single Vellum item.
• Record all contributing sources in the item's provenance notes so the creator can audit where it came from.
• On conflict, prefer the higher-confidence or more-recent source. Surface genuine conflicts to the creator rather than silently picking one.
• Credentials from every source are never imported; they rebind through the vault regardless of which source they came from.

The unified inventory drives per-source rebind/import routing — each row's action resolves against the source it came from:

• ChatGPT conversation archives → the chatgpt-import skill (see below; do not parse ZIPs here).
• Claude exports / self-summaries → references/claude.md.
• OpenClaw / Hermes / Manus and other local-workspace assistants → their existing references.
• ChatGPT non-conversation material (custom instructions, saved memories, GPT configs) → references/chatgpt.md.

Keep the existing Review Surface and Port / Review / Re-setup / Disregard flow. Multi-source just means one combined checklist with source labels, not a separate pass per source.

3. Present a Review Surface

Prefer a rich checklist when an interactive surface is available. The checklist should let the creator mark each item as:

• Port: bring it into Vellum now.
• Review: inspect in more depth before importing.
• Re-setup: recreate through Vellum setup flows because direct import is unsafe or impossible.
• Disregard: leave it behind.

If a rich UI is not available on the current channel, present the same information as a concise markdown table and ask for the creator's choices.

Suggested checklist groups:

• Identity and personality
• Memory and relationship knowledge
• Conversations and attachments
• Skills, tools, MCP, browser, and computer-use capabilities
• Apps, widgets, dashboards, and custom UIs
• Channels, clients, contacts, and guardian verification
• Integrations, OAuth apps, credentials, and secrets
• Trust rules, approvals, and permission expectations
• Schedules, heartbeats, watchers, followups, and task queues
• Workspace files, projects, notes, and persistent artifacts
• Inference profiles and provider connections

4. Port What Maps Cleanly

Use the most native Vellum primitive available. Prefer existing Vellum setup/import flows over custom conversion. Keep source provenance in notes when useful so the creator can audit where migrated material came from.

For each migrated group, report what changed and what remains pending. If an item is skipped, say why.

5. Rebuild What Cannot Be Safely Ported

Some internals should be rebuilt instead of copied:

• API keys, tokens, cookies, and browser sessions.
• Provider-specific OAuth refresh tokens.
• Foreign approval policies whose semantics do not match Vellum trust rules.
• Opaque vector stores, caches, embeddings, hidden chain-of-thought, or model traces.
• Runtime-specific process state, queues, locks, or binary databases that are not documented.
• Capabilities that depend on a foreign tool runtime unavailable in Vellum.

When rebuilding, explain the Vellum equivalent and ask whether the creator wants to re-set it up now.

Vellum Primitive Map

Memory Import Guidance

Memory import is a review-first pipeline: extract candidates deterministically, review every item with the creator, shape the approved items into v3 article pages, ingest them as a batch, then verify. Nothing is saved unreviewed at any step.

1. Extract candidates

Use the bundled parsers to pull candidates out of the source artifacts. Both emit MemoryImportItem[] JSON ({ text, source, origin_date?, context? }) on stdout and a human-readable inventory on stderr, and both redact credential-shaped values before anything reaches stdout:

• ChatGPT non-conversation material (saved memories, custom instructions):

  bun run {baseDir}/scripts/parse-chatgpt-memory.ts --file /path/to/chatgpt-export.zip
  

• Hermes / OpenClaw memory.db snapshots (always a .backup snapshot, never a live DB; see the provider references):

  bun run {baseDir}/scripts/parse-agent-memory-db.ts --file /path/to/memory.db.snapshot --source hermes
  

  (or --source openclaw)

• Claude has no deterministic importer. Fall back to the interview flow: invite the source assistant to produce a portable self-summary and treat its items as the candidate list. Ask for comprehensive but reviewable output: identity and background; preferences and communication style; important relationships; active projects and open loops; durable instructions the creator gave it; meaningful history from recent conversations; uncertainties and low-confidence inferences clearly labeled.

The self-summary is worth collecting for any source assistant that can still answer questions; it complements parser output with material no export captures.

2. Review with the creator

Present the candidate inventory (the parsers' stderr census plus the items themselves) in conversation and let the creator decide what survives. Drop stale, inferred, speculative, or emotionally loaded items unless the creator explicitly keeps them. Never bulk-dump raw parser output into memory: parsers produce candidates, not memories.

3. Shape approved items into v3 article pages

Write the approved items as concept pages in a staging directory (for example .mv3/staging/), one .md file per page. Follow the vellum-memory-v3-migration skill's references/v3-wiki-principles.md for the article shape rather than improvising; the essentials are:

• The lead paragraph is the summary (there is no summary: field; the lead is the retrieval card).
• Detail lives in ## sections with names that work as navigation.
• Flat kebab-case slug; the staged filename minus .md becomes the slug.
• links: entries annotated with why-notes: each entry names a target slug plus one line on why the link exists, in the exact format the principles doc shows.
• Provenance frontmatter on every imported page: source: import:<provider> (e.g. import:chatgpt). Add origin_date: (ISO 8601) when the source material carries a date (a parser-emitted origin_date, or a date the creator confirms); it drives the page's effective recency, so imported pages rank by when their content originally dates from, not by import time. When the original date is unknown, omit the field rather than inventing one; the page then ranks by its write time like any other new page.

4. Ingest

assistant memory ingest --dir .mv3/staging --dry-run

Review the per-page dry-run results (written / skipped / invalid) with the creator, fix any invalid pages, then run the same command without --dry-run. Existing slugs are skipped unless --overwrite is passed. If the command fails because the consolidation lock is held, wait for consolidation to finish and retry; do not work around the lock.

5. Verify

• Check the summary counts: written, skipped, invalid.
• Spot-check retrieval on two or three imported facts; that spot-check is the verification. (assistant memory v3 eval does not apply here: it compares two complete corpora, and an import's staging directory holds only the new pages, not a corpus.)

Small volumes

A handful of approved facts does not need the staging pipeline; save them through the normal remember tool instead.

Warning: never bulk-append imported facts to memory/buffer.md. Bulk appends share one minute-stamp and force consolidation to process the whole buffer in a single run; assistant memory ingest exists precisely to bypass that hazard.

Internals Salvage Guidance

When source files are available, inspect them directly and classify them:

• High-confidence portable: markdown, JSON/YAML config with clear labels, prompt files, skill docs, app source, workflow docs, schedules, contact lists, exported conversations.
• Medium-confidence portable: SQLite tables with obvious names, tool manifests, MCP configs, integration metadata without secrets, memory summaries with unclear provenance.
• Low-confidence or non-portable: embeddings, vector indexes, binary stores, caches, encrypted blobs, cookies, refresh tokens, queue state, process supervision files, undocumented schema fragments.

For medium- and low-confidence items, ask before importing and prefer converting into reviewed notes or setup tasks.

Final Migration Report

End with a concise report:

• Ported successfully.
• Needs creator review.
• Needs re-setup in Vellum.
• Disregarded or intentionally left behind.
• Residual risk: anything uncertain, sensitive, or not yet verified.

If the migration created follow-up work, offer the next concrete step rather than claiming the migration is complete.