User Profiles & Session Persistence
Relevant source files
The following files were used as context for generating this wiki page:
User Profiles and Session Persistence provide the structural foundation for identity management and state retention in Hermes Agent. The system enables independent agent instances to maintain isolated configurations, memories, and interaction histories across multiple platforms.
The profile system isolates user data, while the persistence layer handles the recording of transcripts and state transitions. This architecture ensures that the agent remembers user preferences, environment details, and lessons learned between sessions.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md, gateway/session_persistence.py
User Profiles
Profiles allow you to run multiple independent Hermes instances. Each profile maintains an isolated environment for configurations, sessions, skills, and memory.
Profile Structure
Hermes stores profile data in specific directories. The system resolves the home directory from the $HERMES_HOME environment variable if it is set. By default, profiles reside in ~/.hermes/profiles/<name>/.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md, website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md
| File/Directory | Purpose |
|---|---|
config.yaml | Main settings and toolset configurations. |
.env | API keys and secrets. |
SOUL.md | Primary identity and communication style. |
state.db | SQLite database for session state and FTS5 search. |
sessions/ | Routing index and request dumps. |
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md, website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md
Profile Management
You manage profiles through CLI commands. The system supports cloning existing profiles to preserve model and base configurations.
- Create Profile:
hermes profile create <name>initializes a new isolated directory. - Clone Profile: Using the
--cloneflag copies the active profile's settings to a new instance. - Configure Profile: The system patches
config.yamlto define specific toolsets and skills for the profile.
Sources: optional-skills/creative/kanban-video-orchestrator/references/kanban-setup.md, skills/autonomous-ai-agents/hermes-agent/SKILL.md
The diagram above shows the logic for resolving agent identity and loading the persistent state at session startup.
Session Persistence
The persistence layer records every interaction and state change. This allows Hermes to resume work or reflect on past conversations.
Data Storage
Hermes uses a dual-storage approach for sessions:
- SQLite (state.db): Stores canonical session data and supports Full-Text Search (FTS5) for fast retrieval of past context.
- JSONL Transcripts: The
sessions/directory contains.jsonlfiles representing raw interaction transcripts and request dumps.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md, gateway/session_persistence.py
Session Resumption
The system allows users to continue previous workflows using session identifiers.
--continue: Resumes the most recent session.--resume <session_id>: Loads a specific session from the persistence store.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md, gateway/session.py
This sequence illustrates how the persistence layer retrieves historical data to restore the agent's context.
Identity & SOUL.md
The SOUL.md file defines the agent's primary identity within a profile. It dictates tone, personality, and communication style.
Identity Injection
When a session starts, Hermes reads the SOUL.md from the active profile. It scans for prompt-injection patterns and replaces the default identity text in the system prompt. If the file is missing or empty, the system reverts to the built-in default identity.
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md, gateway/session_identity.py
SOUL.md vs. AGENTS.md
The system distinguishes between global identity and project-specific rules:
- SOUL.md: Defines who the agent is (e.g., direct, calm, precise).
- AGENTS.md: Defines what the agent does for a specific project (e.g., coding standards, file paths).
Sources: website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/use-soul-with-hermes.md
Configuration Persistence
Profile configurations are managed through config.yaml. The agent uses specific tools to update these settings without corrupting the file structure.
- Config Tooling: Use
hermes config set <key> <value>to modify settings. - Toolsets: Profiles restrict which tools are available (e.g.,
terminal,file,web). - Always Load Skills: Configures specific skills that load automatically every time a profile session starts.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md, optional-skills/creative/kanban-video-orchestrator/references/kanban-setup.md
Data Privacy & Redaction
The persistence system includes security measures to prevent sensitive data leaks.
- Secrets and API keys stay in the
.envfile. config.yamlcontains only non-sensitive settings.- The system includes approval modes and PII redaction logic during session recording.
Sources: skills/autonomous-ai-agents/hermes-agent/SKILL.md, gateway/session_persistence.py
Summary
The User Profiles and Session Persistence systems ensure Hermes Agent remains a consistent, reliable, and secure assistant. By isolating environments through profiles and systematically recording state through persistence modules, the agent provides a unified experience across different interfaces and projects while maintaining a high standard of data integrity.