Skip to main content

Hermes profile lifecycle

Use when managing the lifecycle of Hermes profiles. Manage Hermes profiles as durable role identities. A profile is an isolated home with configuration, credentials, sessions, skills, and runtime state; treat retirement as a migration, not a directory cleanup.

Always-on rules​

  • Name active profiles by role (coordinator, implementer, reviewer, verifier, artifact-compiler), never by model, provider, or launcher. Keep the exact provider/model in configuration and receipts.
  • Keep the primary default profile unless the user explicitly replaces the gateway identity. It is operational infrastructure, not a model-named worker.
  • Use Hermes-native profile commands. Never raw-move or raw-delete $HOME/.hermes/profiles/<name>.
  • Export and restore-test before retirement. A successful export alone is not proof the archive is importable.
  • Remove shared messaging credentials from non-gateway worker profiles. One bot credential cannot safely identify several profiles.
  • Preserve source state.db bytes and row counts before any consolidation. Never merge session databases with unreviewed ad hoc SQL; FTS tables, session relationships, and profile provenance can be corrupted while the file still opens.
  • Abort retirement when a candidate gains a live process, enabled scheduler, service reference, or current operational consumer between inventory and deletion.

Procedure​

1. Define role targets and migration mapping​

List profiles with hermes profile list. Classify each as:

  • retained role profile;
  • new role profile to create;
  • model/tool-named profile to archive;
  • required default infrastructure.

Map every active consumer and each old state store to a target role before changing anything. Do not force mixed historical work into a false role merely to empty a directory; preserving an immutable legacy database beside a migration manifest is preferable to misclassification.

2. Inventory state and consumers​

For every profile, record sanitized configuration, description, model binding, aliases, distribution metadata, file/byte totals, state.db hash and table counts, sessions, snapshots, memories, and skills. Detect credential duplication by comparing fingerprints internally; never print credential values or their hashes.

Census live processes and CWDs, enabled cron jobs, user/system services, $HOME/.hermes/scripts, current operational source, and direct state.db readers.

Separate active consumers from immutable historical receipts/scripts. Migrate active references; leave historical evidence byte-identical and point its manifest to the archived database.

3. Create and qualify role profiles​

Use hermes profile create <role> --clone-from <source> --no-alias --description "..." only when the source is a suitable starting point. Cloning is initialization, not inheritance; inspect the result for stale model identity, skills, memories, credentials, and channel configuration.

Set descriptions with hermes profile describe <role> --text "..."; description text is not a positional argument. Install the role's required skills explicitly and verify their file hashes when copied from an approved local source.

Author $HERMES_HOME/SOUL.md as the profile's durable role identity before qualification:

  1. Inventory the profile description and installed skill frontmatter names; do not infer capabilities from directory names or from another profile.
  2. Use a compact structure such as Identity, Character, Skill posture, and Boundaries. Define who the role is, how it communicates, which installed class-level skills it prefers, and what authority it must not assume.
  3. Keep the identity model- and provider-neutral. Put current bindings in configuration and receipts, never in SOUL text.
  4. Name a skill in the SOUL only when that exact canonical skill name is installed in the same profile. For skills backed by MCP or another external tool, verify both the behavior contract and the reachable tool surface.
  5. Preserve separation of duties in the identity: implementers do not self-review, coordinators do not manufacture independent verdicts, compilers do not issue semantic verdicts, and reviewers do not remediate the subject they judge.
  6. Keep project paths, repository conventions, ports, temporary commands, and one-off workflow detail out of SOUL; place project-local instructions in AGENTS.md or the applicable skill. A specialist SOUL may state stable role procedure and gates, but must not become a project runbook.
  7. Validate every SOUL as non-empty, scan it for stale model/provider identity, resolve each named skill against the profile's installed SKILL.md frontmatter, run hermes -p <role> config check, and start a fresh session before probing behavior because existing sessions retain their original system prompt.

Do not copy the generic default SOUL into a specialist profile: doing so erases the role boundary while leaving the profile looking configured. Keep the default profile broad and accountable; make worker profiles narrow and explicit.

A skill that requires an external tool is two separate profile obligations: install/auto-load the behavior contract and configure/smoke-test the tool in that same profile. Classify profiles by authority, not title: every profile allowed to emit dependency-sensitive code—including a general default agent or a compiler that generates execution stubs—needs the documentation gate; do not add external retrieval to an artifact-only reviewer when it would violate the review evidence boundary.

For each documentation-gated profile, install the reviewed Context7 skill, set skills.auto_load through hermes -p <role> config set, and add Context7 through hermes -p <role> mcp add. Require skill-list and auto-load readback, hermes -p <role> mcp list, hermes -p <role> mcp test context7, and hermes -p <role> config check to pass. Put the gate in the authoring SOUL and require the dependency, version, topic, and resolved Context7 library ID in the handoff or receipt. Put the corresponding requirement in the coordinator's code-writing briefs. A policy skill without reachable tools is not enforcement, and a connected MCP server without an auto-loaded behavior contract is not a role guarantee.

Start a fresh session because MCP tools and auto-loaded skills are assembled at startup. Run an actual read-only probe that calls both Context7 resolution and documentation query; a plausible answer is not proof of tool use. Verify the exact session's recorded tool names and tool-call count in that profile's canonical state.db. System prompts may be deduplicated: follow sessions.system_prompt_hash to system_prompts.hash and inspect system_prompts.prompt rather than treating an empty sessions.system_prompt as absence. Apply the approved one-run route-override rule below when the persistent route is unavailable, and report that capacity failure separately without silently rebinding the profile.

Also run a no-tool response that verifies the exact role/profile and actual provider/model telemetry, then a disposable file-write/readback probe. A profile may have its own configured terminal CWD, so verify the real artifact path rather than assuming the caller's shell workdir controlled it.

4. Normalize channels and bindings​

Use hermes -p <name> config set ... or config unset ... for config.yaml; never hand-edit it. Remove duplicate SLACK_* entries atomically from non-gateway profile .env files without logging values, and remove stale channel configuration with hermes -p <name> config unset platforms.slack when present.

Re-run hermes profile list. Any duplicate-bot warning means cleanup is incomplete.

Bind the role's current provider/model in configuration, but keep the profile name, description, prompts, files, and contracts model-neutral. An unavailable primary route is a capacity result, not evidence that the role profile is invalid; qualify mechanics with another already-approved explicit route and record the primary failure separately.

5. Migrate consumers and state​

Replace active --profile <model-name> references with role profiles while retaining exact explicit provider/model flags when route proof is required. Update active telemetry readers to the target role store or a receipt-bound interface.

Before touching a source database, acquire a stable snapshot or stop its writers; hash the database and record table counts; preserve it in the native export; verify destination schema and collision rules; then migrate only through a supported Hermes path or a separately tested migration with transactional rollback, base-table/FTS validation, and count reconciliation.

Do not treat a copied state.db as successfully consolidated merely because SQLite opens it.

6. Export and prove restoration​

Export one candidate at a time to bound disk pressure:

hermes profile export <name> -o <archive-root>/<name>.tar.gz

Inspect archive root, path traversal, credential-file absence, and member types before import. Named-profile exports preserve runtime state such as state.db while excluding .env and auth.json and redacting staged text.

Hermes import may reject symlink-bearing runtime caches even when export succeeded. If unsupported members occur, remove only regenerable, inactive profile-local caches or runtime installs, re-export, and retry. Never remove sessions, databases, receipts, or user-authored content to make an archive pass.

Import under a temporary name, compare sanitized model/config fields and exact state.db hash, then delete the temporary profile through Hermes. See references/profile-archive-and-restore.md for the bounded recipe.

7. Retire and verify​

Immediately before deletion, repeat the process/service/cron/reference census. Remove aliases through supported commands, then retire exactly the approved profiles with hermes profile delete -y <name>.

Verify that hermes profile list equals the approved role set; no duplicate messaging warning remains; each retained role passes hermes -p <role> config check and a bounded probe; state/session counts reconcile to the migration manifest; archives retain hashes and tested restore commands; and gateway, services, cron, and role-bound controllers remain healthy.

Report restored/retired counts, exact retained roles, archive manifest path, state migration totals, route-probe results, and any capacity blocker separately from migration correctness.

8. Audit installed skills per profile before pinning or citing them​

Skill availability is per-profile. A dispatcher that accepts a skill pin resolves those names against the assignee profile's installed set, and an unknown name kills the worker during skill resolution — before it reads its brief — so the card burns its retries and produces no work and no verdict. Read that failure as a dispatch defect, not a finding about the candidate: the exact head stays unreviewed and no prior verdict transfers to it.

Default posture: do not pin skills when the brief is self-contained. When a pin is genuinely needed, enumerate the assignee's actual installed names first and pass them in the exact path form printed:

find "$HOME/.hermes/profiles/<assignee>/skills/" -maxdepth 3 -iname 'skill.md' -printf '%h\n' \
  | sed 's|.*/skills/||' | sort

Verify per assignee every time rather than trusting a remembered list or an operational note. A written-down claim about which profile carries which skill decays as profiles are created, cloned, and retired; re-derive it from disk. When an on-disk operational rule turns out to be wrong, correct the sentence in place with the evidence that disproved it — appending a later note under a wrong claim leaves the wrong claim as the first thing the next reader acts on.

To confirm two profiles carry the same skill rather than merely the same name, compare SKILL.md digests; separate inodes with equal digests mean independent copies of identical content, and a shared name with differing digests is drift to resolve before either is cited as authority.

Audit each SOUL.md against the same inventory: every skill the SOUL names must resolve to an installed SKILL.md in that same profile, and a skill supplied through auto-load configuration must appear in that profile's config readback rather than being assumed from the default profile. Confirm the profile set itself from the profiles directory before reasoning about any of them — notes and briefs routinely reference role profiles that were never created or have since been retired.

When a bundle must reach a worker that does not inherit the host's skills, bind it in the brief text with absolute paths to the installed files, never through a pin.

When auditing role bindings, report a role whose configured route has no secondary as a distinct finding: a single-route role stalls its whole lane when that provider rate-limits, and the absence is invisible while the primary is healthy.

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/autonomous-ai-agents/hermes-profile-lifecycle/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/autonomous-ai-agents/hermes-profile-lifecycle/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

version 1.0.0.

Published by Muse · 2026-10-04.