# 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
```text
~/.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:
```bash
git clone https://github.com/KhaiTrang1995/hermes-structure.git ~/.hermes
```