Where Hermes stores skills, SOUL.md, memories, and context files

Hermes (Nous Research’s self-improving agent) keeps everything under one home directory — ~/.hermes by default ($HERMES_HOME) — and borrows its per-project context files from other tools’ conventions rather than defining its own dotfolder in your repos. ~ is your home directory.

At a glance

Artifact	Global	Per-project	Format
Skills	~/.hermes/skills/<category>/<skill>/SKILL.md + category-level DESCRIPTION.md	— (external dirs via config.yaml)	Markdown + YAML frontmatter
Persona	~/.hermes/SOUL.md	—	Markdown
Memories	~/.hermes/memories/MEMORY.md, USER.md	—	Markdown
Context files	—	first match of .hermes.md/HERMES.md → AGENTS.md → CLAUDE.md → .cursorrules	Markdown
Session history	~/.hermes/state.db	—	SQLite (FTS-searchable)
Config	~/.hermes/config.yaml	—	YAML

Hermes nests skills — and puts DESCRIPTION.md files in the tree

Hermes organizes skills into category folders: each skill is skills/<category>/<skill>/SKILL.md, and the category folder itself carries a DESCRIPTION.md with its own frontmatter describing the group (categories can nest further, e.g. skills/mlops/models/DESCRIPTION.md). A scanner or backup that expects the flat skills/<name>/SKILL.md layout of Claude Code misses both the nesting and every DESCRIPTION.md.

Skills

~/.hermes/skills/ is the source of truth — the built-in skill library is copied there on install, and when Hermes creates or improves a skill (it does this autonomously after complex tasks), it writes there too. SKILL.md frontmatter takes name, a deliberately short description, and optional version, platforms, and metadata.hermes.* fields; the format is compatible with the open Agent Skills standard, so skills written for Claude Code or Cursor generally work. Extra skill directories (a team share, ~/.agents/skills) plug in via skills.external_dirs in ~/.hermes/config.yaml.

SOUL.md

~/.hermes/SOUL.md is the persona file — global personality and tone, loaded into every session regardless of project. It is never read from the working directory, which makes it the one rules-like file on this page that can’t be committed to a repo.

Memories

Hermes’s curated memory is two small Markdown files under ~/.hermes/memories/: MEMORY.md (the agent’s notes — environment, project conventions, lessons learned) and USER.md (your profile and preferences). Both are hard-capped in size (roughly 800 and 500 tokens) and injected into the system prompt at session start; when a write would exceed the cap, the memory tool errors rather than silently dropping entries. Unbounded recall lives in ~/.hermes/state.db, a SQLite store of past sessions with full-text search.

Project context files

Hermes defines no .hermes/ folder inside your repos. Instead it checks the working directory for the first match of .hermes.md/HERMES.md, AGENTS.md, CLAUDE.md, or .cursorrules — only one is loaded — and repeats the same lookup up through parent directories as it touches files. It also reads .cursor/rules/*.mdc modules. One well-maintained AGENTS.md therefore serves Hermes, Codex, Cursor, and Claude Code at once.

Native Windows uses %LOCALAPPDATA%\hermes

On Linux, macOS, and WSL2 the home directory is ~/.hermes. A native Windows install lives under %LOCALAPPDATA%\hermes instead — tooling that hardcodes the dotfolder path finds nothing on native Windows.

Seeing all of it at once

Quartermaster’s scanner walks every location on this page — including the nested skill categories and their DESCRIPTION.md files — and indexes the artifacts into one searchable registry alongside Claude Code, Cursor, Codex, and 8 more tools. SQLite memory stores like state.db are skipped by design (the curated Markdown is the source), and it can convert skills between Hermes and the flat-layout tools. Secrets are never indexed — env/header key names kept, values dropped. See the full discovery map or the quickstart.