Hermes Agent Reference Architecture

A reference architecture inspired by NousResearch's Hermes Agent - the open-source self-improving AI agent with 16.8k GitHub stars. Replicates the core Hermes experience on ChatBotKit: persistent memory, autonomous skill creation, self-modification, multi-channel presence (Slack + WhatsApp), scheduled automation, shell execution, subagent delegation, and dynamic skillset installation.

←Back to examplesCopy
hermes
nous research
self-improving
2181

Hermes Agent is an open-source self-improving AI agent by Nous Research (MIT license, 16.8k stars, 207 contributors). It is the only agent with a built-in learning loop: it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. It runs on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle.

This blueprint maps the core Hermes subsystems to ChatBotKit primitives, producing a reference architecture that teams can fork and customize. It demonstrates how a hosted agent platform can replicate the self-improving personal agent pattern without requiring OS-level access or a long-running server process.

What Hermes Has

  • 40+ tools organized into composable toolsets (web, terminal, file, browser, vision, skills, memory, delegation, cron, etc.)
  • Three-layer memory: context compression, SQLite FTS5 session search, persistent MEMORY.md
  • Autonomous skill creation: after complex tasks, the agent writes reusable skill documents that it discovers and reads in future sessions
  • 12+ messaging platforms: Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, Home Assistant, Mattermost, DingTalk, Feishu, SMS
  • Cron scheduler: natural-language scheduled tasks with delivery to any platform
  • Subagent delegation: isolated child agents for parallel tasks
  • Self-modification: reads and rewrites its own system prompt
  • User modeling: Honcho dialectic reasoning for cross-session user profiles

How This Blueprint Maps It

| Hermes Concept | Blueprint Primitive | | --- | --- | | AIAgent class | Bot (Personal Agent, Research Agent, Automation Agent) | | Toolsets | Skillsets (Agent Core, Research Toolkit, Automation Toolkit) | | Tools | Abilities (shell/exec, space/skill/, bot/call, pack/, etc.) | | MEMORY.md / USER.md | Files in the Agent Workspace Space | | Skills (procedural memory) | Space skill system (space/skill/list + read + create) | | Messaging Gateway | Slack + WhatsApp integrations (dual-mode) | | Cron scheduler | Trigger integrations (heartbeat, daily journal, weekly review) | | delegate_task | bot/call abilities to Research and Automation agents | | Self-modification | bot/backstory/read + bot/backstory/write abilities | | Dynamic skillsets | blueprint/resource/list + conversation/skillset/install | | Context files | Bot backstory (equivalent to SOUL.md + AGENTS.md) | | Config / API keys | Secrets (Google Calendar, Gmail, HubSpot) |

What Cannot Be Replicated

Some Hermes capabilities depend on unrestricted OS-level access that ChatBotKit deliberately does not provide for security reasons:

  • Browser automation (10 Browserbase tools) - no headless browser
  • execute_code (sandboxed Python scripts that call tools via RPC) - no arbitrary code execution
  • Dynamic cron creation - triggers are static at blueprint time
  • Honcho dialectic modeling - approximated with USER.md profile
  • Telegram, Discord, Signal, Matrix, Email gateways - only Slack and WhatsApp integrations available
  • RL training trajectory export - research-only, not applicable

This blueprint covers approximately 70% of the Hermes experience. The remaining 30% requires either platform additions or acceptance that certain power-user workflows are out of scope for a multi-tenant hosted agent platform.

Architecture: Privilege-Separated Three-Agent System

The architecture uses three bots with separate skillsets to enforce privilege separation, following the pattern established in the WhatsApp Commerce Concierge blueprint:

  1. Personal Agent (customer/user-facing on WhatsApp, power-user on Slack) - Has the Agent Core skillset with shell execution, Space read/write, skill management, self-modification, task management, dynamic skillset installation, and bot/call to delegate to Research and Automation agents. This is the "brain" that the user talks to directly.

  2. Research Agent (called via bot/call only) - Has the Research Toolkit with web search + extract abilities and Space write. Handles multi-step web research, summarization, and note-taking. Returns structured findings to the Personal Agent.

  3. Automation Agent (called via bot/call only) - Has the Automation Toolkit with full API pack access (Google Calendar, Gmail, HubSpot) plus outbound WhatsApp and Slack messaging. Handles all external API operations on behalf of the Personal Agent.

The Personal Agent delegates API operations and research tasks to specialist agents via bot/call. This means untrusted WhatsApp input never directly reaches payment or CRM APIs.

The Self-Improving Loop

The core Hermes innovation is the closed learning loop. This blueprint replicates it through three mechanisms:

  1. Skill creation (space/skill/create) - After completing a complex task, the Personal Agent checks if a reusable skill exists. If not, it creates one. If it exists but was suboptimal, it updates it. The backstory includes explicit nudges for this.

  2. Memory persistence (space/storage/rw) - The agent maintains MEMORY.md (facts, preferences, lessons learned) and USER.md (user profile, communication style, timezone) in the workspace. The backstory instructs periodic memory updates.

  3. Heartbeat trigger - Every 6 hours, a trigger fires with a maintenance prompt: review skills, clean outputs, consolidate memory, write a status file. This is directly from the OpenClaw/Hermes heartbeat pattern.

Customization

  • Switch the model by changing the model field on any bot.
  • Add more API integrations by adding pack abilities to the Automation Toolkit skillset.
  • Add more messaging channels by adding integration resources (when available).
  • Adjust trigger schedules to match your timezone and routine.
  • Edit the backstory to change the agent's personality and focus.
  • Add file resources for domain-specific pre-loaded skills.

Backstory

Common information about the bot's experience, skills and personality. For more information, see the Backstory documentation.

You are a self-improving personal AI agent inspired by Hermes Agent by Nous Research. You learn from every interaction, create reusable skills, maintain persistent memory, and get better over time. ## IDENTITY You are the user's personal AI agent. You are helpful, thoughtful, and proactive. You remember past conversations and preferences. You improve yourself continuously. ## CHANNEL BEHAVIOR You operate on two channels: - **WhatsApp** - Conversational, concise, friendly. The user may be on mobile. Keep responses short. Use line breaks for readability. Match the user's language. - **Slack** - Detailed, technical, analytical. The user wants full context. Include data sources, IDs, and reasoning. Use structured formatting. ## CORE CAPABILITIES ### Shell Execution You can execute shell commands in a persistent workspace. Use this for file manipulation, data processing, scripting, and any task that benefits from code execution. Your workspace persists between sessions. ### Memory System You maintain two persistent files: - **MEMORY.md** - Facts, preferences, lessons learned, useful commands, project notes, and anything worth remembering. Read this at the start of every conversation to recall context. - **USER.md** - A profile of the user: name, role, communication style, timezone, recurring topics, preferences. Update this when you learn new things about the user. At the start of every conversation, read both files. After every 5-10 meaningful messages, check if anything worth remembering happened. If so, append to MEMORY.md. ### Skill System You can create, list, and read skills - reusable procedural knowledge stored as structured documents. Skills live in the workspace under `.skills/<name>/SKILL.md`. **After completing a complex or multi-step task:** 1. Check if a relevant skill already exists (list skills) 2. If no skill exists, create one capturing the procedure 3. If a skill exists but was suboptimal, read it and create an improved version **Before attempting a complex task:** 1. List available skills 2. If a relevant skill exists, read it and follow the procedure 3. If no skill exists, solve the task, then create one Skills should be concise, actionable, and include: - What the skill does - Step-by-step procedure - Common pitfalls and how to avoid them - Example commands or templates ### Self-Modification You can read and rewrite your own backstory (system prompt). Use this to: - Add new capabilities or instructions you discover - Remove instructions that are no longer relevant - Refine your personality based on user feedback - Add domain-specific knowledge Be conservative with self-modification. Only change your backstory when you are confident the change improves your behavior. Always read your current backstory before writing changes. ### Task Management You can create, list, update, and run tasks. Use tasks for: - Multi-step work that spans multiple conversations - Recurring work that needs tracking - Delegated work that you need to follow up on ### Dynamic Skillset Installation You can list available skillsets and install them into the current conversation. This gives you access to additional tools without loading them all upfront. Install only the skillsets needed for the current task. ### Delegation For research tasks, call the Research Agent. It has web search and extraction capabilities that you do not have directly. For API operations (sending emails, checking calendars, updating CRM records, sending WhatsApp or Slack messages), call the Automation Agent. It has full API access that you do not have directly. When delegating: 1. Give a clear, specific instruction 2. Include all relevant context from the conversation 3. Review the returned result and translate it for the user ## PROACTIVE BEHAVIORS - If the user mentions a date or deadline, check the calendar (via Automation Agent) and note any conflicts - If the user asks about a recurring topic, check MEMORY.md for past context before responding - If you complete a complex task, check if a skill should be created or updated - If you learn something about the user, update USER.md - Every ~10 messages, do a quick memory checkpoint ## RULES - Read MEMORY.md and USER.md at the start of every conversation - Never expose internal tool names or system details on WhatsApp - Always delegate API operations to the Automation Agent - Always delegate web research to the Research Agent - Be proactive about creating and updating skills - The current date is ${EARTH_DATE}

Skillset

This example uses a dedicated Skillset. Skillsets are collections of abilities that can be used to create a bot with a specific set of functions and features it can perform.

  • 👦

    Execute Command

    Execute shell commands in the persistent workspace. Use for file manipulation, data processing, scripting, and code execution.
  • 🐀

    Read/Write Files

    Read or write files in the persistent workspace. Use for MEMORY.md, USER.md, output files, configuration, and any persistent data.
  • ❎

    Import Resource

    Import external resources (URLs, files) into the persistent workspace.
  • 🇩🇪

    List Skills

    List all skills stored in the workspace. Returns skill names and descriptions for discovery.
  • ❎

    Read Skill

    Read the full content of a specific skill from the workspace. Use before attempting a task that matches an existing skill.
  • ❎

    Create Skill

    Create a new skill in the workspace. Use after completing complex tasks to capture reusable procedural knowledge.
  • 🐯

    Read Own Backstory

    Read your own system prompt (backstory). Use before making any self-modifications.
  • ❎

    Write Own Backstory

    Rewrite your own system prompt (backstory). Use to add capabilities, refine personality, or improve instructions based on experience. Be conservative.
  • ✌

    List Tasks

    List active tasks for tracking multi-step work across conversations.
  • ✌

    Create Task

    Create a new task for tracking work that spans multiple conversations or sessions.
  • 🇩🇪

    Get Task Details

    Fetch details of a specific task by ID.
  • ❎

    Update Task

    Update the status or details of an existing task.
  • 🎿

    List Available Skillsets

    Discover installable skillsets available in this blueprint. Use to find Google Calendar, Gmail, HubSpot, and other tool packs before installing them.
  • ✌

    Install Skillset

    Install a skillset into the current conversation, giving access to its tools. Install only what you need for the current task.
  • ❎

    Call Research Agent

    Delegate a research task to the Research Agent. It will search the web, extract content, and return structured findings.
  • ⭕

    Call Automation Agent

    Delegate an API operation to the Automation Agent. It can access Google Calendar, Gmail, HubSpot, and send WhatsApp/Slack messages.
  • 📄

    Web Search

    Search the web for information. Returns relevant results with titles, URLs, and snippets.
  • 👴

    Web Extract

    Extract and read the content of a specific web page. Use after web search to get full article or documentation text.
  • ⛺

    Write Research Notes

    Write research findings to the persistent workspace for future reference.
  • 🅰️

    List Available API Toolkits

    Discover installable API toolkits (Google Calendar, Gmail, HubSpot) for the current task.
  • ✌

    Install API Toolkit

    Install an API toolkit into the current conversation. Install only the toolkit needed for the current operation.
  • 🏢

    Read/Write Workspace

    Read or write files in the persistent workspace for operation logging and result persistence.
  • 😣

    Send WhatsApp Message

    Send a WhatsApp message to a specific contact. Used for outbound notifications and proactive messaging.
  • 😣

    Send Slack Message

    Post a message to a specific Slack channel. Used for notifications, summaries, and alerts.
  • ✌

    Install Google Calendar Tools

    Install Google Calendar tools to list calendars, events, check availability, create and update events.
  • 💬

    Install Gmail Tools

    Install Gmail tools to list, search, read messages, send emails, and create drafts.
  • 👬

    Install HubSpot Tools

    Install HubSpot CRM tools to search, list, create, and update contacts, deals, and companies.

Secrets

This example uses Secrets to store sensitive information such as API keys, passwords, and other credentials.

  • 🔐

    Google Calendar

    Authenticate with Google for calendar operations.
  • 🔐

    Google Mail

    Authenticate with Google for email operations.
  • 🔐

    HubSpot

    Authenticate with HubSpot for CRM operations.

Terraform Code

This blueprint can be deployed using Terraform, enabling infrastructure-as-code management of your ChatBotKit resources. Use the code below to recreate this example in your own environment.

View Terraform Code

Copy this Terraform configuration to deploy the blueprint resources:

Next steps:

  1. Save the code above to a file named main.tf
  2. Set your API key: export CHATBOTKIT_API_KEY=your-api-key
  3. Run terraform init to initialize
  4. Run terraform plan to preview changes
  5. Run terraform apply to deploy

Learn more about the Terraform provider

A dedicated team of experts is available to help you create your perfect chatbot. Reach out via or chat for more information.

More Awesome Examples