Customize SOUL.md Without Crossing Profile Boundaries

SOUL.md is the durable identity file for a Hermes instance. It defines voice, tone, communication style, and how the agent handles uncertainty, disagreement, and ambiguity. At session start, Hermes reads the file from the active HERMES_HOME, scans it for prompt-injection patterns, truncates it if necessary, and uses it as the first identity slot in the system prompt. If the file is missing, empty, or unavailable, Hermes falls back to its built-in identity.[1]

Keep identity separate from project operations

Write broadly applicable guidance in SOUL.md: be direct, avoid hype, explain uncertainty, or challenge weak assumptions. Put repository-specific rules in AGENTS.md, including file paths, test commands, architecture notes, ports, and workflow constraints. Use /personality for a temporary session mode rather than repeatedly rewriting the durable baseline.[1]

A strong identity file is stable, specific in voice, and short enough to remain coherent. Avoid contradictory demands and micromanagement of every response shape. Because its contents enter the system prompt, keep credentials, private records, temporary client details, and other sensitive or short-lived data out of the file.

Understand the active profile boundary

A Hermes profile is a separate home directory with its own config.yaml, .env, SOUL.md, memory, sessions, skills, cron jobs, and state database. This lets a coding agent, personal assistant, and research profile use different identities without mixing state.[2] Before editing, identify the active profile and its HERMES_HOME; a repo-local SOUL.md is not the instance identity file described by the guide.[1]

Profile cloning deserves special care. A config clone can copy configuration, credentials, SOUL.md, and skills while leaving sessions and memory fresh; a full clone copies more state. Treat a clone as a deliberate transfer, then review the new profile’s identity, capabilities, and credentials instead of assuming it is blank or harmless.[2]

Edit iteratively

Start from the seeded file, remove language that does not fit, and add a small set of clear defaults. Begin a new session after editing. Test the identity with prompts that reveal style—an ambiguous question, a disagreement, a request for a short explanation, and a situation requiring uncertainty. Adjust only what remains consistently wrong. If guidance is ignored, check for conflicts, excessive length, higher-priority instructions, or text that resembles prompt injection.[1]

Customization checklist

Confirm the active profile and the HERMES_HOME being edited.
Keep the file focused on durable identity and communication style.
Move project paths, commands, and workflow rules to AGENTS.md.
Remove secrets, private records, and temporary task context.
Start a new session after each meaningful edit.
Test the intended profile and confirm other profiles remain unchanged.

Common pitfalls

Editing a repository-local file and expecting it to replace instance identity.
Turning SOUL.md into a project runbook or command catalog.
Adding conflicting instructions or generic filler until the file is ineffective.
Expecting an existing session to adopt edits without a restart.
Copying credentials or sensitive context into prompt-visible identity text.
Cloning a profile and overlooking copied configuration or capabilities.

Verification

Open a fresh session in the intended profile and test tone, brevity, uncertainty, and disagreement. Confirm project-specific instructions still come from project context. Start a different profile and verify its identity did not change. If behavior is missing, inspect the correct home file, confirm it is non-empty, and simplify any content that may be conflicting, truncated, or blocked by the scanner.