Hermes Agent Configuration Surface

Complete map of Hermes Agent’s native configuration files and optional memory plugins. AGENTS.md and MEMORY.md are both natively supported.

Why / When to Use

Reference when setting up a new Hermes project, troubleshooting context loading, or designing the Hermes fleet architecture. Also useful when deciding what to put in SOUL.md vs MEMORY.md vs AGENTS.md.

Core Configuration Files

SOUL.md (Identity & Persona)

• Location: project root or ~/.hermes/SOUL.md
• Purpose: Defines Hermes’s persona, tone, and behavioral rules
• Loaded: Every session, first in context
• Editable: Yes, by the user — this is the primary customization point

AGENTS.md (Project Context — per-directory)

• Location: Any directory; Hermes discovers them via progressive subdirectory scan
• Purpose: Per-project instructions, tech stack, conventions, constraints
• Loaded: From the working directory and all parent directories up to the project root
• Hierarchy: 4-level progressive discovery — root → workspace → project → subdirectory
• Interchangeable with: CLAUDE.md, CONTEXT.md, README.md (Hermes reads all four formats)
• Note: Same format as CLAUDE.md used by Claude Code — fully compatible

project/
  AGENTS.md          ← root-level project context
  backend/
    AGENTS.md        ← backend-specific rules (loaded when working in backend/)
  frontend/
    AGENTS.md        ← frontend-specific rules (loaded when working in frontend/)

MEMORY.md (Persistent Agent Memory)

• Location: ~/.hermes/MEMORY.md (global) or per-project
• Purpose: Agent-curated persistent memory store — facts Hermes has learned about you/project
• Cap: 2,200 characters maximum
• Editable: By Hermes (agent writes to it); user can also edit manually
• Not a hand-authored config — Hermes populates this over time from conversations
• Format: Key-value facts, preferences, recurring patterns

USER.md (User Profile)

• Location: ~/.hermes/USER.md
• Purpose: Static user profile — name, role, preferences, communication style
• Editable: By user; Hermes reads but does not overwrite

FTS5 Session Database

• Location: ~/.hermes/sessions.db (SQLite with FTS5 extension)
• Purpose: Full-text searchable history of all Hermes conversations
• Hermes queries this to retrieve relevant past context automatically
• Not a config file — managed internally

Skills Library

• Location: ~/.hermes/skills/ or project-local skills/
• Purpose: Reusable prompt templates / task patterns Hermes can invoke by name
• Format: Markdown files with frontmatter

Optional External Memory Plugins (8 available)

Hermes supports 8 optional plugins for extended memory beyond MEMORY.md:

Key Options / Variants

AGENTS.md vs CLAUDE.md: Both are interchangeable in Hermes. Use AGENTS.md for Hermes-specific projects; CLAUDE.md if the same project also uses Claude Code directly (Claude Code reads CLAUDE.md natively).

MEMORY.md cap: 2,200 characters is a hard limit. Hermes prunes older facts when it writes new ones. If critical context is being lost, move it to USER.md or a project AGENTS.md instead.

Context priority order: SOUL.md → USER.md → AGENTS.md (root to current dir) → MEMORY.md → FTS5 retrieved sessions → current conversation

Multi-Agent (Commander) Setup

For a multi-agent Hermes fleet, the Commander’s AGENTS.md defines:

• Routing logic: which specialist agent to invoke for which task type
• Shared context each agent inherits
• Handoff protocols between agents

Each specialist Hermes instance gets its own AGENTS.md (and its own MEMORY.md if run in isolation). This means per-domain memory accumulates separately — the PKM agent and the dev agent don’t pollute each other’s context.

Specialist agents in progress (as of 2026-05-23):

• #notes PKM agent — handles note creation and daily summaries

→ See hermes-commander-setup for the Commander AGENTS.md draft.

Gotchas

• MEMORY.md is managed by the agent, not the user — hand-editing it is fine but Hermes may overwrite sections on the next write cycle
• AGENTS.md must be in a directory Hermes has been asked to work in (or a parent) — files outside the working tree are not discovered
• FTS5 database requires SQLite compiled with the FTS5 extension (standard on most systems)
• Skills library is not auto-discovered — skills must be explicitly referenced or Hermes must know the skills path

Source

Conversation “Hermes benefits and capabilities” — 2026-05-22. Verified via official Hermes documentation sources cited in the conversation.