hermes-internals

Hermes Agent — Internals & Surfaces

Hermes is a self-improving, terminal-native agent: persistent memory, agent-created skills, a 20+ platform messaging gateway, runnable on local/Docker/SSH/Daytona/ Modal/Singularity backends, against Nous Portal / OpenRouter / OpenAI / Anthropic / any OpenAI-compatible endpoint. MIT licensed. Repo: github.com/NousResearch/hermes-agent. Docs: hermes-agent.nousresearch.com/docs.

A machine-readable doc index lives at /docs/llms.txt; the full concatenated docs at /docs/llms-full.txt.

The four surfaces (and when to use each)

Hermes is one engine you can reach four ways. Choosing the right one is the single biggest lever on speed when testing or automating.

Surface	What it is	Best for	Avoid for
CLI (hermes chat -q "…")	one headless run per process	a human running one ad-hoc prompt	batch/QA — cold start per call is the bottleneck
Python library (from run_agent import AIAgent)	in-process agent, full control	QA at scale, batch trajectories, embedding in tools, tool-call inspection	nothing — this is the default for automation
API server (api_server adapter / hermes serve)	OpenAI-compatible /v1/chat/completions	end-to-end tests through the real serving path, any OpenAI-style frontend	inspecting intermediate tool calls (returns final text only)
Gateway (hermes gateway start)	long-lived multi-platform message router	production: Telegram/Discord/Slack/…, cron delivery, pairing	unit-style testing of agent logic (too much machinery)

Speed rule of thumb: anything that runs more than one prompt should use the library (in-process + parallel) or the API server, never a loop of hermes chat.

AIAgent — the knobs that matter

from run_agent import AIAgent

agent = AIAgent(
    model="anthropic/claude-sonnet-4.6",
    quiet_mode=True,          # suppress CLI spinners — REQUIRED when embedding
    skip_memory=True,         # don't read/write MEMORY.md — stateless & faster
    skip_context_files=True,  # don't inject AGENTS.md/.hermes.md
    max_iterations=6,         # cap tool-calling loops (default 90 is generous)
    enabled_toolsets=["web"], # or disabled_toolsets=[...]
)
text = agent.chat("…")                     # -> final string
result = agent.run_conversation("…")       # -> {"final_response", "messages"}