Hermes Agent Deep Cuts: Import the Workflow, Leave the Credentials Behind

Oct 12, 2026 5 min read

A Codex setup can become Hermes memory, an MCP server entry, and an installed skill without importing its login token. I ran hermes import-agent codex --dry-run against a disposable fixture: Hermes listed each destination, then reported that it had modified no files. The useful part is what happens after that first migration, when the source setup changes.

It translates files, not whole agents

hermes import-agent supports Claude Code and Codex CLI. It reads selected setup files and maps them into Hermes concepts. Codex AGENTS.md instructions become entries in memories/MEMORY.md; config.toml MCP servers become mcp_servers in config.yaml; and skill directories with a SKILL.md land under skills/codex-imports/. Claude settings have their own mappings, including Bash permission rules into Hermes command allow and deny lists.

That translation is intentionally partial. A command file does not become a skill automatically, and agent-specific permissions without a Hermes equivalent are reported rather than silently approximated. Credential stores are not read. Secret-looking MCP environment variable names are stripped from imported server definitions so you can configure those values deliberately in Hermes.

The command always builds a preview first. Without --dry-run, an interactive terminal can confirm and apply it. In a non-interactive session, it stops at the preview unless you pass --yes. That makes the preview a useful migration review, not a cosmetic progress screen.

Run the migration in two passes

Point at the source explicitly when you have more than one agent setup or want to avoid relying on auto-detection:

hermes import-agent codex --source "$HOME/.codex" --dry-run
hermes import-agent codex --source "$HOME/.codex"

The first command is read-only with respect to the import. Inspect the plan for unexpected MCP servers, skipped permissions, or skill conflicts. The second command shows the preview again, then asks before writing when run interactively. On a managed migration where the preview has already been reviewed, --yes skips that confirmation.

Conflicts are skipped by default. --overwrite replaces conflicting items, so it belongs in a deliberate migration command, not a routine sync job. Memory entries and permission patterns merge with existing Hermes content. The importer avoids duplicating memory entries it recognizes as equivalent.

For reference, this excerpt is actual output from a disposable Codex fixture with one AGENTS.md, one MCP server, and one skill. The preview heading is omitted here because it contains punctuation this publication avoids:

  No changes have been made yet. Review the list below:

◆ Dry Run Results
  No files were modified. This is a preview of what would happen.

  ✓ Would import:
      agents-md              → ~/.hermes/profiles/blogposter/cache/scratch/hermes-import-agent-demo/home/.hermes/memories/MEMORY.md
      mcp-servers            → config.yaml mcp_servers.review
      skill                  → ~/.hermes/profiles/blogposter/cache/scratch/hermes-import-agent-demo/home/.hermes/skills/codex-imports/review

  ─ Skipped:
      memories                No memories directory found

  Summary: 3 would import, 1 skipped

Those destinations are from the isolated test home, not a suggested installation path. On your machine, the profile home is the target. The command itself prints both source and target before import.

The sync manifest is a digest, not a mirror

A successful import records the source location and a content digest in import-sync.json inside the Hermes home. hermes import-agent --sync compares the files the importer reads with that saved digest. If nothing changed, it skips the source. If files changed, it re-imports without prompting. --dry-run previews this sync without applying it.

hermes import-agent --sync --dry-run
hermes import-agent --sync

The digest is computed from the relevant instructions, configuration, memories, and skill files. Credential files such as auth.json and .credentials.json are excluded. A refreshed token therefore does not trigger an import, and the token still is not copied. A change to a skill or MCP configuration does.

This makes sync suitable for an explicit scheduled job after you have reviewed the original migration. It is scoped to previously registered sources. It does not discover new agent folders, and it does not continuously mirror every file under either home directory.

The gotcha: edits in Hermes are a conflict

Imported skills are not blindly overwritten during sync. Hermes records the digest of the copy it installed. If you edit that skill under the Hermes import category, the destination no longer matches the recorded digest. A later sync reports a conflict and leaves your local edit alone. That is usually the right result, but it can look like sync failed to pick up an upstream fix.

Keep a local fork under a separate skill name or path if you want to preserve your changes and accept future source refreshes. Otherwise, inspect the conflict and consciously decide whether to restore the imported copy. Do not set overwrite on the initial import just to make a scheduled sync simpler. That choice is recorded in the sync manifest and can make later updates replace conflicting items, which weakens the protection you want for local edits.

A second trap is assuming that imported setup is complete. The migration leaves API keys and credentials out by design, and some source-agent features have no direct Hermes equivalent. A clean import report does not mean every behavior from the old agent moved over.

Verify before you trust the migration

Start with the preview and check its per-item destinations. After an approved import, use hermes profile show <name> to confirm the intended profile and hermes skills list to check installed skills. Review the relevant mcp_servers and permissions in that profile’s config.yaml; do not print credential values while inspecting it.

For later updates, run the dry-run sync first. A source marked unchanged is being skipped by its digest check, not re-copied. A changed source should produce a per-item plan. If an edited imported skill is reported as a conflict, Hermes is preserving the local version, not silently ignoring all upstream changes.

The migration is most useful when you treat it as a reviewed translation and the manifest as an update boundary. Your old agent’s working habits can come across. Its secrets, assumptions, and every tool-specific behavior should not.