1. WHAT IS AGENTIC AI, AND WHY SHOULD YOU CARE?Before we talk about Hermes Agent specifically, we need to lay some groundwork. You have probably used a chatbot before. You type a question, it gives you an answer, and that is the end of the story. The chatbot does not remember you the next day. It does not learn from your preferences. It does not go off and do things on your behalf while you sleep. It just sits there, waiting for your next question, like a very knowledgeable but entirely passive encyclopedia. Agentic AI is a completely different beast. The word "agentic" comes from "agent," meaning something that acts. An agentic AI system does not just respond to your questions. It plans, it decides, it executes actions in the real world, it checks its own results, and it adapts based on what it finds. Think of the difference between asking a colleague "how do I send a report?" versus handing a task to a colleague and saying "please prepare and send the weekly report every Friday." The first is a chatbot. The second is an agent. Agentic AI systems can use tools, meaning they can browse the web, write and run code, read and write files, send messages, call APIs, and much more. They can break a big goal into smaller steps and work through those steps one by one, checking their progress along the way. They can even spawn other agents to help them with sub-tasks, much like a manager delegating work to a team. The field of Agentic AI has exploded in 2025 and 2026, and several powerful open-source systems have emerged. One of the most exciting and technically sophisticated among them is Hermes Agent, built by Nous Research. It is the subject of this entire tutorial, and by the end, you will understand not just what it is, but how it works under the hood, why it is special, and how it compares to its closest competitor, OpenClaw.
2. WHAT IS HERMES AGENT?Hermes Agent is an open-source, self-improving agentic AI system developed by Nous Research and released in February 2026. It is written primarily in Python and is available under the permissive MIT license, meaning you can use it, modify it, and build on top of it freely. The name "Hermes" is well chosen. In Greek mythology, Hermes was the messenger of the gods, associated with speed, intelligence, communication, and the ability to move between worlds. Hermes Agent embodies all of these qualities. It communicates across platforms, it reasons intelligently, it moves between your local machine and cloud environments, and it does all of this at remarkable speed. But the most important thing about Hermes Agent is captured in one phrase: it gets smarter the more you use it. Unlike a traditional chatbot or even a simple agentic tool, Hermes Agent has a built-in learning loop. Every time it successfully completes a complex task, it analyzes what it did, writes down the key steps as a reusable "Skill," and stores that knowledge permanently. The next time you ask it to do something similar, it already knows how. This is not a metaphor. The agent literally writes its own procedural documentation and uses it in future sessions. Hermes Agent is designed to feel less like a tool and more like a persistent employee. It remembers your name, your preferences, your ongoing projects, and the quirks of your working environment. It can run scheduled tasks while you sleep. It can manage your messages across Telegram, Discord, Slack, WhatsApp, and Signal. It can write and execute code, search the web, manipulate files, and automate complex workflows, all with minimal supervision. To give you a concrete sense of scale: Hermes Agent ships with over 40 built-in tools out of the box. It supports more than 200 AI models through integrations with OpenRouter, OpenAI, Anthropic, Google, and local Ollama instances. It runs on Linux, macOS, Windows (via WSL2), and even Android via Termux. And it does all of this while storing your data locally, with zero telemetry and no data sent back to any company without your explicit consent. This is not a toy. This is a serious piece of infrastructure for personal and professional automation.
3. THE ARCHITECTURE OF HERMES AGENTTo truly understand Hermes Agent, you need to understand its architecture. The system is built around five core pillars, each of which plays a distinct and essential role. These pillars are Memory, Skills, Soul, Crons, and Self-Improvement. Surrounding all of them is the Agent Loop Engine, which is the beating heart of the system, the orchestration mechanism that ties everything together. Let us walk through each component in depth.
3.1 THE AGENT LOOP ENGINEAt the very center of Hermes Agent is the Agent Loop Engine. This is the component that makes the agent actually do things, as opposed to just saying things. The engine is implemented in a class called AIAgent, which lives in a file called run_agent.py. The Agent Loop Engine works like this: you give the agent a goal or a task. The engine assembles a prompt by combining your request with the agent's memory, its soul definition, its available skills, and its tool descriptions. It then sends this assembled prompt to the language model of your choice. The model responds, and the response might be a direct answer, or it might be a request to use one of the agent's tools, for example, "I need to search the web for this information" or "I need to run this Python script." If the model requests a tool, the engine executes that tool, captures the result, and feeds the result back into the conversation as a new message. The model then processes the tool result and either produces another tool call or generates a final answer. This cycle continues, turn by turn, until the task is complete. Each full cycle is called an iteration. Here is a simplified conceptual illustration of the loop: +------------------+ | User Request | +------------------+ | v +------------------+ | Prompt Assembly | <-- Memory + Soul + Skills + Tools +------------------+ | v +------------------+ | Language Model | +------------------+ | +-------+-------+ | | v v [Tool Call] [Final Answer] | | v | [Execute Tool] | | | +-------+-------+ | v +------------------+ | Save to SQLite | <-- Session persistence after every turn +------------------+ | v +------------------+ | Reflective Phase | <-- Self-improvement after task completion +------------------+ The engine is described as a stateless dispatcher, which is an important architectural concept. This means that the engine itself does not hold state in memory between turns. Instead, all persistent state, meaning the full conversation history, memory changes, and skill updates, is stored in an append-only log on disk, backed by SQLite by default, or PostgreSQL for higher-durability production deployments. Each step of the agent is a pure function: it takes the current state and an action as inputs, and it produces a new state and a set of side effects as outputs. This design makes the system highly reliable and easy to debug. To prevent the agent from running forever on a task and consuming unlimited resources, the engine uses an Iteration Budget. By default, each agent is allowed a maximum of 50 iterations per task. As the agent approaches this limit, the engine injects warning messages into the conversation, first a gentle caution at 70% of the budget consumed, then a more urgent warning at 90%. This gives the language model a chance to wrap up gracefully rather than being cut off mid-task. Subagents, which we will discuss later, have their own independent iteration budgets. The engine also supports provider failover, meaning that if your primary language model provider is unavailable or returns an error, the engine can automatically switch to a fallback model without interrupting the task. This makes Hermes Agent remarkably robust in production environments.
3.2 MEMORY: THE AGENT THAT NEVER FORGETSOne of the most frustrating things about traditional chatbots is that they forget everything the moment a session ends. You explain your project, your preferences, your constraints, and then tomorrow you have to explain it all again from scratch. Hermes Agent solves this problem with a sophisticated, multi-layered memory system. The memory system is built around two primary files that live in your home directory under ~/.hermes/. The first is MEMORY.md, which stores environmental facts, learned workflows, lessons from past mistakes, and general knowledge about your projects and working context. The second is USER.md, which stores a profile of you as a user: your name, your communication style, your timezone, your preferences, and anything else the agent has learned about how you like to work. At the start of every new session, both files are loaded and injected into the system prompt as a frozen snapshot. This means the agent begins every conversation already knowing who you are and what you have been working on. It is a bit like starting a meeting with a colleague who has read all the previous meeting notes before walking in the door. The agent manages its own memory using a built-in memory tool. When it learns something worth remembering, it calls this tool with an "add" action to write a new entry. When an existing entry becomes outdated, it uses a "replace" action to update it. When something is no longer relevant, it uses a "remove" action to clean it up. Character limits on the memory files ensure that the agent does not simply accumulate noise indefinitely; when the memory is full, the agent must consolidate or replace entries, keeping the most important information and discarding the rest. For users who need even more powerful memory capabilities, Hermes Agent supports external memory provider plugins. These include systems like Honcho, Hindsight, and Mem0, which can add capabilities such as knowledge graphs, semantic search across past conversations, and automatic fact extraction. These plugins slot into the memory architecture cleanly, without requiring changes to the core agent code. Here is a simplified example of what a MEMORY.md file might look like after a few weeks of use: ## Environment - OS: Ubuntu 22.04, Python 3.12, GPU: NVIDIA RTX 4090 - Primary editor: VS Code with Vim keybindings - Project root: ~/projects/siemens-automation/ ## Workflows - To run the test suite: cd ~/projects/siemens-automation && pytest -v - To deploy to staging: ./scripts/deploy.sh --env staging - Database migrations must always be run before deploying new code ## Lessons Learned - The API rate limit for the external data service is 100 req/min. Always add a 0.6s sleep between batch requests to avoid 429 errors. - The legacy CSV export tool crashes on files larger than 500MB. Use the streaming variant in tools/stream_export.py instead. ## Active Projects - Automating the weekly KPI report for the Berlin office (in progress) - Migrating the legacy sensor data pipeline to the new cloud stack This kind of persistent, structured memory is what allows Hermes Agent to function as a genuine long-term assistant rather than a stateless question- answering machine.
3.3 SKILLS: THE AGENT'S PROCEDURAL MEMORYIf Memory is the agent's declarative knowledge, meaning facts about the world and about you, then Skills are its procedural knowledge, meaning knowledge of how to do things. Skills are the most architecturally distinctive feature of Hermes Agent, and they are central to its self-improvement capability. A Skill in Hermes Agent is a Markdown file with YAML frontmatter, stored in the ~/.hermes/skills/ directory. Each skill describes a specific workflow or capability in natural language, and the agent reads these skill files and uses them as instructions when performing related tasks. Skills can also include an optional scripts/ subdirectory containing helper Python scripts that the agent can execute as part of the workflow. Here is an example of what a skill file might look like. This one teaches the agent how to generate a weekly summary report from a set of log files: --- name: weekly-log-summary description: > Generates a formatted weekly summary report from application log files. Extracts error counts, warning counts, and key events, then formats the result as a Markdown report and saves it to the reports/ directory. version: 1.2.0 author: hermes-agent (auto-generated) license: MIT platforms: - linux - macos requires_tools: - terminal - file_read - file_write --- ## Weekly Log Summary Skill ### Steps 1. Identify the log directory. Default is ~/logs/. Ask the user if unclear. 2. Find all .log files modified in the last 7 days using the terminal tool. 3. For each log file, count ERROR and WARNING occurrences using grep. 4. Extract the 10 most recent ERROR lines from each file for context. 5. Compile the results into a Markdown report with the following sections: - Summary table (file name, error count, warning count) - Top errors section with representative error messages - Recommendations section based on error patterns 6. Save the report to ~/reports/weekly-YYYY-MM-DD.md using today's date. 7. Confirm the report location to the user. ### Notes - If a log file is larger than 200MB, use tail -n 50000 to limit processing. - Always check that the reports/ directory exists before writing. Notice how the skill is written in plain language, not code. The agent reads this skill and uses it as a guide when performing the task. The skill captures the institutional knowledge of how to do the job correctly, including edge cases and gotchas that the agent has learned from experience. Skills are loaded using a technique called Progressive Disclosure. When the agent starts a session, it sees only the name and description of each skill, not the full content. This keeps the initial system prompt small and efficient. When the agent determines that a particular skill is relevant to the current task, it loads the full skill content into its context. This design keeps token costs low while still making the full library of skills available. Hermes Agent ships with a substantial library of built-in skills covering common tasks like web research, code generation, file management, and API integration. Users can also install community-contributed skills from the Hermes skill hub using a simple command. And, most importantly, the agent creates new skills automatically, which brings us to the next pillar.
3.4 SOUL: THE AGENT'S IDENTITYThe Soul pillar is perhaps the most philosophically interesting component of Hermes Agent. It is implemented as a file called SOUL.md, which lives at ~/.hermes/SOUL.md and is loaded as the very first element of the system prompt at the start of every session. The SOUL.md file defines the agent's personality, its tone, its communication style, and its hard limits. It is hand-authored by the user, meaning you write it yourself to define the kind of assistant you want. You might specify that the agent should be concise and technical, or warm and explanatory, or formal and precise. You might specify that it should never take irreversible actions without explicit confirmation, or that it should always explain its reasoning before acting. Unlike the MEMORY.md and USER.md files, which the agent updates automatically, the SOUL.md file is static. The agent does not modify it. It is the foundation of the agent's identity, and it remains constant across all sessions. Every piece of user feedback and every learned preference gets encoded into the memory files, but the core personality defined in SOUL.md never changes unless you change it yourself. A simple SOUL.md file might look like this: # Agent Soul You are a highly capable, reliable, and honest AI assistant. ## Personality You are direct, precise, and technically sophisticated. You prefer concise answers over verbose ones. You explain your reasoning when it is non-obvious, but you do not over-explain simple things. ## Hard Limits - Never delete files without explicit confirmation from the user. - Never send messages or emails without showing the draft first. - Never make purchases or financial transactions of any kind. - Always ask for clarification when a task is ambiguous. ## Communication Style Use plain language. Avoid jargon unless the user has demonstrated familiarity with technical concepts. When in doubt, explain. The Soul pillar is what gives Hermes Agent its consistent character. No matter which language model is powering the agent on a given day, no matter which tools are being used, the soul definition ensures that the agent behaves in a way that is predictable, trustworthy, and aligned with your expectations.
3.5 CRONS: THE AGENT THAT WORKS WHILE YOU SLEEPThe Crons pillar gives Hermes Agent the ability to be proactive. Rather than waiting passively for you to give it a task, the agent can be configured to perform tasks automatically on a schedule, without any human intervention. Crons in Hermes Agent work similarly to traditional Unix cron jobs, but with a crucial difference: you can create them using natural language. Instead of writing a cryptic cron expression like "0 8 * * 1", you can simply tell the agent "send me a summary of my open tasks every Monday morning at 8 AM." The agent will create both a skill to perform the task and a cron job to run it on schedule. When a cron job fires, the agent spins up a fresh, isolated session to execute the relevant skill. This isolation is important for safety: cron sessions are prevented from creating new cron jobs themselves, which prevents runaway automation scenarios where the agent accidentally schedules an exponentially growing number of tasks. The results of the cron session are delivered back to you through your configured messaging channel, whether that is Telegram, Discord, Slack, or another platform. Here is a conceptual example of how you might set up a cron job through the Hermes Agent CLI: $ hermes chat You: Every weekday at 7 AM, check my project's GitHub repository for any new pull requests opened in the last 24 hours and send me a summary via Telegram. Hermes: I will create a skill and a scheduled job for that. Here is what I am planning: Skill: github-pr-daily-summary Schedule: 0 7 * * 1-5 (weekdays at 07:00) Delivery: Telegram The skill will: 1. Query the GitHub API for PRs opened in the last 24 hours 2. Format a summary with PR title, author, and link 3. Send the summary to your Telegram Shall I proceed? You: Yes, go ahead. Hermes: Done. The job is scheduled. You will receive your first summary tomorrow morning at 7 AM. This kind of proactive, scheduled automation is what transforms Hermes Agent from a reactive tool into a genuine autonomous assistant.
3.6 SELF-IMPROVEMENT: THE LEARNING LOOPThe Self-Improvement pillar is the crown jewel of Hermes Agent's architecture. It is the mechanism by which the agent gets better over time, and it is what most fundamentally distinguishes Hermes Agent from every other agentic AI system currently available. The self-improvement loop works in three phases. The first phase is execution: the agent performs a task, using its tools, memory, and existing skills. The second phase is reflection: after completing the task, the agent enters a Reflective Phase in which it analyzes what it did, identifies the key steps, and evaluates whether the workflow was efficient and correct. The third phase is codification: if the agent determines that the workflow is worth remembering, it writes a new skill file capturing the steps, or it updates an existing skill file to incorporate what it learned. Skill creation is triggered automatically under specific conditions. These conditions include completing a complex task that required five or more tool calls, encountering an error and discovering a working solution, being corrected by the user and finding a better approach, and discovering a non-trivial workflow that is likely to be repeated. The agent does not create a skill for every single task, only for those that represent genuine, reusable procedural knowledge. Beyond the basic learning loop, Hermes Agent includes an advanced optimization engine called GEPA, which stands for Genetic-Pareto Prompt Evolution. GEPA is an offline optimization pipeline that takes the self-improvement concept to a much deeper level. Rather than simply recording what the agent did, GEPA analyzes execution traces to understand why tasks failed. It then proposes targeted improvements through an evolutionary search process: it mutates the text of skills, prompts, tool descriptions, and configurations, evaluates the results of those mutations, and selects the best-performing variants. The name "Genetic-Pareto" refers to the two key mechanisms at work. The "Genetic" part refers to the evolutionary search strategy, which is inspired by genetic algorithms: variants are mutated, evaluated, and selected in a process analogous to natural selection. The "Pareto" part refers to the optimization criterion, which seeks variants that are optimal across multiple dimensions simultaneously, for example, maximizing task success rate while minimizing token cost. GEPA is remarkable for several reasons. It does not require GPU training, meaning it operates entirely through API calls to the language model. A full optimization run typically costs between two and ten US dollars. And it has been shown to outperform reinforcement learning approaches and previous prompt optimization tools, even when given as few as three examples to learn from. Every evolved variant must pass a full test suite, adhere to size limits, maintain caching compatibility, preserve semantic meaning, and undergo human review before being deployed. This ensures that the self-improvement process is safe and auditable. The combination of the basic learning loop and GEPA means that Hermes Agent does not just remember how to do things. It actively optimizes how it does things, becoming measurably more capable and efficient with each cycle.
4. HOW TO INSTALL AND USE HERMES AGENTNow that you understand the architecture, let us get practical. Installing Hermes Agent is straightforward. The system requires Python 3.11 or higher, at least 4 GB of RAM (8 GB or more is recommended), and an API key from at least one language model provider such as OpenRouter, OpenAI, or Anthropic. If you want to run models locally, you will also need Ollama installed and a GPU with at least 8 GB of VRAM. The simplest way to install Hermes Agent on Linux, macOS, or WSL2 is with the one-line installer: curl -fsSL \ https://raw.githubusercontent.com/NousResearch/hermes-agent/main/\ scripts/install.sh | bash The installer automatically detects your operating system, installs all required dependencies including Node.js, Git, ripgrep, and ffmpeg, and launches a setup wizard that guides you through choosing and configuring your preferred language model provider. The entire process typically takes between five and fifteen minutes on a standard internet connection. For Windows users who are not yet using WSL2, there is an early-beta PowerShell installer available as well, though the WSL2 path is currently more stable and better supported. If you prefer a containerized deployment, for example on a VPS or a cloud server, Docker is the recommended approach. The process involves three steps. First, clone the repository. Second, configure your environment variables. Third, start the container. # Step 1: Clone the repository to your local machine or server git clone https://github.com/NousResearch/hermes-agent.git cd hermes-agent # Step 2: Copy the example environment file and fill in your values. # At minimum, you need to provide your LLM provider API key. cp .env.example .env # Now open .env in your editor and add your API keys and configuration. # Step 3: Build the Docker image and start the container in detached mode. # The --build flag ensures you always start with the latest code. docker compose up -d --build Once installed, you can start an interactive session with the agent simply by running the hermes command in your terminal: $ hermes chat This opens a full Text User Interface (TUI) in your terminal, where you can type messages to the agent and see its responses, tool calls, and reasoning in real time. The TUI also shows you the current iteration count, the memory usage, and the active model, giving you full visibility into what the agent is doing at every step.
4.1 YOUR FIRST CONVERSATION WITH HERMES AGENTLet us walk through a realistic first conversation to illustrate how the agent works in practice. Imagine you are a data analyst who wants to automate a weekly reporting task. $ hermes chat Hermes: Hello! I am Hermes. I am ready to help. What would you like to work on today? You: I have a folder of CSV files at ~/data/sales/ that gets updated every week. Each file contains daily sales data for one region. I want you to write a Python script that reads all the CSV files, calculates the total sales per region for the current week, and outputs a summary table. Hermes: Understood. Let me start by examining the structure of your CSV files so I can write the script correctly. [Tool: file_list] Listing files in ~/data/sales/ Found: north_europe.csv, south_europe.csv, americas.csv, asia_pacific.csv, middle_east.csv [Tool: file_read] Reading first 5 rows of north_europe.csv date,region,product,units_sold,revenue_eur 2026-05-12,North Europe,Widget A,142,7100.00 2026-05-12,North Europe,Widget B,89,4450.00 ... The structure is clear. Each file has a date column, a region column, and a revenue_eur column. I will write a script that filters for the current ISO week, aggregates by region, and prints a formatted summary table. [Tool: file_write] Writing ~/scripts/weekly_sales_summary.py The agent then writes the script. Let us look at what it produces, because this is a good example of the kind of clean, well-documented code that Hermes Agent generates: ```python #!/usr/bin/env python3 """ weekly_sales_summary.py Reads all CSV files from the ~/data/sales/ directory, filters rows belonging to the current ISO week, and prints a formatted summary table showing total revenue per region. Generated by Hermes Agent | Nous Research """ import csv import os from datetime import date, datetime from pathlib import Path def get_current_iso_week() -> tuple[int, int]: """Return the current (year, ISO week number) as a tuple.""" today = date.today() iso_cal = today.isocalendar() return iso_cal.year, iso_cal.week def load_sales_data(sales_dir: Path) -> list[dict]: """ Load all CSV files from the given directory into a list of row dicts. Args: sales_dir: Path to the directory containing sales CSV files. Returns: A flat list of row dictionaries from all CSV files combined. """ all_rows = [] for csv_file in sorted(sales_dir.glob("*.csv")): with open(csv_file, newline="", encoding="utf-8") as f: reader = csv.DictReader(f) for row in reader: all_rows.append(row) return all_rows def filter_by_week( rows: list[dict], year: int, week: int ) -> list[dict]: """ Filter rows to only those belonging to the specified ISO week. Args: rows: Full list of row dicts loaded from CSV files. year: The ISO year to filter by. week: The ISO week number to filter by. Returns: A filtered list containing only rows from the target week. """ filtered = [] for row in rows: try: row_date = datetime.strptime(row["date"], "%Y-%m-%d").date() row_iso = row_date.isocalendar() if row_iso.year == year and row_iso.week == week: filtered.append(row) except (ValueError, KeyError): # Skip rows with missing or malformed date fields. continue return filtered def aggregate_by_region(rows: list[dict]) -> dict[str, float]: """ Sum total revenue per region from the given rows. Args: rows: Filtered list of row dicts for the target week. Returns: A dict mapping region name to total revenue in EUR. """ totals: dict[str, float] = {} for row in rows: region = row.get("region", "Unknown") try: revenue = float(row.get("revenue_eur", 0)) except ValueError: revenue = 0.0 totals[region] = totals.get(region, 0.0) + revenue return totals def print_summary_table( totals: dict[str, float], year: int, week: int ) -> None: """ Print a formatted ASCII summary table to stdout. Args: totals: Dict mapping region to total revenue. year: ISO year of the report. week: ISO week number of the report. """ print(f"\nWeekly Sales Summary | Year {year}, Week {week:02d}") print("=" * 45) print(f" {'Region':<25} {'Revenue (EUR)':>15}") print("-" * 45) grand_total = 0.0 for region, revenue in sorted(totals.items()): print(f" {region:<25} {revenue:>15,.2f}") grand_total += revenue print("-" * 45) print(f" {'TOTAL':<25} {grand_total:>15,.2f}") print("=" * 45) print() def main() -> None: """Main entry point: load, filter, aggregate, and display.""" sales_dir = Path.home() / "data" / "sales" if not sales_dir.exists(): print(f"Error: Sales directory not found at {sales_dir}") return year, week = get_current_iso_week() all_rows = load_sales_data(sales_dir) weekly_rows = filter_by_week(all_rows, year, week) if not weekly_rows: print(f"No data found for Year {year}, Week {week:02d}.") return totals = aggregate_by_region(weekly_rows) print_summary_table(totals, year, week) if __name__ == "__main__": main()
After writing the script, the agent does not stop there. It immediately runs the script to verify that it works correctly, shows you the output, and then enters its Reflective Phase. Because this task involved multiple tool calls (listing files, reading a file, writing a script, running the script), it meets the threshold for skill creation. The agent writes a new skill called "csv-weekly-aggregation" to its skills directory, capturing the workflow for future use. The next time you ask it to do something similar with a different dataset, it will already know the pattern.
This is the self-improvement loop in action. You did not have to ask the agent to remember this. It did it automatically, because it recognized that the workflow was non-trivial and worth preserving.
4.2 WORKING WITH SUBAGENTS
One of the most powerful features of Hermes Agent is its ability to spawn subagents for parallel or complex workstreams. A subagent is a short-lived, isolated child agent that the parent agent creates to handle a specific sub-task. Each subagent has its own conversation history, its own terminal session, and its own toolset. When the subagent finishes its work, only its final summary is returned to the parent agent's context, keeping the parent's conversation clean and focused.
Subagents are particularly useful for tasks that would otherwise flood the parent agent's context window with irrelevant details, for tasks that require a fresh perspective uncontaminated by the parent's prior reasoning, and for tasks that can be executed in parallel to save time.
Here is a conceptual Python example showing how you might use Hermes Agent's Python API to orchestrate a parent agent that spawns subagents for a research task:
#!/usr/bin/env python3
"""
parallel_research.py
Demonstrates how to use the Hermes Agent Python API to run a parent
agent that delegates research sub-tasks to isolated subagents and
then synthesizes their results into a final report.
"""
from hermes_agent import AIAgent
def run_subagent_research(topic: str) -> str:
"""
Spawn an isolated subagent to research a specific topic.
The subagent has no knowledge of the parent conversation.
It receives only a focused task description and returns
a concise summary of its findings.
Args:
topic: The specific topic for the subagent to research.
Returns:
A string containing the subagent's research summary.
"""
# quiet_mode=True suppresses CLI output when running programmatically.
# skip_memory=True prevents this stateless subagent from reading or
# writing the persistent memory files, keeping it truly isolated.
subagent = AIAgent(quiet_mode=True, skip_memory=True)
prompt = (
f"Research the following topic thoroughly using web search "
f"and any other available tools. Provide a concise, factual "
f"summary of your findings in 3-5 paragraphs.\n\n"
f"Topic: {topic}"
)
result = subagent.chat(prompt)
return result
def synthesize_report(
topic_results: dict[str, str],
report_title: str
) -> str:
"""
Use a parent agent to synthesize subagent research into a report.
Args:
topic_results: Dict mapping topic name to research summary.
report_title: Title for the final synthesized report.
Returns:
The synthesized report as a string.
"""
# The parent agent uses persistent memory and its full skill set.
parent_agent = AIAgent(quiet_mode=True)
# Build a synthesis prompt that includes all subagent findings.
sections = "\n\n".join(
f"=== {topic} ===\n{summary}"
for topic, summary in topic_results.items()
)
synthesis_prompt = (
f"You have received research summaries on several related topics. "
f"Synthesize them into a coherent, well-structured report titled "
f"'{report_title}'. Identify common themes, highlight key insights, "
f"and note any contradictions or gaps in the research.\n\n"
f"{sections}"
)
return parent_agent.chat(synthesis_prompt)
def main() -> None:
"""
Orchestrate parallel research across multiple topics and synthesize
the results into a unified report.
"""
research_topics = [
"Current state of agentic AI frameworks in 2026",
"Self-improving AI systems and their safety implications",
"Open-source vs proprietary AI agents: a comparison",
]
print("Launching research subagents...")
topic_results = {}
# In a production system, these could be run in parallel using
# concurrent.futures.ThreadPoolExecutor for better performance.
for topic in research_topics:
print(f" Researching: {topic}")
topic_results[topic] = run_subagent_research(topic)
print(f" Done: {topic}")
print("\nSynthesizing results with parent agent...")
report = synthesize_report(
topic_results,
report_title="The State of Agentic AI in 2026"
)
print("\n" + "=" * 60)
print(report)
print("=" * 60)
if __name__ == "__main__":
main()
This example illustrates the clean separation between the parent agent, which holds the overall context and synthesizes the final result, and the subagents, which are focused, isolated workers that do not contaminate each other's reasoning. The parent never sees the raw tool calls and intermediate steps of the subagents. It only sees their final summaries. This keeps the parent's context window lean and its reasoning sharp.
The comment about ThreadPoolExecutor is worth noting. In a real production deployment, you would run the subagents in parallel threads or processes to dramatically reduce the total time required. Hermes Agent's stateless, append-only architecture makes this safe to do, because each subagent writes to its own isolated session store and does not interfere with others.
4.3 CONFIGURING TOOLS AND CONNECTING TO MESSAGING PLATFORMS
Hermes Agent's tool configuration is managed through a central config.yaml file, which is the single source of truth for all non-secret configuration. You can edit this file directly or use the hermes config command-line interface.
To enable only a specific subset of tools, for example if you want a minimal agent that can only search the web and read files, you would configure the enabled_toolsets key. To disable specific capabilities while keeping everything else, you would use disabled_toolsets. Here is an example of what a minimal config.yaml might look like:
# config.yaml - Hermes Agent Configuration
# Manages all non-secret settings. API keys go in .env, not here.
# The default model to use. Can be overridden per-session with
# the 'hermes model' command.
default_model: openrouter/nous/hermes-3-405b
# Maximum number of iterations per task before the agent wraps up.
max_iterations: 50
# Restrict the agent to only these tool categories.
# Remove this key to enable all available toolsets.
enabled_toolsets:
- web_search
- file_operations
- terminal
# The execution environment for terminal commands.
# Use 'docker' for sandboxed execution (recommended for production).
# Use 'local' for direct execution on your machine.
terminal_backend: docker
Connecting Hermes Agent to a messaging platform like Telegram is a common and very useful configuration. Once connected, you can interact with your agent from your phone, from anywhere in the world, without needing to open a terminal. The setup process involves four steps.
First, create a new Telegram bot by messaging @BotFather in Telegram and following its instructions. BotFather will give you a bot token, which is a long string that looks something like 7234567890:AAHdqTcvCH1vGWJxfSeofSs.
Second, find your personal Telegram user ID by messaging @userinfobot in Telegram. It will reply with your numeric user ID.
Third, add both values to your .env file:
# .env - Secret configuration. Never commit this file to version control.
OPENROUTER_API_KEY=sk-or-...your-key-here...
TELEGRAM_BOT_TOKEN=7234567890:AAHdqTcvCH1vGWJxfSeofSs
TELEGRAM_ALLOWED_USERS=123456789
Fourth, start the Hermes Gateway process, which is the component that bridges your messaging platforms to the agent:
$ hermes gateway start
After that, you can send a message to your Telegram bot and Hermes Agent will respond, with full access to all its tools, memory, and skills, directly from your phone. You can ask it to run scripts, search the web, check your files, or execute any other task, all from a simple chat interface.
5. HERMES AGENT vs. OPENCLAW
Now that you have a thorough understanding of Hermes Agent, it is time to compare it with its closest open-source competitor: OpenClaw. Both systems are agentic AI platforms that run locally, connect to messaging platforms, and can execute complex multi-step tasks. But they have fundamentally different philosophies, architectures, and strengths.
Understanding the differences will help you choose the right tool for your specific situation.
5.1 PHILOSOPHY AND FOCUS
The most fundamental difference between Hermes Agent and OpenClaw is their core philosophy. Hermes Agent is built around the idea of depth: one agent that gets progressively better at your specific workflows over time. Its entire architecture, from the learning loop to GEPA to the skill system, is oriented toward making a single agent more capable and more personalized with each passing week.
OpenClaw, by contrast, is built around the idea of breadth: a control-plane- first gateway that orchestrates multiple agents across multiple channels simultaneously. Its architecture is organized around connecting your AI to as many services and platforms as possible, as quickly as possible. Where Hermes Agent asks "how can this agent get smarter?", OpenClaw asks "how can this agent reach more places?"
Neither philosophy is wrong. They are simply optimized for different use cases. If you want one agent that deeply understands your work and improves over time, Hermes Agent is the right choice. If you want an agent that can quickly coordinate across many channels and integrate with a large ecosystem of pre-built skills, OpenClaw may serve you better.
5.2 ARCHITECTURE COMPARISON
The architectural differences between the two systems are significant and worth examining in detail.
Hermes Agent centers on a single agent's execution loop. The AIAgent class is the core orchestration engine, and everything, memory, skills, soul, crons, and self-improvement, revolves around making that single agent more capable. The system is Python-native, stateless at the runtime level with all state persisted to SQLite or PostgreSQL, and deeply modular.
OpenClaw uses a layered, multi-agent architecture with a clear separation between layers. At the top is the Connector Layer, which monitors input channels like WhatsApp, Telegram, Discord, Slack, iMessage, and Microsoft Teams. Below that is the Integration Gateway, which acts as the central control plane, intercepting messages and routing them to the appropriate agent. Below that is the Agent Core or Orchestrator, which handles reasoning and task planning. Below that is the Memory System, and at the bottom is the Execution Layer, where actual actions are taken.
OpenClaw is written in TypeScript rather than Python, and it requires Node.js 22 or higher and the Bun runtime for fast TypeScript execution. This makes it a better fit for teams that are already working in the JavaScript/TypeScript ecosystem.
The following table summarizes the key architectural differences:
Feature | Hermes Agent | OpenClaw
-------------------------|----------------------|----------------------
Primary Language | Python | TypeScript
Core Architecture | Single-agent loop | Multi-agent gateway
Memory Implementation | MEMORY.md + USER.md | SQLite/Redis + vector
Skill Creation | Automatic (learning) | Manual (human-written)
Self-Improvement | Yes (GEPA + loop) | No
Setup Time | 2-4 hours | Under 30 minutes
Community Skills | Self-generated | ClawHub marketplace
Security Record (2026) | Zero CVEs reported | Multiple CVEs reported
Model Support | 200+ via OpenRouter | Major providers + Ollama
Best For | Deep, adaptive work | Broad, fast integration
5.3 SKILL CREATION: AUTOMATIC VS. MANUAL
One of the starkest differences between the two systems is how skills are created. In Hermes Agent, skill creation is automatic. The agent observes its own behavior, identifies reusable workflows, and writes skill files without any human intervention. After approximately five complex executions of a similar workflow, the agent will propose creating a skill and, with your approval, codify it permanently.
In OpenClaw, skills are created manually by humans. Users write skill files themselves, or they download pre-built skills from the ClawHub community marketplace. This gives OpenClaw a much larger library of immediately available skills, because the community has been contributing to ClawHub for longer than Hermes Agent has existed. However, it also means that OpenClaw's skill library does not adapt to your specific workflows. You get what the community has written, not what your particular work patterns require.
The security implications of this difference are also significant. Because Hermes Agent's skills are self-generated from your own interactions, there is no risk of installing a malicious skill from an external source. OpenClaw's community marketplace, ClawHub, has experienced incidents involving malicious skills in 2026, which is a meaningful security concern for enterprise deployments.
5.4 SETUP AND EASE OF USE
OpenClaw has a clear advantage when it comes to initial setup speed. With Docker Compose, you can have OpenClaw running in under 30 minutes. Its TypeScript-based architecture and Docker-first deployment model make it very accessible to teams that want to get something working quickly.
Hermes Agent requires more investment upfront. A full local setup with memory and tools properly configured typically takes between two and four hours. The system is more developer-oriented, with more configuration options and a steeper learning curve. However, this investment pays dividends over time, because the agent's self-improving architecture means that it becomes progressively easier and more productive to work with as the weeks go by.
The choice between the two systems often comes down to your time horizon. If you need something working today and you are willing to maintain it manually, OpenClaw is the faster path. If you are willing to invest a few hours upfront in exchange for a system that grows with you over months and years, Hermes Agent is the more powerful long-term choice.
5.5 SECURITY
Security is an area where Hermes Agent has a notable advantage. As of May 2026, Hermes Agent has zero reported agent-specific CVEs (Common Vulnerabilities and Exposures). Its architecture emphasizes container hardening and namespace isolation for subagents, and its self-generated skill system eliminates the risk of supply-chain attacks through malicious community skills.
OpenClaw has reported multiple CVEs in 2026, including some rated as high severity. The ClawHub community skill marketplace has also experienced issues with malicious skills being uploaded and downloaded by unsuspecting users. For enterprise deployments where security is a primary concern, this is a significant consideration.
Both systems support running commands in Docker containers for sandboxed execution, and both allow you to restrict which tools the agent can use. But Hermes Agent's overall security posture is currently stronger, both architecturally and in terms of its track record.
6. PUTTING IT ALL TOGETHER
Let us step back and look at the complete picture. Hermes Agent is not just another chatbot wrapper. It is a fundamentally new kind of software: a persistent, self-improving AI system that learns from your work, adapts to your preferences, and becomes more capable over time.
Its architecture is built on five interlocking pillars. Memory gives it continuity across sessions, so it never forgets who you are or what you have been working on. Skills give it procedural knowledge, a growing library of reusable workflows that it builds and refines automatically. Soul gives it a consistent identity and personality, defined by you and stable across all sessions. Crons give it proactivity, the ability to work on your behalf without waiting to be asked. And Self-Improvement, powered by the learning loop and the GEPA evolutionary engine, gives it the ability to get genuinely better at its job over time.
The Agent Loop Engine ties all of these pillars together into a coherent, reliable, and auditable system. Its stateless dispatcher architecture, backed by SQLite or PostgreSQL, makes it robust and debuggable. Its iteration budget system prevents runaway processes. Its provider failover capability makes it resilient to model outages. And its subagent system makes it scalable to complex, multi-threaded tasks.
Compared to OpenClaw, Hermes Agent trades quick initial setup for long-term depth and adaptability. It trades a large community skill marketplace for a more secure, self-generated skill system. It trades TypeScript's broad ecosystem for Python's rich data science and automation tooling. And it trades breadth-first multi-agent coordination for depth-first single-agent mastery.
Neither system is universally better. But for users who want an AI assistant that truly grows with them, that learns their workflows, remembers their preferences, and becomes more capable with every passing week, Hermes Agent represents the current state of the art in open-source agentic AI.
The ancient Hermes was the messenger of the gods, the guide of souls, and the patron of travelers between worlds. The modern Hermes Agent aspires to something similar: to be the intelligent, tireless, ever-improving companion that helps you navigate the increasingly complex landscape of modern knowledge work.
And unlike the ancient god, this one you can run on your laptop.
SUMMARY REFERENCE CARD
HERMES AGENT AT A GLANCE
Developer : Nous Research Released : February 2026 License : MIT (open source) Language : Python 3.11+ Latest Version : v0.14.0 (May 16, 2026)
FIVE CORE PILLARS Memory : Persistent facts in MEMORY.md and USER.md Skills : Auto-generated reusable workflow files Soul : Static personality definition in SOUL.md Crons : Scheduled autonomous task execution Self-Improve : Learning loop + GEPA evolutionary engine
KEY NUMBERS Built-in tools : 40+ Supported models : 200+ via OpenRouter Iteration budget : 50 turns per task (default) GEPA run cost : $2-$10 per optimization cycle Security CVEs : 0 reported (as of May 2026)
SUPPORTED PLATFORMS OS : Linux, macOS, WSL2, Android (Termux) Messaging : Telegram, Discord, Slack, WhatsApp, Signal Model providers : OpenRouter, OpenAI, Anthropic, Google, Ollama
HERMES AGENT vs. OPENCLAW Hermes Agent : Depth, self-improvement, Python, security OpenClaw : Breadth, fast setup, TypeScript, marketplace
INSTALLATION (one line) curl -fsSL https://raw.githubusercontent.com/NousResearch/\ hermes-agent/main/scripts/install.sh | bash
No comments:
Post a Comment