Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/techjarves/Hermes-USB-Portable/llms.txt

Use this file to discover all available pages before exploring further.

The data/ directory is the heart of your Hermes Portable installation. Every piece of personal state — your API credentials, LLM configuration, chat histories, persistent memory, custom skills, and logs — lives inside it. Nothing is written to the host system’s home directory. When you move the portable folder to a new machine or a different USB drive, your entire agent context moves with it.

​
Directory Structure

data/
├── .env                # API keys and credentials
├── config.yaml         # Hermes LLM provider configuration
├── sessions/           # Chronological chat histories
├── memories/           # Persistent memory databases
├── skills/             # Learned custom skills
├── logs/
│   ├── agent.log       # Main agent activity log
│   ├── errors.log      # Error output
│   └── gateway.log     # Messaging gateway log
├── state.db            # Gateway state and locks
└── SOUL.md             # Custom system prompt loaded on every launch

​
File Reference

FilePathPurpose
API Keysdata/.envSecrets — OpenRouter, OpenAI, Anthropic, Telegram, and other provider credentials
Settingsdata/config.yamlAll Hermes configuration: active LLM provider, model, and feature flags
Chat Historydata/sessions/Saved conversations, one file per session
Memorydata/memories/Persistent memory databases built up across conversations
Skillsdata/skills/Reusable custom skills Hermes has learned or been taught
Logsdata/logs/agent.log, errors.log, and gateway.log for diagnostics
State DBdata/state.dbGateway state and process locks
Custom Promptdata/SOUL.mdSystem prompt injected at the start of every conversation

​
SOUL.md — Custom System Prompt

Creating a file at data/SOUL.md lets you inject a persistent system prompt into every Hermes conversation without modifying any source code. Whatever you write in that file is loaded automatically on launch and prepended to the agent’s context. Common uses for SOUL.md:
  • Give Hermes a specific persona or communication style
  • Add standing instructions (“always respond in Spanish”, “prefer concise answers”)
  • Include background context about your projects or preferences that you want Hermes to remember across sessions
To activate it, simply create the file: 
# Create or edit data/SOUL.md with any text editor
echo "You are a helpful assistant that always reasons step by step." > data/SOUL.md
Delete the file to revert to Hermes’s default system prompt.

​
HERMES_HOME Environment Variable

Both launchers set the HERMES_HOME environment variable to the absolute path of the data/ folder before starting Hermes: 
# Set automatically by launch.sh / launch.bat:
export HERMES_HOME="<portable-root>/data"
This overrides Hermes’s default behaviour of writing to ~/.hermes/ on the host machine. As a result, all reads and writes from the Hermes process are redirected into the portable data/ directory — no files are created in the user’s home folder.
If you ever run hermes commands outside of the portable launcher (e.g., from a global install), Hermes will fall back to ~/.hermes/ because HERMES_HOME will not be set. Always use launch.bat or launch.sh to ensure full isolation.

​
Backup and Restore

​
What to Back Up

Back up the entire data/ folder. It contains everything that is uniquely yours:
WhatWhy
data/.envYour API keys — losing these requires regenerating keys from each provider
data/config.yamlYour LLM provider and model preferences
data/sessions/Your full conversation history
data/memories/The accumulated memory Hermes has built from your conversations
data/skills/Any custom skills you have created or taught
data/SOUL.mdYour custom system prompt, if you use one
A simple archive command works well for point-in-time backups: 
tar -czf hermes-data-backup-$(date +%Y%m%d).tar.gz data/
You can also use the built-in backup command from inside a Hermes session: 
hermes backup

​
What Is Safe to Delete

The .cache/runtimes/ directory holds the downloaded Python and Node.js interpreters for each platform. It can be deleted freely to reclaim disk space — the launcher will re-download and rebuild the runtimes automatically on the next launch. 
.cache/runtimes/   ← safe to delete; rebuilt automatically on next launch
data/              ← DO NOT delete; contains all your personal data
src/               ← safe to delete; re-cloned automatically on next launch
Always back up the data/ folder before running a full reset. The reset scripts (reset-windows.ps1 -Mode full / reset-unix.sh full) delete everything including data/, and this cannot be undone.

Build docs developers (and LLMs) love

Get started for freeTalk to us