--- name: species-migration description: Migrate from OpenClaw, Hermes, Manus, and other assistant species into Vellum by inspecting their exports, files, prompts, memory, tools, workflows, integrations, and relationships, then mapping as much as safely possible into Vellum primitives without hard-coded foreign-species porting logic. compatibility: "Designed for Vellum personal assistants" metadata: emoji: "🧬" vellum: display-name: "Species Migration" activation-hints: - "User wants to migrate from OpenClaw, Hermes, Manus, or another assistant species into Vellum" - "User has an assistant export, workspace, prompt bundle, memory dump, tool config, or migration request from another assistant system" - "User asks what can be preserved when switching assistant species" avoid-when: - "User is moving an existing Vellum assistant between Vellum homes; use backup/restore or teleport workflows instead" --- # Species Migration Help the creator migrate from another assistant species 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 species' 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-species references Once the source species 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: - [Hermes → Vellum](references/hermes.md) - [OpenClaw → Vellum](references/openclaw.md) 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, transferred either as a chat attachment or via a short-TTL signed URL the assistant fetches with `curl`. See [`references/README.md`](references/README.md) for the shared tar-and-transport model and the rules each per-species reference must follow. ## Migration Workflow ### 1. Establish the Source and Migration Goal Ask only for missing essentials: - Source species 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. ### 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 | Source assistant concept | Vellum primitive | Migration guidance | | ----------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Name, persona, tone, identity docs, system prompts | Identity, Personality, Avatar, `SOUL.md`, user persona files | Preserve explicit creator-approved identity/personality material. Convert brittle prompt hacks into plain behavioral guidance. | | Current focus, scratchpads, working notes | `NOW.md`, Workspace notes, Memory | Preserve active projects and open loops. Avoid importing stale scratch state as permanent truth. | | Memory databases, summaries, profiles, user facts | Memory | Prefer source-produced summaries or human-readable exports. Preserve attribution where possible. Use review for inferred or sensitive facts. | | Conversation history | Conversations and Memory | Import supported structured exports when available. Otherwise summarize useful history into memory candidates rather than dumping logs blindly. | | Tools, skills, commands, plugins, playbooks | Skills | Recreate as Vellum skills when the capability is still useful. Keep instructions portable; avoid foreign runtime assumptions. | | MCP servers | MCP | Recreate server registrations and required environment through Vellum's MCP setup flow. Reconnect secrets through the credential vault. | | Browser automation state, browsing tasks | Browser capability | Recreate workflows and permissions. Do not import cookies or browser profile secrets directly. | | Computer-use automations | Computer Use capability | Recreate task intent and permission expectations. Verify host-computer access through Vellum's own consent model. | | Custom dashboards, tools, visual workflows | Apps or Widgets | Persistent interactive tools should become Apps. Transient conversation UI should become Widgets or normal chat flows. | | Slack, Telegram, email, phone, webhooks | Channels and Integrations | Reconnect channels through Vellum setup skills. Expect some providers, especially Slack, to need fresh setup. | | Friends, coworkers, allowed users | Contacts and Trusted Contacts | Map relationships into Contacts. Grant channel access through trusted-contact and guardian flows, not direct database edits. | | Owner/admin identity, approval authority | Guardian Verification | Verify the creator/guardian on each channel needed for secure access and approvals. | | Secrets, API keys, tokens, OAuth refresh tokens | Credential Vault and OAuth Integrations | Never paste or import raw secrets. Rebind through secure prompts, OAuth connect flows, or provider setup skills. | | Autonomy settings, allowlists, deny rules | Trust Rules and Permissions | Translate intent, not syntax. Start conservative when semantics are unclear. | | Timed jobs and reminders | Schedules | Recreate one-shot and recurring tasks using Vellum schedules. Preserve the user-visible intent and delivery channel. | | Autonomous monitors and polling jobs | Watchers | Rebuild as watchers when the source monitors external events. Reconnect provider credentials first. | | Periodic self-checks | Heartbeats | Use Vellum heartbeats for agenda-free self-checking, not for specific timed jobs. | | Pending replies or nudges | Followups | Preserve expected-response workflows as followups when the source tracks sent messages awaiting replies. | | Reusable action templates and queues | Task Queue | Recreate repeatable work as tasks or queued work items when the creator expects review before completion. | | Model routing, fast/quality/cost modes, provider keys | Inference Profiles and Provider Connections | Map source behavior to named profiles such as balanced, quality, or cost/speed variants. Reconnect provider credentials safely. | | Files, projects, notes, attachments | Workspace | Copy useful, non-secret artifacts into the Vellum workspace with clear organization. Leave local worktree artifacts and foreign caches behind. | ## Memory Import Guidance When the source assistant can answer questions, invite it to produce a portable self-summary instead of scraping every internal file. 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. Then present the summary as memory candidates for creator review. Do not silently save sensitive, speculative, or emotionally loaded claims. ## 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.