Reference agent — langstage-hermes¶
Not a surface but an agent: the family's reference implementation, a faithful reproduction of Nous Research's Hermes Agent on top of LangGraph and deepagents. Drop it into any stage to see a rich, real-world agent at work.
What it is¶
A deepagents-built agent with a closed reflection → skill-creation loop:
- After about 10 tool-using iterations, a review subagent writes or patches a
SKILL.mdcapturing the pattern it just used, and adds it to a skill library. - Next session, the agent sees the library's skill descriptions at startup and can
skill_view(name)to load a skill's body on demand. - A curator ages out skills that aren't used and archives stale ones.
- Frozen-snapshot memory (
MEMORY.mdandUSER.md) keeps prompt-cache hits for the whole session, and FTS5 session search indexes every past conversation locally.
Try it without a key¶
demo runs the real reflection loop (the review subagent, skill_manage, the
skill library, the audit log and the FTS5 store) against a scripted model: no
network, no key. It prints the skill the loop wrote. The loop runs in a throwaway
home that is removed afterwards (--keep-workspace keeps it), so nothing lands in
your real skill library. If HERMES_HOME is set, only the demo session is copied
into <HERMES_HOME>/state.db, so search can find it.
Demo¶
langstage-hermes demo, then search and skills list, with HERMES_HOME in a temp directory. No API key.Run it standalone¶
Needs a model key
chat and the live part of verify call the model. The default is
anthropic:claude-sonnet-4-6 with ANTHROPIC_API_KEY.
langstage-hermes doctor # Python, packages, keys, HERMES_HOME; keyless
langstage-hermes verify # offline checks, then one live round-trip
langstage-hermes chat # interactive REPL
langstage-hermes chat -a my_agent.py:graph # chat with a different agent
verify runs its offline checks first (bundled prompts and skills, a writable
HERMES_HOME, the FTS5 store), so a keyless run still tells you the install is
sound. verify --json and doctor --json print a top-level ok plus a per-check
list, and .ok matches the exit code, so langstage-hermes doctor --json | jq -e .ok
is a one-line gate. Without a key, verify --json reports the live round-trip as
skipped, so a keyless CI check never makes a paid call. doctor also checks the
provider package for the auxiliary (reflection) model when it differs from the main
one.
In chat: /skills, /model <id>, /memory, /compress, /quit.
Run it on any stage¶
It's a CompiledGraph, so any surface can run it:
langstage-cli -a langstage_hermes.agent:graph # terminal
langstage run --agent langstage_hermes.agent:graph # web
langstage-jupyter -a langstage_hermes.agent:graph # JupyterLab
langstage-agui --agent langstage_hermes.agent:graph # AG-UI endpoint
Add Hermes to an existing agent¶
Already have an agent? Keep your model, tools and system prompt, and add Hermes's learning loop as middleware:
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain_core.tools import tool
from langgraph.checkpoint.memory import InMemorySaver
from langstage_hermes import hermes_middleware
@tool
def lookup_order(order_id: str) -> str:
"""Look up an order by id."""
return f"order {order_id}: shipped"
model = init_chat_model("anthropic:claude-sonnet-4-6")
agent = create_agent(
model,
tools=[lookup_order],
system_prompt="You are Acme's support agent.",
middleware=[*hermes_middleware(aux_model=model)],
checkpointer=InMemorySaver(),
)
By default you get reflection (a review subagent saves what worked as skills and
memory), skills, memory, recorder (every turn searchable with
session_search) and curator.
- More, or less.
include=addscompression,todo,cronjob(approval-gated, as above) orbudget;exclude=drops a default. - Your prompt is kept. Hermes appends its sections (tool guidance, your memory and user profile, the skills index) after your system prompt; it never replaces it.
- No tool list to maintain. Hermes's tools ride on the middleware, so
create_agentbinds them for you. aux_modelruns the review subagent. Pass your own model to keep one provider and key.
It works with deepagents.create_deep_agent too (leave out todo, which deep agents
already have). For the whole Hermes agent, use langstage_hermes.agent:graph as above.
Look inside, offline¶
These read local state only: keyless, no model call. Each takes --json.
langstage-hermes search "profile slow python" # BM25 matches with highlighted snippets
langstage-hermes search --session <id> --around <msg> --window 5 # a window around one message
langstage-hermes search --browse --limit 20 # recent sessions
langstage-hermes memory show # USER.md + MEMORY.md, with size vs budget
langstage-hermes memory notes "rollback" # what MarkdownProvider would recall
langstage-hermes tools --implemented-only # the toolsets and their tools
searchunderstands FTS5 syntax: multi-word queries are AND, andOR, quoted phrases and prefixwildcards*work.--jsonsnippets are plain text withmatch_rangesoffsets.memory showprints each layer's size against its budget. An over-budget layer is still injected in full; the agent'smemorytool just refuses new entries until it's trimmed.
See and undo memory changes¶
The agent edits USER.md and MEMORY.md on its own, and both go into every later
session's prompt. Each change is recorded with the text it replaced, when it
happened, who made it (agent, or review for the review that runs after a turn)
and in which session.
langstage-hermes audit log --memory # memory changes only (--skills: skills only)
langstage-hermes memory show --history # the same list
langstage-hermes audit show <id> # the whole layer before and after one change
langstage-hermes audit rollback memory:user <id> # undo one change (memory:memory for MEMORY.md)
- A rollback undoes one change and keeps the rest. The entry that change removed or replaced comes back, and the entry it wrote goes. Entries added later stay. With nothing changed since, the layer comes back exactly as it was, in the same order.
- A layer never holds the same entry twice. The
memorytool'saddskips text the layer already holds, andreplacerefuses to overwrite an entry with the text of another one; it tells the agent toremovethe entry it no longer needs. - It refuses instead of guessing. If the entry has been changed again since (by a later change, or by hand), or the result would exceed the layer's size budget, nothing is changed and the message names the change to undo first.
- A rollback is itself recorded, so it can be undone the same way. It reaches the agent's prompt from the next session on.
- Hand edits are not recorded.
audit lognotes when a layer on disk no longer matches its last recorded change, andaudit diff memory:user <id>shows the difference. - Where the text lives. The before and after text is stored in
<HERMES_HOME>/state.db, next to your recorded conversations. Removing an entry from memory does not remove it from that log.
Turn a memory layer off¶
To keep the agent from building a profile of you, set user_profile_enabled = false
under [memory] in langstage-hermes.toml. USER.md then stays out of the prompt,
and the memory tool no longer offers it; a call that names it anyway is refused.
memory_enabled = false does the same for MEMORY.md.
With one layer off, the agent's memory guidance and the review that runs after a turn
ask only for what the other layer keeps. With the profile off, they are told not to
save personal facts about you in MEMORY.md instead. With both off, the agent and its
review get no memory tool at all, and langstage-hermes tools marks the toolset ✗.
Files already on disk are left as they are. memory show and /memory still print an
off layer's file, marked OFF with the setting that turned it off, and
memory show --json reports "enabled": false for it.
Skills¶
langstage-hermes skills list # bundled + user skills (--json)
langstage-hermes skills show <name>
langstage-hermes skills validate ./my-skill # check a SKILL.md without installing; exit 0/1
langstage-hermes skills install ./my-skill # install a skill directory
langstage-hermes skills audit # validate every installed skill
langstage-hermes skills remove <name> # archive it; prints the exact rollback command
What install copies. Installing a file (SKILL.md, or a draft with another
name) copies only that file. Installing a directory copies the skill's contents
but never hidden entries (.git, .env*, .venv), symlinks, node_modules,
__pycache__, virtualenvs, *.egg-info or compiled Python files, and lists what it
skipped. So pointing it at a messy working directory can't leak secrets into the
agent's context. To ship support files (references/, templates/, scripts/),
install the directory.
A skill needs a description and a non-empty body. validate, install and
audit reject one without, and the loader skips it with a warning rather than list
it to the model. Bundled skills can't be removed (hide one with
skills.disabled / LANGSTAGE_HERMES_SKILLS_DISABLED); when the agent edits a
bundled skill, it edits a copy in your skills directory.
Plugins. langstage-hermes plugins list shows the plugins discovered from all
four sources.
Audit log. Every skill change the agent or the CLI makes is recorded:
langstage-hermes audit log, audit show <id> --diff, audit diff, and
audit rollback <name> <id>. Each row names who made the change and the session
it happened in: agent for a skill saved during a turn, review for one the
review that runs after a turn wrote on its own, cli for a change you made from
the command line. Memory changes are in the same log (see
See and undo memory changes).
Curator¶
The curator marks a skill stale after 30 days without use and archives it after
90 (curator.stale_after_days / curator.archive_after_days). "Use" means the agent actually loaded or edited the skill, not the file's
modification time. Pinned skills and bundled skills are never touched.
langstage-hermes curator status
langstage-hermes curator run # a lifecycle pass now
langstage-hermes curator pin <name> # never archive this one (unpin to undo)
langstage-hermes curator pause # stop scheduled runs (resume to restart)
Scheduled runs (cron)¶
langstage-hermes cron create --prompt "summarize today's notes" --schedule "0 18 * * MON-FRI"
langstage-hermes cron list
langstage-hermes cron run-due # one tick: run every due job, then exit
langstage-hermes cron daemon # run forever
--scheduletakes an interval (30m,every 2h), a standard cron expression (includingMON-FRI,JAN, and@daily/@hourly/@weekly), or a one-shotonce at 2026-10-01T09:00. A one-shot time in the past is refused.pause,resumeanddeletemanage jobs. A one-shot job whose run failed stays in the list, disabled, with its error.- A failed run logs one line; set
LANGSTAGE_DEBUG=1for the traceback. The daemon recovers from a lock file left by a crash.
Letting the agent schedule jobs¶
The agent can't schedule jobs unless you turn on its cronjob tool (off by default):
With it on, a chat request like "summarize this repo every morning at 9" can create the job itself.
list,show,pauseanddeleterun straight away.create,resumeandrun-nowstart or restart unattended runs, so they pause first and say what will be scheduled or run. Nothing happens until you approve. The web and terminal stages show Approve / Reject;langstage-hermes chatasksapprove? [y/N, or type a reason to reject], and/yoloapproves automatically.- A cron run's own agent never gets the tool, and
[agent] disabled_toolsets = ["cronjob"]turns it off even with the flag on.
Picking a model¶
Any init_chat_model string works, via --model or model.default in
langstage-hermes.toml. For OpenAI or 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 # OpenRouter only
langstage-hermes chat --model openai:openai/gpt-4o-mini
Set LANGSTAGE_HERMES_MODEL_AUX too, so the reflection subagent uses the same
provider. Other extras: [daytona], [modal] and [ssh] terminal backends.
Configuration¶
- Home. Skills, memory,
state.dband cron jobs live in the hermes home:LANGSTAGE_HERMES_HOME, elseHERMES_HOME, else~/.langstage-hermes. An existing~/.deepagent-hermesfrom before the rename keeps being used. - Files.
langstage-hermes.toml(project) and$HERMES_HOME/config.toml(global) layer over the defaults, thenLANGSTAGE_HERMES_*env vars, then CLI flags. Relative paths in a TOML file resolve against that file's directory. - Inspect.
langstage-hermes --show-configprints each value and its source;--show-config --jsonprints the same as JSON, with anissueslist. A malformed file is reported as MALFORMED. Unknown keys in the hermes TOML files are listed intoml.unknown_keysand asissueswith adid_you_meanhint, so--show-config --json | jq -e '.toml.unknown_keys == []'works as a CI config lint. - Legacy names.
deepagent-hermes.toml,DEEPAGENT_HERMES_*and thedeepagent-hermescommand still work and print a one-line deprecationnote:(silence withLANGSTAGE_SUPPRESS_LEGACY_NOTICE=1).
The full field list is in SPEC §2.