langstage-hermes

A faithful reproduction of Nous Research's Hermes Agent on top of LangGraph + deepagents + langstage-core.

Status: live on PyPI (renamed from deepagent-hermes — the old name now just installs this one, and the deepagent-hermes command still works). Spec at SPEC.md. Release notes in CHANGELOG.md. The runtime is verified end-to-end against a real Anthropic model — both the memory loop and the skill-creation loop close autonomously; see examples/dogfood.py and examples/dogfood_procedural.py for the traces.

What it is

A deepagents-built agent with a closed reflection→skill-creation loop:

• After ~10 tool-using iterations, a review subagent runs in the background, writes/patches a SKILL.md capturing the pattern it just exercised, and ships it to a skill library.
• Next session, the agent reads the library at startup, sees the new skill's description in its system prompt, and can skill_view(name) to load the full body on demand (progressive disclosure per the agentskills.io spec).
• A weekly curator consolidates skills into umbrellas and archives stale ones.
• A frozen-snapshot memory (MEMORY.md + USER.md) preserves prefix-cache hits for the entire session.
• FTS5 session search indexes every past conversation in a local SQLite DB.
• Bundled MarkdownProvider that keyword-searches <HERMES_HOME>/memories/notes/*.md — drop hand-authored long-form context there and the agent surfaces relevant sections on demand. Zero external dependencies.

Designed to be loaded into the LangStage host family without UI changes — set LANGSTAGE_AGENT_SPEC=langstage_hermes.agent:graph in any of them.

Every stage for your LangGraph agent

langstage-hermes is the reference agent of the LangStage family: write your agent once — any LangGraph CompiledGraph — and run it on every stage with the same spec string (module:attr or path/to/file.py:attr), the same langstage.toml config file, and the same LANGSTAGE_* environment variables.

Serve over AG-UI

This surface's agent — any LangGraph CompiledGraph — can also be served over the AG-UI protocol as a standalone HTTP endpoint. Install the extra and point the bundled console script at your agent spec:

pip install "langstage-core[agui]"
langstage-agui --agent langstage_hermes.agent:graph

📖 Full documentation: https://dkedar7.github.io/langstage-docs/

Installation

pip install langstage-hermes

Or with uv (recommended):

uv venv .venv
. .venv/Scripts/activate      # Windows
. .venv/bin/activate          # macOS / Linux
uv pip install langstage-hermes

Optional extras

pip install "langstage-hermes[openai]"     # OpenAI / OpenRouter / any OpenAI-wire provider
pip install "langstage-hermes[daytona]"    # Daytona sandbox terminal backend
pip install "langstage-hermes[modal]"      # Modal sandbox terminal backend
pip install "langstage-hermes[ssh]"        # paramiko-backed SSH terminal backend
pip install "langstage-hermes[dev]"        # tests + lint (contributors only)

Picking a model

By default the agent uses anthropic:claude-sonnet-4-6 and needs ANTHROPIC_API_KEY set. Swap the model via --model on the CLI or model.default in langstage-hermes.toml — any init_chat_model string works.

OpenAI / OpenRouter

pip install "langstage-hermes[openai]"
export OPENAI_API_KEY=sk-…                   # or: OPENROUTER_API_KEY=sk-or-v1-…
export OPENAI_BASE_URL=https://openrouter.ai/api/v1   # only for OpenRouter
langstage-hermes chat --model openai:openai/gpt-4o-mini

For OpenRouter specifically you usually also want:

export LANGSTAGE_HERMES_MODEL_DEFAULT="openai:openai/gpt-4o-mini"
export LANGSTAGE_HERMES_MODEL_AUX="openai:openai/gpt-4o-mini"

so the reflection subagent uses the same cheap model.

Verify your setup

langstage-hermes verify

does one live round-trip against the configured model and confirms the prompts, bundled skills, and FTS5 store all wire up correctly. Run this first on any fresh install — if it passes, chat will work.

Quick start

# show resolved config + sources
langstage-hermes --show-config

# interactive chat
langstage-hermes chat

# chat against a different agent (same spec format as every LangStage
# stage; overrides LANGSTAGE_AGENT_SPEC)
langstage-hermes chat -a my_agent.py:graph

# from inside chat:
#   /skills            list available skills
#   /model anthropic:claude-haiku-4-5-20251001    switch models
#   /memory            dump current memory snapshot
#   /compress          force context compression
#   /quit

Load into an existing host

Any LangStage host can run this agent:

# langstage-cli
LANGSTAGE_AGENT_SPEC="langstage_hermes.agent:graph" langstage-cli

# langstage-jupyter — set the same in langstage.toml under [agent]
printf '[agent]\nspec = "langstage_hermes.agent:graph"\n' >> langstage.toml
langstage-jupyter

Configuration

langstage-hermes.toml (project) or $HERMES_HOME/config.toml (global — default ~/.langstage-hermes/config.toml, and it moves with a custom HERMES_HOME). Layered resolution: defaults < TOML < LANGSTAGE_HERMES_* env < CLI overrides. See SPEC §2 for every field; langstage-hermes --show-config prints the resolved value + source of each.

Architecture

See SPEC.md for the full 21-section requirements doc. Top-level layout:

• src/langstage_hermes/agent.py — the compiled graph (entry point for hosts)
• src/langstage_hermes/config.py — HermesConfig(HostConfig) resolver
• src/langstage_hermes/state.py — HermesState (extends AgentState)
• src/langstage_hermes/reflection.py — closed-loop middleware + review subagent
• src/langstage_hermes/skills/ — SkillLibrary, loader, tools
• src/langstage_hermes/memory/ — frozen-snapshot memory + provider ABC
• src/langstage_hermes/store/sqlite_fts.py — BaseStore with FTS5
• src/langstage_hermes/search/session_search.py — session_search tool
• src/langstage_hermes/compression.py — HermesCompressionMiddleware
• src/langstage_hermes/caching.py — AnthropicCachingS3Middleware
• src/langstage_hermes/budget.py — IterationBudgetMiddleware
• src/langstage_hermes/tools/ — registry + 33 toolsets + 6 terminal envs
• src/langstage_hermes/cron/ — daemon + cronjob tool
• src/langstage_hermes/plugins/ — discovery + lifecycle hooks
• src/langstage_hermes/cli.py — langstage-hermes entry point
• prompts/ — verbatim/paraphrased system-prompt building blocks

Status by subsystem

License

MIT. See LICENSE. This project is a faithful reproduction of the design ideas in Nous Research's Hermes Agent — see NOTICE for attribution.