CodeDocs Vault

Hermes Agent - Codebase Analysis

Generated 2026-04-16 from commit 8021a735 (main branch)

Documents

# Document What It Covers
00 Overview Purpose, problem solved, target users, tech stack, entry points, repository scale
01 Architecture Component diagram, data flow, directory structure, state transitions, dependency graph
02 Agent Core AIAgent class, conversation loop, API call lifecycle, streaming, error recovery hierarchy, session persistence
03 Tools System Tool registry, self-registration, discovery pipeline, toolsets, key tool implementations (terminal, file, browser, code exec, delegate, MCP)
04 Security 10-layer security stack: command approval, path security, file protection, credential filtering, SSRF prevention, content scanning, memory injection defense, skill guard, delegation isolation, execution sandboxing
05 Skills, Memory & Learning Skills system (format, discovery, creation, self-improvement, hub), memory system (frozen snapshots, nudging, injection defense), session search, todo tool, the closed learning loop
06 Gateway & Messaging Gateway architecture, 26+ platform adapters, message processing pipeline, slash commands, streaming, session management, cron system, MCP server, authorization
07 LLM Patterns Multi-provider abstraction, prompt engineering (prefix cache optimization, ephemeral injection), context management, token tracking, tool call validation, reasoning support, guardrails, fallback strategy
08 Design Patterns Self-registering modules, frozen snapshot pattern, adapter pattern, parallel execution, progressive disclosure, circuit breaker, iteration budget, WAL convoy prevention, notable tradeoffs, potential pitfalls
09 Key Files Map Complete file-to-responsibility map organized by tier, dependency graph, configuration files, important prompts

Quick Reference

What makes Hermes Agent different from other AI agents?

  1. Closed learning loop: Creates skills from experience, improves them during use, maintains memory across sessions, searches past conversations
  2. Multi-platform: Single gateway process serves 26+ messaging platforms simultaneously
  3. Provider-agnostic: Works with any OpenAI-compatible endpoint (200+ models)
  4. Runs anywhere: Local, Docker, SSH, Modal (serverless), Daytona, Singularity (HPC)
  5. Research-ready: Batch trajectory generation, RL training, SWE benchmarking

Key architectural decisions

Decision Rationale
Frozen memory snapshots Preserves Anthropic prompt cache (4-10x cost reduction)
AST-based tool discovery Zero-config tool addition: drop a .py, register, done
Progressive skill disclosure Prevents 100-skill library from consuming context window
Shared iteration budget Prevents runaway delegation chains from burning API credits
SQLite WAL + FTS5 Zero-dependency session store with full-text search
Subprocess-based environments No heavy client library dependencies for Docker/SSH/etc.

Reading order for new contributors

  1. Start with 00-overview.md for the big picture
  2. Read 01-architecture.md for component relationships
  3. Read 09-key-files-map.md to know what to open
  4. Then dive into whichever subsystem you're working on (02-08)