# 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
```
