The Hermes Filesystem Layout

+15 Mana ✨
Installation Guide: Filesystem Layout(DOCUMENTATION)

Introduction

After a per-user install, Hermes lives in three places on your machine: a code directory, an executable on your PATH, and a data directory. Knowing what is where, and which files are durable, which are caches, and which are secrets, lets you back up, debug, and migrate Hermes without guesswork.

Key Concepts

  • Code directory: ~/.hermes/hermes-agent/, the installed source (immutable from the user's perspective).
  • Binary: ~/.local/bin/hermes, the symlink the shell finds when you type hermes.
  • Data directory: ~/.hermes/, sessions, memory, skills, configuration, credentials.
  • state.db: The SQLite database under ~/.hermes/ that holds session messages, IDs, titles, and counters.

Real World Context

Suppose you want to back up everything Hermes knows about you before reinstalling on a new laptop. You do not need to copy the code directory, that comes back with a fresh install. You need exactly the contents of ~/.hermes/ minus hermes-agent/: that is your sessions, your skills, your config, your credentials. Knowing the layout makes that obvious.

Deep Dive

The standard per-user layout

text
~/.hermes/
├── hermes-agent/      # installed code (replaceable)
├── state.db           # SQLite: sessions, messages, memory
├── config/            # provider config, fallback chains
├── credentials/       # encrypted API keys (per provider)
├── skills/            # user-installed skills
├── logs/              # rotating logs
└── cache/             # transient downloads, prefetches

~/.local/bin/hermes    # the binary symlink on $PATH

The shape is "code is one thing, data is another." The code directory is something Hermes manages for itself; the data directory is yours.

Why state.db

Sessions need to survive crashes, persist across reboots, and be queryable. SQLite gives Hermes ACID writes, indexed queries, and a single-file format that is trivial to copy or back up. Every message you and the agent exchange ends up as a row in state.db.

Reading vs. writing the data dir

Almost everything in ~/.hermes/ is meant to be read by you (debugging, backups, audits) but written only by Hermes. The exception is config files, where editing by hand is supported and sometimes necessary.

Common Pitfalls

  1. Editing state.db by hand, Do not. Use hermes commands to manage sessions. Direct SQL writes can corrupt the DB.
  2. Backing up hermes-agent/ instead of ~/.hermes/ data, The code is replaceable; the data is not. Back up the data dir.

Best Practices

  1. Snapshot ~/.hermes/ before risky operations, Before a major upgrade or experimental config change, copy the directory.
  2. Treat ~/.local/bin/hermes as a symlink, not a binary, It points into the code directory. Do not cp it elsewhere; let the installer manage it.

Summary

  • Three locations: code (~/.hermes/hermes-agent/), binary (~/.local/bin/hermes), data (~/.hermes/).
  • state.db is the SQLite session store and the single most important file in your install.
  • Code is replaceable; data is yours, back up the data, not the code.

Code Examples

bash
# Back up everything Hermes knows about you (skip the replaceable code)
tar -czf hermes-backup.tgz \
  ~/.hermes/state.db \
  ~/.hermes/config \
  ~/.hermes/credentials \
  ~/.hermes/skills

# Restore on a new machine after a fresh `hermes` install
tar -xzf hermes-backup.tgz -C ~/
✓ Completed