← Back to Knowledge
Applied AI · Agent architecture

Hermes Agent: building an agent means designing a system, not just a prompt

Hermes Agent is an open-source framework from Nous Research that runs one agent core across terminal, desktop, IDE, API, and messaging surfaces. Its useful design unit is the profile: identity, models, tools, memory, skills, security, and automation with separate lifecycles.

A Hermes execution flow

  1. InputCLI · gateway · ACP · API · cron
  2. PromptSOUL · context · skills · memory
  3. Providermodel · API mode · fallback
  4. Agent loopreason · call tools · iterate
  5. Executionterminal · files · web · MCP
  6. State & outputSQLite · FTS5 · delivery

One core, many surfaces

The AIAgent core serves several entry points: CLI and TUI, desktop application, messaging gateway, ACP for editors, an OpenAI-compatible server, batch runner, and Python library. Interface differences live outside the central loop, allowing the same agent to act from Telegram or an IDE without duplicating execution logic.

  • CLI/TUI for interactive terminal work.
  • Desktop and dashboard for sessions, configuration, and visual operations.
  • Gateway for Telegram, Discord, Slack, WhatsApp, and other adapters.
  • ACP, API, and batch modes for editors, applications, and experiments.

The architecture behind the agent loop

AIAgent assembles the prompt and tool schemas, resolves the provider and API mode, makes an interruptible model request, and dispatches tool calls. Results return to history and the cycle continues until a final response, a budget boundary, or an interruption.

  • Three modes converge on one internal history: chat completions, Codex Responses, and Anthropic Messages.
  • Multiple tool calls can execute concurrently while results return in original order.
  • Retries, fallback providers, compression, and persistence belong to the loop rather than an improvised wrapper.
  • Role alternation and tool-call/result pairs remain history invariants.

Capabilities: tools organized into toolsets

Hermes exposes tools as registered functions and groups them into toolsets that can be enabled per surface. The catalog covers web, browser, operating system, repositories, documents, media, and external services; actual availability depends on configuration, credentials, and backend.

  • Web and browser: search, extraction, automation, snapshots, and vision.
  • Engineering: terminal, processes, file operations, patches, search, LSP, and programmatic Python execution.
  • Multimodal: vision, image and video generation, STT, and text-to-speech.
  • Orchestration: todo, clarify, delegation, cron, kanban, goals, and background jobs.
  • Integrations: MCP, Home Assistant, Spotify, Discord, and specialized plugins.

Memory, sessions, and skills are different systems

Memory stores compact stable facts; USER.md models the user; SQLite and FTS5 persist and search sessions; skills contain procedures that load only when relevant. This separation keeps baseline context small and turns a repeatable solution into reusable capability.

  • MEMORY.md and USER.md enter as snapshots when the prompt is created or rebuilt.
  • session_search retrieves stored conversations without treating them as permanent memory.
  • SKILL.md uses progressive disclosure: compact index, main content, then references on demand.
  • The agent can create and improve skills; an optional gate can require review for every write.

Automation, delegation, and extensibility

Hermes can turn a conversation into parallel or durable work. Subagents isolate context for concurrent tasks; execute_code composes several tools from Python; cron runs scheduled jobs; webhooks react to external events; MCP and plugins add capabilities without changing the core.

  • delegate_task creates isolated workers and returns their results to the parent agent.
  • Cron supports schedules, attached skills, scripts, workdir, and multi-platform delivery.
  • HMAC-authenticated webhooks can trigger runs from GitHub, CI, monitoring, or internal systems.
  • MCP discovers tools over stdio or HTTP and registers them beside native tools.
  • Plugins can contribute tools, hooks, memory providers, context engines, and visual surfaces.

SOUL.md defines identity; AGENTS.md defines the project

SOUL.md lives in HERMES_HOME and occupies the first position in the system prompt. It should contain voice, character, posture toward uncertainty, and interaction style that apply across contexts. Repository conventions, commands, ports, and architecture belong in project context files.

  • SOUL.md: durable identity, tone, directness, stylistic boundaries, and operating values.
  • .hermes.md or AGENTS.md: project rules, architecture, commands, and verification.
  • Skills: reusable procedures and specialized knowledge loaded on demand.
  • Memory/User: stable facts about environment, preferences, and person—not long procedures.
  • /personality: temporary session overlay, not a replacement for a designed identity.

How to build a Hermes agent

The recommended path is to create an isolated profile, define its identity, select model and tools, add project rules and skills, configure memory and integrations, and test with adversarial tasks before enabling automation. A profile can then be exported or published as a versioned distribution.

  • Create: `hermes profile create research-bot`, then run its setup.
  • Define identity in `$HERMES_HOME/SOUL.md` without secrets or temporary paths.
  • Select provider/model, fallbacks, and least-privilege toolsets.
  • Add AGENTS.md, skills, MCP, and cron only when the use case earns them.
  • Dogfood, inspect traces, validate approvals, and publish as a Git distribution if it will be shared.

The system prompt is a deliberately stable composition

Hermes orders the prompt into stable, contextual, and volatile tiers. SOUL.md, tool guidance, and skills form the stable prefix; project rules form context; memory, user profile, timestamp, and session data form the volatile tier. Per-call overlays do not mutate the cached prefix.

  • Prefix stability preserves prompt caching and continuity.
  • Context files pass through security scanning and truncation before inclusion.
  • Memory writes do not silently rewrite an already-frozen prompt.
  • Compression summarizes the middle of history while preserving recent messages and tool pairs.

Operational power requires explicit boundaries

An agent with terminal, browser, credentials, and messaging can produce real effects. Hermes provides command approval, secret redaction, backend isolation, profile separation, gateway authorization, MCP environment filtering, and checkpoints, but the operator still owns the risk configuration.

  • Use smart or manual approvals; reserve yolo mode for deliberately disposable environments.
  • Keep secrets in `.env` or authentication stores, never in SOUL.md, skills, or repositories.
  • Choose local, Docker, SSH, or cloud backends according to acceptable blast radius.
  • Treat skills, plugins, MCP servers, and distributions as privileged third-party code.
  • Verify artifacts, CI, deployment, and external effects before declaring work complete.

Official sources