AI
Hermes AI Agent by Nous Research: Architecture, Self-Learning Loop, and Getting Started
May 202612 min read
Photo by Unsplash
Photo by Unsplash
Most open-source AI agent frameworks give you a loop: LLM call, tool call, repeat. Hermes Agent by Nous Research goes significantly further. It has a closed self-learning loop where the agent stores successful task approaches as skills in a vector database, retrieves similar skills on future tasks, refines them based on outcomes, and gradually improves without human intervention. It supports 200+ models via OpenAI, Anthropic, and OpenRouter APIs — switchable via config, no code changes. It runs on Telegram, Discord, Slack, WhatsApp, Signal, and CLI through a single gateway interface. This post is a deep dive into the architecture and a practical getting-started guide.
The concept that distinguishes Hermes from frameworks like AutoGPT, LangChain agents, or CrewAI is the closed self-learning loop. In a standard agent framework, the agent tackles every task from scratch. Hermes adds a persistent layer: after completing a task, it serializes the approach and stores it as an embedding in a vector database. On the next similar task, the agent retrieves the most relevant stored skills, uses them to bootstrap its planning, and after execution, updates the skill's success rate and refines the approach.
The skill store is implemented as a vector database (the default is Chroma, with support for Pinecone and Weaviate). Each skill entry contains: a natural language description of the task type, an embedding vector, the successful execution trace (tool calls, parameters, response handling), a success rate updated after each execution, and a version history. When a new task comes in, Hermes embeds the task description and retrieves the top-k most similar skills by cosine similarity.
Hermes exposes a single agent interface to multiple platform connectors. The Telegram connector, Discord connector, Slack connector, and CLI all talk to the same underlying agent loop — the platform is just a transport layer. This means you configure the agent once and deploy it across all the channels your users prefer. Adding a new platform connector requires implementing a simple adapter interface.
HERMES CLOSED SELF-LEARNING LOOP
══════════════════════════════════
┌─────────────┐
│ Task Input │ ◄── Telegram / Discord / Slack / CLI
└──────┬──────┘
│
▼
┌─────────────────────────────────────────────┐
│ Planning & Decomposition │
│ (200+ models: GPT-4o / Claude / Gemini) │
└──────────────────┬──────────────────────────┘
│
┌───────────┴───────────┐
▼ ▼
┌─────────────┐ ┌──────────────────┐
│ Skill Store │ │ Tool Execution │
│ (vector DB) │◄──────►│ 40+ built-ins │
│ │ lookup │ + MCP tools │
└──────┬──────┘ └────────┬─────────┘
│ │
│ ┌────────────────────┘
│ │ execution result
▼ ▼
┌─────────────────────────────┐
│ Skill Refinement │
│ new approach stored back │
│ into vector DB as skill │
└──────────────┬──────────────┘
│
▼
Next Task Input
(better than before)
Subagent execution: Docker │ SSH │ Modal │ DaytonaStart with the CLI connector when developing custom tools and workflows. It gives you immediate feedback without needing to configure a bot token or deal with platform rate limits. Once your tools work correctly in the CLI, switching to Telegram or Slack is a config change, not a code change.
Hermes requires Python 3.11+ and a model provider API key. The installation is a standard pip install from the cloned repository. Configuration is file-based — a .env for secrets and a config.yaml for agent behavior. The most important config decision upfront is the model provider: Hermes supports OpenAI, Anthropic, and OpenRouter out of the box. OpenRouter is particularly useful for experimentation because it routes to 200+ models through a single API key.
MCP (Model Context Protocol) is Hermes's extension mechanism for adding new capabilities. Custom MCP tools are Python classes that inherit from MCPTool and implement an execute method. The tool is described to the LLM via docstring and type annotations — Hermes generates the JSON schema for the LLM's tool call automatically from the Python type hints. Tools can be synchronous or async.
# 1. Clone and install
git clone https://github.com/nousresearch/hermes-agent
cd hermes-agent
pip install -e ".[all]"
# 2. Configure .env
cat > .env << 'EOF'
# Choose your model provider (no code changes needed to switch)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...
# Platform connectors — enable only what you need
TELEGRAM_BOT_TOKEN=...
DISCORD_BOT_TOKEN=...
SLACK_BOT_TOKEN=...
EOF
# 3. Start the agent
python -m hermes.main --platform telegram
# 4. Add a custom MCP tool (Python example)
# tools/my_tool.py
from hermes.mcp import MCPTool
class DeployStatusTool(MCPTool):
name = "get_deploy_status"
description = "Check the latest deployment status on our VPS"
async def execute(self, service: str) -> dict:
# Call your internal API
result = await fetch_deploy_api(service)
return {"service": service, "status": result["status"]}
# Register in hermes config:
# mcp_tools:
# - tools.my_tool.DeployStatusTool
# 5. Skill store — Hermes stores this execution as a skill:
# {
# "skill_id": "deploy-status-check-v2",
# "embedding": [...], # vector for similarity search
# "approach": "Call get_deploy_status, then parse status field",
# "success_rate": 0.94
# }Hermes's subagent layer allows the main agent to delegate compute-intensive tasks to specialized subagents running on different infrastructure. Docker subagents run in isolated containers — ideal for tasks that require specific dependencies or security isolation. SSH subagents run on remote machines — useful for tasks that need access to production systems. Modal and Daytona subagents enable serverless execution for bursty workloads.
The self-learning loop has a failure mode: if the agent stores a flawed approach as a successful skill, future similar tasks will inherit the flaw. Monitor the skill store's entries during the first few weeks of deployment, and implement a quality gate on skill storage — require at least 3 successful executions before a skill reaches a high confidence rating.
The use cases that benefit most from Hermes's architecture are those involving repetitive research and synthesis tasks where the optimal approach improves with experience. Daily digest agents that aggregate news, PRs, and monitoring alerts learn which sources are most relevant over time. Code review agents accumulate project-specific knowledge in the skill store. Cross-platform customer support agents that handle both Telegram and Slack inquiries share a single skill base.
Use Hermes when you want the self-learning loop and multi-platform deployment without building the infrastructure yourself. If you need a single-purpose agent for a narrow, well-defined task, LangChain or a direct API call with tool use is simpler. Hermes shines when: the task space is broad and unpredictable, you want the agent to improve over time without re-prompting, you need one agent accessible from multiple platforms, and you need distributed execution for resource-intensive subtasks.