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.