Hermes Agent (NousResearch) -- Independent Technical Evaluation. Architecture, strengths, red flags, and comparison to Claude Code / Codex CLI.
Repository: https://github.com/nousresearch/hermes-agent License: MIT | Language: Python 3.11+ Stars: ~96K | Forks: ~13.5K | Open Issues: ~1,800 | Total Issues Filed: ~11,700 | Contributors: 30 Evaluated: April 17, 2026
Hermes Agent is a general-purpose AI agent platform that wraps LLM API calls (OpenAI, Anthropic, OpenRouter, 200+ models) with a standard tool-calling loop, persistent memory, multi-platform messaging gateway, and self-improving skill system. It is an open-source alternative to Claude Code / Codex CLI, designed to run across Telegram, Discord, Slack, WhatsApp, Signal, WeChat, iMessage (via BlueBubbles), and CLI simultaneously.
It is not tied to NousResearch's Hermes fine-tuned models. Any model works. The NousResearch connection is organizational (they built it), not technical (it does not require their models).
Standard synchronous tool-calling loop:
- Send messages + tool schemas to LLM API (OpenAI-compatible format)
- If response has tool calls, execute them via
handle_function_call() - Append results, loop until model produces final text response or hits iteration limit (default 90)
This is the same pattern as Claude Code, Codex CLI, aider, and every other agent. No novel architecture here.
| Component | Implementation | Notes |
|---|---|---|
| Tool Registry | ~50 built-in tools (terminal, file ops, browser, search, code exec, image gen, TTS, transcription, MCP client, subagent delegation, cron) | Tools self-register at import time |
| Memory | File-backed MEMORY.md + USER.md, frozen into system prompt at session start | Has injection/exfiltration scanning |
| Skills | Markdown-based with YAML frontmatter, nearly identical to Claude Code's design (they cite Anthropic) | Self-improving: agent can generate and refine skills |
| Gateway | 15+ platform adapters with session persistence and voice memo transcription | The most distinctive component |
| Context Compression | Auto-compresses middle turns, protects head/tail, structured Resolved/Pending tracking | Uses auxiliary model for summarization |
| Subagent Delegation | Spawns child agents with isolated context and restricted toolsets | Max depth 2, 3 concurrent children |
| MCP Client | ~1050 lines, stdio + HTTP transports, auto-reconnect, thread-safe, OSV checking | Credential stripping on output |
| Execution Backends | Local, Docker, SSH, Daytona, Modal, Singularity | Serverless options hibernate when idle |
| Session Store | SQLite with WAL mode, FTS5 full-text search across all messages | Tracks tokens, costs, model config |
| Trajectory/RL | JSONL trajectory saving, compression, Atropos RL integration | NousResearch training data pipeline |
Keyword-based routing between cheap and strong models. Detects "complex" keywords (debug, implement, refactor) and routes to a stronger model. Simple heuristic, not learned.
This is the genuine differentiator. The closest competitor is OpenClaw (~359K stars, 24+ platform adapters), but Hermes matches it on session persistence, voice memo transcription, and unified context across channels. If you need an LLM-backed bot running on Telegram + Discord + Slack simultaneously, these two are the leading options, with Hermes having tighter integration between gateway and agent runtime.
Five defensive patterns worth studying independently:
Memory content threat scanning. Regex patterns detecting "ignore previous instructions", credential exfiltration via curl/wget, role hijacking in memory entries. Scans all memory writes before persistence.
Context file injection scanning. Checks AGENTS.md, .cursorrules, SOUL.md for invisible unicode, hidden HTML divs, prompt injection patterns before system prompt injection.
OSV malware checking for MCP packages. Validates npm/pypi packages against the Open Source Vulnerability database before spawning MCP server processes. Good supply chain hygiene.
Credential stripping from output. Redacts API keys, tokens, and secrets from all terminal and chat display output.
Structured context compression. Summaries with Resolved/Pending tracking and "different assistant" handoff framing (from Codex) to prevent the model from re-executing compacted instructions as active tasks.
The agent can generate new skills from experience and refine existing ones during use. Conceptually interesting for long-running personal assistants, though it introduces drift risk.
Multi-instance support via separate HERMES_HOME directories. Each profile gets isolated config, API keys, memory, sessions, skills, and gateway settings. Clean separation for different use cases or clients.
For 30 contributors, this is a maintenance debt signal. Over 11,000 issues have been filed in the project's history, with ~1,800 currently open. Commit cadence is high (multiple per day), but the ratio of issues filed to contributors suggests feature velocity is prioritized over stability.
Everything (CLI, gateway, tools, RL training, MCP, 15 platform adapters) lives in one repo. run_agent.py imports from dozens of modules. Fragile to extend or contribute to.
Their AGENTS.md warns against running pytest directly (local-vs-CI drift). A wrapper script is needed to unset all API keys and normalize the environment. This is a sign of accidental coupling.
The trajectory saving, compression, and RL components exist to generate training data for NousResearch's next-generation models. The agent is partly a data collection pipeline for their model training. This is transparent (MIT license, well-documented), but it means some design decisions serve NousResearch's training needs rather than end-user needs. Understand this before investing deeply.
Multiple recent commits involve WeChat media uploads, SSL certs for macOS, QR rendering, iLink session management, DingTalk, Feishu, QQ Bot. This suggests the project's active user base skews toward the Chinese market, which influences feature priorities.
They explicitly state: "The system protects the operator from LLM actions, not from malicious co-tenants." Prompt injection from third parties is out of scope unless it bypasses the approval system. Reasonable for personal use, limits multi-tenant deployment.
| Dimension | Claude Code | Hermes Agent | Codex CLI |
|---|---|---|---|
| Code intelligence | LSP, AST-aware | Terminal + file tools | Terminal + file tools |
| Model lock-in | Claude only | Any (200+) | OpenAI only |
| Multi-platform messaging | CLI only | 15+ platforms | CLI only |
| Memory persistence | CLAUDE.md + MEMORY.md | MEMORY.md + USER.md | None |
| Skill system | SKILL.md with frontmatter | Nearly identical | None |
| MCP support | Native, deep | Client-side wrapper | Limited |
| Multi-agent | Native Teams, Task tool | delegate_tool (max depth 2) | None |
| Self-improvement | None | Skill generation | None |
| Prompt caching | Native Anthropic | Client-side control | Native OpenAI |
| IDE integration | VS Code, JetBrains | ACP adapter (limited) | VS Code |
| Security | Sandbox, permissions | Approval gate, redaction | Sandbox |
- Personal assistant on messaging platforms. If you want an LLM-backed bot in Telegram, Discord, or WhatsApp with persistent memory and tool use, this is the best open-source option.
- Model-agnostic workflows. If you need to switch between providers (Anthropic, OpenAI, Mistral, local models) within one agent framework.
- NousResearch community members. If you're already in the Nous ecosystem and want to contribute training data via trajectory capture.
- Teams already using Claude Code or Codex CLI. The code intelligence gap is significant. Hermes cannot navigate codebases, use LSP, or do AST-aware editing.
- Production multi-agent orchestration. Max depth 2, 3 concurrent children, no topology awareness. Use dedicated orchestration frameworks instead.
- Security-sensitive deployments. The operator-trust security model and monolithic architecture are not suited for multi-tenant or adversarial environments.
Among personal-assistant-class agents (persistent memory, multi-platform messaging, self-improving skills), Hermes Agent is one of the most feature-complete open-source options, alongside OpenClaw. Its messaging gateway is a genuine strength, though OpenClaw matches it on platform breadth. As a coding agent, it is materially behind Claude Code and Codex CLI, lacking LSP integration, AST awareness, and IDE support. The ~1,800 open issue backlog (11,700 total filed) and monolithic architecture suggest integration risk.
Adopt if your primary use case is a multi-platform messaging bot with persistent memory and tool use.
Do not adopt if your primary use case is software engineering, code navigation, or multi-agent orchestration.
Borrow regardless: The five defensive security patterns (memory threat scanning, context injection scanning, OSV checking, credential stripping, structured context compression) are independently valuable for any agent setup.
Evaluated by Michael O'Boyle with Claude Code (Opus 4.6).
The trajectory section is the part I would be most careful with. Saving trajectories for RL/data flywheel is different from saving replayable regression artifacts for operators.
For agent platforms with external tools, I think the useful artifact is a typed event log that can be replayed/gated without re-running destructive actions: tool sequence, args/response hashes, approvals, and side-effect diffs. That gives teams a way to test whether a model/prompt/tool change reintroduces unsafe behavior before it reaches production.
I built a small open-source protocol + CLI for this exact boundary: https://github.com/anzal1/agentreplay