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

Search your session history

Every conversation is indexed in a local SQLite FTS5 store at <HERMES_HOME>/state.db. Query it from the terminal — keyless and offline, no model call — in the three documented modes:

# DISCOVERY — BM25 top-N with a highlighted snippet (prints session_id + message_id)
langstage-hermes search "profile slow python"
langstage-hermes search "profile slow python" --limit 10 --json

# SCROLL — a ±window view centred on a message (window clamped 1–20)
langstage-hermes search --session sess-1a2b3c --around 8 --window 5

# BROWSE — recent sessions, newest first (also the default with no query)
langstage-hermes search --browse --limit 20

--json emits structured output for scripting/CI. The same flag is honored by skills list, skills audit, and audit log, so the skill inventory and mutation log are scriptable too (each prints one JSON object with stable keys). FTS5 syntax works: multi-word queries default to AND, and OR, quoted "phrases", and prefix wildcards* are all honored.

Want a store to try it against, keyless? Point HERMES_HOME at a directory and run langstage-hermes demo — with HERMES_HOME set the demo records its session into that same <HERMES_HOME>/state.db, so search reads it straight back:

export HERMES_HOME=~/.langstage-hermes    # any stable directory
langstage-hermes demo                     # populates <HERMES_HOME>/state.db
langstage-hermes search "python"          # finds the demo session

(A bare langstage-hermes demo with no HERMES_HOME set uses a throwaway home and cleans up after itself, so it never litters your default store — pass --keep-workspace to inspect it.)

Preview your notes

Drop hand-authored long-form context in <HERMES_HOME>/memories/notes/*.md and the bundled MarkdownProvider surfaces relevant sections to the agent on demand (enable it with memory.provider = "markdown"). Preview exactly what it will recall from the terminal — keyless and offline, no model call — so note authors get a feedback loop without a chat turn:

langstage-hermes memory notes "rollback"            # prints the source file + matching section
langstage-hermes memory notes "rollback" --json     # {"query", "count", "results":[{file, section, snippet}]}

Recall is the same dumb-but-robust keyword overlap the agent uses (query tokens ≥ 3 chars, ranked by distinct hits). --limit N caps the sections returned; a missing/empty notes dir or a no-match query prints a clear message, never a traceback.

Read your memory

The frozen-snapshot memory (MEMORY.md + USER.md) is the layer the agent grows about you and the session, but inside a chat only the /memory slash command could read it — and chat needs an API key. Dump the current snapshot straight from the terminal — keyless and offline, no model call — to answer "what has the agent learned about me?" without spending a turn:

langstage-hermes memory show                 # both USER.md + MEMORY.md, with char count vs budget
langstage-hermes memory show --user          # just USER.md
langstage-hermes memory show --session       # just MEMORY.md
langstage-hermes memory show --json          # {"user": {...}, "memory": {...}} for scripting / CI

Each layer prints its char count against the configured truncation budget (memory_char_limit = 2200, memory_user_char_limit = 1375) so you can see when a snapshot is near or over budget. A missing/empty layer prints a clear one-line message, never a traceback (memory dump is an alias for memory show).

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.