Import from Hermes or OpenClaw

If you are coming from Hermes or OpenClaw, you do not have to start empty. atomic-agent import reads the other agent’s state directory and copies your conversation history and scheduled jobs into Atomic Agent’s own stores.

It is a one-shot migration, not a sync. Run it once when you switch, or again later to pick up what you left behind.

Developer Preview

Atomic Agent is a Developer Preview. Import options and report shapes can move between releases. Pin a release if you script this.

Start with a dry run

Always. --dry-run runs the full reconciliation — reading the source, matching against your existing sessions, detecting conflicts — and then writes nothing. You get the exact report the real run would produce, with none of the consequences.

atomic-agent import hermes --dry-run

1. Preview. Run with --dry-run and read the report: how many sessions, how many cron jobs, and how many conflicts.

2. Resolve conflicts. If items are flagged as conflicting, decide whether you want --overwrite or would rather leave your existing data alone.

3. Import. Re-run without --dry-run. You get an interactive confirmation unless you pass --yes.

Hermes

atomic-agent import hermes [--source DIR] [--preset default|full]
                           [--include a,b] [--exclude a,b]
                           [--migrate-secrets] [--limit N]
                           [--overwrite] [--dry-run] [--yes]

Flag	Default	Description
--source DIR	~/.hermes, or HERMES_STATE_DIR	Hermes state directory to read.
--preset default|full	default	What to import. default is sessions + cron.
--include a,b	—	Add options on top of the preset (sessions, cron).
--exclude a,b	—	Remove options from the preset.
--migrate-secrets	off	Also copy allowlisted provider keys into <stateDir>/.env. See below.
--limit N	no limit	Cap the number of sessions imported. Must be a non-negative integer.
--overwrite	off	Overwrite destinations that differ instead of flagging them as conflicts.
--dry-run	off	Preview only; never write.
--yes	off	Skip the interactive confirmation.

atomic-agent import hermes --dry-run
atomic-agent import hermes --yes
atomic-agent import hermes --migrate-secrets --overwrite

If your include/exclude combination leaves nothing selected, the command exits 1 with nothing selected to import rather than doing a silent no-op.

OpenClaw

atomic-agent import openclaw [--source DIR] [--agent NAME]
                             [--include a,b] [--exclude a,b]
                             [--limit N] [--overwrite] [--dry-run] [--yes]

Flag	Default	Description
--source DIR	~/.openclaw, or OPENCLAW_STATE_DIR	OpenClaw state directory to read.
--agent NAME	main	Which OpenClaw agent’s sessions to import.
--include a,b	—	Add options (sessions, cron).
--exclude a,b	—	Remove options.
--limit N	no limit	Cap the number of sessions imported.
--overwrite	off	Overwrite differing destinations.
--dry-run	off	Preview only.
--yes	off	Skip confirmation.

atomic-agent import openclaw --dry-run
atomic-agent import openclaw --agent main --yes

OpenClaw has no --preset

OpenClaw takes --include and --exclude but no --preset, and no --migrate-secrets — secret migration is a Hermes-only path.

The subcommand is required

import on its own is not a command. Running it with no source prints the help text and exits 1:

atomic-agent import          # prints help, exits 1
atomic-agent import --help   # prints help, exits 0

An unrecognised source (atomic-agent import claude) also exits 1.

Imported sessions never collide

Sessions arrive with a namespace prefix — hermes: or openclaw: — so an imported conversation can never overwrite a native Atomic Agent session that happens to share an id.

Conflicts are detected structurally, on the full transcript rather than just the identifier. Two consequences worth knowing:

• Re-running the same import is safe. Identical items are skipped and reported as duplicates, not written twice.
• An item flagged as a conflict genuinely differs in content. --overwrite replaces your side with the source’s; without it, your existing data wins and the difference is reported.

Tip

Because import is idempotent on the source, --limit is a reasonable way to try it out. Import ten sessions, look at them in the TUI, then re-run without the limit to bring the rest across.

Migrating secrets

Hermes stores provider API keys in its own .env. --migrate-secrets copies them into <stateDir>/.env — but only two, and only these two:

Key
OPENROUTER_API_KEY
AIMLAPI_API_KEY

The allowlist is hard-coded. Any other variable in the source .env is ignored, as are allowlisted keys with empty values. Both names are identical across the two projects, so the copy is verbatim.

Secrets are never part of a preset

--migrate-secrets is the only way to move keys. Neither --preset default nor --preset full includes them, and --include secrets will not conjure them. That is deliberate: copying credentials should be a thing you typed, not a thing a preset did for you.

The import report prints key names only, never values.

From the TUI

You do not have to use the command line. The TUI has an Import tab with the same two paths, reachable with the /import slash command:

atomic-agent tui
# → /import

The panel offers a preview (the same reconciliation as --dry-run) and an execute action that writes sessions, tasks, and — when you ask for it — secrets.

Related

CLI Reference

Every command and flag, with import alongside the rest.

Why local-first

Where imported sessions, tasks, and secrets land in the state directory.

Scheduling

What imported cron jobs become once they are in the task queue.

Configuration

config.json, .env, and the state directory layout.