What does this PR do?

This extends the functionality of personalities by allowing for more verbose personality profiles defined in separate files (e.g. ~/.hermes/personalities/my_verbose_personality_profile.md). This maintains backwards compatibility with the currently described personality definition process and keeps the config.yaml file relatively clean so that a single verbosely defined personality profile doesn't dominate the entire config.

I believe this splits the difference of SOUL.md and personalities by offering the canvas of a dedicated file for defining a personality, while allowing for a the flexibility of a session level personality overlay.

Related Issue

No existing issue.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• cli.py

  • Add _load_personality_file() helper function to load personality content from external files (supports absolute paths, ~/ home paths, and relative paths resolved from HERMES_HOME)
  • Update _resolve_personality_prompt() to detect and load {file: "..."} references
  • Update _handle_personality_command() to skip saving file references to config (session-only), preserving the config.yaml as clean source of truth

• gateway/run.py

  • Update _resolve_prompt() with identical file reference logic for consistency with CLI

• tests/test_personality_none.py

  • Add TestPersonalityFileReference test class with 10 test cases covering:
    • File content loading
    • Relative path resolution
    • Home directory path (~/) support
    • Missing file handling
    • File + supplemental fields (tone, style)
    • Config save behavior (file references are session-only, inline configs still save)

How to Test

1. Create a personality profile in a .md file (for example: ~/.hermes/personalities/my_verbose_personality_profile.md)
2. Set up the personality in config.yaml like normal, but add the file key and point to the directory you chose to put your personality profile

agent:
  personalities:
    verbose: You are a verbosely defined AI assistant.
      file: "~/.hermes/personalities/my_verbose_personality_profile.md"

3. Run python cli.py to launch the agent
4. Test the personality with /personality my_verbose_personality_profile. You should get a confirmation that the personality loaded like any other personality, with the addition of an the first 60 characters of the resolved profile.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform:

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

• This skill is broadly useful to most users (if bundled) — see Contributing Guide
• SKILL.md follows the standard format (frontmatter, trigger conditions, steps, pitfalls)
• No external dependencies that aren't already available (prefer stdlib, curl, existing Hermes tools)
• I've tested the skill end-to-end: hermes --toolsets skills -q "Use the X skill to do Y"

Screenshots / Logs

Example of a personality profile loading from file: