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, but do not rely on deterministic adapters for OpenClaw, Hermes, Manus, or any other non-Vellum internals. These systems evolve quickly; inspect the actual source artifacts in front of you and map them into Vellum primitives.

## 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 create scripts or deterministic code that encode assumptions about another assistant's private filesystem or database schema.
- 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](references/chatgpt.md)
- [Claude → Vellum](references/claude.md)
- [Hermes → Vellum](references/hermes.md)
- [OpenClaw → Vellum](references/openclaw.md)

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`](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 C