Hermes Directory Structure Template

This repository provides a standardized filesystem layout template for the ~/.hermes folder, organized systematically by purpose. It serves as a boilerplate for configuring, extending, and managing Hermes AI agents.

Filesystem Layout

~/.hermes/
├── config.yaml                 # Main configuration
├── .env                        # API keys and secrets
├── auth.json                   # OAuth provider credentials
├── SOUL.md                     # Agent identity (slot #1 in system prompt)
├── memories/
│   ├── MEMORY.md               # Persistent agent facts
│   └── USER.md                 # User model
├── skills/                     # All skills (bundled, hub, agent-created)
│   ├── mlops/
│   │   ├── axolotl/
│   │   │   ├── SKILL.md        # The system prompt for the skill
│   │   │   ├── references/     # Docs the agent reads
│   │   │   └── scripts/        # Executable helpers
│   │   └── vllm/
│   ├── devops/
│   └── .hub/                   # Skills Hub state
├── sessions/                   # Per-platform session metadata
├── state.db                    # SQLite session store with FTS5
├── cron/
│   ├── jobs.json               # Scheduled jobs
│   └── output/                 # Cron run outputs
├── plugins/                    # Custom plugins
├── hooks/                      # Lifecycle hooks
├── skins/                      # CLI themes
└── logs/
    ├── agent.log               # Core agent diagnostics
    ├── gateway.log             # Gateway traffic logs
    └── errors.log              # Error tracking

Component Breakdown

1. Configuration

Core files that the agent boots from on every single run.

• config.yaml: Handles global settings, model endpoints, and operational parameters.
• .env: Local environment variables dedicated to sensitive API keys and tokens.
• auth.json: Manages active OAuth tokens and multi-provider credentials.
• SOUL.md: Defines the core identity, behavioral constraints, and personality baseline of the agent.

2. Knowledge

Persistent memory layers that span across all active communication channels and sessions.

• MEMORY.md: Fact base and long-term world knowledge collected by the agent.
• USER.md: Profile, preferences, and behavioral insights compiled about the user.

3. Capabilities (Skills)

Modular skill packs that grant specific executable abilities to the agent. Skills can be built-in, downloaded via the Hub, or dynamically generated by the agent itself.

Each individual skill follows a strict internal structure:

• SKILL.md: The technical system prompt instructing the agent how and when to invoke the skill.
• references/: Contextual documentation, API specs, or reference guides required by the skill.
• scripts/: Executable automation code, binaries, or helper tools that the skill triggers.

4. Runtime State

Tracks ephemeral execution data and platform alignment.

• sessions/: Stores metadata partitioned by specific platforms (e.g., Slack, Discord, Terminal).
• state.db: Embedded SQLite database utilizing FTS5 extension for ultra-fast, full-text historical search.

5. Automation

Allows the agent to execute periodic, autonomous operations without explicit user invocation.

• cron/jobs.json: Defines schedules, intervals, and target functions for background tasks.
• cron/output/: Captures execution logs and standard output so the agent can audit its own background tasks.

6. Extension

The dedicated customization surface area for advanced customization.

• plugins/: Standalone logic blocks that extend core architectural capabilities.
• hooks/: Interceptors for system lifecycle events (e.g., pre-boot, post-response).
• skins/: Custom visual definitions and styling sheets for the command-line interface.

7. Observability

Dedicated diagnostics system for error isolation, routine auditing, and debugging.

Logs are separated by subsystem (agent.log, gateway.log, errors.log) to streamline stack trace analysis.

Getting Started

To initialize this structure locally inside your environment, clone this template directly into your home directory or target path:

git clone https://github.com/KhaiTrang1995/hermes-structure.git ~/.hermes