| 1 | # Migrate Agents |
| 2 | |
| 3 |  |
| 4 | |
| 5 | Migrate Agents is a bundled Agent Zero plugin for bringing retained work |
| 6 | home from the five most-used open agent harnesses: |
| 7 | |
| 8 | - OpenClaw |
| 9 | - Hermes Agent |
| 10 | - OpenCode |
| 11 | - Claude Code |
| 12 | - Codex |
| 13 | |
| 14 | The plugin checks an export before importing it. You choose which chats, |
| 15 | projects, memories, instructions, and skills to bring into Agent Zero. |
| 16 | Credentials, authentication files, and hidden reasoning are excluded. |
| 17 | |
| 18 | ## Enable |
| 19 | |
| 20 | Enable **Migrate Agents** in Plugins, then use its **Open** button. |
| 21 | |
| 22 | ## Prepare an export |
| 23 | |
| 24 | | Source | Recommended input | |
| 25 | | --- | --- | |
| 26 | | OpenClaw | `openclaw backup create --verify`, an agent SQLite snapshot, or legacy transcript JSONL | |
| 27 | | Hermes Agent | `hermes sessions export backup.jsonl --redact`, `~/.hermes/state.db`, or a folder/archive containing memories and skills | |
| 28 | | OpenCode | `opencode export <session-id> > session.json`, repeated for each session you want | |
| 29 | | Claude Code | A folder/archive from `~/.claude/projects`, plus any `CLAUDE.md` and skills you want | |
| 30 | | Codex | The `sessions/` and `archived_sessions/` folders beneath `CODEX_HOME` (normally `~/.codex`) | |
| 31 | |
| 32 | You can choose individual files, a whole directory, ZIP, TAR, or TAR.GZ. The |
| 33 | preview is read-only. Import does not start until you review the manifest and |
| 34 | confirm it. |
| 35 | |
| 36 | ## What maps cleanly |
| 37 | |
| 38 | | Source material | Agent Zero destination | Notes | |
| 39 | | --- | --- | --- | |
| 40 | | User and assistant messages | Native chats | Source ID, timestamps, and workspace metadata are retained when available. | |
| 41 | | Retained workspace paths | Native projects | Chats from the same retained workspace are attached to the same imported project. Project files are not reconstructed from transcript metadata alone. | |
| 42 | | Tool activity | Historical tool records | Sanitized and inert; never replayed as commands. | |
| 43 | | Memory Markdown | `usr/knowledge/_migrate_agents/<source>/memories/` | Each document receives a provenance header. | |
| 44 | | `SOUL.md`, `USER.md`, `CLAUDE.md`, `AGENTS.md`, and related instructions | `usr/knowledge/_migrate_agents/<source>/instructions/` | Instructions remain separately selectable from memories. | |
| 45 | | Agent Skills containing `SKILL.md` | `usr/skills/_migrate_agents/<source>/` | Complete skill folders are copied under unique names. | |
| 46 | | Attachment references | Chat metadata or text | Binary attachment copying is not automatic. | |
| 47 | |
| 48 | ## Deliberate privacy boundary |
| 49 | |
| 50 | Migrate Agents never imports provider keys, credentials, authentication |
| 51 | state, channel bindings, schedules, hidden reasoning, or live services. It |
| 52 | redacts obvious secret assignments, bearer tokens, private keys, and embedded |
| 53 | data URLs from imported text and tool records. This is defense in depth, not a |
| 54 | guarantee; review migrated material before sharing it. |
| 55 | |
| 56 | The Codex adapter follows the preservation and privacy rules of the |
| 57 | `convert-codex-chats` utility skill: public user/commentary/final events are |
| 58 | retained, tool calls and results are paired when available, encrypted or hidden |
| 59 | reasoning is excluded, and historical actions are not presented as replayable. |
| 60 | |
| 61 | ## Limits |
| 62 | |
| 63 | - 5,000 expanded files per migration |
| 64 | - 100 MiB per file |
| 65 | - 256 MiB expanded total |
| 66 | - Preview lists are capped at 200 rows, while import still processes the full accepted bundle |
| 67 | - Modern OpenClaw conversation imports require its per-agent database or transcript artifacts; the global control-plane database does not contain chats |
| 68 | |
| 69 | ## Development |
| 70 | |
| 71 | No third-party Python or JavaScript packages are required. |
| 72 | |
| 73 | ```bash |
| 74 | python -m pytest plugins/_migrate_agents/tests -q |
| 75 | ``` |
| 76 | |
| 77 | Harness logo SVGs are bundled locally under `webui/assets/`; provenance and |
| 78 | license details are recorded in `webui/assets/ATTRIBUTION.md`. |