Hermes Agent Architecture: Memory, Context & Gateways Explained
Hermes is a modular AI agent built on a simple loop: receive message, build context from markdown files and memory, send to LLM, execute tools, update memory. It connects via CLI, API, or a gateway system that integrates Telegram, Slack, email, and other messaging platforms. Memory combines markdown files (soul.md, user.md, memory.md), a local SQLite database of all conversations, and optional external memory providers. Context compression triggers at 50% capacity by default, and cron jobs enable scheduled automated tasks.
High-Level Architecture Overview
Core Components
Hermes consists of an AI agent core (agentic loop) that can be accessed via three entry points: CLI (command line), API, and a gateway system. The agent connects to tools, skills, and memory systems that enable it to execute tasks and learn from interactions.
Entry Points to the Agent
Users can interact with Hermes through three methods: the command-line interface (CLI), a direct API, or a gateway system that bridges messaging platforms like Telegram, Slack, and email.
The Agent Loop
Simple Iterative Loop
The agent loop is minimalist and runs identically to other simple agents like PyAgent and OpenCode. Each cycle begins when a user sends a message, then the agent builds context, sends it to the LLM, handles any tool calls, and finally updates memory with learnings.
Memory Update: Continuous Learning
After the LLM generates a response, Hermes analyzes the interaction to identify information worth remembering. This memory update step enables the agent to learn and improve over time, retaining insights for future similar queries.
Context Building
Soul.md: Agent Personality
Soul.md is a markdown file that defines the agent's personality, tone, goals, and approach. It is similar to detailed system prompts like those used by Claude. If left empty, Hermes uses a default system prompt identifying itself as a virtual assistant.
User.md: User Profile
User.md is automatically updated by Hermes whenever it learns information about the user from conversations. It stores user-provided details such as profession, projects, and preferences, allowing the agent to personalize future interactions.
Memory.md: Arbitrary Facts
Memory.md stores arbitrary learned facts, workflows, tool usage patterns, and interesting insights from conversations. Unlike user.md, it captures general knowledge rather than personal information about the user.
Context Components Sent to LLM
Every message to the LLM includes: system prompt, soul.md, user.md, memory.md, skill descriptions, tool descriptions, summaries of past conversations (if external memory is enabled), and the current message history.
Context Compression
Compression Threshold and Trigger
Hermes monitors context window usage and triggers compression when it reaches 50% capacity by default (customizable to 70% or 80% for smaller models). Compression summarizes older messages and replaces them with a condensed summary to preserve context space.
Two Compression Check Points
Hermes checks context usage at two moments: before each message (before calling the LLM) and on error (if the LLM returns a context window error). Before the first message, it estimates tokens using character count divided by 4; after the first message, it uses the LLM's actual token usage response.
Compression Prompt Structure
The compression prompt asks the LLM to summarize conversations into structured sections including: full goal, constraints, completed actions, active state, historical progress, current blocks, key decisions, resolved questions, relevant files, critical context, previous summaries, and next turns to incorporate.
Gateway System
Multi-Platform Messaging Integration
The gateway is an async.io loop that continuously listens to multiple messaging platforms (Telegram, Discord, Email, SMS, WhatsApp, Slack, etc.). Each platform requires independent configuration because they use different connection methods: webhooks, polling loops, or WebSockets.
Message History Construction
When the gateway receives a single message from a platform like Telegram, it must reconstruct the full conversation context. It queries a local SQLite database using a session identifier (e.g., 'telegram_[session_id]') to retrieve all previous messages in that conversation thread.
Session Manager and Message Handling
The gateway includes a session manager that decides how to handle multiple incoming messages. If a user sends a message while the agent is already processing, the manager can queue it, interrupt the agent (with /interrupt), or steer it (with /steer) depending on the command prefix used.
Memory Systems
Three-Layer Memory Architecture
Hermes uses three memory layers: markdown files (soul.md, user.md, memory.md) appended to every context, a local SQLite database storing full transcripts of all sessions, and optional external memory providers (Mem0, SuperMemory, Honcho) for enhanced semantic recall.
SQLite Session Storage
Every message from every conversation is stored in a local SQLite database with session identifiers that include the gateway name (e.g., 'telegram_[id]'). A separate bare text table stores only message text to enable efficient similarity searches across all conversations.
External Memory Providers
External memory systems like Mem0, SuperMemory, and Honcho are optional providers that specialize in agent memory. They use different approaches: similarity search, semantic extraction via LLM, or full conversation history analysis. Hermes queries external memory after the first message to anticipate follow-up questions.
External Memory Query Timing
External memory is queried after the first message in a conversation. After the agent responds to the initial message, it queries the external memory system to retrieve related past conversations, allowing it to provide context-aware responses on follow-up messages.
Cron Jobs
Scheduled Task Automation
Cron jobs allow users to schedule automated tasks for Hermes to execute at specific times (daily, weekly, monthly). Examples include sending daily AI news emails, posting community updates to Slack every day, or sending weekly reports to a manager.
Cron Loop and Tick Function
Hermes runs its own internal cron loop (not tied to system cron) that executes a tick function every minute. This function checks a jobs.json file for scheduled tasks due at that moment and executes them if conditions are met.
Cron Job Storage and Output
Cron jobs are stored as plain JSON in ~/.hermes/cron/jobs.json (not SQLite as documentation suggests). Each job has an ID directory in ~/.hermes/cron/output/ containing markdown files for each run, allowing users to review execution history and results.
Home Messaging Integration
Cron job notifications are sent to the user's designated home messaging platform (configured during gateway setup), not through the agent's send message tool. For example, if Telegram is set as home, all cron notifications appear there automatically.
Notable quotes
The agent loop is very straightforward. It's just a loop that runs time after time, every single time that the user sends a message. — Presenter
The gateway is what allows you to call, to talk to your agent via different messaging platforms such as Telegram, WhatsApp, email, text message, Slack. — Presenter
Memory update essentially tells the agent to analyze that message and to see if there is anything worthy of being remembered and being written into the memory. — Presenter
Action items
- Create or customize your soul.md file to define your agent's personality, tone, and goals rather than relying on the default system prompt.
- Enable external memory (Mem0, SuperMemory, or Honcho) to improve how Hermes learns and recalls information across conversations.
- Configure at least one gateway (Telegram, Slack, or Email) during setup to enable multi-platform access to your agent.
- Set up cron jobs for recurring tasks like daily news summaries or weekly reports by defining them in ~/.hermes/cron/jobs.json.
- Designate a home messaging platform during gateway configuration so cron job notifications are delivered to your preferred channel.
- Review your SQLite database periodically to understand what conversations and memory your agent has stored.
- Adjust context compression threshold (from default 50%) if using a smaller model with limited context window.