# Hermes — full corpus # Hermes Agent Knowledge Base LLM-maintained research KB on [Hermes Agent](https://github.com/NousResearch/hermes-agent) — used as the research backbone for YouTube videos and the "Complete Hermes Agent Masterclass" ## Structure - `raw/` — immutable source documents (transcripts, release notes, community pages) - `wiki/` — synthesized knowledge (summaries, concepts, entities, syntheses) Schema and maintenance rules: see `CLAUDE.md`. ## Usage - Add new sources: drop them into `raw/` and ask the LLM to "ingest" them - Ask questions: the LLM reads the wiki to synthesize answers with links - Draft video modules: ask "draft module on " to produce slide + script outlines sourced from the wiki ## Version Hermes Agent latest verified release: **v0.8.0 / v2026.4.8** (2026-04-08) Based on [llm-wiki-template](https://github.com/anthropics/llm-wiki-template) / Karpathy's LLM Wiki pattern. --- title: "Hermes Agent KB — Master Index" type: index updated: 2026-06-10 hermes_version: "v0.16.0" --- # Hermes Agent KB — Master Index **Latest verified Hermes version:** v0.16.0 / v2026.6.5 (2026-06-05) **KB pages:** 104 (22 summaries + 18 concepts + 56 entities + 6 syntheses + 2 system) ## Summaries ✅ (22/22) ### Video Transcripts (8) - [[summaries/transcript-did-hermes-kill-openclaw]] — "Did Hermes Agent just kill OpenClaw? (full guide)" - [[summaries/transcript-setup-tutorial-gemma]] — "Full Setup Tutorial (Gemma 4)" - [[summaries/transcript-why-hermes-replaced-openclaw]] — "Why The Hermes Agent Just Replaced OpenClaw (DGX Spark)" - [[summaries/transcript-247-self-evolving]] — "24/7 Self-Evolving AI Agent" - [[summaries/transcript-switching-to-hermes]] — "I am Switching to Hermes Agent" - [[summaries/transcript-hermes-full-course-2hr]] — "Hermes FULL COURSE 2 HOURS" - [[summaries/transcript-biggest-problem-openclaw]] — "Hermes Just Solved the Biggest Problem With OpenClaw" - [[summaries/transcript-live-masterclass-browser-qwen]] — "LIVE: Masterclass + Browser Agents + FREE Qwen 3.6" ### Release Notes (10) - [[summaries/release-v0.6.0]] — multi-instance release (2026-03-30) - [[summaries/release-v0.7.0]] — resilience release (2026-04-03) - [[summaries/release-v0.8.0]] — intelligence release (2026-04-08) - [[summaries/release-v0.9.0]] — everywhere release (2026-04-13) - [[summaries/release-v0.10.0]] — tool gateway release (2026-04-16) - [[summaries/release-v0.11.0]] — interface release (2026-04-23) - [[summaries/release-v0.12.0]] — curator release (2026-04-30) - [[summaries/release-v0.13.0]] — tenacity release (2026-05-07) - [[summaries/release-v0.14.0]] — foundation release (2026-05-16) - [[summaries/release-v0.15.0]] — velocity release (2026-05-28) + patches v0.15.1/v0.15.2 - [[summaries/release-v0.16.0]] — surface release (2026-06-05) — native desktop app, web admin panel **(latest)** ### Community / External (2) - [[summaries/community-resources]] — get-hermes.ai community page (25 projects) - [[summaries/awesome-hermes-agent]] — awesome-hermes-agent inventory (90+ projects) ## Concepts ✅ (18/18) ### Core Features - [[concepts/skills-system]] - [[concepts/memory-system]] - [[concepts/cli-reference]] — `hermes` terminal commands + the `config set` auto-routing rule - [[concepts/configuration-reference]] — `~/.hermes/` layout, config check/migrate after updates - [[concepts/cron-scheduling]] - [[concepts/subagents-delegation]] - [[concepts/mcp-integration]] - [[concepts/model-switching]] - [[concepts/auxiliary-models]] — 8 built-in side-task slots (vision, compression, web_extract, approval, mcp, title_generation, skills_hub, curator) + plugin-registered custom tasks (v0.15) - [[concepts/migration-from-openclaw]] - [[concepts/self-improvement-loop]] ### Infrastructure - [[concepts/deployment-backends]] - [[concepts/messaging-gateway]] - [[concepts/profiles-multi-instance]] - [[concepts/approval-system]] ### Research & ML - [[concepts/ml-research-pipeline]] - [[concepts/local-models-airplane-mode]] - [[concepts/onchain-workflows]] ## Entities (56 built, 10 platforms pending) ### Versions ✅ - [[entities/version-v0.6.0]], [[entities/version-v0.7.0]], [[entities/version-v0.8.0]], [[entities/version-v0.9.0]], [[entities/version-v0.10.0]], [[entities/version-v0.11.0]], [[entities/version-v0.12.0]], [[entities/version-v0.13.0]], [[entities/version-v0.14.0]], [[entities/version-v0.15.0]], [[entities/version-v0.16.0]] ### Deployment Backends ✅ (6/6 built) [[entities/backend-local]], [[entities/backend-docker]], [[entities/backend-modal]], [[entities/backend-ssh]], [[entities/backend-singularity]], [[entities/backend-daytona]], plus [[entities/hermes-desktop-app]] ### Messaging Platforms (12/22 built) **Built:** [[entities/platform-telegram]], [[entities/platform-discord]], [[entities/platform-slack]], [[entities/platform-whatsapp]], [[entities/platform-signal]], [[entities/platform-email]], [[entities/platform-matrix]], [[entities/platform-home-assistant]], [[entities/platform-dingtalk]], [[entities/platform-mattermost]], [[entities/platform-feishu]], [[entities/platform-wecom]] **Pending:** `platform-bluebubbles`, `platform-weixin`, `platform-wecom-callback`, `platform-qqbot`, `platform-yuanbao`, `platform-microsoft-teams`, `platform-google-chat`, `platform-line`, `platform-simplex`, `platform-sms` ### Memory Providers ✅ (8/8 built) [[entities/memory-honcho]], [[entities/memory-supermemory]], [[entities/memory-mem0]], [[entities/memory-retaindb]], [[entities/memory-hindsight]], [[entities/memory-byterover]], [[entities/memory-holographic]], [[entities/memory-openviking]] ### Inference Providers ✅ (6/6 built) [[entities/provider-nous-portal]], [[entities/provider-openrouter]], [[entities/provider-anthropic]], [[entities/provider-openai-codex]], [[entities/provider-google-ai-studio]], [[entities/provider-ollama-local]] ### Nous Research & Projects ✅ [[entities/nous-research]], [[entities/hermes-self-evolution]], [[entities/hermes-paperclip-adapter]], [[entities/autonovel]] ### Community Projects ✅ (7/7) - [[entities/community-orange-book]] (1.9k★, Chinese guide) - [[entities/community-awesome-hermes]] (curated ecosystem directory) - [[entities/community-mission-control]] (3.7k★, fleet orchestration) - [[entities/community-webui]] (Claude-style three-panel UI) - [[entities/community-workspace]] (1.1k★, most complete web GUI: chat, terminal, memory browser, skills manager) - [[entities/community-agency-agents-zh]] (5.8k★, 193 personas) - [[entities/community-gbrain]] (4.8k★, opinionated brain config) ### Ecosystem / Comparisons - [[entities/openclaw]] — the rival harness Hermes is constantly compared to and migrated from - [[summaries/skills-catalog]] — the 644-skill / 16-category map (78 built-in · 45 optional · 521 community) ## Syntheses ✅ (6/6) - [[syntheses/cron-troubleshooting-checklist]] — the four-category check order (timing/delivery/permissions/skill-loading) - [[syntheses/onchain-stack-recipe]] — onchain agent stack configuration recipe - [[syntheses/hermes-vs-openclaw]] — feature-by-feature comparison, "pick X if" recommendations - [[syntheses/memory-providers-compared]] — 8 memory backends across cost/hosting/features - [[syntheses/deployment-backends-compared]] — 6 backends across cost/isolation/persistence - [[syntheses/local-stack-playbook]] — end-to-end 100%-local configuration recipe --- ## Gaps / TODO All previously-pending platform, memory, provider, backend, and Nous-project entity pages were built 2026-06-10 (zero dangling wikilinks as of that date). What remains: ### Medium (write as content demands) - Remaining platform entities (10): bluebubbles, weixin, wecom-callback, qqbot, yuanbao, microsoft-teams, google-chat, line, simplex, sms - **`memory-memori` entity page** — the refreshed docs document a ninth memory provider (Memori Cloud, 5 tools, `hermes-memori` plugin); [[syntheses/memory-providers-compared]] includes it marked docs-only/unverified pending its page. - Refresh `memory-honcho`, `memory-mem0`, `memory-supermemory` (still v0.8.0-era; the other five memory pages and all 12 platform pages are now v0.16.0). - Staleness backlog: remaining pages with `hermes_version: "v0.8.0"` — re-verify when each topic comes up. The `raw/` docs mirrors were refreshed 2026-06-10 (v0.16.0-era) via `fetch_docs.py`, except 3 pages now 404 upstream (environments, rl-training, skills-godmode — still 2026-04-13 copies; the docs may have moved/renamed them). - Cross-check flagged: the messaging overview table (`raw/docs-user-guide-messaging.md`) says WhatsApp voice "—" while the WhatsApp platform docs describe STT-in / MP3-out; platform page follows the per-platform doc. ### Low (nice-to-have) - More community project entities beyond the top 7 - Per-skill entity pages for notable community skills (avoid-ai-writing, drawio-skill, etc.) **How to fill:** ask the LLM to "build entity page for ``" — it will read relevant raw sources + existing concept pages, write to schema, and link back. --- title: "Approval System" type: concept tags: [tools, gateway, foundational, well-established, advanced] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/04-tools-mcp-cron-subagents.md"] confidence: high hermes_version: "v0.8.0" --- # Approval System ## Definition The **approval system** is Hermes' guardrail against catastrophic shell commands. Every `terminal` and `process` invocation is matched against a hand-curated list of **`DANGEROUS_PATTERNS`** (~30+ regex pairs covering recursive `rm`, `chmod 777`, `mkfs`, `dd`, SQL `DROP`/`TRUNCATE`, fork bombs, `bash -c` shell escapes, `curl|sh` pipes, `kill -9 -1`, `git reset --hard`, `git push --force`, writes to `/etc/`, `~/.ssh/`, `~/.hermes/.env`, and self-termination via `pkill`). When a match fires the agent must either receive explicit approval, hit a permanent allowlist, or run inside a sandboxed [[concepts/deployment-backends]] backend that auto-bypasses the prompt. Implementation lives in `tools/approval.py` (~923 lines). ## How It Works Before a command executes, Hermes calls `_normalize_command_for_detection()` — strips ANSI escapes, removes null bytes, and applies **Unicode NFKC normalization**. NFKC collapses lookalike Unicode characters (e.g. fullwidth slashes, mathematical bold letters) so an attacker can't sneak `rm -rf /` past the regex by writing it with exotic glyphs. The normalized string is then matched against `DANGEROUS_PATTERNS`. If a pattern matches, the configured **approval mode** decides what happens next. ### Four approval modes Set under `approvals.mode` in `~/.hermes/config.yaml`: - **`manual`** (default) — CLI prompt offering `[o]nce / [s]ession / [a]lways / [d]eny`, with a 60-second timeout. On the gateway, the choice surfaces as a **native UI**: - Telegram — emoji reactions plus inline buttons (added in v0.8.0) - Slack — thread-preserving inline buttons (added in v0.8.0) - Feishu — interactive cards (added in v0.8.0) - **`smart`** — an auxiliary LLM (`_smart_approve()`) returns `APPROVE`, `DENY`, or `ESCALATE`. On `ESCALATE` (or any uncertainty) it falls back to the manual flow. - **`off`** — bypasses all checks. Equivalent to permanent yolo mode. - **`tirith`** — an external content-level policy layer (configured via `security.tirith_*` keys). Tirith findings are advisory and **cannot be permanently allowlisted**; they re-fire every run. ### Allowlist persistence Choosing `[a]lways` (or its native-UI equivalent) calls `save_permanent_allowlist()`, which appends the normalized command pattern to **`command_allowlist:`** in `config.yaml`. The list is reloaded at startup, so future runs of the same command skip the prompt entirely. `[s]ession` adds it to the in-memory allowlist for the current process / chat session only; `[o]nce` is fire-and-forget. ### `/yolo` — bypassing approvals Two scopes: - **CLI flag `--yolo`** — sets `HERMES_YOLO_MODE=1` in the process environment. Process-scoped — once `hermes chat` exits, yolo is gone. - **Gateway `/yolo` slash command** — toggles `is_session_yolo_enabled(session_key)` in a thread-safe in-memory map. Session-scoped per `(platform, chat_id)`; one chat can be yolo while another is strict. ### Auto-bypass on sandboxed backends When `terminal.backend` is `docker`, `singularity`, `modal`, or `daytona`, the approval prompt is **skipped entirely** — the rationale is that the host filesystem isn't reachable, so the worst case is a wrecked container. Only `local` and (depending on configuration) `ssh` backends trigger the full approval flow. See [[concepts/deployment-backends]]. ## Key Parameters Top-level `approvals` section in `config.yaml`: - `approvals.mode` — `manual | smart | off | tirith` - `command_allowlist:` — list of permanently approved commands (managed via `[a]lways` choice) - `security.tirith_enabled`, `security.tirith_path`, `security.tirith_timeout`, `security.tirith_fail_open` — Tirith layer config Env / runtime: - `HERMES_YOLO_MODE` — set by `--yolo` flag - `/yolo` — gateway slash command (per-session toggle) - `/approve` and `/deny` — inline-dispatched on the gateway (bypass the background task system so they cannot be deduped) `DANGEROUS_PATTERNS` examples (non-exhaustive, ~30+ regex pairs total): - Recursive `rm -rf /`, `rm -rf ~`, etc. - `chmod 777` and other world-writable mode bits - `mkfs` (filesystem format) - `dd` (raw device write) - SQL `DROP TABLE`, `DROP DATABASE`, `TRUNCATE` - Fork bombs `:(){ :|:& };:` - `bash -c` shell escapes hiding command intent - `curl … | sh`, `wget … | bash` install pipes - `kill -9 -1`, `pkill` self-termination - `git reset --hard`, `git push --force` (destructive history rewrites) - Writes to `/etc/`, `~/.ssh/`, `~/.hermes/.env` ## When To Use - **Default `manual` mode for personal use** — the 60s prompt is the right tradeoff between friction and safety. - **`smart` mode for high-volume agents** — an auxiliary cheap LLM clears obviously-safe commands (e.g. `rm` of a generated tmp file the agent itself just wrote), only escalating ambiguous cases. - **`off` or `--yolo` for sandboxed dev loops** — pair with a Docker or Modal backend so the worst case is a destroyed container, never the host. - **`tirith` layer when policy is content-based** — e.g. forbidding any command that touches a regulated data path; advisory findings stay sticky. - **Permanent allowlist for repetitive trusted commands** — `[a]lways`-approving your own `npm test` saves dozens of prompts per day. - **`/yolo` per-session on the gateway** — let the Telegram coding chat be yolo while the email channel stays strict. ## Risks & Pitfalls - **Pattern coverage is heuristic, not exhaustive.** Novel destructive commands can slip through; `manual` mode is your last line of defence. - **Permanent allowlists are durable.** A command added once stays approved across all future sessions. Audit `command_allowlist:` periodically. - **Sandboxed-backend auto-bypass means the host is safe but the container isn't.** Don't mount sensitive host volumes read-write into a yolo container. - **`/yolo` on a gateway session is sticky** until you toggle it back or the session resets (`session_reset` defaults to 1440 min idle). Easy to forget. - **Smart mode adds latency and cost** per command — auxiliary LLM call on every dangerous match. - **Tirith findings can't be allowlisted** — designed for compliance scenarios but can be surprising if you expect "always approve" to stick. - **Unicode obfuscation is mostly mitigated** by NFKC, but very new Unicode tricks may still bypass the regex; treat the system as defence-in-depth, not a perimeter. - **Approval prompts on the gateway can be missed** if no operator is watching the chat — the 60s timeout then denies the command. - **`/approve` and `/deny` inline-dispatch** intentionally bypass the background task system. Don't expect them to show up in `/queue`. ## Related Concepts - [[concepts/deployment-backends]] — sandboxed backends auto-bypass approval - [[concepts/messaging-gateway]] — native approval UI lives on Telegram, Slack, Feishu - [[concepts/profiles-multi-instance]] — `command_allowlist` is per-profile - [[concepts/skills-system]] — skill-defined commands also pass through approval - [[concepts/subagents-delegation]] — subagents inherit the parent's approval mode - [[entities/version-v0.8.0]] — release that added native approval buttons ## Sources - `raw/04-tools-mcp-cron-subagents.md` (Section A3, "Dangerous Command Approval") - Source files referenced: `tools/approval.py` (923 lines) --- title: "Auxiliary Models — Dedicated Providers for 8 Built-in Side Tasks" type: concept tags: [provider, model-switching, cost-optimization, foundational] created: 2026-04-13 updated: 2026-06-01 sources: ["raw/docs-user-guide-configuration.md", "raw/docs-developer-guide-provider-runtime.md", "raw/docs-developer-guide-adding-providers.md", "raw/docs-developer-guide-architecture.md", "raw/docs-developer-guide-agent-loop.md", "raw/release-v0.15.0.md"] confidence: high hermes_version: "v0.15.0" --- # Auxiliary Models — Dedicated Providers for 8 Built-in Side Tasks > **Roster history (read first):** The set of auxiliary tasks has changed across releases. As of **v0.15.0** the eight built-in slots are **`vision`, `compression`, `web_extract`, `approval`, `mcp`, `title_generation`, `skills_hub`, `curator`**. Earlier KB notes listed `flush_memories` (replaced by `curator` in v0.12) and `session_search` (removed in v0.15 — it is now a free, no-LLM FTS5 tool, not an aux-model task). Plugins can register *additional* custom aux tasks via `register_auxiliary_task()` (v0.15), so the set is no longer fixed at exactly eight. ## Definition Hermes routes a set of internal "side tasks" through a separate, user-configurable model path — the **auxiliary model system**. Instead of burning your main agent's (expensive) model on every image analysis, web page summary, or context compression, you can point each task slot at its own provider and model — typically a cheap/fast one. By default Hermes auto-detects the first available provider from a short chain and uses Gemini Flash for everything. There are **eight built-in slots** (below) plus any custom slots a plugin registers. ## How It Works When an auxiliary task fires (e.g. the agent opens an image, the context compressor kicks in, a skill match is scored), the main agent's runtime doesn't handle it. Control passes to `agent/auxiliary_client.py`, which looks at the `auxiliary:` block in `~/.hermes/config.yaml` (or env var overrides) to resolve: 1. **Which provider** to use (`provider: auto` walks a chain; a named provider is used directly; `base_url` short-circuits both) 2. **Which model** to request (provider's default if unspecified; Gemini Flash in the `auto` path) 3. **Which auth** to use (`api_key`, or `OPENAI_API_KEY` as a fallback for custom `base_url`) 4. **How long to wait** (the `timeout` field) The resulting aux request runs on its own HTTP client, independent of the main conversational model — so it cannot "steal" context from the main chat, nor does its usage count against the main model's rate limits. ### The `auto` resolution chain Per the docs: *"Uses the first available provider (OpenRouter → Nous → Codex) with Gemini Flash."* In practice the chain prefers aggregator providers first (cheap, many models available), then Nous Portal, then Codex OAuth. If the user has none of these configured and no `base_url` override, Hermes will fail the aux call. ### Independence from main-agent routing Per `docs-developer-guide-provider-runtime.md`: *"Auxiliary tasks use their own independent provider auto-detection chain."* They share the same underlying transport infrastructure (`resolve_provider_client()`) but maintain separate credential bundles, timeouts, and retry behavior. ## Key Parameters ### The 8 built-in auxiliary task slots (v0.15) | Slot | What it does | Default timeout | |---|---|---| | `vision` | Image analysis (`vision_analyze` tool + browser screenshots) | 30s (+30s image download) | | `web_extract` | Web page summarization + browser text extraction | 360s | | `approval` | Dangerous command classifier (powers `approvals.mode: smart`) | 30s | | `compression` | Summarizes middle turns of long conversations. Model/provider set HERE (`auxiliary.compression.provider/model`); the top-level `compression:` block holds thresholds only | 120s | | `title_generation` | Auto-names sessions (the v0.15 slot that replaced `session_search`) | 30s | | `skills_hub` | Skill matching and search | 30s | | `mcp` | MCP tool dispatch helper | 30s | | `curator` | Autonomous skill/memory maintenance (v0.12 swap-in for the old `flush_memories`) | 30s | > **No longer aux:** `session_search` was a slot through v0.14 but was rebuilt in **v0.15** into a single three-mode (discovery/scroll/browse) FTS5 tool with **no LLM, no cost, ~20ms** — so it no longer consumes an auxiliary model. Don't bill it as an aux cost item. ### Plugin-registered custom tasks (v0.15) Plugins can add their own auxiliary tasks via `PluginContext.register_auxiliary_task(key=..., display_name=..., description=..., defaults={...})`. The eight built-in keys above are **reserved** (registering one raises `ValueError`). A custom task's `defaults` accept `provider` (default `"auto"`), `model` (default `""`), `timeout` (default 60), and `extra_body`. This means the auxiliary set is extensible — "8" is the built-in floor, not a hard ceiling. ### Layered fallback (v0.15) Auxiliary calls now degrade through a ladder on capacity errors (402 / 429 / connection): **primary → resolution chain → main agent → graceful fail.** This is resilience, not routing — there is still no per-tool/per-complexity rule engine. ### The 5 config knobs per slot ```yaml auxiliary: vision: provider: "auto" # "auto" | "openrouter" | "nous" | "codex" | "copilot" | "anthropic" | "main" | "zai" | "kimi-coding" | "minimax" | model: "" # e.g. "openai/gpt-4o", "google/gemini-2.5-flash" — empty = provider default base_url: "" # Custom OpenAI-compatible endpoint; overrides provider when set api_key: "" # Key for base_url (falls back to OPENAI_API_KEY) timeout: 30 # Seconds; raise for slow local models download_timeout: 30 # vision only — HTTP image download ``` ### The `"main"` special value `provider: "main"` means "use whatever provider my main agent uses." It is valid **only** inside `auxiliary:`, `compression:`, and `fallback_model:` configs. Not valid at the top-level `model.provider`. Useful when you've set up a custom endpoint as your main model and want auxiliary tasks to share the same endpoint. ### Env var overrides (legacy, vision + web_extract only) ``` AUXILIARY_VISION_PROVIDER AUXILIARY_VISION_MODEL AUXILIARY_VISION_BASE_URL AUXILIARY_VISION_API_KEY AUXILIARY_WEB_EXTRACT_PROVIDER AUXILIARY_WEB_EXTRACT_MODEL AUXILIARY_WEB_EXTRACT_BASE_URL AUXILIARY_WEB_EXTRACT_API_KEY ``` The other 6 slots are `config.yaml`-only. ### Compression has TWO config blocks (corrected v0.15) This is the number-one footgun — and the direction is the opposite of what older docs implied: - **Top-level `compression:`** — `enabled`, `threshold`, `target_ratio`, `protect_last_n`, `protect_first_n`. This block controls **behavior/thresholds only**, NOT the model. - **`auxiliary.compression:`** — `provider`, `model`, `base_url`, `timeout` (default 120s). This is where you set **which model does the summarization** — same shape as every other aux task. Defaults to `auto` → your main chat model. - The legacy keys `compression.summary_provider` / `summary_model` / `summary_base_url` are **auto-migrated to `auxiliary.compression.*` on first load (config version 17)**. Don't author new configs with them. Source: `cli-config.yaml.example` (compression block has no summary_* keys; comment points to `auxiliary.compression`) + `website/docs/user-guide/configuration.md` lines 646, 937. ## When To Use **Default (`auto`): routes to your main chat model.** Per `configuration.md`, `auxiliary.*.provider: "auto"` sends each side task to your main provider/model. Fine if your main is cheap/local; on an expensive main model (Opus, etc.) explicitly point aux tasks at a cheap model (e.g. Gemini Flash on OpenRouter) to avoid inflating cost. **Override when:** - Your main model is expensive (Opus, GPT-5) and you're watching auxiliary usage inflate your bill. Route `compression` + `curator` + `title_generation` to Gemini Flash or a cheap Haiku/Kimi variant. (Note: `session_search` no longer costs anything — it's a free FTS5 tool since v0.15.) - Your main model isn't multimodal but you want vision. Point `auxiliary.vision` at GPT-4o or a dedicated vision model. - You're running airplane-mode locally and want all aux tasks on a local `base_url` (Ollama, vLLM, llama.cpp). See [[syntheses/local-stack-playbook]]. - You want separation of duties — e.g. `approval` on a dedicated heavier model for better dangerous-command judgment. - Your main model is rate-limited and you want aux tasks on a different credential pool. ## Risks & Pitfalls - **Vision requires a multimodal model.** Setting `provider: "main"` without checking multimodal capability breaks image analysis silently. Check before swapping. - **The two-compression-blocks footgun.** Swap the compression model under `auxiliary.compression.provider/model` — the same shape as every other aux task. The top-level `compression:` block is thresholds/behavior only; putting a model there (`compression.summary_model`) hits a legacy path that auto-migrates. (Older KB notes had this reversed.) - **Credential gaps in `auto`.** If the chain (OpenRouter → Nous → Codex) finds no credentials, aux calls fail and the feature that triggered them (e.g. vision, compression) fails too. (As of v0.15, layered fallback softens this — primary → chain → main agent → graceful fail.) - **Slow local models + default 30s timeout.** Vision on a local 8B multimodal may exceed 30s. Raise the `timeout`. - **`base_url` overrides provider.** If both are set, `base_url` wins and `provider` is ignored. Easy to forget when debugging. - **Aux is not covered by the main `fallback_model` system.** The main-agent fallback chain does not apply to aux calls. Each aux task does its own resolution. - **Env var overrides only work for vision and web_extract.** Don't try `AUXILIARY_MCP_MODEL` — it won't be read. ## Related Concepts - [[concepts/model-switching]] — the main-agent `/model` system; auxiliary is a parallel track - [[concepts/approval-system]] — the `approvals.mode: smart` mode is powered by `auxiliary.approval` - [[concepts/mcp-integration]] — the `auxiliary.mcp` slot helps dispatch MCP tool calls - [[concepts/memory-system]] — memory writes are handled by the `curator` slot (the v0.12 successor to the old `flush_memories`) - [[concepts/skills-system]] — `auxiliary.skills_hub` scores skill matches - [[syntheses/local-stack-playbook]] — routing all 8 aux slots to a local `base_url` is the local-stack completion - [[entities/version-v0.8.0]] — early aux behavior (402-fallback, vision auto-detection main-first) - [[entities/version-v0.15.0]] — roster change (session_search → title_generation), `register_auxiliary_task()`, layered fallback ## Sources - `raw/docs-user-guide-configuration.md` — primary reference for the config surface (§ Auxiliary Models) - `raw/docs-developer-guide-provider-runtime.md` — confirmation that auxiliary tasks use an independent resolution chain - `raw/docs-developer-guide-adding-providers.md` — `_API_KEY_PROVIDER_AUX_MODELS` table for per-provider default aux models - `raw/docs-developer-guide-architecture.md` — locates `agent/auxiliary_client.py` in the codebase - `raw/docs-developer-guide-agent-loop.md` — positions aux client in the run-agent call graph --- title: "CLI Reference — hermes Terminal Commands" type: concept tags: [cli, commands, reference] created: 2026-06-09 updated: 2026-06-10 confidence: high sources: [raw/docs-reference-cli-commands.md, raw/docs-user-guide-cli.md, raw/docs-reference-profile-commands.md, raw/docs-reference-slash-commands.md, raw/docs-user-guide-configuration.md] hermes_version: "v0.16.0" --- # CLI Reference — `hermes` Terminal Commands ## Definition The full surface of `hermes` commands you run from a shell. **In-chat slash commands** (`/model`, `/new`, `/background` … typed inside a CLI session or a messaging chat) are a separate surface driven by the same central `COMMAND_REGISTRY` in `hermes_cli/commands.py` — they are out of scope here; see `raw/docs-reference-slash-commands.md`. Some names exist on both surfaces (`hermes cron` vs `/cron`, `hermes model` vs `/model`): the terminal form manages state from outside a session, the slash form acts inside one. ## How It Works ``` hermes [global-options] [subcommand/options] ``` Bare `hermes` starts an interactive chat session. **Global options** (work in front of any command): | Option | Description | |---|---| | `--version`, `-V` | Show version and exit | | `--profile `, `-p` | Run under a specific profile (overrides the sticky default from `hermes profile use`) | | `--resume `, `-r` | Resume a previous session by ID or title | | `--continue [name]`, `-c` | Resume the most recent session (optionally matching a title) | | `--worktree`, `-w` | Start in an isolated git worktree (parallel agents) | | `--yolo` | Bypass dangerous-command approval prompts | | `--pass-session-id` | Include the session ID in the system prompt | | `--ignore-user-config` | Ignore `~/.hermes/config.yaml`, use built-in defaults (`.env` credentials still load) | | `--ignore-rules` | Skip auto-injection of `AGENTS.md`, `SOUL.md`, `.cursorrules`, memory, preloaded skills | | `--tui` / `--cli` | Force the React/Ink TUI or the classic prompt_toolkit REPL (`--tui` ≡ `HERMES_TUI=1`; both override `display.interface`) | | `--dev` | With `--tui`: run TS sources via `tsx` instead of the prebuilt bundle | ### Chat & sessions ``` hermes chat [options] ``` | Option | Description | |---|---| | `-q`, `--query "..."` | One-shot, non-interactive prompt | | `-m`, `--model ` | Override the model for this run | | `--provider ` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot-acp`, `copilot`, `anthropic`, `gemini`, `google-gemini-cli`, `huggingface`, `novita`, `openai-api`, `zai`, `kimi-coding`, `kimi-coding-cn`, `minimax`, `minimax-cn`, `minimax-oauth`, `kilocode`, `xiaomi`, `arcee`, `gmi`, `alibaba`, `alibaba-coding-plan`, `deepseek`, `nvidia`, `ollama-cloud`, `xai`, `xai-oauth`, `qwen-oauth`, `bedrock`, `opencode-zen`, `opencode-go`, `azure-foundry`, `lmstudio`, `stepfun`, `tencent-tokenhub` (some have aliases, e.g. `grok` → `xai`) | | `-t`, `--toolsets ` | Enable a comma-separated set of toolsets | | `-s`, `--skills ` | Preload skills (repeatable or comma-separated) | | `-v` / `-Q` | Verbose / quiet (programmatic) output | | `--image ` | Attach a local image to a single query | | `--checkpoints` | Filesystem checkpoints before destructive file changes | | `--ignore-user-config` / `--ignore-rules` | Isolated runs (see global options); combine both for fully clean repros | | `--source ` | Session source tag (default `cli`; use `tool` for integrations) | | `--max-turns ` | Max tool-calling iterations per turn (default 90, or `agent.max_turns`) | `--resume`, `--continue`, `--worktree`, `--yolo`, `--pass-session-id` also work directly on `chat`. ``` hermes chat -q "Summarize the latest PRs" hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6 hermes chat --quiet -q "Return only JSON" hermes -w -q "Fix issue #123" # isolated worktree hermes -s hermes-agent-dev,github-auth # preload skills ``` **`hermes -z `** — purest scripted one-shot: single prompt in, final reply text out, nothing else on stdout/stderr (no banner, spinner, tool previews, or `Session:` line). Takes `-m/--model` and `--provider` per-run overrides (or `HERMES_INFERENCE_MODEL`); reads stdin. Use `chat -q` instead if you want tool output in the transcript. ``` hermes sessions ``` `browse` = interactive picker with search/resume; `export [--session-id ID]` writes JSONL; `rename ` titles a session. Sessions live in SQLite at `~/.hermes/state.db`. ### Gateway service ``` hermes gateway <run|start|stop|restart|status|list|install|uninstall|setup> ``` | Subcommand | Description | |---|---| | `setup` | Interactive messaging-platform wizard | | `run [--no-supervise]` | Foreground (recommended for WSL, Docker, Termux); `--no-supervise` opts out of s6 auto-restart inside the Docker image | | `install` / `uninstall` | Install/remove the systemd (Linux) or launchd (macOS) service | | `start` / `stop` / `restart` / `status` | Manage the installed service; `--all` on start/stop/restart acts on **every profile's** gateway | | `list` | Cross-profile overview: each profile's gateway state with PID | WSL: use `hermes gateway run` (systemd is unreliable), e.g. `tmux new -s hermes 'hermes gateway run'`. See [[concepts/messaging-gateway]]. ### Platform pairing & access ``` hermes whatsapp # WhatsApp bridge: mode selection + QR-code pairing hermes slack manifest [--write [PATH]] [--name N] [--description D] [--slashes-only] hermes pairing <list|approve|revoke|clear-pending> ``` | Subcommand | Description | |---|---| | `list` | Show pending and approved users | | `approve <platform> <code>` | Approve a pairing code, e.g. `hermes pairing approve telegram XKGH5N7P` | | `revoke <platform> <user-id>` | Revoke a user's access | | `clear-pending` | Clear pending pairing codes | Unknown users who DM the bot receive a one-time code (expires after 1 hour, rate-limited). `hermes slack manifest` generates a Slack app manifest registering every gateway command as a native Slack slash command — re-run after `hermes update` to pick up new commands. ### Setup & config ``` hermes setup [model|tts|terminal|gateway|tools|agent] [--quick] [--non-interactive] [--reset] [--reconfigure] [--portal] hermes portal [status|open|tools] hermes config <show|edit|set|path|env-path|check|migrate> ``` `setup` runs the full wizard or one section; on an existing install it reconfigures by default (`--quick` = only prompt for missing items). `hermes setup --portal` is the one-shot easiest path: OAuth into Nous Portal + opt into the Tool Gateway. `hermes portal` (default `status`) shows Portal auth + per-tool Tool Gateway routing; `open` launches the subscription page; `tools` lists gateway partners. `config edit` opens `config.yaml`; `config check` finds missing/stale options after updates; `config migrate` adds newly introduced options interactively; `config path` / `config env-path` print file locations. See [[concepts/configuration-reference]]. ### Models, providers & auth ``` hermes model # interactive provider + model selector (add providers, OAuth, API keys) hermes fallback [list|add|remove|clear] hermes auth <add|list|remove|reset|status|logout|spotify> hermes proxy <start|status|providers> hermes secrets bitwarden <setup|status|sync|install|disable> # alias: bw ``` `hermes model` switches default providers, handles OAuth logins (Codex/Nous/Anthropic/Copilot), and configures custom/self-hosted endpoints; the choice persists to `config.yaml`. `hermes login` / `hermes logout` are **removed** — use `hermes auth`. Mid-session switching is the `/model` slash command ([[concepts/model-switching]]). ``` hermes auth add openrouter --api-key sk-or-v1-xxx hermes auth add anthropic --type oauth hermes auth status anthropic && hermes auth logout anthropic hermes auth reset openrouter # clear cooldowns ``` `fallback` manages the provider chain tried on rate-limit/overload/connection errors (`add` uses the same picker as `hermes model`). `proxy start [--provider nous|xai] [--host 127.0.0.1] [--port 8645]` runs a local OpenAI-compatible endpoint that attaches your real OAuth credentials to outbound requests. `secrets bitwarden` pulls API keys from Bitwarden Secrets Manager at startup instead of `~/.hermes/.env` (`sync --apply` to export now). ### Profiles, backup & restore ``` hermes profile <list|use|create|describe|delete|show|alias|rename|export|import|install|update|info> hermes backup [-o PATH] [--quick] [--label NAME] hermes import <zipfile> [--force] hermes checkpoints [status|list|prune|clear|clear-legacy] ``` | Subcommand | Description | |---|---| | `list` / `use <name>` | List profiles (`*` = active) / set the sticky default | | `create <name> [--clone] [--clone-all] [--clone-from <src>] [--no-alias] [--description "..."] [--no-skills]` | New profile; `--clone` copies config + `.env` + `SOUL.md`, `--clone-all` copies everything; `--no-skills` = empty profile with zero bundled skills | | `describe [<name>] [--text "..."] [--auto] [--all] [--overwrite]` | Read/set a profile description (used by the kanban orchestrator for routing); `--auto` generates one via the auxiliary LLM | | `delete <name> [-y]` | Permanently delete (cannot delete the active profile) | | `show <name>` / `rename <old> <new>` | Inspect / rename | | `alias <name> [--remove] [--name ALIAS]` | Manage the `~/.local/bin/<name>` wrapper script | | `export <name> [-o FILE]` / `import <archive> [--name NAME]` | **Local backup/restore** of a profile as `.tar.gz` | | `install <source> [--name N] [--alias] [--force] [-y]` | Install a **profile distribution** from a git URL or local dir (`distribution.yaml` manifest; `.env`/`auth.json` never shipped) | | `update <name> [--force-config] [-y]` | Re-pull a distribution; user data (memories, sessions, auth) never touched | | `info <name>` | Show a profile's distribution manifest (version, requirements, source, install date) | `hermes backup` zips the whole Hermes home (WAL-safe via SQLite `backup()`; `--quick` = critical state files only); top-level `hermes import <zip>` restores it — stop the gateway first. `hermes checkpoints` inspects/prunes/clears the shadow git store at `~/.hermes/checkpoints/` behind `/rollback` (`prune --retention-days N --max-size-mb N`). See [[concepts/profiles-multi-instance]]. ``` hermes profile export work -o work-backup.tar.gz hermes profile install github.com/user/my-distro --alias hermes -p work chat -q "Hello from work profile" ``` ### Skills ``` hermes skills <browse|search|install|inspect|list|check|update|audit|uninstall|reset|opt-out|opt-in|publish|snapshot|tap|config> hermes bundles <list|show|create|delete|reload> hermes curator <status|run|backup|rollback|pause|resume|pin|unpin|restore|archive|prune|list-archived> ``` ``` hermes skills search react --source skills-sh hermes skills search https://mintlify.com/docs --source well-known hermes skills install https://sharethis.chat/SKILL.md --name my-skill # direct single-file SKILL.md URL hermes skills install skills-sh/anthropics/skills/pdf --force hermes skills reset google-workspace --restore # un-stick a user_modified bundled skill hermes skills opt-out --remove --yes # stop bundled-skill seeding; delete unmodified ones hermes skills config # per-platform enable/disable UI ``` `--force` overrides non-dangerous policy blocks only — never a `dangerous` scan verdict. Sources: `official`, `skills-sh`, `well-known` (sites exposing `/.well-known/skills/index.json`), `browse-sh` (200+ site-specific browser-automation skills). `bundles` groups several skills under one `/<bundle-name>` slash command (`create --skill <id>` repeatable; stored in `~/.hermes/skill-bundles/`). `curator` is the auxiliary-model background skill maintainer — `run --dry-run` previews, `backup`/`rollback` snapshot `~/.hermes/skills/`, `pin` exempts a skill; bundled and hub skills are never touched. See [[concepts/skills-system]]. ### Plugins, MCP & tools ``` hermes plugins [install <id> [--force]|update|remove|enable|disable|list] hermes mcp [picker|catalog|install <name>|serve|add|remove|list|test|configure|login] hermes tools [--summary] hermes lsp <status|list|install <id>|install-all|restart|which <id>> hermes computer-use <install [--upgrade]|status> ``` Bare `hermes plugins` opens a composite UI: general plugin toggles + provider plugins (Memory Provider, Context Engine — saved to `memory.provider` / `context.engine` in `config.yaml`). Bare `hermes mcp` opens the Nous-approved catalog picker; `catalog` lists it scriptably; `install <name>` installs an entry; `add <name> [--url URL] [--command CMD] [--auth oauth|header]` adds a custom server with auto tool discovery; `login <name>` forces OAuth re-auth; `serve` exposes Hermes itself as an MCP server ([[concepts/mcp-integration]]). `hermes tools` without `--summary` opens the per-platform tool configuration UI. `lsp` manages background language servers (pyright, gopls, …) feeding diagnostics into `write_file`/`patch` post-write checks. `computer-use` installs/checks the macOS cua-driver backend. ### Memory ``` hermes memory <setup|status|off> ``` `memory setup` selects one external provider (honcho, openviking, mem0, hindsight, holographic, retaindb, byterover, supermemory); built-in `MEMORY.md`/`USER.md` memory is always active. An active provider may register its own top-level command (e.g. `hermes honcho` when Honcho is active) — inactive providers expose nothing. See [[concepts/memory-system]]. ### Automation — cron, webhooks, kanban, hooks, send ``` hermes cron <list|create|edit|pause|resume|run|remove|status|tick> hermes webhook <subscribe|list|remove|test> hermes kanban [--board <slug>] <action> hermes hooks <list|test <event>|revoke|doctor> hermes send --to <platform[:chat_id]> "message" ``` `cron create` (alias `add`) builds a job from a prompt, with repeatable `--skill`; `cron edit` supports `--clear-skills`, `--add-skill`, `--remove-skill`; `cron tick` runs due jobs once and exits ([[concepts/cron-scheduling]]). `hermes webhook subscribe <name>` takes `--prompt` (with `{dot.notation}` payload refs), `--events`, `--skills`, `--deliver log|telegram|discord|slack|github_comment`, `--deliver-chat-id`, `--secret` (HMAC auto-generated if omitted), and `--deliver-only` (skip the agent, deliver the rendered prompt literally — zero LLM cost). Subscriptions persist to `~/.hermes/webhook_subscriptions.json` and hot-reload without a gateway restart. `kanban` is the multi-profile collaboration board (human/scripting surface; agent workers use the `kanban_*` toolset instead). Board management: `boards <list|create|switch|show|rename|rm>`; one SQLite DB per board, dispatcher sweeps all boards. Task actions: `init`, `create "<title>"` (`--assignee`, `--parent`, `--workspace`, `--priority`, `--skill` …), `list`, `show`, `assign`, `link`/`unlink`, `claim`, `comment`, `complete`, `block`/`schedule`/`unblock`, `archive`, `tail`, `dispatch`, `context`, `specify`, `decompose`, `gc`. Board resolution: `--board` flag → `HERMES_KANBAN_BOARD` env → `~/.hermes/kanban/current` → `default`. `hooks` inspects/tests/approves shell-script hooks declared in `config.yaml` (consent allowlist at `~/.hermes/shell-hooks-allowlist.json`). `send` posts a one-shot message to a configured platform with **no agent loop and no LLM** — reuses gateway credentials, talks directly to bot-token platform REST APIs (no running gateway needed for Telegram/Discord/Slack/Signal/SMS/WhatsApp-CloudAPI). Options: `--to platform[:chat_id[:thread_id]]` or `platform:#channel`, `--file PATH` (or stdin), `--subject`, `--list [platform]`, `--quiet`, `--json`. Exit codes: 0 success, 1 delivery failure, 2 usage error. ### Diagnostics & observability ``` hermes status [--all] [--deep] # agent/auth/platform status (--all = redacted shareable) hermes doctor [--fix] # diagnose config + dependencies, optionally auto-repair hermes dump [--show-keys] # plain-text setup summary for support threads hermes debug share [--lines N] [--expire DAYS] [--local] hermes logs [agent|errors|gateway|gui|desktop|list] [-n N] [-f] [--level LEVEL] [--session ID] [--since 30m|1h|2d] [--component NAME] hermes insights [--days N] [--source cli|telegram|discord|...] hermes prompt-size [--platform <name>] [--json] hermes security audit [--json] [--fail-on low|moderate|high|critical] [--skip-venv] [--skip-plugins] [--skip-mcp] ``` ``` hermes logs gateway -n 100 hermes logs --level WARNING --since 1h hermes logs errors --since 30m -f ``` Log files live in `~/.hermes/logs/` (rotated: `agent.log.1`, …); filters combine with AND; new log names `gui` (dashboard/TUI/PTY-bridge) and `desktop` (Electron app). `dump` covers version/commit, environment, profile, model, terminal backend, presence of all 22 API keys, services, cron/skill counts, and config overrides. `debug share` uploads a redacted report (system info + recent logs, keys always redacted) to paste.rs/dpaste.com; `--local` prints instead. `prompt-size` breaks down the fixed per-call prompt budget (skills index, memory, profile, tool schemas) entirely offline. `security audit` is the on-demand OSV.dev supply-chain scan of the venv, plugin requirements, and pinned MCP servers. ### Integration surfaces ``` hermes acp # ACP stdio server for editors (pip install -e '.[acp]') hermes dashboard [--port 9119] [--host 127.0.0.1] [--no-open] [--insecure] [--stop] [--status] hermes completion [bash|zsh|fish] # shell completion (covers subcommands + profile names) ``` `dashboard` (requires `hermes-agent[web]`; browser Chat tab needs the `pty` extra) replaces the former `hermes web` name; `--stop`/`--status` manage running dashboard processes. ### Migration & maintenance ``` hermes claw migrate [--dry-run] [--preset full|user-data] [--migrate-secrets] [--overwrite] [--no-backup] [--source <path>] [--workspace-target <path>] [--skill-conflict skip|overwrite|rename] [--yes] hermes migrate xai [--apply] [--no-backup] hermes version hermes update [--check] [--backup] [--no-backup] [--yes] hermes uninstall [--full] [--gui] [--yes] ``` `claw migrate` imports an OpenClaw setup (30+ categories) — **secrets are never imported unless `--migrate-secrets` is passed, even under `--preset full`**; a pre-migration zip snapshot is taken by default. See [[concepts/migration-from-openclaw]]. Top-level `hermes migrate` (distinct from `claw migrate`) rewrites `config.yaml` to replace retired models/settings — currently `xai`; dry-run by default, `--apply` to write. `update` handles both git installs (pull + reinstall) and pip installs (PyPI upgrade); `--check` previews, `--backup` snapshots `HERMES_HOME` first (off by default; `updates.pre_update_backup: true` to always); running gateways restart automatically after success. `postinstall` is an internal idempotent bootstrap for non-Python deps after pip installs. `uninstall --full` also deletes config/data; `--gui` removes only the desktop Chat GUI. ## Key Parameters ### The `config set` routing rule (worth knowing) `hermes config set` **routes values to the right file automatically** — API keys go to `~/.hermes/.env`, everything else to `config.yaml`: ``` hermes config set model anthropic/claude-opus-4 hermes config set terminal.backend docker hermes config set OPENROUTER_API_KEY sk-or-... # → .env ``` ### Defaults worth memorizing - `hermes chat --max-turns` default **90** (`agent.max_turns`) - `hermes logs` default **50 lines**, `agent.log` - `hermes dashboard` default **port 9119**, bind `127.0.0.1` - `hermes proxy start` default **port 8645**, provider `nous` - `hermes insights` default window **30 days** - `hermes debug share` default **200 lines/log, 7-day expiry** - `hermes checkpoints prune` default **7-day retention, 500 MB cap** - `hermes security audit --fail-on` default **critical** - Pairing codes expire after **1 hour** ## When To Use - **Daily driving:** bare `hermes`, `hermes -c` to pick up where you left off, `hermes chat -q` for one-shots; `hermes -z` when a script needs only the final answer text. - **Running a bot 24/7:** `hermes gateway setup` → `install` → `start`; `hermes pairing approve` to admit users; `hermes gateway list` to survey multiple profiles. - **Switching models/providers:** `hermes model` (default), `/model` (mid-session), `hermes fallback` for automatic failover. - **Parallel/isolated instances:** `hermes profile create work --clone` + `hermes -p work …`. - **Backups:** `hermes backup` (whole home) or `hermes profile export` (one profile) before risky upgrades; `hermes import` / `profile import` to restore. - **Sharing a setup:** `hermes profile install <git-url>` consumes a profile distribution. - **Troubleshooting:** `hermes doctor --fix` → `hermes logs -f` → `hermes dump` or `hermes debug share` for support threads. ## Risks & Pitfalls - **`hermes login` is removed** — older tutorials referencing it should be read as `hermes auth` / `hermes model` / `hermes setup`. - **`hermes web` is now `hermes dashboard`** — the old name no longer appears in the docs. - **`claw migrate` never imports secrets without `--migrate-secrets`** — `--preset full` alone is not enough (this changed from earlier behavior where `full` included secrets). - **Two different `migrate` commands:** `hermes migrate` rewrites config for retired models; `hermes claw migrate` imports from OpenClaw. - **WSL:** `hermes gateway start` relies on systemd and misbehaves — use `gateway run` under tmux. - **`hermes profile delete` is permanent** (config, memories, sessions, skills) and refuses to delete the active profile. - **`hermes uninstall --full` deletes all config/data**, not just the program. - **`skills install --force` cannot override a `dangerous` audit verdict** — only softer policy blocks. - **Stop the gateway before `hermes import`** — restoring a backup over a running install conflicts with live processes. ## Related Concepts - [[concepts/configuration-reference]] — what the keys set by `hermes config set` mean - [[concepts/messaging-gateway]] — what `hermes gateway` / `hermes pairing` / `hermes whatsapp` manage - [[concepts/cron-scheduling]] — `hermes cron` in depth - [[concepts/profiles-multi-instance]] — `hermes profile` in depth - [[concepts/skills-system]] — `hermes skills` in depth - [[concepts/model-switching]] — `hermes model` vs `/model` - [[concepts/memory-system]] — `hermes memory` and provider plugins - [[concepts/mcp-integration]] — `hermes mcp` - [[concepts/migration-from-openclaw]] — `hermes claw migrate` - [[concepts/approval-system]] — what `--yolo` bypasses ## Sources - `raw/docs-reference-cli-commands.md` (primary — full per-command options; fetched 2026-06-10, v0.16.0-era) - `raw/docs-user-guide-cli.md` (chat options, sessions, keybindings context; fetched 2026-06-10) - `raw/docs-reference-profile-commands.md` (profile/describe/distributions/completion detail; fetched 2026-06-10) - `raw/docs-reference-slash-commands.md` (CLI-vs-in-chat boundary only) - `raw/docs-user-guide-configuration.md` (`config set` routing rule) <!-- ===== hermes/wiki/concepts/configuration-reference.md ===== --> --- title: "Configuration Reference — ~/.hermes/ Layout & Management" type: concept tags: [configuration, config-yaml, env, reference] updated: 2026-06-09 confidence: high sources: [raw/docs-user-guide-configuration.md] --- # Configuration Reference — `~/.hermes/` All settings live under **`~/.hermes/`**: ``` ~/.hermes/ ├── config.yaml # settings (model, terminal, TTS, compression, …) ├── .env # API keys and secrets ├── auth.json # OAuth provider credentials (Nous Portal, etc.) └── … ``` ## Managing configuration ``` hermes config # view current configuration hermes config edit # open config.yaml in your editor hermes config set K V # set a value (auto-routes: keys → .env, rest → config.yaml) hermes config check # find missing options (run after updates) hermes config migrate # interactively add missing options ``` **After updating Hermes, run `hermes config check`** — new versions add options; `migrate` fills them interactively. Full option tables: `raw/docs-user-guide-configuration.md`. Related: [[concepts/cli-reference]] · [[concepts/auxiliary-models]]. <!-- ===== hermes/wiki/concepts/cron-scheduling.md ===== --> --- title: "Cron & Scheduling" type: concept tags: [cron, tools, agent-loop, foundational, well-established] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/04-tools-mcp-cron-subagents.md", "raw/release-v0.8.0.md"] confidence: high hermes_version: "v0.8.0" --- # Cron & Scheduling ## Definition Hermes' cron system lets the agent run itself on a schedule — a persistent, in-process scheduler that turns any natural-language prompt into a recurring or one-shot job. A tick runs every 60 seconds inside the gateway, fires due jobs as fresh agent turns, delivers the response to any configured messaging channel, and archives the output locally. It is implemented by `/cron/jobs.py` (762 lines) and `/cron/scheduler.py` (990 lines). ## How It Works Jobs are stored in `~/.hermes/cron/jobs.json` (directory mode 0700, file mode 0600, atomic rewrites). Output from each run is archived to `~/.hermes/cron/output/<job_id>/<timestamp>.md`. The gateway fires the scheduler every 60 seconds and a file lock `.tick.lock` prevents concurrent ticks. **Schedule syntax** (`parse_schedule()`) accepts four kinds: - **Duration one-shot** — `"30m"`, `"2h"`, `"1d"` (fires once after that duration) - **Recurring interval** — `"every 30m"`, `"every 2h"` - **Cron 5-field** — `"0 9 * * *"` (parsed via croniter) - **ISO timestamp** — `"2026-02-03T14:00"` (timezone-aware, fires once at that wall-clock instant) A job record looks like this: ```json {"id":"a1b2c3d4","name":"Morning briefing","prompt":"Summarize overnight GitHub activity", "schedule":{"kind":"cron","expr":"0 8 * * *"},"deliver":"telegram", "repeat":{"times":null,"completed":0},"skills":["github-review"],"script":"morning_data.py"} ``` **Grace window.** `_compute_grace_seconds()` returns half the job's period, clamped to `[120s, 7200s]`. If the gateway was down when a job was due, it will still fire on the next tick provided the gap is inside that window — so a daily briefing catches up after an overnight gateway restart instead of silently skipping. **Three entry points** create and manage jobs: - **CLI** — `hermes cron list|create|edit|pause|resume|run|remove|tick|status` - **Slash command** — `/cron` from any chat platform - **Programmatic tool** — the agent itself calls `cronjob(action="create", schedule=..., prompt=..., name=..., deliver=..., repeat=..., skill=..., script=...)` during a turn, so a user can say "schedule this every morning" and the agent creates the job itself **Pre-run script injection (added in v0.8.0).** `_run_job_script()` executes a Python script from `$HERMES_HOME/scripts/` before the LLM turn starts. Timeout defaults to `cron.script_timeout_seconds: 120`. stdout is wrapped into the prompt: ``` ## Script Output The following data was collected by a pre-run script. Use it as context. ``` <stdout> ``` <original prompt> ``` Both stderr and stdout pass through `redact_sensitive_text()` before being concatenated. On failure the prompt gets a `## Script Error` block instead. This pattern lets cron jobs collect deterministic data (RSS pulls, API scrapes, DB queries) via plain Python, then hand it to the LLM only for summarization and delivery — much cheaper than asking the agent to use web tools every run. **Delivery channels.** The `deliver` field accepts: `local`, `origin`, `telegram`, `discord`, `slack`, `whatsapp`, `signal`, `matrix`, `mattermost`, `homeassistant`, `dingtalk`, `feishu`, `wecom`, `weixin`, `email`, `sms`, `webhook`, `bluebubbles`. You can also pin to a specific conversation with `"platform:chat_id"`. Values are validated against `_KNOWN_DELIVERY_PLATFORMS` (a frozenset) to prevent environment-variable enumeration attacks. `*_HOME_CHANNEL` env vars supply fallback destinations. When the gateway is running, delivery uses the live adapter (required for Matrix end-to-end encryption); otherwise it falls back to the standalone HTTP sender. `MEDIA:` tags in the response turn into native attachments via `send_voice` / `send_image_file` / `send_video` / `send_document`. Set `cron.wrap_response: false` to skip the header/footer wrapper. **`[SILENT]` suppression.** `SILENT_MARKER = "[SILENT]"`. As of v0.8.0 it works anywhere in the response, not only as a prefix. The system prompt instructs the agent: *"If there is genuinely nothing new to report, respond with exactly '[SILENT]' to suppress delivery."* The output is still archived locally — only the push to the messaging channel is skipped. This keeps high-frequency monitoring jobs (GitHub watchers, alerting) from becoming noise. **Delivery failure tracking.** `mark_job_run()` records `last_delivery_error` separately from `last_error`. A job can succeed (the LLM turn ran cleanly) while delivery fails (Telegram rate-limited, Slack token expired). `hermes cron list` surfaces this as `⚠ Delivery failed: <reason>`. Combined with v0.8.0's inactivity-based timeouts, actively-working cron jobs run indefinitely without being killed by a wall-clock limit. ## Key Parameters | Key | Purpose | |---|---| | `schedule` | One of `{kind: "duration"\|"interval"\|"cron"\|"iso", expr: ...}` | | `prompt` | Free-text task for the agent | | `deliver` | Channel shorthand or `platform:chat_id` | | `repeat.times` | `null` for unlimited, integer for fixed count | | `skills` | Skills auto-loaded for the run | | `script` | Python file in `$HERMES_HOME/scripts/` run before the LLM turn (v0.8.0) | | `cron.script_timeout_seconds` | Pre-run script timeout (default 120s) | | `cron.wrap_response` | Toggle delivery header/footer | ## When To Use - **Daily briefings** — GitHub activity, inbox digests, calendar previews - **Repository/release monitoring** — watch specific repos, notify on issues or PRs - **Home Assistant status checks** — periodic environment reports - **Session memory digests** — schedule `session_search` summaries - **RSS / news polling** — pre-run script pulls feeds, LLM distills, `[SILENT]` when empty - **Time-bounded one-shots** — ISO timestamps for "remind me at 3pm Thursday" ## Risks & Pitfalls - **Gateway must be running** for ticks to fire — jobs stored on disk are only evaluated every 60s by the gateway process. If you kill the gateway overnight, only jobs inside the grace window catch up. - **`deliver` strings must match the allowlist** — arbitrary env-var names are rejected by design; spell channel names exactly. - **Pre-run scripts run unsandboxed** — they execute as the user. Keep them in `$HERMES_HOME/scripts/` and treat that directory like any other auth-bearing location. - **Wall-clock timeout is gone** — active jobs run indefinitely as of v0.8.0, so a runaway long prompt will keep going until it actually stops tool activity. Pair long jobs with `max_iterations`-style caps in the prompt. - **`[SILENT]` swallows silently** — if delivery vanishes, check the local archive before assuming the job broke. - **Concurrent ticks are prevented by `.tick.lock`** but a crashed process may leave a stale lock; `hermes cron tick` from the CLI can force a manual run. ## Related Concepts - [[concepts/subagents-delegation]] — cron jobs can spawn subagents for parallel subtasks - [[concepts/skills-system]] — `skills` field auto-loads skills per job - [[concepts/messaging-gateway]] — delivery channels are gateway adapters - [[concepts/model-switching]] — cron jobs can pin cheap models for routine digests - [[entities/version-v0.8.0]] — pre-run scripts, `[SILENT]` anywhere, inactivity timeouts ## Sources - `raw/04-tools-mcp-cron-subagents.md` section C (C1–C5) - `raw/release-v0.8.0.md` — pre-run scripts, inactivity timeouts, `[SILENT]` update <!-- ===== hermes/wiki/concepts/deployment-backends.md ===== --> --- title: "Deployment Backends" type: concept tags: [backend, infrastructure, foundational, well-established, intermediate] created: 2026-04-12 updated: 2026-06-04 sources: ["raw/05-deployment-and-platforms.md", "https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29"] confidence: high hermes_version: "v0.15.1" --- # Deployment Backends ## Definition A **deployment backend** (also called the *terminal backend* in Hermes parlance) is the execution environment that the agent's `terminal` and `process` tools run commands inside. Hermes ships six backends — `local`, `docker`, `ssh`, `singularity`, `daytona`, and `modal` — selected via the `terminal:` block in `~/.hermes/config.yaml` or via `hermes setup` → "Terminal Backend." All backends auto-mount the user's skills directory and credential files, so behaviour from the agent's perspective is uniform: the differences live in isolation, cost, persistence, and platform availability. ## How It Works The backend is configured under `terminal:` in `~/.hermes/config.yaml`. Credential resolution follows a priority chain — **CLI flags → `config.yaml` → `.env` → defaults** — and `hermes doctor` diagnoses backend-specific problems. Every backend exposes the same tool surface; the executor under the hood differs: - **Local** runs commands in a subprocess on the host shell. - **Docker** spawns/attaches an ephemeral container per session, hardened with `--cap-drop ALL`, no-privilege-escalation, a 256 PID limit, and capped tmpfs. - **SSH** opens an OpenSSH `ControlMaster` connection with a 5-minute idle keepalive; with `persistent_shell: true` it keeps a long-lived bash that preserves cwd and env across calls. - **Singularity / Apptainer** runs `--containall --no-home`, auto-converting Docker URLs to `.sif` files cached locally; scratch directory resolves through `TERMINAL_SCRATCH_DIR → TERMINAL_SANDBOX_DIR/singularity → /scratch/$USER/hermes-agent → ~/.hermes/sandboxes/singularity`. - **Daytona** provisions a managed cloud workspace that hibernates when idle and resumes on the next session. - **Modal** boots a serverless container; filesystem state is captured as snapshots (tracked in `~/.hermes/modal_snapshots.json`) restored on the next run. The six sandboxed backends — Docker, Singularity, Daytona, and Modal — also auto-bypass the [[concepts/approval-system]] dangerous-command prompt because the host filesystem is not exposed. ## Key Parameters Common keys under `terminal:` (full list lives in [[concepts/profiles-multi-instance]]-aware `config.yaml`): - `backend` — `local | docker | ssh | singularity | daytona | modal` - `docker_image` — image to spawn (e.g. `nikolaik/python-nodejs:python3.11-nodejs20`) - `docker_forward_env` — list of env vars to inject into the container (e.g. `["GITHUB_TOKEN"]`) - `docker_volumes` — host:container bind mounts (`:ro` allowed) - `container_memory` / `container_cpu` / `container_disk` — resource caps (MiB / cores / MiB) - `container_persistent` — keep workspace between sessions (Daytona, Modal, Singularity) - `persistent_shell` — long-lived bash for SSH - `singularity_image` — Docker URL or local `.sif` path Per-backend env vars: `TERMINAL_SSH_HOST/USER/PORT/KEY`, `TERMINAL_SSH_PERSISTENT`, `TERMINAL_SCRATCH_DIR`, `TERMINAL_SANDBOX_DIR`, `DAYTONA_API_KEY`, `MODAL_TOKEN_ID`, `MODAL_TOKEN_SECRET` (or `~/.modal.toml`). ### Example configs Docker with a forwarded GitHub token, two volume mounts, and a 5 GiB memory cap: ```yaml terminal: backend: docker docker_image: "nikolaik/python-nodejs:python3.11-nodejs20" docker_forward_env: ["GITHUB_TOKEN"] docker_volumes: - "/home/user/projects:/workspace/projects" - "/home/user/data:/data:ro" container_memory: 5120 ``` Singularity for an HPC cluster with a persistent container: ```yaml terminal: backend: singularity singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20" container_persistent: true ``` Daytona managed workspace (1 vCPU, 5 GiB RAM, 10 GiB disk, persistent): ```yaml terminal: backend: daytona container_cpu: 1 container_memory: 5120 container_disk: 10240 container_persistent: true ``` Modal serverless (1 vCPU, 5 GiB RAM, 50 GiB disk, snapshot persistence): ```yaml terminal: backend: modal container_cpu: 1 container_memory: 5120 container_disk: 51200 container_persistent: true ``` SSH with a persistent shell: ```yaml terminal: backend: ssh persistent_shell: true ``` ## When To Use | Backend | Best for | Cost | Persistence | |---|---|---|---| | **Local** ([[entities/backend-local]]) | Dev, personal use, trusted single-user machines | Free | Host filesystem (always) | | **Docker** ([[entities/backend-docker]]) | Most users wanting isolation without cloud bills | Free | Volumes you mount; container lifecycle ~2h/session | | **SSH** ([[entities/backend-ssh]]) | $5 VPS, remote GPU boxes, distributed compute | Hosting fees (~$5/mo) | Remote host's filesystem | | **Singularity** ([[entities/backend-singularity]]) | HPC clusters where Docker is forbidden | Free (cluster allocation) | Optional via `container_persistent` | | **Daytona** ([[entities/backend-daytona]]) | Managed cloud dev, team collaboration | Metered; hibernates idle | Workspaces stopped (not deleted), resumed next session | | **Modal** ([[entities/backend-modal]]) | Ephemeral cloud compute, evals, zero infra overhead | ~$5/mo baseline + metered ("nearly nothing when idle") | Filesystem snapshots; live processes/background jobs NOT preserved | You can also run **Hermes itself inside Docker** rather than just the terminal backend: ```bash docker run -d --name hermes --restart unless-stopped \ -v ~/.hermes:/opt/data nousresearch/hermes-agent gateway run ``` The full comparison lives in [[syntheses/deployment-backends-compared]]. ## Risks & Pitfalls - **Local has zero isolation** — the agent has full filesystem access. Mitigate with `hermes tools` to restrict the toolset. - **Never run two Docker containers against the same `~/.hermes`** — the SQLite session store will corrupt. - **Docker browser tools need `--shm-size=1g`** for headless Chromium. - **Docker dashboard insecure mode is now an explicit env opt-in (v0.15.1).** Binding the Hermes dashboard to `0.0.0.0` no longer implies insecure-mode access; you must set `HERMES_DASHBOARD_INSECURE=1` in the container env. If you were relying on the old "bind to 0.0.0.0 = allow insecure access" behavior, your dashboard is now refused/limited by default and you need to opt in explicitly. See [[entities/backend-docker]] for the entity-level setup recipe. - **SSH `stdin_data` and `sudo` fall back to one-shot mode** — shell state lost on restart; design prompts accordingly. - **Singularity image pulls are slow** vs Docker because the Docker URL is converted to `.sif` on first use. - **Daytona caps disk at 10 GiB** and requires an active subscription. - **Modal cold starts are slow**, snapshots restore filesystem only — long-running daemons die between sessions. Kill runaway containers with `scripts/kill_modal.sh`. - **Credential drift** — keys in `.env` override `config.yaml`; use `hermes doctor` if a backend can't auth. ## Related Concepts - [[concepts/messaging-gateway]] — gateway uses the same backend for tool calls - [[concepts/profiles-multi-instance]] — each profile has its own `config.yaml` and therefore its own backend - [[concepts/approval-system]] — sandboxed backends auto-bypass dangerous-command prompts - [[syntheses/deployment-backends-compared]] — head-to-head matrix - [[syntheses/local-stack-playbook]] — local-only configuration recipe - Per-backend entity pages: [[entities/backend-local]], [[entities/backend-docker]], [[entities/backend-ssh]], [[entities/backend-singularity]], [[entities/backend-daytona]], [[entities/backend-modal]] ## Sources - `raw/05-deployment-and-platforms.md` (Section A, "Deployment Backends") - Source files referenced: `agent/`, `hermes_cli/setup.py`, `docker/entrypoint.sh`, `scripts/kill_modal.sh` <!-- ===== hermes/wiki/concepts/local-models-airplane-mode.md ===== --> --- title: "Local Models & Airplane Mode" type: concept tags: [local-models, provider, memory, tools, foundational, well-established, intermediate] created: 2026-04-12 updated: 2026-04-12 sources: - "raw/02-install-and-setup.md" - "raw/04-tools-mcp-cron-subagents.md" - "raw/05-deployment-and-platforms.md" - "raw/transcript-setup-tutorial-gemma.txt" - "raw/transcript-hermes-full-course-2hr.txt" - "raw/transcript-did-hermes-kill-openclaw.txt" - "raw/awesome-hermes-agent-readme.md" confidence: high hermes_version: "v0.8.0" --- # Local Models & Airplane Mode ## Definition Hermes can run 100% locally — no API keys, no cloud round-trips, no telemetry leaving the box — but there is **no single `--airplane-mode` flag that flips this on**. "Airplane mode" is a stack you assemble from interchangeable local components: a local LLM server (Ollama / vLLM / llama.cpp / LM Studio / SGLang) wired through Hermes' `custom` OpenAI-compatible provider, plus local replacements for every cloud tool Hermes would otherwise call (TTS, STT, web search, embeddings, memory). The setup tutorial frames the goal cleanly: "you'll be able to chat with a Hermes agent that is 100% private." ## How It Works Hermes treats every external service as a pluggable provider. Each provider category has at least one local-only option, and the choice is made independently per category — so you can mix-and-match a local LLM with cloud TTS, or fully local everything. **1. Local LLM (the core)** — pick one: | Server | How Hermes connects | Notes | |---|---|---| | **Ollama** | `custom` provider, base URL `http://localhost:11434/v1`, no API key | Easiest. Auto-lists installed models so `ollama pull <model>` then re-run `hermes setup` and the model appears. The setup transcript walks through this exactly. | | **vLLM** | `custom` provider, OpenAI-compatible endpoint | Best throughput on a single GPU; serves quantized models with continuous batching. | | **llama.cpp** | `custom` provider, server mode | CPU-friendly via GGUF quants; covered by `mlops/inference/llama-cpp` skill. | | **LM Studio** | `custom` provider, GUI-managed local server | Easiest on macOS/Windows for non-CLI users. | | **SGLang** | `custom` provider | Used by Hermes' own RL pipeline (see [[concepts/ml-research-pipeline]]); structured-output specialist. | All five present an OpenAI-compatible `/v1/chat/completions` endpoint, so they slot in at `hermes setup → Inference Provider → custom (LM Studio/Ollama/vLLM/llama.cpp)`. Models the community has reported running well include Qwen3 (8B/32B), Gemma 3 4B/E4B/E2B, MiniMax M2.7. The Gemma setup transcript notes the smaller E2B "wasn't able to do like basic tasks" and recommends "the E4B, which is a 9.6 gig model" as the floor for agentic use. **2. Local TTS — NeuTTS Air** — a local text-to-speech provider that ships in Hermes (selectable during setup as `neutts`). No API key, runs entirely on-device, supports voice cloning. The setup transcript: "for text-to-speech, I don't want to use any cloud versions. I actually prefer, when I'm running these AI agents, to always use locally hosted stuff. So, for this instance, I'm going to go with this NEUTTS, which is local on a device." Selecting it triggers a one-time download of the TTS model and dependencies. **3. Local STT — faster-whisper** — `stt: provider: local` in `config.yaml`. ~150 MB model auto-downloaded on first use. Transcribes voice memos sent to the messaging gateway entirely locally. Alternative remote backends (`groq`, `openai`) exist for users who want speed over privacy. **4. Self-hosted Web Search — Firecrawl** — Hermes' default web search/extract provider has a self-hostable Docker version. Set `FIRECRAWL_API_URL=http://localhost:3002` (or wherever your container exposes it) instead of `FIRECRAWL_API_KEY`. The Gemma transcript walks through the Docker setup: "Firecrawl has an option to use a paid cloud service, where you can pay them and pay per use, or you could also go and use their self-hosted version." Once configured, `web_search` and `web_extract` tools route through your container. **5. Local Memory — Hindsight (embedded)** — A long-term memory provider for agents with retain/recall/reflect workflows, supporting semantic, graph, and temporal retrieval. The community-maintained `hindsight` plugin runs the memory layer in-process — no external memory service required. Catalogued in the awesome-hermes README under memory plugins (see [[entities/memory-hindsight]]). **6. Holographic Memory — zero-dep SQLite + FTS5 + HRR** — A first-class memory plugin shipping pure-Python with no external service. Stores conversation history in SQLite with FTS5 full-text search, and uses Holographic Reduced Representations (HRR) for vector recall — meaning vectors are computed and stored locally without any embedding API. The most "airplane" memory option (see [[entities/memory-holographic]]). **7. Hermes' built-in cross-session memory** — Even with no plugin, Hermes' core `session_search` already uses **FTS5 SQLite** locally with optional Gemini Flash summarization. With local-only providers configured, summarization can be pointed at the local LLM instead, keeping the loop closed. **8. Browser** — `browser: provider: local` runs local Chromium via Playwright. Camofox (anti-detection Firefox) can also run locally. Browserbase, Browser Use cloud, Firecrawl cloud are all opt-in remote alternatives. **9. Code execution** — `execute_code` runs in-process Python by default — local. For isolation use the local Docker backend ([[entities/backend-docker]]). **10. Image generation** — No fully local default; FAL is the cloud option. For airplane mode, install `mlops/inference/...` skills and self-serve a local SDXL/FLUX model (out of the box this is the only category without a turnkey local provider). ## Key Parameters **`config.yaml`:** ```yaml model: provider: custom base_url: http://localhost:11434/v1 # Ollama default api_key: "" # Ollama needs none model: gemma3:e4b tts: provider: neutts stt: provider: local # faster-whisper model: base browser: provider: local # local Chromium memory: provider: holographic # zero-dep SQLite+HRR ``` **`.env`:** ``` FIRECRAWL_API_URL=http://localhost:3002 # Deliberately omit: OPENAI_API_KEY, ANTHROPIC_API_KEY, FIRECRAWL_API_KEY, # EXA_API_KEY, FAL_KEY, ELEVENLABS_API_KEY ``` **Verifying airplane status:** `hermes doctor` lists configured providers; `hermes config show` prints the resolved chain. Disconnect Wi-Fi and run a `web_search` — failure means a remote tool slipped through. ## When To Use - **Privacy-critical work.** Legal, medical, internal company data — nothing should ever leave the device. - **Cost control / experimentation.** "I don't want to use any paid models" — no per-token billing while iterating on skills, prompts, or workflows. The free Gemma/Qwen route lets you tinker indefinitely. - **Air-gapped environments.** Research clusters, classified labs, on-prem deployments behind firewalls. - **Edge devices.** Termux on Android, low-power VPS, Raspberry Pi-class hardware (with quantized GGUF models). - **Reproducible research.** Pin the local model + skills + memory state and your trajectories are deterministic in a way no cloud API can promise. - **Latency-sensitive loops.** Local inference (especially with vLLM/SGLang) has zero network RTT. ## Risks & Pitfalls - **No single switch.** Mis-configure one category and you'll silently call out — e.g. leaving `FIRECRAWL_API_KEY` set wins over `FIRECRAWL_API_URL` in some code paths. Audit `hermes config show` and disconnect from the network to confirm. - **Small models fail at agentic tasks.** Gemma E2B (~7 GB) "wasn't able to do like basic tasks" per the Gemma tutorial; jump to E4B (~9.6 GB) or larger. Below ~7B parameters, tool-call reliability collapses. - **Context windows.** Local quantized models often have 8K–32K context vs the 200K+ of frontier APIs. Increase compression aggressiveness (`compression.threshold: 0.40`) or hit "context too big" hangs (a recurring complaint in transcripts). - **TTS/STT first-run downloads.** NeuTTS dependencies and faster-whisper's ~150 MB model auto-download on first use — fine on broadband, painful on tethered/airplane connections. Pre-warm before going offline. - **Image generation gap.** No turnkey local image gen — you must self-host SDXL/FLUX via the `mlops/inference` skills if you want airplane-grade `image_generate`. - **MCP servers can phone home.** Each MCP server (filesystem, GitHub, Notion, etc.) is its own network actor — `npx`/`uvx`-launched stdio servers may make network calls regardless of Hermes' config. Audit each server. - **Local backend ≠ sandboxed.** Running locally with `terminal: backend: local` means the agent has your shell. The masterclass transcripts repeatedly warn: "for production use Docker or Modal as your back end because the container, it is the security boundary." Airplane mode is about privacy, not safety — combine with [[entities/backend-docker]] for isolation. - **Hermes Setup quirks.** The Gemma walkthrough hit setup wizard bugs ("the system crashes... this also happens to me and it's completely normal, I think") that required restarting from `hermes` after initial config. ## Related Concepts - [[concepts/ml-research-pipeline]] — local SGLang + vLLM serving overlap with the RL training stack - [[concepts/memory-system]] — Hindsight and Holographic memory providers in detail - [[concepts/deployment-backends]] — local + Docker as the airplane-friendly backend pair - [[concepts/self-improvement-loop]] — works fully offline since GAPA and skills live in `~/.hermes/` - [[entities/provider-ollama-local]] - [[entities/memory-hindsight]], [[entities/memory-holographic]] - [[entities/backend-local]], [[entities/backend-docker]] - [[syntheses/local-stack-playbook]] — turnkey configuration recipe ## Sources - `raw/02-install-and-setup.md` — provider list including `custom (LM Studio/Ollama/vLLM/llama.cpp)`, env vars, `tts`/`stt`/`browser` sections of `config.yaml` - `raw/04-tools-mcp-cron-subagents.md` — `text_to_speech` provider list including local NeuTTS, `session_search` FTS5 SQLite - `raw/05-deployment-and-platforms.md` — local terminal backend, Honcho/Hindsight/holographic memory references, faster-whisper/groq/openai STT options - `raw/transcript-setup-tutorial-gemma.txt` — full local-stack walkthrough (Ollama + Gemma + NeuTTS + self-hosted Firecrawl + Docker) - `raw/transcript-hermes-full-course-2hr.txt` — Ollama + MiniMax/Qwen practical use, "you can run it for free" - `raw/transcript-did-hermes-kill-openclaw.txt` — local model emphasis, "Hermes has said on record they support open models" - `raw/awesome-hermes-agent-readme.md` — Hindsight, Honcho self-hosted, holographic memory plugins <!-- ===== hermes/wiki/concepts/mcp-integration.md ===== --> --- title: "MCP Integration" type: concept tags: [mcp, tools, platform, foundational, well-established] created: 2026-04-12 updated: 2026-06-04 sources: ["raw/04-tools-mcp-cron-subagents.md", "raw/release-v0.6.0.md", "raw/release-v0.8.0.md", "https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29"] confidence: high hermes_version: "v0.15.1" --- # MCP Integration ## Definition Model Context Protocol (MCP) integration in Hermes has three distinct directions: (1) Hermes consumes external MCP servers as additional tools, (2) Hermes exposes itself as an MCP server via `hermes mcp serve` so other clients (Claude Desktop, Cursor, VS Code) can browse its sessions and messages, and (3) editor clients can pass their own MCP servers into Hermes per-session. The consumer path is handled by `tools/mcp_tool.py` (2195 lines); the server path by `mcp_serve.py` (867 lines); the client-provided path by `acp_adapter/server.py`. ## How It Works ### Consuming external MCP servers Configure them in `config.yaml`: ```yaml mcp_servers: filesystem: command: npx args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"] github: command: npx args: ["-y", "@modelcontextprotocol/server-github"] env: GITHUB_PERSONAL_ACCESS_TOKEN: ghp_... notion: url: https://mcp.notion.com/mcp auth: oauth stripe: url: https://mcp.stripe.com headers: Authorization: "Bearer ${MCP_STRIPE_API_KEY}" tools: exclude: [delete_customer] prompts: false resources: false ``` Two transports are supported: **stdio** (local subprocess — the `command` form) and **HTTP** (remote URL — the `url` form). Each exposed tool becomes `mcp_<server>_<tool>` inside Hermes' registry. Every server with at least one tool gets its own toolset named `mcp-<server>`, so it can be enabled/disabled as a unit. Discovery is dynamic — when a server emits `notifications/tools/list_changed`, Hermes auto-refreshes without restart. **Docker stdio command resolution (v0.15.1):** MCP servers configured with a bare command such as `npx`, `npm`, or `node` now resolve against `/usr/local/bin` inside the Docker image, so common Node-based MCP servers launch correctly under the Docker terminal backend. The fix is scoped to command resolution — it does not pull arbitrary host binaries into the container, and the OSV malware scan still runs before launch. On a host or non-Docker backend, command resolution is unchanged. **CLI workflow.** `hermes mcp add <name> --url | --command | --preset` does discovery first: it temporarily connects, lists tools, shows a checkbox picker, and saves tokens to the profile's `.env` as `MCP_<SERVER>_API_KEY`. `hermes mcp list`, `remove`, and `test` round out the management surface. `/reload-mcp` reloads config without restarting Hermes. ### `hermes mcp serve` — exposing Hermes AS an MCP server Starts a stdio MCP server using the FastMCP SDK. Exposes **10 tools** (the 9 OpenClaw-compatible tools plus `channels_list` which is Hermes-specific): `conversations_list`, `conversation_get`, `messages_read`, `attachments_fetch`, `events_poll`, `events_wait`, `messages_send`, `permissions_list_open`, `permissions_respond`, `channels_list` An **EventBridge** polls `~/.hermes/sessions/sessions.json` and `state.db` every 200ms so clients get near-real-time event streams. Read operations work without a running gateway; send operations require it. Stdio is the only transport currently shipped (v0.6.0 mentioned HTTP support; stdio remains the production path as of v0.8.0). Client config for Claude Code: ```json {"mcpServers": {"hermes": {"command": "hermes", "args": ["mcp", "serve"]}}} ``` ### OAuth 2.1 PKCE (added in v0.8.0) `tools/mcp_oauth.py` (482 lines) implements standards-compliant browser-based authorization code flow with PKCE, using the MCP SDK's `OAuthClientProvider`. Tokens persist to `$HERMES_HOME/mcp-tokens/<server>.json`, survive restarts, and auto-refresh. An ephemeral localhost HTTP server captures the OAuth redirect. Triggered by `auth: oauth` in the server's config block. Notion's hosted MCP is the reference case. ### OSV malware scanning (added in v0.8.0) Before launching any `npx` or `uvx` MCP server, `tools/osv_check.py` queries `https://api.osv.dev/v1/query` for MAL-* advisories. Regular CVEs are deliberately ignored (too noisy); only confirmed-malicious package advisories block the launch. Typical response time is ~300ms with a 10s timeout; on network errors it fails open so offline installs still work. ### Client-Provided MCP Editor integrations (VS Code, Zed, JetBrains) pass a `list[McpServerStdio | McpServerHttp | McpServerSse]` into Hermes' ACP adapter via `newSession`, `loadSession`, `resumeSession`, or `forkSession`. Hermes registers them per-session, refreshes its tool surface, and emits `session/available_commands_update` so the editor's slash-command palette stays accurate. ### Common MCP servers in the Hermes ecosystem Obsidian, Notion, Linear, GitHub, filesystem, Stripe, Time, SiYuan, AgentMail, QMD research, Google Workspace, PowerPoint. ## Key Parameters | Key | Purpose | |---|---| | `mcp_servers.<name>.command` + `args` | stdio transport | | `mcp_servers.<name>.url` | HTTP transport | | `mcp_servers.<name>.env` | Environment variables for stdio subprocess | | `mcp_servers.<name>.headers` | Custom auth headers for HTTP | | `mcp_servers.<name>.auth: oauth` | Triggers OAuth 2.1 PKCE flow (v0.8.0) | | `mcp_servers.<name>.tools.{exclude, prompts, resources}` | Per-server scope limits | | `$HERMES_HOME/mcp-tokens/<server>.json` | Persistent OAuth tokens | ## When To Use - **Consuming external MCP** — integrate SaaS or OS-level capabilities (Linear issues, Notion pages, Stripe payments, filesystem) without writing a custom tool - **`hermes mcp serve`** — when you want Claude Desktop, Cursor, or another MCP-native client to drive Hermes' conversations and sessions - **Client-provided MCP** — editor-specific tool surfaces that should live only inside one IDE session - **OAuth rather than static tokens** — any hosted MCP that offers it; removes long-lived secrets from config files - **OSV check remains on by default** — no reason to disable unless you have air-gapped offline runs ## Risks & Pitfalls - **Tool surface explosion** — every MCP server adds N tools. Use `tools.exclude` and toolset toggles to keep the schema small or model selection degrades. - **`npx`/`uvx` runs arbitrary packages** — OSV catches known-malicious ones but does not sandbox; remote-origin servers are more trust-sensitive than stdio servers you wrote yourself. - **OAuth redirect requires localhost** — remote/headless flows need manual token capture. - **Dynamic discovery can thrash** — a flaky MCP server emitting frequent `list_changed` notifications invalidates the tool cache repeatedly. Disable discovery or pin the server list for production. - **`hermes mcp serve` send ops need the gateway** — if the gateway is down, clients can read but not send. - **Hermes-as-client and Hermes-as-server are independent** — running `mcp serve` does not expose client-side MCP servers to those clients. ## Related Concepts - [[concepts/cron-scheduling]] — cron jobs can call MCP tools (e.g. Linear status digests) - [[concepts/subagents-delegation]] — children inherit MCP tool visibility subject to toolset intersection - [[concepts/messaging-gateway]] — EventBridge polls gateway state for `hermes mcp serve` - [[concepts/profiles-multi-instance]] — each profile gets its own `mcp-tokens/` dir - [[concepts/approval-system]] — MCP tool calls flow through the same approval layer - [[entities/version-v0.6.0]] — introduced `hermes mcp serve` + dynamic discovery - [[entities/version-v0.8.0]] — added OAuth 2.1 PKCE + OSV scanning ## Sources - `raw/04-tools-mcp-cron-subagents.md` section B (B1–B5) - `raw/release-v0.6.0.md` — `hermes mcp serve` introduction - `raw/release-v0.8.0.md` — MCP OAuth 2.1 + OSV malware scanning <!-- ===== hermes/wiki/concepts/memory-system.md ===== --> --- title: "Memory System" type: concept tags: [memory, foundational, well-established, intermediate, vs-openclaw, provider] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/02-install-and-setup.md", "raw/04-tools-mcp-cron-subagents.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.7.0.md", "raw/release-v0.8.0.md", "raw/01-community-resources.md", "raw/awesome-hermes-agent-readme.md", "raw/transcript-247-self-evolving.txt", "raw/transcript-switching-to-hermes.txt", "raw/transcript-hermes-full-course-2hr.txt", "raw/transcript-did-hermes-kill-openclaw.txt", "raw/transcript-why-hermes-replaced-openclaw.txt"] confidence: high hermes_version: "v0.8.0" --- # Memory System ## Definition Hermes Agent's memory subsystem is a **two-layer architecture** that separates the always-on built-in store from a pluggable provider interface. The built-in layer is two human-readable markdown files (`MEMORY.md` for agent-curated notes about the project / world, and `USER.md` for a model of the user) maintained at `~/.hermes/memories/` and refreshed via a single `memory` tool. The external layer is a plugin ABC — at most one provider is active at a time — that swaps in third-party backends (Honcho, mem0, Supermemory, RetainDB, Hindsight, ByteRover, Holographic, OpenViking) without touching the agent loop. On top of both layers, FTS5 SQLite full-text search over the session history (`session_search`) gives the agent recall of any prior conversation, even from a month ago. This design contrasts sharply with [[entities/openclaw]]'s single hardcoded memory file and is what makes Hermes feel like "an agent that compounds value over time" rather than a stateless chatbot. ## How It Works ### Layer 1: Built-in markdown memory Two files live at `~/.hermes/memories/`: - **`MEMORY.md`** — agent-curated notes about ongoing projects, recurring constraints, environment quirks, decisions made. Default char limit: `memory_char_limit: 2200`. - **`USER.md`** — the agent's model of *who you are*: work style, preferences, domain knowledge, communication tone. Default char limit: `user_char_limit: 1375`. Maintenance is gated by `user_profile_enabled`. Both files are loaded into context at the start of every session. The agent updates them through the single built-in `memory` tool, which performs append / replace / prune operations and respects the per-file character cap. A "nudge" mechanism (`nudge_interval: 10`, `flush_min_turns: 6`) periodically reminds the model to consolidate working memory into these files instead of letting useful context fall off the conversation window. Because the files are plain markdown, the human can open them in any text editor, audit what the agent thinks about them, redact entries, or copy them between profiles. (The [[concepts/profiles-multi-instance]] system clones `MEMORY.md` and `USER.md` along with config and `SOUL.md` when you run `hermes profile create --clone`.) ### Layer 2: Pluggable provider interface (added in v0.7.0) v0.7.0 generalised memory into a provider plugin system. Third-party backends implement a simple ABC and register via the plugin loader. **Only one external provider is active at a time** — the built-in markdown layer always coexists; the provider augments it. The eight currently supported providers are: | Provider | What it adds | |---|---| | [[entities/memory-honcho]] | Reference plugin. Dialectic user modeling with profile-scoped host/peer resolution. Restored to full parity in v0.7.0. | | [[entities/memory-mem0]] | Hosted vector + graph memory layer popular outside Hermes. | | [[entities/memory-supermemory]] | Multi-container, configurable `search_mode`, identity templates. Added in v0.8.0. | | [[entities/memory-retaindb]] | Long-horizon retention DB with structured queries. | | [[entities/memory-hindsight]] | Self-hosted memory backend by Vectorize. Pairs well with high-context-pressure workloads. | | [[entities/memory-byterover]] | Cross-tool memory bus targeting developer agents. | | [[entities/memory-holographic]] | Experimental dense-retrieval store. | | [[entities/memory-openviking]] | Community-built local-first option. | Setup is a single command: ```bash hermes memory setup # interactive picker → writes provider block to config.yaml hermes memory status # show which provider is active + counts hermes memory off # revert to built-in only ``` Honcho has its own dedicated subcommand surface for advanced users (`hermes honcho {setup,status,sessions,map,peer,mode,tokens,identity,migrate}`) covering session-to-peer mapping, dialectic mode, and identity templating. ### Layer 3 (cross-cutting): FTS5 session search Independent of the memory file/provider distinction, every session is indexed in an FTS5 SQLite database at `~/.hermes/sessions/`. The `session_search` built-in tool (toolset: Session Search) lets the agent issue full-text queries over its own conversational history with optional Gemini Flash summarisation of the matches. This is the mechanism behind the masterclass framing of "first-layer cross-session memory" — the agent can retrieve context from a conversation a month ago without any external provider, just by searching its own logs. The CLI exposes the same store: `hermes sessions {list,export,delete,prune,stats,rename,browse}`. ### How "remember from a month ago" actually works When a user reopens an old topic, three mechanisms converge: 1. **Curated persistence** — anything important that was written into `MEMORY.md` / `USER.md` is already in context. 2. **FTS5 search** — `session_search("...keywords...")` pulls any historical conversation that mentions the topic, summarised by an auxiliary model. 3. **External provider recall** — if Honcho/mem0/Supermemory/etc. is configured, semantic + episodic recall returns relevant facts, peer relationships, and consolidated summaries. The combination is what differentiates Hermes from [[entities/openclaw]], whose memory is a single hardcoded file with no provider pluggability and no cross-session FTS index. ## Key Parameters ### `config.yaml` `memory:` section ```yaml memory: memory_enabled: true user_profile_enabled: true memory_char_limit: 2200 # cap on MEMORY.md user_char_limit: 1375 # cap on USER.md nudge_interval: 10 # turns between consolidation nudges flush_min_turns: 6 # minimum turns before a flush is allowed provider: builtin # builtin | honcho | mem0 | supermemory | retaindb | hindsight | byterover | holographic | openviking ``` ### Session-store configuration - `session_reset.mode` — `both | idle | daily | none` - `session_reset.idle_minutes` — default `1440` (24h) - `session_reset.at_hour` — default `4` (4 AM local) - `group_sessions_per_user` — default `true`. Per-platform overrides in `~/.hermes/gateway.json`. ### Environment variables - `HONCHO_API_KEY` — Honcho cloud - Provider-specific keys are written to `~/.hermes/.env` by `hermes memory setup` ### Cross-platform memory continuity Per-chat session store keyed by `(platform, chat_id)`. **Skill state, memory (Honcho), and FTS5 session search are SHARED across platforms.** Resuming a topic from a different channel pulls prior context via cross-session recall — this is what enables patterns like "start in CLI, finish on Telegram." See [[concepts/messaging-gateway]] for the cross-platform mirror. ## When To Use - **Start with built-in.** For most users, `MEMORY.md` + `USER.md` + FTS5 session search is sufficient and requires zero setup. - **Add an external provider when you hit context pressure.** Symptoms: you find yourself re-explaining context across sessions, the agent forgets project conventions, summarisation evicts important facts. See the awesome-hermes "Memory pressure handling with Honcho/Hindsight" recipe. - **Pick Honcho for user modeling.** The reference plugin offers dialectic peer modeling — best when the agent needs to model multiple distinct humans (e.g. team gateway). - **Pick Supermemory for multi-container search.** When you need different memory namespaces per project or per role (added in v0.8.0). - **Pick a self-hosted provider (Hindsight, openviking, honcho-self-hosted) when data residency matters.** - **Use FTS5 session_search liberally.** It's free, local, and the agent uses it autonomously when it suspects a prior conversation is relevant. ## Risks & Pitfalls - **One provider at a time.** Switching providers does NOT migrate existing memories between them. Plan carefully; consider exporting via `hermes sessions export` first. - **`memory_char_limit` evicts silently.** When `MEMORY.md` exceeds the cap, the agent's prune step decides what to drop — track changes via git on `~/.hermes/memories/` if the contents are critical. - **Built-in is always on.** Even with an external provider configured, `MEMORY.md` and `USER.md` still load into context. Disabling requires `memory_enabled: false` (and `user_profile_enabled: false`). - **Sessions DB can grow large.** `hermes sessions prune` is not automatic; long-running gateway instances should schedule a prune via [[concepts/cron-scheduling]]. - **FTS5 search quality depends on language.** Default tokenizer is English-centric — non-Latin scripts may need a custom tokenizer. - **`USER.md` carries a privacy surface.** Anything the agent infers about you ends up there in plain text; review periodically before sharing your `~/.hermes/` (e.g. when filing bug reports via `hermes dump`). - **Provider keys leak into `.env`.** `hermes memory setup` writes `HONCHO_API_KEY` etc. into `~/.hermes/.env` — back this file up encrypted. - **Cross-platform recall requires shared HERMES_HOME.** A profile-based split (different `HERMES_HOME` per profile) intentionally isolates memory; a "team Hermes" needs a single home or an external provider. - **No automatic cross-provider migration tool.** Moving from mem0 → Supermemory is a manual operation. ## Related Concepts - [[concepts/skills-system]] — skills are procedural memory; this page covers episodic + semantic memory. - [[concepts/profiles-multi-instance]] — each profile gets its own `MEMORY.md` / `USER.md`; `--clone` copies them. - [[concepts/messaging-gateway]] — cross-platform session continuity rests on shared memory + FTS5. - [[concepts/migration-from-openclaw]] — `hermes claw migrate` imports OpenClaw's `SOUL.md` and memory files. - [[concepts/self-improvement-loop]] — GAPA writes successful patterns back into both skills and memory. - [[entities/memory-honcho]], [[entities/memory-mem0]], [[entities/memory-supermemory]], [[entities/memory-retaindb]], [[entities/memory-hindsight]], [[entities/memory-byterover]], [[entities/memory-holographic]], [[entities/memory-openviking]] - [[syntheses/memory-providers-compared]] — feature-by-feature comparison of all 8 providers. - [[syntheses/hermes-vs-openclaw]] — section on memory vs OpenClaw's hardcoded file. ## Sources - `raw/02-install-and-setup.md` — `memory:` config block, `hermes memory` and `hermes honcho` CLI surface, `MEMORY.md`/`USER.md` clone behavior in profiles - `raw/04-tools-mcp-cron-subagents.md` — `memory` tool registration, `session_search` (FTS5 + Gemini Flash) tool entry, subagent memory blocking - `raw/05-deployment-and-platforms.md` — cross-platform shared memory + FTS5 continuity - `raw/release-v0.7.0.md` — pluggable Memory Provider Interface (ABC + plugin), Honcho parity restoration - `raw/release-v0.8.0.md` — Supermemory provider added (multi-container, search_mode, identity template) - `raw/01-community-resources.md` — `honcho-self-hosted` community project - `raw/awesome-hermes-agent-readme.md` — "Memory pressure handling with Honcho/Hindsight" recipe - `raw/transcript-247-self-evolving.txt` — "evolving memory system" framing, GAPA writes to memory - `raw/transcript-switching-to-hermes.txt` — trajectory capture, OpenClaw's plugin-based memory contrast - `raw/transcript-hermes-full-course-2hr.txt` — three-layer framing (FTS5 cross-session + Honcho user model + skills as procedural) - `raw/transcript-did-hermes-kill-openclaw.txt` — comparative framing - `raw/transcript-why-hermes-replaced-openclaw.txt` — `soul user.md` configuration mention <!-- ===== hermes/wiki/concepts/messaging-gateway.md ===== --> --- title: "Messaging Gateway" type: concept tags: [gateway, platform, foundational, well-established, intermediate] created: 2026-04-12 updated: 2026-06-10 sources: ["raw/05-deployment-and-platforms.md", "raw/release-v0.9.0.md", "raw/docs-user-guide-messaging.md", "raw/docs-user-guide-messaging-sms.md", "raw/docs-user-guide-messaging-weixin.md", "raw/docs-user-guide-messaging-wecom-callback.md", "raw/docs-user-guide-messaging-bluebubbles.md", "raw/release-v0.11.0.md", "raw/release-v0.12.0.md", "raw/release-v0.13.0.md", "raw/release-v0.14.0.md", "raw/release-v0.15.0.md", "https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5"] confidence: high hermes_version: "v0.16.0" --- # Messaging Gateway ## Definition The **messaging gateway** is a single long-running background process (`gateway/run.py`) that multiplexes platform adapters into one shared agent loop. As of v0.9.0 it ships **sixteen documented platforms** — Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, WeCom Callback, Weixin (WeChat), and BlueBubbles (iMessage) — plus Webhooks and an Open WebUI/API-server surface; later releases grew the roster to **23 platforms by v0.15.0** (see "Platforms added after v0.9.0" below). It routes inbound messages into a per-chat session store, dispatches them to `AIAgent`, and ticks the cron scheduler every 60 seconds. Operators run it as a foreground process during testing or install it as a launchd / systemd service for 24/7 availability. ## How It Works The gateway is the long-lived daemon that "wears all the hats." Each platform adapter ([[entities/platform-telegram]], [[entities/platform-discord]], [[entities/platform-slack]], [[entities/platform-whatsapp]], [[entities/platform-signal]], [[entities/platform-email]], [[entities/platform-matrix]], [[entities/platform-home-assistant]], [[entities/platform-dingtalk]], [[entities/platform-mattermost]], [[entities/platform-feishu]], [[entities/platform-wecom]], plus SMS, WeCom Callback, Weixin, and BlueBubbles) speaks the platform's native protocol and normalises traffic to a common message envelope. The gateway then: 1. Looks up or creates a per-chat **session** keyed by `(platform, chat_id)`. 2. Dispatches the message to the agent loop, which uses the session's [[concepts/skills-system]], [[concepts/memory-system]], and tool budgets. 3. Streams output back through `gateway/delivery.py`, optionally transforming `MEDIA:/path` markers into native attachments (voice, image, video, document). 4. Runs cron ticks (file-locked via `.tick.lock`) every 60 s — see [[concepts/cron-scheduling]]. 5. Cross-mirrors messages between platforms when needed via `gateway/mirror.py`. Each `HERMES_HOME` (i.e. each [[concepts/profiles-multi-instance]] profile) runs its own gateway instance. Since v0.12.0 the gateway is also a **plugin host**: drop-in messaging adapters can ship outside the core (Microsoft Teams was the first plugin-shipped platform), and since v0.15.0 Discord and Mattermost themselves run as bundled plugins. ### Service commands ```bash hermes gateway setup # Interactive wizard hermes gateway # Foreground (alias for `gateway run`) hermes gateway install # Install as launchd (macOS) or systemd (Linux) service sudo hermes gateway install --system # Linux: boot-time system service hermes gateway start|stop|restart|status hermes gateway list # Cross-profile status (added in v0.13.0) hermes logs gateway # Unified ~/.hermes/logs/ viewer ``` On macOS the service file lands at `~/Library/LaunchAgents/ai.hermes.gateway.plist`; on Linux it uses systemd user or system units (logs via `journalctl`). The gateway is **WSL-aware** with smart systemd detection (added in v0.9.0) — on WSL prefer `hermes gateway run` under tmux. Full command surface: [[concepts/cli-reference]]. ### v0.8.0 features - **Inactivity-based timeouts** replace wall-clock — active tasks never get killed mid-stream. - **Native approval buttons** — Slack thread-preserving buttons, Telegram emoji reactions, Feishu cards. Inline `/approve` and `/deny` are dispatched directly (bypassing the background task system) so they are never deduped. - **Media delivery** with `MEDIA:/path` syntax — now supported on Signal and Mattermost in addition to the older platforms. - **`notify_on_complete`** — background terminal jobs ping the originating chat when they exit. - **Live `/model` switching** mid-conversation, available across all platforms. - **Cross-platform mirror** (`gateway/mirror.py`) — start a task on the CLI, get pinged on Telegram; or have `send_message` route output to a different platform from the one that triggered it. See the "Cross-Platform Continuity" pattern below. ### v0.9.0 features - **Three new platforms** — BlueBubbles (iMessage), Weixin (WeChat via iLink Bot API), and WeCom Callback (self-built enterprise app) take the roster from 12 to 16. - **Unified proxy support** — SOCKS proxy, `DISCORD_PROXY`, and macOS system-proxy auto-detection across all gateway platforms. - **Per-platform display verbosity** — `tool_progress` overrides per platform. - **Inbound text batching** for Discord, Matrix, WeCom + adaptive delay. - **Gateway status scoped to the active profile.** - **Matrix** migrated from matrix-nio to mautrix-python. - **Discord** adds an `allowed_channels` whitelist, forum-channel topic inheritance in threads, and `DISCORD_REPLY_TO_MODE`. ### Gateway changes after v0.9.0 (v0.10–v0.16) - **v0.11.0** ([[entities/version-v0.11.0]]) — QQBot becomes the 17th platform; dedicated `TELEGRAM_PROXY`; `DISCORD_ALLOWED_ROLES` role-based access; gateway proxy mode (forward messages to a remote API server); per-channel ephemeral prompts (Discord/Telegram/Slack/Mattermost); webhook direct-delivery mode (zero-LLM push); `--all` flag for `gateway start|restart`; auto-continue interrupted work after gateway restart; the agent is blocked from self-destructing the gateway via terminal. - **v0.12.0** ([[entities/version-v0.12.0]]) — pluggable gateway platforms (plugin host); Microsoft Teams ships as the first plugin platform (19th); Tencent Yuanbao native adapter (18th); media parity (native multi-image sends across Telegram/Discord/Slack/Mattermost/Email/Signal, centralized audio routing with FLAC); `pre_gateway_dispatch` plugin hook; Slack `channel_skill_bindings`. - **v0.13.0** ([[entities/version-v0.13.0]]) — Google Chat (20th); security wave: redaction ON by default, Discord role-allowlists guild-scoped, **WhatsApp rejects strangers by default**; `allowed_channels`/`allowed_chats`/`allowed_rooms` allowlists across Slack, Telegram, Mattermost, Matrix, DingTalk; sessions auto-resume after gateway restarts; `hermes gateway list`; new `as_document` skill directive (double-bracket marker in skill output) forces document delivery on supporting platforms. - **v0.14.0** ([[entities/version-v0.14.0]]) — LINE and SimpleX Chat bring the total to 22; Microsoft Teams wired end-to-end (Graph auth, webhook listener, outbound delivery); heavyweight platform SDKs (Slack/Matrix/Feishu/DingTalk) now lazy-install on first use; native clarify buttons on Telegram + Discord. - **v0.15.0** ([[entities/version-v0.15.0]]) — ntfy (23rd, push notifications without signup); deliverable mode (agents ship artifacts as native uploads) and `hermes send` to pipe script output to any platform; Discord + Mattermost migrated to bundled plugins; per-platform knobs (Telegram in-place status edits, `ignore_root_dm`; Discord `allow_any_attachment`, native voice transcription; Signal `require_mention`). - **v0.16.0** ([[entities/version-v0.16.0]]) — structured stream-event protocol with per-platform streaming defaults (Telegram on, Discord off) and dashboard toggles; the web dashboard's Channels page now configures every messaging platform from the browser (no more `config.yaml`-over-SSH); the new desktop app ([[entities/hermes-desktop-app]]) connects to a remote gateway over OAuth or username/password. ### Access control The gateway defaults to **denial of unknown users** on every platform. To grant access either: - Add the user to the platform's allowlist env var (e.g. `TELEGRAM_ALLOWED_USERS`, `SLACK_ALLOWED_USERS`). - Have the user **DM-pair**: they send the bot a message, receive a pairing code, and an operator runs `hermes pairing approve <platform> <code>`. Pairing state is managed via `hermes pairing list|approve|revoke|clear-pending`. Codes expire after 1 hour and are rate-limited. ### Skill-aware slash commands Every installed [[concepts/skills-system]] skill **auto-registers as a slash command** on capable platforms (Discord uses native Application Commands, capped at 100 per bot). All platforms also share a built-in shortlist: `/new`, `/model`, `/voice`, `/background`, `/retry`, `/skills`, `/compress`, `/stop`, `/status`, `/usage`, `/help`, `/sethome` ### Session reset Idle session reset defaults to **1440 minutes** (24 h) and is configurable per-platform in `~/.hermes/gateway.json`. Reset modes (`session_reset.mode`) are `both | idle | daily | none`, with `at_hour: 4` (4 AM) for the daily option. ## Key Parameters Top-level knobs: - **Env vars (per platform):** `TELEGRAM_BOT_TOKEN`, `TELEGRAM_ALLOWED_USERS`, `DISCORD_BOT_TOKEN`, `DISCORD_ALLOWED_USERS`, `SLACK_BOT_TOKEN`, `SLACK_APP_TOKEN`, `SLACK_ALLOWED_USERS`, `WHATSAPP_ALLOWED_USERS`, `EMAIL_ADDRESS/PASSWORD`, `MATRIX_HOMESERVER`, `MATRIX_ACCESS_TOKEN`, `HASS_TOKEN`, `HASS_URL`, `DINGTALK_CLIENT_ID/CLIENT_SECRET`, `MATTERMOST_URL/TOKEN`, `FEISHU_APP_ID/APP_SECRET`, `WECOM_BOT_ID/SECRET`, `WECOM_CALLBACK_CORP_ID/CORP_SECRET/AGENT_ID/TOKEN/ENCODING_AES_KEY`, `WEIXIN_ACCOUNT_ID`, `BLUEBUBBLES_SERVER_URL/PASSWORD`, `TWILIO_ACCOUNT_SID/AUTH_TOKEN/PHONE_NUMBER` + `SMS_WEBHOOK_URL`, plus master `GATEWAY_ALLOWED_USERS` and `GATEWAY_ALLOW_ALL_USERS` (default `false`). - **Config file:** `~/.hermes/gateway.json` — per-platform session reset, mention rules, ignored channels. - **Pairing:** `hermes pairing approve <platform> <code>` after user DMs the bot. - **Slash command catalogue:** auto-registered from installed skills + the shared shortlist. - **Display:** `display.tool_progress` (`off|new|all|verbose`, per-platform overrides), `display.background_process_notifications` (`all|result|error|off`). ### Sixteen platforms at a glance The sixteen platforms documented in the official messaging guide (v0.9.0 baseline): | # | Platform | Auth | Notable trait | |---|---|---|---| | 1 | Telegram | `TELEGRAM_BOT_TOKEN` (BotFather) | Voice STT/TTS, emoji-reaction approvals, forum-topic skill binding | | 2 | Discord | `DISCORD_BOT_TOKEN` + Members & Message Content intents | Skills as Application Commands, `/sethome` for proactive messages, voice-channel mode | | 3 | Slack | `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` (Socket Mode) | Multi-workspace via comma-separated tokens; native approval buttons preserve thread context | | 4 | WhatsApp | `hermes whatsapp` QR (Baileys, **not** Business API) | Dedicated bot number recommended; unofficial — risk of bans | | 5 | Signal | `signal-cli` linked secondary device (`SIGNAL_ACCOUNT`) | Attachments ≤100 MB, phone redaction in logs | | 6 | SMS | Twilio: `TWILIO_ACCOUNT_SID/AUTH_TOKEN/PHONE_NUMBER` + `SMS_WEBHOOK_URL` | Plain text only (no media/voice); needs a public webhook endpoint; shares creds with the telephony skill | | 7 | Email | IMAP 993 + SMTP 587 (`EMAIL_ADDRESS/PASSWORD`) | 15 s polling, In-Reply-To threading, image attachments cached for vision | | 8 | Home Assistant | `HASS_TOKEN`, `HASS_URL` | WebSocket state stream; `ha_call_service` tool | | 9 | Mattermost | `MATTERMOST_URL` + `MATTERMOST_TOKEN` | REST v4 + WebSocket; v0.8.0 file attachments | | 10 | Matrix | `MATRIX_HOMESERVER` + access token; optional E2EE | mautrix-python since v0.9.0; reactions, read receipts, rich formatting | | 11 | DingTalk | `DINGTALK_CLIENT_ID/CLIENT_SECRET` (Stream Mode) | Persistent WebSocket through NAT; 20K-char message cap | | 12 | Feishu / Lark | `FEISHU_APP_ID/APP_SECRET` (QR via `hermes gateway setup`) | Must subscribe to `card.action.trigger` for buttons | | 13 | WeCom | `WECOM_BOT_ID`, `WECOM_SECRET` | Bot-style over persistent WebSocket; AES media auto-handled | | 14 | WeCom Callback | `WECOM_CALLBACK_CORP_ID/CORP_SECRET/AGENT_ID/TOKEN/ENCODING_AES_KEY` | Self-built enterprise app via encrypted XML callbacks; needs a public callback URL; multi-corp routing (added in v0.9.0) | | 15 | Weixin (WeChat) | `WEIXIN_ACCOUNT_ID` — iLink Bot API, QR setup | Personal WeChat accounts; long-polling, no public endpoint needed (added in v0.9.0) | | 16 | BlueBubbles (iMessage) | `BLUEBUBBLES_SERVER_URL` + `BLUEBUBBLES_PASSWORD` | Bridges iMessage via an always-on Mac running BlueBubbles Server ≥1.0.0; auto-webhook registration (added in v0.9.0) | Beyond these sixteen, **Webhooks** act as an event-driven inbound surface (`hermes webhook subscribe`, HMAC-secured, direct-delivery mode since v0.11.0), and the **API server / Open WebUI** integration exposes the agent to browsers. ### Platforms added after v0.9.0 Later releases extend the roster (no per-platform pages yet): **QQBot** (17th, v0.11.0), **Tencent Yuanbao** (18th, v0.12.0), **Microsoft Teams** (19th, plugin-shipped, v0.12.0; end-to-end in v0.14.0), **Google Chat** (20th, v0.13.0), **LINE** and **SimpleX Chat** (21st–22nd, v0.14.0), **ntfy** (23rd, v0.15.0). ### Cross-Platform Continuity `gateway/mirror.py` performs cross-session mirroring for `send_message` and explicit-target delivery — output can be routed to a platform other than the one that originated the request. Per-chat session store keyed by `(platform, chat_id)` is per-channel, but skill state, [[entities/memory-honcho]] memory, and FTS5 session search are **shared**. Typical pattern: start on CLI, run `/background <prompt>`, receive the completion ping on Telegram via `notify_on_complete`. ## When To Use - **Always-on personal assistant** — install as a launchd/systemd service so the gateway answers DMs while you sleep. - **Team bot** — Slack or Discord with allowlisted user IDs; skills become the surface area. - **Cross-device continuity** — start on desktop CLI, finish on phone (Telegram/Signal); since v0.16.0 the desktop app ([[entities/hermes-desktop-app]]) can attach to a remote gateway too. - **Home automation** — Home Assistant + Matrix or Telegram for voice control and alerts. - **Cron delivery target** — scheduled jobs ([[concepts/cron-scheduling]]) deliver to whichever platform is convenient. - **Multi-region deployment** — pair gateway with a [[concepts/deployment-backends]] like `daytona` or `modal` to scale beyond one machine. ## Risks & Pitfalls - **Default-deny is strict.** New users get silently ignored unless allowlisted or DM-paired. Confirm allowlists with `hermes status`. Since v0.13.0 WhatsApp also rejects strangers by default. - **Two gateway instances on the same `HERMES_HOME` corrupt the SQLite session store.** Use [[concepts/profiles-multi-instance]] profiles for parallel instances. - **Linux systemd needs lingering** for user services to survive logout: `sudo loginctl enable-linger $USER` (or install the boot-time system service with `sudo hermes gateway install --system`). - **Discord intents** — Server Members Intent and Message Content Intent must be enabled in the Developer Portal or the bot sees nothing. - **Telegram BotFather "Privacy Mode" must be off** for group reads; remove and re-add the bot after toggling. - **WhatsApp via Baileys is unofficial** — avoid bulk messaging to limit ban risk; use a dedicated number. - **Feishu cards error 200340** if `card.action.trigger` is not subscribed. - **Email allowlist is critical** — anyone with the address can command the agent otherwise. - **Slack** requires `/invite @Hermes` in every channel, plus the Messages Tab enabled for DMs. - **Skill slash command cap (100/bot on Discord)** — beyond that some skills won't surface as Application Commands. - **SMS adapter refuses to start without `SMS_WEBHOOK_URL`** (required for Twilio signature validation) and needs a publicly reachable server. - **BlueBubbles needs an always-on Mac** signed into Messages.app running BlueBubbles Server ≥1.0.0. - **WeCom Callback needs a public HTTPS callback endpoint** (or a tunnel) — unlike bot-mode WeCom, which connects outbound over WebSocket. ## Related Concepts - [[concepts/deployment-backends]] — gateway tools execute through the configured backend - [[concepts/profiles-multi-instance]] — each profile = its own gateway instance - [[concepts/skills-system]] — skills auto-register as slash commands - [[concepts/cron-scheduling]] — cron ticks run inside the gateway loop - [[concepts/approval-system]] — native approval buttons live on Telegram, Slack, Feishu - [[concepts/model-switching]] — `/model` works mid-conversation across platforms - [[concepts/cli-reference]] — `hermes gateway|pairing|whatsapp|webhook` command surface - Per-platform entity pages: [[entities/platform-telegram]], [[entities/platform-discord]], [[entities/platform-slack]], [[entities/platform-whatsapp]], [[entities/platform-signal]], [[entities/platform-email]], [[entities/platform-matrix]], [[entities/platform-home-assistant]], [[entities/platform-dingtalk]], [[entities/platform-mattermost]], [[entities/platform-feishu]], [[entities/platform-wecom]] (SMS, WeCom Callback, Weixin, BlueBubbles and the post-v0.9.0 platforms have no entity pages yet) ## Sources - `raw/05-deployment-and-platforms.md` (Section B, "Messaging Gateway + 12 Platforms") - `raw/docs-user-guide-messaging.md` (16-platform comparison table, gateway commands, security, service management) - `raw/docs-user-guide-messaging-sms.md`, `raw/docs-user-guide-messaging-weixin.md`, `raw/docs-user-guide-messaging-wecom-callback.md`, `raw/docs-user-guide-messaging-bluebubbles.md` (new-platform auth/setup) - `raw/release-v0.9.0.md` (16-platform milestone, proxy/WSL/batching, Matrix migration) - `raw/release-v0.11.0.md` … `raw/release-v0.15.0.md` (platform additions 17–23, plugin host, security wave, deliverable mode) - v0.16.0 release tag (stream-event protocol, dashboard Channels page, desktop remote-gateway connect) - Source files referenced: `gateway/run.py`, `gateway/delivery.py`, `gateway/mirror.py`, `gateway/pairing.py`, `gateway/session.py`, `gateway/hooks.py`, `gateway/platforms/*.py`, `hermes_cli/gateway.py`, `hermes_cli/pairing.py` <!-- ===== hermes/wiki/concepts/migration-from-openclaw.md ===== --> --- title: "Migration from OpenClaw" type: concept tags: [vs-openclaw, foundational, well-established, beginner, cli, config] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/02-install-and-setup.md", "raw/awesome-hermes-agent-readme.md", "raw/release-v0.6.0.md", "raw/transcript-switching-to-hermes.txt", "raw/transcript-hermes-full-course-2hr.txt", "raw/transcript-live-masterclass-browser-qwen.txt", "raw/transcript-did-hermes-kill-openclaw.txt", "raw/transcript-why-hermes-replaced-openclaw.txt"] confidence: high hermes_version: "v0.8.0" --- # Migration from OpenClaw ## Definition `hermes claw migrate` is the official, in-tree command for moving an existing OpenClaw setup over to Hermes Agent. It transfers the user-facing parts of an OpenClaw install — `SOUL.md`, memories, skills, command allowlist, messaging settings, TTS assets, and a curated set of API keys — into the equivalent locations under `~/.hermes/`. The migration first shipped end-to-end in v0.3.0, and v0.6.0 substantially expanded it to cover sessions, cron jobs, and memory. As of Hermes v0.8.0 it is the recommended path; the older community tool `openclaw-to-hermes` (built when the native `hermes-migrate` had critical bugs) is now obsolete for v0.3.0+. The command is offered automatically the first time you run `hermes setup` if `~/.openclaw/` is detected on disk. ## How It Works ### Three invocation paths 1. **Automatic during first-time setup.** `hermes setup` runs an `is_managed()` guard and `_has_any_provider_configured()` probe; if it sees `~/.openclaw/`, the very first prompt offers OpenClaw migration before anything else is configured. Accept and the wizard runs the equivalent of `hermes claw migrate` interactively, then continues to the standard provider / backend / messaging / tools sections. 2. **Standalone CLI command.** `hermes claw migrate [flags]` can be run any time after install. The companion `hermes claw cleanup` removes the OpenClaw install once you are confident the migration succeeded. 3. **Agent-guided.** Inside an interactive session, asking the agent to "migrate from OpenClaw" triggers it to invoke the same command via its `terminal` tool, walk you through the prompts, and explain each step. ### What gets migrated | OpenClaw artifact | Hermes destination | |---|---| | `SOUL.md` (system persona) | `~/.hermes/SOUL.md` | | `MEMORY.md`, `USER.md` and other memory files | `~/.hermes/memories/` | | Installed skills | `~/.hermes/skills/` (under their original category, conflict policy applied) | | Command allowlist | `command_allowlist:` block in `config.yaml` | | Messaging gateway settings (Telegram, Discord, Slack, etc.) | corresponding env vars in `~/.hermes/.env` and platform sections in `gateway.json` | | TTS assets (custom voices, audio cache) | `~/.hermes/tts/` | | Allowlisted API keys | `~/.hermes/.env` | | Cron jobs (v0.6.0+) | Hermes cron store (see [[concepts/cron-scheduling]]) | | Session history (v0.6.0+) | `~/.hermes/sessions/` | **API keys carried across (default allowlist):** OpenRouter, OpenAI, Anthropic, ElevenLabs, Telegram. Anything else is held back by default unless you pass `--migrate-secrets` (see flag reference). ### What does NOT migrate - **WhatsApp pairing.** Baileys session state (`~/.openclaw/whatsapp/...`) is not portable; you must re-pair via `hermes whatsapp` after migration. - **`source: file` / `source: exec` SecretRefs.** Any OpenClaw secret that resolves dynamically from a file or a shell command is skipped — Hermes refuses to inline the resolved values and asks you to recreate the reference manually. - **Custom OpenClaw plugins** outside the supported skill / memory / cron surfaces. - **Live process state** (active sessions, in-flight jobs, background tasks). ### Migration report Every run writes an itemised report to `~/.hermes/migration/<timestamp>/` containing: a manifest of source → destination paths, a list of conflicts and how they were resolved, a list of skipped items with reasons, and a copy-on-write backup of any pre-existing Hermes file it overwrote. The report is the canonical artifact to review when deciding whether to run `hermes claw cleanup`. ### Conflict handling defaults - **Skill name collision.** Default policy: `keep-existing` — Hermes keeps its own copy and notes the OpenClaw version in the report. Override via `--skill-conflict {keep-existing|overwrite|rename|skip}`. - **Memory files.** Merged by default (Hermes appends OpenClaw entries beneath a marker line); use `--overwrite` to replace. - **`SOUL.md`.** Skipped if a Hermes `SOUL.md` already exists, unless `--overwrite`. - **API keys already in `~/.hermes/.env`.** Always preserved — OpenClaw keys are written only for variables not already set. - **Workspace target.** Defaults to `~/.hermes/`; redirect with `--workspace-target /path/to/alt/home` when migrating into a profile or staging directory. ## Key Parameters ### Full flag reference ```bash hermes claw migrate [--dry-run] [--preset {user-data,full}] [--overwrite] [--migrate-secrets] [--workspace-target PATH] [--skill-conflict {keep-existing,overwrite,rename,skip}] [--yes] hermes claw cleanup [--yes] ``` | Flag | Effect | |---|---| | `--dry-run` | Walk the OpenClaw install and produce a migration report WITHOUT writing anything. The single most important flag — always run this first. | | `--preset user-data` | Migrate `SOUL.md`, memories, skills, allowlist, messaging settings, TTS assets, and the default-allowlisted API keys. (Default preset.) | | `--preset full` | Adds cron jobs and session history on top of `user-data`. Use for a true cutover. | | `--overwrite` | Replace any pre-existing Hermes file with the OpenClaw version on conflict. Without this, conflicts are merged or skipped per the default policy. | | `--migrate-secrets` | Carry across API keys outside the default allowlist (OpenRouter / OpenAI / Anthropic / ElevenLabs / Telegram). Skipped values are still listed in the report so you can move them by hand. | | `--workspace-target PATH` | Redirect the destination root from `~/.hermes/` to an alternative HERMES_HOME — useful when migrating into a [[concepts/profiles-multi-instance]] profile. | | `--skill-conflict POLICY` | One of `keep-existing` (default), `overwrite`, `rename` (suffix the OpenClaw skill `-from-openclaw`), `skip`. | | `--yes` | Skip all interactive confirmations. Required for non-TTY use. | ### Recommended dry-run-first workflow ```bash # 1. Preview what would happen hermes claw migrate --dry-run --preset full # 2. Inspect the report ls -la ~/.hermes/migration/ $EDITOR ~/.hermes/migration/<timestamp>/report.md # 3. Run for real once satisfied hermes claw migrate --preset full # 4. Restart the gateway so newly migrated skills are picked up hermes gateway restart # 5. Re-pair platforms that did not move (WhatsApp at minimum) hermes whatsapp # 6. Once verified, remove OpenClaw hermes claw cleanup ``` ## When To Use - **You are already running OpenClaw and want to evaluate Hermes side by side.** Run with `--workspace-target ~/hermes-trial/` so OpenClaw stays untouched at `~/.openclaw/` and Hermes runs from a separate HERMES_HOME you can throw away. - **You are cutting over.** Use `--preset full --migrate-secrets` after a successful `--dry-run`. - **You want a partial copy** (e.g. just skills and memory). Run `--preset user-data` and ignore the cron/session history. - **You are seeding a new Hermes [[concepts/profiles-multi-instance]] profile** with an existing OpenClaw config — combine with `--workspace-target ~/.hermes/profiles/<name>/`. ## Risks & Pitfalls - **Always `--dry-run` first.** The migration is mostly idempotent but is NOT trivially reversible — skill collisions and merged memory files are particularly hard to unwind. - **WhatsApp WILL break post-migration.** Baileys session state is not portable; budget time to re-pair via `hermes whatsapp` (QR scan). - **`source: file` / `source: exec` SecretRefs are silently skipped.** Read the report to identify them; recreate manually as either plain `.env` entries or proper Hermes credential pool entries. - **Default secret allowlist is conservative.** Without `--migrate-secrets`, only OpenRouter / OpenAI / Anthropic / ElevenLabs / Telegram cross over. Tool keys like `EXA_API_KEY`, `FIRECRAWL_API_KEY`, `BROWSERBASE_*` need to be moved manually or with the flag. - **Skill conflicts default to keep-existing.** If you want OpenClaw's version to win, you must pass `--skill-conflict overwrite` — easy to miss. - **Restart the gateway after migration.** Newly migrated skills register their slash commands on gateway start; without a restart they will not appear in Telegram/Discord/Slack. - **Migrating into the active HERMES_HOME mid-session is unsupported.** Stop `hermes gateway` first or use `--workspace-target` to land in a fresh tree. - **Don't run `hermes claw cleanup` until you've verified the new install.** Cleanup is destructive and removes `~/.openclaw/`. - **Pre-v0.3.0 history.** The community tool `openclaw-to-hermes` was the only working path before native migration was reliable; it should NOT be used today (the awesome-hermes index now explicitly recommends `hermes claw migrate`). - **Migration report is the source of truth.** When something looks wrong post-migration, read `~/.hermes/migration/<ts>/report.md` before re-running anything. ## Related Concepts - [[concepts/skills-system]] — destination for migrated OpenClaw skills; conflict-resolution policies live here. - [[concepts/memory-system]] — destination for `MEMORY.md`, `USER.md`, and `SOUL.md`. - [[concepts/profiles-multi-instance]] — combine with `--workspace-target` to migrate into an isolated profile. - [[concepts/messaging-gateway]] — Telegram/Discord/Slack settings move; WhatsApp re-pair required. - [[concepts/cron-scheduling]] — receives migrated cron jobs under `--preset full`. - [[concepts/approval-system]] — destination for OpenClaw command allowlist. - [[syntheses/hermes-vs-openclaw]] — strategic comparison; explains why migration is offered first-class. - [[entities/openclaw]] — the source system. ## Sources - `raw/02-install-and-setup.md` — `hermes claw {migrate,cleanup}` CLI entry, OpenClaw migration offer in first-time `hermes setup` flow - `raw/awesome-hermes-agent-readme.md` — guidance to prefer native `hermes claw migrate` over the community `openclaw-to-hermes` tool from v0.3.0+; side-by-side migration recipe - `raw/release-v0.6.0.md` — comprehensive OpenClaw migration guide expansion (sessions, cron, memory) - `raw/transcript-switching-to-hermes.txt` — narrative description of the migration scope (`SOUL.md`, memories, skills, API keys, messaging configs) - `raw/transcript-hermes-full-course-2hr.txt` — `hermes claw migrate` walkthrough, dry-run callout, automatic detection during onboarding - `raw/transcript-live-masterclass-browser-qwen.txt` — live demo of `hermes claw migrate` - `raw/transcript-did-hermes-kill-openclaw.txt` — comparative framing for migration motivation - `raw/transcript-why-hermes-replaced-openclaw.txt` — `soul user.md` configuration mention establishing source artifacts <!-- ===== hermes/wiki/concepts/ml-research-pipeline.md ===== --> --- title: "ML Research Pipeline" type: concept tags: [ml-research, tools, advanced, developer, well-established, foundational] created: 2026-04-12 updated: 2026-04-13 sources: - "raw/04-tools-mcp-cron-subagents.md" - "raw/03-skills-system.md" - "raw/transcript-hermes-full-course-2hr.txt" - "raw/transcript-switching-to-hermes.txt" - "raw/02-install-and-setup.md" - "raw/ml-research-recipe.md" confidence: high hermes_version: "v0.8.0" --- # ML Research Pipeline ## Definition Hermes ships a complete ML and reinforcement-learning research toolchain inside the agent — not as an optional add-on, but as a first-class set of tools, skills, and CLI scripts. This is the same harness Nous Research uses to train the Hermes model family, exposed so that any user can capture trajectories, generate datasets at scale, fine-tune small models, run RL training loops, and write conference-grade papers — all from inside an agent conversation. As one community reviewer put it, Hermes is "built for tinkerers" with "machine learning tools built-in" and "reinforcement learning tools built-in" because Nous "are the people behind Hermes model family. So, they know how models learn because they train them for legitimately a living and that shows in the architecture." ## How It Works The pipeline has four layered components that feed into each other: **1. Trajectory Capture (`agent/trajectory.py`)** — Every agent run records a full trajectory: every tool call, every decision, every result, in order. Most agent frameworks throw this away when the task ends ("most agent frameworks they just throw that away completely. Like the task is done, the memory's gone. Hermes keeps it instead"). Hermes serializes the trajectory to ShareGPT JSONL — the de-facto fine-tuning format with `from`/`value` pairs that Axolotl, Unsloth, TRL, and HuggingFace `datasets` all consume natively. This single decision is what makes the [[concepts/self-improvement-loop]] possible and what lets a Hermes user export "training data for your own models" without any extra plumbing. **2. Batch Runner (`batch_runner.py`, 1287 lines)** — A standalone script (separate from the in-agent `delegate_task` tool — see [[concepts/subagents-delegation]]) for offline, parallel dataset processing. Spawns a multiprocessing Pool, each worker an independent AIAgent, and writes results checkpoint-resumably: ```bash python batch_runner.py --dataset_file=data.jsonl --batch_size=10 --run_name=my_run [--resume] [--distribution=image_gen] ``` Trajectories are saved as ShareGPT-format from/value pairs alongside per-tool success/failure stats normalized via `_normalize_tool_stats()`. Output is HuggingFace-compatible Arrow/Parquet so the resulting dataset can be `dataset.push_to_hub()`'d directly, or loaded into Axolotl/Unsloth without conversion. Toolset distributions in `/toolset_distributions.py` let you preset which tool subset each batch worker is allowed to use (e.g. `--distribution=image_gen` restricts to image-related tools). **3. Trajectory Compressor (`trajectory_compressor.py`)** — Long agent runs blow past fine-tuning context windows (16K–128K tokens). The compressor takes a recorded trajectory and folds intermediate tool outputs into summarized states so the conversation still fits, while preserving the gradient signal of the actual decision sequence. This is what makes hour-long agent traces usable as SFT data on a 32K-context base model. **4. RL Pipeline — Tinker + Atropos** — Ten dedicated RL tools registered in `tools/registry.py`, exposed to the agent itself so it can drive its own training: | Tool | Purpose | |---|---| | `rl_list_environments` | List available Atropos RL environments | | `rl_select_environment` | Pick an environment for a run | | `rl_get_current_config` / `rl_edit_config` | Read/edit the run config | | `rl_start_training` / `rl_stop_training` | Kick off / abort a run | | `rl_check_status` / `rl_list_runs` / `rl_get_results` | Monitor + retrieve | | `rl_test_inference` | Smoke-test the trained policy | Behind the tools is `rl_cli.py`, the standalone command-line entry point. The default recipe — hardcoded in `tools/rl_training_tool.py` — is **Qwen/Qwen3-8B + LoRA rank 32 + SGLang inference on :8001 + Atropos trajectory API on :8000 + Weights & Biases logging**, 2500 training steps, learning rate 4e-5, max_token_length 8192, checkpoint every 25 steps. Tinker is actually **Thinking Machines Lab's managed LoRA training API** (not Nous's) — Atropos is Nous's environment library, `tinker-atropos` is the glue. `TINKER_API_KEY`, `WANDB_API_KEY`, and `RL_API_URL` are the three env vars required (see [[entities/version-v0.8.0]] env reference). ## Recipe A — Tinker + Atropos (default) **Prerequisites:** Sign up at `https://auth.thinkingmachines.ai/sign-up`, generate a key at `https://tinker-console.thinkingmachines.ai/keys`, put `TINKER_API_KEY=tnkr_...` and `WANDB_API_KEY=...` in `~/.hermes/.env`. Clone `github.com/NousResearch/tinker-atropos` and `pip install -e .` in it. **Step 1 — Generate trajectories.** Either use session history already written to `trajectory_samples.jsonl`, or synthesize a batch: ```bash python batch_runner.py \ --dataset_file=prompts.jsonl \ --batch_size=10 --run_name=my_run \ --distribution=default --num_workers=4 ``` where `prompts.jsonl` is one `{"prompt": "..."}` per line. Output lands in `data/my_run/trajectories.jsonl` as ShareGPT `from`/`value` pairs (`system`/`human`/`gpt`/`tool` roles). **Step 2 — Compress** long runs to fit the 8192 token trainer window: ```bash python trajectory_compressor.py --input=data/my_run/trajectories.jsonl --target_max_tokens=8000 ``` **Step 3 — Edit config.** Start from `tinker-atropos/configs/default.yaml`, change `tokenizer_name` and `openai[0].model_name` to `Qwen/Qwen3-8B`, confirm `tinker.lora_rank: 32`, `tinker.learning_rate: 0.00004`, `env.max_token_length: 8192`, `env.total_steps: 2500`, `tinker.save_checkpoint_interval: 25`. **Step 4 — Launch (three terminals, or use `rl_cli.py` to auto-orchestrate):** ```bash # Terminal 1 run-api # Atropos API on :8000 # Terminal 2 python launch_training.py --config configs/qwen3_8b.yaml # trainer + SGLang on :8001 # Terminal 3 python tinker_atropos/environments/gsm8k_tinker.py serve --config configs/qwen3_8b.yaml ``` Or simply: `python rl_cli.py "Train Qwen3-8B on GSM8K with LoRA rank 32"` (spawns all three, 5s → 120s delays). **Step 5 — Monitor.** `rl_check_status` tool (inside Hermes) returns current WandB metrics. Dashboard at `wandb.ai/<user>/hermes-rl`. `rl_test_inference` hits the running policy. **Step 6 — Retrieve weights.** Training emits a `tinker://<hash>` path: ```bash python tinker_atropos/utils/download_weights.py # saves to ./checkpoints/<hash>/ ``` Load with `PeftModel.from_pretrained(base_model, "./checkpoints/<hash>/")`. **Cost/time (inferred, not official):** a full 2500-step Qwen3-8B LoRA run takes ~4–12h wall clock and ~tens of dollars at typical Tinker rates. Smoke-test first with `quick_test.yaml` (10 steps, Llama-3.2-1B, minutes). ## Recipe B — No Tinker (Axolotl / Unsloth fallback) Everything up to compression works without a Tinker account — you still end up with a ShareGPT JSONL. Then fine-tune offline: **Axolotl (Qwen3-8B, QLoRA rank 32, single 24GB GPU):** ```yaml # qwen3_8b_lora.yml base_model: Qwen/Qwen3-8B load_in_4bit: true datasets: - path: data/my_run/trajectories_compressed.jsonl type: sharegpt conversation: chatml adapter: lora lora_r: 32 lora_alpha: 64 lora_target_modules: [q_proj, k_proj, v_proj, o_proj, gate_proj, down_proj, up_proj] sequence_len: 8192 micro_batch_size: 2 gradient_accumulation_steps: 8 num_epochs: 3 learning_rate: 2e-4 output_dir: ./qwen3-8b-hermes-lora flash_attention: true ``` ```bash accelerate launch -m axolotl.cli.train qwen3_8b_lora.yml python -m axolotl.cli.merge_lora qwen3_8b_lora.yml ``` **Unsloth** (2–5× faster on the same GPU) and **TRL** (most control) are the other supported routes — see the `skills/mlops/training/unsloth/` and `trl-fine-tuning/` skills. **What you give up:** no online RL reward loop. Axolotl/Unsloth is SFT-only on your captured trajectories. To do RL without Tinker, run GRPO locally via `skills/mlops/training/grpo-rl-training/` on your own GPU cluster. For "train Hermes on my own history," SFT is the right default. Full step-by-step commands, verbatim configs, a concrete ShareGPT trajectory example, and confidence assessment live in `raw/ml-research-recipe.md` (raw source, outside the wiki). The whole pipeline ties back to the underlying model — the transcript-247 video notes Hermes is "powered by the Hermes 3 model built on Llama 3.1 and fine-tuned using a reinforcement learning framework called Atropos. The training specifically targets tool calling accuracy and long-range planning." **5. MLOps Skills Library** — Bundled skills under `skills/mlops/` (see [[concepts/skills-system]]) cover the full MLOps lifecycle: - `training/axolotl`, `training/unsloth`, `training/peft`, `training/pytorch-fsdp`, `training/trl-fine-tuning`, `training/grpo-rl-training` - `inference/vllm`, `inference/llama-cpp`, `inference/gguf`, `inference/sglang` (via outlines/guidance/obliteratus) - `cloud/modal`, `evaluation/`, `huggingface-hub/`, `vector-databases/` Plus `research/research-paper-writing` — a skill for drafting NeurIPS/ICML/ICLR-style papers with proper LaTeX, related-work tables, and reproducibility checklists. `research/arxiv` handles paper search and metadata. ## Key Parameters **Environment variables** (set in `~/.hermes/.env`): - `TINKER_API_KEY` — Thinking Machines Tinker managed LoRA training API (key from `tinker-console.thinkingmachines.ai/keys`) - `WANDB_API_KEY` — Weights & Biases experiment tracking - `RL_API_URL` — Atropos trajectory API endpoint (default `http://localhost:8000`) - `HF_TOKEN` — HuggingFace push/pull access (for base model / tokenizer download) **Batch runner flags:** - `--dataset_file` — JSONL input - `--batch_size` — parallel worker count - `--run_name` — checkpoint key - `--resume` — pick up from last checkpoint - `--distribution` — toolset subset (see `toolset_distributions.py`) **Skill catalog** — discoverable via `hermes skills browse`, installable via `hermes skills install official/mlops/<skill>`. The agent autonomously calls `skill_view("axolotl")` etc. when it detects an MLOps task. ## When To Use - **You are training your own models.** This is the entire reason Nous built it this way — you can dogfood the harness that trained Hermes 3. - **You need to generate SFT/RL datasets at scale.** Point batch_runner at a JSONL of prompts and walk away; come back to a Parquet shard ready for `datasets.load_dataset`. - **You want offline benchmarking of agent behavior.** Run a fixed eval set across providers/models and diff the trajectories. - **You are writing an ML paper.** The `research-paper-writing` skill plus `arxiv` plus persistent [[concepts/skills-system]] memory of prior literature reviews compounds across drafts. - **You want to fine-tune on your own usage.** Trajectories captured automatically by Hermes during normal use can be exported and used to train a personalized small model — the loop the [[concepts/self-improvement-loop]] hints at but stops short of automating. ## Risks & Pitfalls - **GPU dependency.** RL training tools require either a Tinker-backed remote GPU pool or a local CUDA box. The 10 RL tools will register but `rl_start_training` fails fast on machines without configured GPU access. - **Trajectory bloat.** Long-running agents can produce trajectories in the megabytes — always run `trajectory_compressor.py` before fine-tuning, otherwise context overflow trashes the run. - **ShareGPT format drift.** Some downstream trainers expect slightly different role names (`human`/`gpt` vs `user`/`assistant`). Confirm your trainer's loader matches the exporter's schema before kicking off a long fine-tune. - **Batch runner is not the same as `delegate_task`.** The runner is offline/scripted; `delegate_task` is interactive subagent spawning ([[concepts/subagents-delegation]]). Mixing them up wastes hours. - **MLOps skills are LLM-generated by default.** Like all skills they may have stale package versions — pin the version in your skill before shipping a reproducible paper. - **WandB is on by default in the recipe** — if you're training a sensitive model, swap to `wandb offline` or strip the integration before launching. - **First-day output is usually bad.** The course transcript warns "be prepared for the first 7 days, it won't be what you want. It won't do anything perfectly. But, the point is it gets better every time." ## Related Concepts - [[concepts/self-improvement-loop]] — trajectory capture is the mechanism behind GAPA and skill auto-creation - [[concepts/skills-system]] — the MLOps skills library and `research-paper-writing` live here - [[concepts/subagents-delegation]] — `delegate_task` (in-agent) vs `batch_runner.py` (offline) - [[concepts/local-models-airplane-mode]] — vLLM, SGLang, llama.cpp inference skills double as local serving for trained models - [[entities/nous-research]] — the lab and its model family - [[entities/hermes-self-evolution]] - [[entities/version-v0.8.0]] — current verified version ## Sources - `raw/04-tools-mcp-cron-subagents.md` — tool registry, batch_runner internals, RL tools list, toolset distributions - `raw/03-skills-system.md` — full MLOps skill catalog under `skills/mlops/` - `raw/transcript-hermes-full-course-2hr.txt` — practical use, Hermes 3 / Atropos lineage, "built for tinkerers" framing - `raw/transcript-switching-to-hermes.txt` — trajectory capture explanation, ShareGPT export, Nous RL pipeline as differentiator - `raw/02-install-and-setup.md` — `TINKER_API_KEY`, `WANDB_API_KEY`, `RL_API_URL` env vars - `raw/ml-research-recipe.md` — end-to-end fine-tune recipe with verbatim configs, both Tinker and non-Tinker paths, confidence assessment <!-- ===== hermes/wiki/concepts/model-switching.md ===== --> --- title: "Model Switching & Credential Pools" type: concept tags: [model-switching, provider, config, foundational, well-established] created: 2026-04-12 updated: 2026-06-04 sources: ["raw/04-tools-mcp-cron-subagents.md", "raw/02-install-and-setup.md", "raw/release-v0.6.0.md", "raw/release-v0.7.0.md", "raw/release-v0.8.0.md", "raw/release-v0.9.0.md", "https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29"] confidence: high hermes_version: "v0.15.1" --- # Model Switching & Credential Pools ## v0.15.1 additions (not yet fully reflected below) - **Unified `/model` picker/listing path with disk cache** — CLI `/model` and `hermes model` now share the same picker/listing code path backed by a disk cache. In-session and out-of-session model selection no longer drift (e.g. a model visible in the picker is now actually selectable mid-session, and vice versa). - **`/yolo` can be enabled mid-session** — the gateway `/yolo` slash command can flip a running chat into approval-bypass mode without restarting the gateway. Behavior is still session-scoped per `(platform, chat_id)`. This is a safety/approval-bypass change, not a model-selection change — for the deeper approval framing see [[concepts/approval-system]]. ## v0.9.0 additions (not yet fully reflected below) - **Fast Mode (`/fast`)** — priority-queue routing for OpenAI Priority Processing models (GPT-5.4, Codex) and Anthropic's fast tier. Toggle mid-session for lower latency on supported models. - **Native xAI (Grok) provider** elevated to first-class with direct API + model catalog - **Native Xiaomi MiMo provider** elevated to first-class with setup wizard + empty-response recovery - **Qwen OAuth provider** with portal request support - **Credential exhaustion TTL reduced from 24h to 1h** — rate-limited pool keys recover ~24× faster - **Custom providers** now included in `/model` listings and resolution - **OpenRouter variant tags** (`:free`, `:extended`, `:fast`) preserved during model switch - **`/model` switch persistence** across gateway messages — fix (was a known issue) - **Structured API error classification** for smarter failover decisions - **Fallback provider activation** on repeated empty responses with user-visible status - **Native `/model` picker modal** for provider → model selection ## Definition Hermes is deliberately provider-agnostic. It speaks to every major hosted inference API and every major local runtime through a uniform provider abstraction, rotates across multiple keys for the same provider, falls back to a different provider entirely when one is down, switches models mid-session on user command, and (optionally) routes simple prompts to a cheap model automatically. All of this is configured in `config.yaml` under `model`, `fallback_providers`, `credential_pool_strategies`, `custom_providers`, and `smart_model_routing`. ## How It Works ### The `/model` command (v0.8.0) `/model` switches the current model and provider mid-session and works across all surfaces: the CLI, Telegram, Discord, Slack, and any gateway platform. Aggregator-aware resolution keeps you on OpenRouter or Nous Portal when the requested model is reachable through them, so you don't accidentally thrash credentials. Telegram and Discord get interactive pickers with inline buttons; other platforms get a text prompt flow. `hermes model` is the equivalent CLI entry point — an interactive provider + model picker when launched outside a session. ### Supported providers From the Full Setup wizard picker, Hermes natively supports: - **Hosted aggregators** — OpenRouter, Kilocode, AI Gateway, OpenCode Zen/Go - **Nous-native** — Nous Portal (OAuth; hosts free-tier Xiaomi MiMo v2 Pro as of v0.8.0) - **Frontier providers** — Anthropic, OpenAI Codex (OAuth), GitHub Copilot (OAuth), Google AI Studio / Gemini (native, added v0.8.0) - **Chinese providers** — Z.AI / GLM, Kimi (Moonshot), MiniMax, MiniMax-CN, DeepSeek, Qwen (OAuth), Xiaomi - **Hugging Face** — inference API - **Local runtimes** — Ollama, vLLM, llama.cpp, LM Studio (via the custom-provider path, which accepts any OpenAI-compatible base URL) Standard env-var keys: `OPENROUTER_API_KEY`, `OPENAI_API_KEY` (+ `OPENAI_BASE_URL`), `ANTHROPIC_API_KEY`, `ANTHROPIC_TOKEN`, `NOUS_API_KEY`, `GOOGLE_API_KEY` / `GEMINI_API_KEY`, `GLM_API_KEY`, `KIMI_API_KEY`, `MINIMAX_API_KEY`, `HF_TOKEN`, `XIAOMI_API_KEY`, `KILOCODE_API_KEY`, `AI_GATEWAY_API_KEY`, `OLLAMA_API_KEY`, `HERMES_QWEN_BASE_URL`. OAuth logins — Nous Portal, Codex, Copilot, Qwen — go through `hermes login [--provider P]`. ### Credential pools (v0.7.0) Pooled credentials let you register **multiple API keys for the same provider**. Managed via `hermes auth {add, list, remove, reset}`. Rotation behavior is set per-provider in `config.yaml` under `credential_pool_strategies`. **Four strategies:** - **`fill_first`** — always use the first healthy key; only rotate when it fails. Simplest, preserves rate-limit buckets on the primary key. - **`round_robin`** — rotate sequentially across the pool per request. Even distribution but ignores key health history. - **`random`** — sample uniformly at random per request. Useful for smoothing out aggregator sticky-routing. - **`least_used`** — thread-safe counter-based selection, the v0.7.0 reference strategy. Best for sustained throughput. **Auto-failover triggers.** A response code of **401** (auth failure — key revoked or invalid) triggers automatic rotation to the next credential. **429** (rate-limit) rotates to preserve throughput. **402** (payment required / out of credits) rotates past an exhausted key. When the whole pool for a given provider is drained or all return the same class of error, Hermes escalates to the fallback provider chain. ### Fallback provider chains (v0.6.0) `fallback_providers` in `config.yaml` is an ordered list of provider configurations. When the primary provider returns errors or is unreachable after exhausting its credential pool, Hermes walks the chain in order and retries the same request. This is distinct from credential rotation — credential pools swap keys within one provider, fallback chains swap providers entirely. Typical chain: Nous Portal → OpenRouter → Anthropic direct → local Ollama. ### Smart model routing `smart_model_routing` in `config.yaml`: ```yaml smart_model_routing: enabled: true max_simple_chars: 160 max_simple_words: 28 cheap_model: <provider/model> ``` When enabled, prompts under the `max_simple_chars` / `max_simple_words` thresholds go to `cheap_model`; anything longer or flagged as complex escalates to the session's main model. Related: `compression.summary_model` / `summary_provider` route context compression to a dedicated cheap model, and `auxiliary.vision.{provider, model}` route image analysis. The v0.8.0 "self-optimized GPT/Codex tool-use guidance" uses a similar auxiliary-model pattern for provider-specific prompt tuning. ### OpenRouter-specific routing `provider_routing` (OpenRouter only) — `sort`, `only`, `ignore`, `order` — fine-grained control over which upstream OpenRouter sees as eligible. Stacks with credential pools. ### Config sketch ```yaml model: provider: openrouter default: anthropic/claude-sonnet-4 context_length: 200000 credential_pool_strategies: openrouter: least_used anthropic: fill_first fallback_providers: - provider: nous model: Hermes-4-405B - provider: anthropic model: claude-sonnet-4 - provider: ollama base_url: http://localhost:11434 model: qwen2.5:32b smart_model_routing: enabled: true cheap_model: openrouter/meta-llama/llama-3.1-8b-instruct max_simple_chars: 160 auxiliary: vision: provider: nous model: xiaomi/mimo-v2-pro ``` ## Key Parameters | Key | Purpose | |---|---| | `model.provider` + `model.default` | Primary provider and model | | `model.api_key` / `base_url` / `context_length` / `max_tokens` | Per-model overrides | | `provider_routing` (OpenRouter) | `sort`, `only`, `ignore`, `order` | | `credential_pool_strategies.<provider>` | `fill_first` / `round_robin` / `random` / `least_used` | | `fallback_providers` | Ordered chain of provider dicts (v0.6.0) | | `smart_model_routing.enabled` | Toggle cheap-model routing | | `smart_model_routing.max_simple_chars` / `max_simple_words` | Simple-prompt thresholds | | `smart_model_routing.cheap_model` | Model for short prompts | | `compression.summary_model` / `summary_provider` | Context compression model | | `auxiliary.vision.{provider, model}` | Vision auxiliary model | | `custom_providers` | User-added OpenAI-compatible endpoints (Ollama/vLLM/llama.cpp/LM Studio) | ## When To Use - **`/model`** — mid-session switch when a provider goes down, or when you need a more capable model for one hard question - **Credential pools** — any time you hit rate limits on a single key; also for team deployments where multiple human-owned keys fund one agent - **`fill_first`** — low-traffic personal use, want predictable billing - **`round_robin` / `random`** — aggregator sticky-routing smoothing - **`least_used`** — sustained throughput across the whole pool - **Fallback chains** — production deployments where uptime matters more than cost per token; always include a local fallback for airplane-mode continuity - **Smart routing** — cron jobs and chatty conversational use where most turns are trivial and paying frontier rates is wasteful - **Local runtimes via `custom_providers`** — air-gapped runs, privacy-sensitive data, hardware you already own (DGX Spark setups, home servers) ## Risks & Pitfalls - **Pools share rate-limit budget with subagents** — a fan-out delegation can exhaust the pool the parent was relying on. - **401/429/402 are the only auto-rotation triggers** — a provider returning 500s or hanging does not rotate until the request times out. - **Fallback chain adds latency** — each step is a full request attempt; chains longer than 2–3 providers produce user-visible delays on outages. - **Smart routing can misclassify** — a short prompt with heavy context is still short by char count. Tune `max_simple_chars` for your workload or disable for agentic use where even tiny prompts trigger deep tool chains. - **OAuth providers (Nous, Codex, Copilot, Qwen)** store credentials under profile home; a stale OAuth token looks like 401 and triggers pool rotation, which can blow through fresh keys if the pool is OAuth-based. Pin OAuth providers to `fill_first`. - **Custom providers need an OpenAI-compatible endpoint** — plain Ollama `/api/generate` is not OpenAI-compatible; use `/v1/chat/completions`. - **Aggregator-aware resolution on `/model`** can keep you on an aggregator when you wanted a direct provider connection — pass the provider prefix explicitly (`anthropic/claude-sonnet-4` vs `claude-sonnet-4`). ## Related Concepts - [[concepts/cron-scheduling]] — cron jobs often pin `cheap_model` explicitly - [[concepts/subagents-delegation]] — `delegation.provider` / `model` override child routing - [[concepts/mcp-integration]] — MCP servers can add tools to any provider/model combination - [[concepts/local-models-airplane-mode]] — end-to-end local stack via `custom_providers` - [[entities/provider-nous-portal]], [[entities/provider-openrouter]], [[entities/provider-anthropic]], [[entities/provider-openai-codex]], [[entities/provider-google-ai-studio]], [[entities/provider-ollama-local]] - [[entities/version-v0.6.0]] — fallback provider chains introduced - [[entities/version-v0.7.0]] — credential pool rotation introduced - [[entities/version-v0.8.0]] — `/model` live switching across platforms, native Google AI Studio, free Xiaomi MiMo v2 Pro ## Sources - `raw/04-tools-mcp-cron-subagents.md` (tool registry and delegation model overrides) - `raw/02-install-and-setup.md` (config structure, provider list, env vars) - `raw/release-v0.6.0.md` — `fallback_providers` - `raw/release-v0.7.0.md` — same-provider credential pools, `least_used` - `raw/release-v0.8.0.md` — `/model` command, Google AI Studio native, MiMo v2 Pro <!-- ===== hermes/wiki/concepts/onchain-workflows.md ===== --> --- title: "Onchain Workflows" type: concept tags: [skills, mcp, platform, emerging, advanced, developer] created: 2026-04-13 updated: 2026-04-13 sources: ["raw/onchain-ecosystem.md", "raw/awesome-hermes-agent-readme.md"] confidence: medium hermes_version: "v0.8.0" --- # Onchain Workflows ## Definition Onchain workflows in Hermes Agent are any task that reads from or writes to a public blockchain — checking a wallet balance, inspecting a smart contract, monitoring DeFi positions, sending a USDC payment, routing a cross-chain message. Hermes does not ship blockchain functionality in its core; all onchain capability comes from **two opt-in first-party skills** (`blockchain/solana`, `blockchain/base`) plus **external MCP servers** plugged in via `config.yaml`. The current ecosystem is read-heavy and write-cautious: every mature Hermes onchain project places signing authority outside the agent's direct control, typically via an explicit operator approval step or an external policy engine. ## How It Works ### The two paths: skill vs MCP server Onchain capabilities reach Hermes by one of two routes, with different tradeoffs. **Skills** (the first-party approach): - A `SKILL.md` file plus a stdlib-only Python helper script in `scripts/` - The agent reads the SKILL.md via [[concepts/skills-system]] progressive disclosure - The agent invokes the script via `execute_code` or `terminal` — exactly like a human would - No extra process, no persistent connection, no typed tool schema - Best for: read-only data fetches, CoinGecko pricing, RPC queries **MCP servers** (the plugin approach): - Separate process exposing typed tools over stdio or HTTP - Configured in `config.yaml` under `mcp_servers:` (see [[concepts/mcp-integration]]) - Each tool becomes `mcp_<server>_<tool>` in Hermes' registry - Auto-refresh on `notifications/tools/list_changed` - Best for: stateful interactions, credentialed APIs, write operations Both are first-class. In practice: data-heavy reads go as skills, anything with credentials or signing goes as MCP or a Hermes plugin. ### First-party skills (v0.8.0) The Hermes repo ships exactly two blockchain skills under `optional-skills/blockchain/`: **`blockchain/solana`** (v0.2.0, by gizdusum) - `wallet`, `tx`, `token`, `activity`, `nft`, `whales`, `stats`, `price` - Default RPC: `https://api.mainnet-beta.solana.com` (override via `SOLANA_RPC_URL`) - Recommended substrate: Helius, QuickNode, or Triton - NFT detection is heuristic (amount=1, decimals=0) — **misses cNFTs and Token-2022** **`blockchain/base`** (v0.1.0, by youssefea) — Base L2 only, not Ethereum mainnet - `wallet`, `tx`, `token`, `gas`, `contract`, `whales`, `stats`, `price` - Default RPC: `https://mainnet.base.org` (override via `BASE_RPC_URL`) - Gas estimates are **L2 only** — don't include L1 data posting fee - Wallet discovery is **limited to ~15 hardcoded popular tokens** because EVM has no native "get all tokens" RPC Both are opt-in. Neither is installed by default — run `hermes skills install blockchain/solana` (or `/base`) to activate. ### MCP server landscape for common needs Mapped to the two chains the user actually targets: **Solana:** - **RPC / Agent Kit:** `sendaifun/solana-mcp` (Solana Agent Kit) - **Data provider:** any of the Helius-backed MCPs (`embetter/solana-helius-mcp`, `laroccacharly/helius-mcp`) - **DEX / swaps:** `kukapay/jupiter-mcp` (Jupiter Ultra API), `Dexter-DAO/dexter-mcp` (60+ DeFi tools) - **Security:** `kukapay/rug-check-mcp`, `tsmboa0/SolSecurity_MCP` - **Explorer:** `wowinter13/solscan-mcp` - **Full-stack agent:** `neekmode/unify` (Drift + Jupiter + Birdeye + Helius) **Ethereum / EVM:** - **Most-starred generic:** `mcpdotdirect/evm-mcp-server` (372★) - **Official data provider:** `alchemyplatform/alchemy-mcp-server` (81★, **official**) - **Etherscan:** `crazyrabbitLTC/mcp-etherscan-server` (29★) - **Dune Analytics:** `kukapay/dune-analytics-mcp` (40★) - **Uniswap:** `kukapay/uniswap-trader-mcp` (35★, automated swaps) - **Aave:** `kukapay/aave-mcp`, `qingfeng/defi-rates-mcp` (13+ protocols) - **NFT:** `ProjectOpenSea/opensea-mcp-next-sample` (OpenSea official sample) - **Multi-chain wallet inspect:** `kukapay/wallet-inspector-mcp` (EVM + Solana) **Chainlink** (first-party in its own repo): `smartcontractkit/chainlink-agent-skills` — two agentskills.io-spec skills (`chainlink-ccip-skill`, `chainlink-cre-skill`), installable via `npx skills add`. Production-grade, 86★, actively maintained. **Refuses mainnet write actions in v0.0.2** and enforces a two-step approval protocol. References an official `@chainlink/mcp-server` as the preferred MCP tool. **Payments:** `nativ3ai/hermes-payguard` is the only mature onchain-payment path. USDC via Circle developer-controlled / user-controlled, CCTP cross-chain, x402 micropayments. Approval is external to the model loop via `payguard approve <intent-id>`. ### Community onchain projects - **`hxsteric/mercury`** — multi-chain (ETH/Base/Solana) cash-flow analyzer, 6 fraud patterns (dust, rapid transfer, mixer, poisoning, dormant, fan-out), WebGL dashboard. Uses subagent delegation for parallel fetching. Skill-based. - **`amrrobb/serpens-hermes`** — Web3 security agent: 11 custom tools under a `web3` toolset (GoPlus + Etherscan + DeFiLlama + web3.py), 4 skills, SOUL.md persona, Telegram gateway. Best current reference implementation of an EVM Hermes agent. - **`gizdusum/hermes-blockchain-oracle`** — Solana intelligence as an MCP server by the same author as the first-party Solana skill. MCP-native version. - **`likidodefi/riskstate-agent-setups`** — reference architectures with external risk governance: `hermes + CoinGlass + RiskState + CoW Swap`, `hermes + CoinGlass + RiskState + Safe`. Pattern: framework decides → intelligence observes → policy permits → execution. ## Key Parameters ### For Solana workflows - Install the skill: `hermes skills install blockchain/solana` - Production RPC: `export SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=...` - Add an MCP server in `config.yaml`: ```yaml mcp_servers: solana-oracle: command: python args: ["-m", "hermes_blockchain_oracle"] env: SOLANA_RPC_URL: "${SOLANA_RPC_URL}" jupiter: command: npx args: ["-y", "@kukapay/jupiter-mcp"] ``` ### For Base / EVM workflows - Install the skill: `hermes skills install blockchain/base` - Production RPC: `export BASE_RPC_URL=https://base-mainnet.g.alchemy.com/v2/...` - For Ethereum mainnet (no first-party skill), use an MCP: ```yaml mcp_servers: alchemy: url: https://mcp.alchemy.com headers: Authorization: "Bearer ${ALCHEMY_API_KEY}" etherscan: command: npx args: ["-y", "mcp-etherscan-server"] env: ETHERSCAN_API_KEY: "${ETHERSCAN_API_KEY}" ``` ### For credentialed / signing workflows - Never put a private key where the model can read it. Use an MCP with env-var injection OR an external executor URL. - Use [[concepts/approval-system]] — set `auto_approval` conservatively for any tool that moves funds. - Consider `nativ3ai/hermes-payguard` for USDC: it gates execution behind a separate-from-model-loop CLI command (`payguard approve <id>`). - Consider the [[concepts/subagents-delegation]] pattern to isolate untrusted analysis (contract bytecode, scraped chat text) from the trusted execution path, CaMeL-style. ### Cron for monitoring Combine with [[concepts/cron-scheduling]]: - Hourly position check → DeFiLlama → Telegram alert if TVL/yield change > threshold - Nightly wallet audit → GoPlus + Etherscan → summary to messaging gateway - Per-block whale watch (via MCP subscription) if the MCP supports it ## When To Use **Use first-party skills when:** - You need basic Solana or Base wallet/token/tx lookups - You want zero infra — just Python stdlib + public RPC - You're doing read-only research, not execution **Use an MCP server when:** - The chain isn't Base or Solana (Ethereum mainnet, Arbitrum, Optimism, etc.) - You need typed tools and enable/disable as a unit - You need write / sign operations with credential handling - You want to aggregate multiple DeFi protocols (Aave + Uniswap + DeFiLlama) **Use a custom plugin (like hermes-payguard) when:** - Funds are moving and you need an external approval boundary - The existing skills/MCPs don't cover the protocol (CCTP, x402) - You need policy enforcement at the tool level, not just the prompt level **Don't try to run a production trading agent yet.** Every mature Hermes onchain project either (a) stays read-only, or (b) uses an external policy engine like RiskState, or (c) refuses writes on mainnet. No public Hermes-based autonomous trading bot has published a track record as of April 2026. ## Risks & Pitfalls ### Private-key management is the single biggest failure mode - **Never** paste a private key into chat or put it in a file the model can read via `execute_code`. - Prefer MCP servers that load keys from env vars at startup and never expose them to tools. - For anything high-value, use an external signer (Safe, Fireblocks, Privy) — the agent stages the transaction, a human or policy engine signs it. - Hermes-payguard's external-approval-stamp pattern is a reasonable baseline. ### Public RPC rate limits will bite you - Both first-party skills warn: public RPCs limit requests. At scale, use Helius/QuickNode/Alchemy with a paid key. - CoinGecko free tier is 10-30 req/min — wallets with many tokens will not get prices on all of them. - Use `--no-prices` on the first-party skill commands when you only need quantities. ### Whale detection is latest-block only - The first-party `whales` command only scans the latest block at query time. Not historical. Not streaming. Don't build a monitoring system on it expecting reliability — use Helius webhooks or a dedicated stream. ### NFT / token discovery is lossy on EVM - Base skill only checks ~15 hardcoded popular tokens. Unknown ERC-20s are invisible in `wallet` output — you have to know the contract address and use `token` explicitly. - cNFTs and Token-2022 NFTs aren't caught by the Solana NFT heuristic. ### Gas estimates are L2-only on Base - The Base `gas` command omits the L1 data posting fee, which can be a meaningful share of total cost. Treat its estimates as lower bounds. ### Mainnet writes are intentionally restricted - Chainlink's CCIP skill refuses all mainnet writes in v0.0.2 — this is by design, not a bug. Any production cross-chain flow needs a custom deployment path. - Hermes-payguard defaults to **mainnet** for Circle/x402 but still requires operator approval for anything above the micro-auto-approve threshold. ### The model can be tricked - Scraped content (token names, Twitter mentions, "helpful" messages) can inject instructions. Keep the untrusted context out of the signing path via subagent isolation or an external policy engine (RiskState pattern). - Tokens can have lookalike contract addresses — don't let the model paste an address from scraped text directly into a trade call. ### Trading bots do not have a track record - RiskState provides architectures, not performance data. Serpens does security, not trading. No published Hermes-based live-trading agent has posted verified returns. Treat any "autonomous trading" project as experimental regardless of its marketing. ### You're relying on centralized data providers - Helius, Alchemy, Etherscan, DeFiLlama, GoPlus, Flipside, CoinGecko — all can go down, change pricing, or deprecate endpoints. Check their status when an agent reports "zero balance" or "no tokens found." ## Related Concepts - [[concepts/skills-system]] — how first-party `blockchain/solana` and `blockchain/base` are structured and discovered - [[concepts/mcp-integration]] — how to add third-party MCP servers like Alchemy, Jupiter, Uniswap, etc. - [[concepts/approval-system]] — the tool-approval surface to constrain any write operation - [[concepts/cron-scheduling]] — scheduled wallet/position checks and alerts - [[concepts/subagents-delegation]] — isolating untrusted analysis from trusted execution - [[concepts/messaging-gateway]] — Telegram alerts are the most common onchain monitoring output ## Sources - `raw/onchain-ecosystem.md` — full inventory of skills, community projects, and MCP servers (2026-04-12) - `raw/awesome-hermes-agent-readme.md` — community list that names `hermes-blockchain-oracle`, `mercury`, `chainlink-agent-skills`, `hermes-payguard`, `ripley-xmr-gateway` - First-party SKILL.md files for `blockchain/solana` and `blockchain/base` in `NousResearch/hermes-agent` - READMEs for: `gizdusum/hermes-blockchain-oracle`, `hxsteric/mercury`, `smartcontractkit/chainlink-agent-skills`, `nativ3ai/hermes-payguard`, `amrrobb/serpens-hermes`, `likidodefi/riskstate-agent-setups` - GitHub Search API surveys of `*+mcp+in:description` (2026-04-12) <!-- ===== hermes/wiki/concepts/profiles-multi-instance.md ===== --> --- title: "Profiles & Multi-Instance" type: concept tags: [config, cli, foundational, well-established, intermediate] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/02-install-and-setup.md", "raw/release-v0.6.0.md"] confidence: high hermes_version: "v0.8.0" --- # Profiles & Multi-Instance ## Definition A **profile** is a fully isolated `HERMES_HOME` directory — its own `config.yaml`, `.env`, memories, sessions, skills, logs, cron jobs, and per-profile `$HOME` for subprocesses. Profiles let one user run multiple Hermes "personas" side by side: a personal assistant on one model, a coder on another, a research agent on a third, each with its own [[concepts/messaging-gateway]] instance, [[concepts/deployment-backends]] backend, allowlist, and memory store. Added in **v0.6.0**. ## How It Works Each profile lives at `~/.hermes/profiles/<name>/` and contains the full Hermes home tree: ``` ~/.hermes/profiles/<name>/ config.yaml # provider, model, terminal backend, agent settings .env # provider keys, allowlists memories/ # MEMORY.md + USER.md + memory provider state sessions/ # session SQLite + FTS5 search index skills/ # installed skills skins/ # CLI skin overrides logs/ # gateway + agent logs plans/ # plan-mode artefacts workspace/ # default cwd cron/ # jobs.json + per-job output home/ # per-profile $HOME used by subprocess (so npm, git, etc. don't bleed across profiles) ``` The special name `default` is an **alias for `~/.hermes/`** itself — your existing top-level Hermes installation IS the `default` profile. ### Naming validation Profile names must match the regex `^[a-z0-9][a-z0-9_-]{0,63}$` — lowercase letters, digits, underscore, hyphen, starting with an alphanumeric, max 64 chars. A short list of reserved names is forbidden (e.g. anything that would collide with internal directory names). ### Wrapper scripts `hermes profile create` writes a wrapper at `~/.local/bin/<name>` so you can launch the profile by typing its name directly: ```bash hermes profile create coder --clone coder chat # equivalent to: hermes -p coder chat ``` Pass `--no-alias` if a binary with that name already exists in `PATH` and would be shadowed. ### Ad-hoc switching Without committing to "use" a profile, prefix any command with `-p <name>` or `--profile=<name>`: ```bash hermes -p coder chat hermes --profile=research gateway run hermes -p assistant cron list ``` Or set the active profile permanently: ```bash hermes profile use coder ``` ## Key Parameters ### Commands | Command | Effect | |---|---| | `hermes profile list` | List all profiles, mark active | | `hermes profile create <name> [--clone \| --clone-all] [--clone-from SRC] [--no-alias]` | Bootstrap dirs and wrapper | | `hermes profile use <name>` | Set the active profile | | `hermes profile show [<name>]` | Print profile metadata | | `hermes profile delete <name>` | Remove the profile (and its wrapper) | | `hermes profile alias <name> <new-alias>` | Add additional wrapper script | | `hermes profile rename <old> <new>` | Rename profile + wrapper | | `hermes profile export <name> <archive.tar.gz>` | Tar.gz the profile dir | | `hermes profile import <archive.tar.gz>` | Restore from archive | ### Clone modes - **No clone** — bootstraps an empty profile. `hermes setup` runs from scratch. - **`--clone`** — copies `config.yaml`, `.env`, `SOUL.md`, `MEMORY.md`, and `USER.md` from the source profile (default `default`). Skills, sessions, logs, cron jobs are NOT copied. - **`--clone-all`** — copies the entire profile tree. - **`--clone-from SRC`** — clone from a specific profile other than `default`. ### Override env var `HERMES_HOME` overrides the profile lookup entirely — point it at any directory and Hermes will treat it as the active home (used internally by `-p` flag and the wrapper scripts). ## When To Use - **Separate personas for different work streams** — `coder` profile pinned to a strong code model, `assistant` profile pinned to a cheap chat model, `research` profile pinned to a long-context model. - **Per-client isolation** — freelancer keeping each client's data, allowlists, and skills in a sealed home. - **Trying a risky config without breaking the working one** — clone, edit, test; delete on failure. - **Running multiple gateways simultaneously** — each profile's gateway is independent, so `coder` can serve Slack while `assistant` serves Telegram from the same machine. - **OpenClaw-style workflow split** — match OpenClaw's named-account model so muscle memory carries over (see [[concepts/migration-from-openclaw]]). - **Backup snapshots** — `hermes profile export` produces a tar.gz of an entire working configuration for offsite storage. ## Risks & Pitfalls - **Profile name collisions with PATH binaries block wrapper creation** — use `--no-alias` and call via `hermes -p <name>`. - **`default` is special** — it points at `~/.hermes/` itself, NOT `~/.hermes/profiles/default/`. Don't try to delete or rename it. - **Clone vs Clone-All confusion** — `--clone` is config-only; sessions and skills must be copied separately or re-installed. `--clone-all` is large and includes log history. - **Two gateways pointed at the same `HERMES_HOME` corrupt SQLite** — that is exactly what profiles solve, so always use a different profile per concurrent gateway. - **Cron jobs are per-profile** — don't expect a job created in the `default` profile to fire while the `coder` gateway is the only one running. - **Reserved / invalid names** silently fail validation — names must match `^[a-z0-9][a-z0-9_-]{0,63}$`. - **Per-profile `$HOME`** means subprocess tools (`npm`, `git`, `gh`, `pip`) get clean caches per profile — useful for isolation, but first-run installs in a new profile may be slow and re-download artefacts. - **Export/import doesn't migrate platform credentials encoded in OS keychains** — rely on `.env` for portable secrets. ## Related Concepts - [[concepts/messaging-gateway]] — each profile runs its own gateway instance - [[concepts/deployment-backends]] — backend choice is per-profile in `config.yaml` - [[concepts/memory-system]] — memories live under each profile - [[concepts/skills-system]] — skills installed per profile - [[concepts/cron-scheduling]] — cron jobs are per-profile - [[concepts/migration-from-openclaw]] — profile model echoes OpenClaw's named-account workflow - [[entities/version-v0.6.0]] — release that introduced profiles ## Sources - `raw/02-install-and-setup.md` (Section 6, "Profile System") - `raw/release-v0.6.0.md` - Source files referenced: `hermes_cli/profiles.py`, `hermes_cli/main.py` <!-- ===== hermes/wiki/concepts/self-improvement-loop.md ===== --> --- title: "Self-Improvement Loop (GAPA)" type: concept tags: [skills, memory, ml-research, foundational, well-established, vs-openclaw, vs-claude-code, intermediate] created: 2026-04-12 updated: 2026-04-12 sources: - "raw/transcript-247-self-evolving.txt" - "raw/transcript-switching-to-hermes.txt" - "raw/transcript-did-hermes-kill-openclaw.txt" - "raw/transcript-hermes-full-course-2hr.txt" - "raw/03-skills-system.md" - "raw/release-v0.8.0.md" confidence: medium hermes_version: "v0.8.0" --- # Self-Improvement Loop (GAPA) ## Definition The self-improvement loop is Hermes' headline differentiator: a closed cycle in which the agent observes its own behavior, identifies what failed, packages what worked into reusable skills, and edits its own prompts and memory — all without human intervention. The mechanism is called **GAPA** ("works like back propagation but for prompts instead of model weights"), it triggers roughly every 15 tool calls, and it is what the Hermes 24/7 Self-Evolving video means by "it gets better the more you use it with no fine-tuning or prompt engineering needed." It is the mechanical instantiation of Nous Research's bet that "an AI agent learns from its interactions and becomes more valuable over time" — the architectural choice that "fundamentally different from ChatGPT or Claude or Open Claude. They reset every time. Hermes it is designed to be getting better." ## How It Works The loop is composed of five stages that fire continuously during normal use. They are not a separate "training mode" — they run in the background of every conversation. **1. Trajectory Capture.** Hermes records every API call, every tool decision, every output, in order. This trajectory is saved to disk and queryable. Most agents discard this state at session end; Hermes keeps it ("Hermes will record everything that it had just done... that full record it is what they call a trajectory. So most agent frameworks they just throw that away completely... Hermes keeps it instead"). See [[concepts/ml-research-pipeline]] for the trajectory subsystem. **2. GAPA Review (~every 15 tool calls).** The agent pauses, reads back the recent trajectory, and asks itself what worked and what failed. The 24/7 Self-Evolving transcript: "with every 15 or so tool calls, it pauses, reviews what happened, figures out what failed, and updates itself. This system is called GAPA. Works like back propagation but for prompts instead of model weights." The cadence is configurable as `skills.creation_nudge_interval` (default 15) in `config.yaml`. The output is a set of edits to the agent's own working prompts and memory — the "backprop for prompts" framing is literal: gradient-equivalent updates without touching model weights. **3. Autonomous Skill Creation.** When the trajectory analysis concludes the work is reusable, Hermes packages it as a `SKILL.md` document (see [[concepts/skills-system]]) — frontmatter, body, sometimes scripts — and writes it to `~/.hermes/skills/`. The transcript: "if it solves something, fixes an error, or you tell it to remember a task, it turns that into a reusable skill and uses it later when it needs to." Concrete examples from community videos: - A Hacker News morning briefing: *"Now, it is capturing everything it learned and turning it into a reusable procedure. So, you can see here, 'Hacker News daily AI briefing skill created.' Now, it's updating the cron job to reference this new skill."* Single complex prompt → autonomous skill + cron wired together. - A manim animation skill: *"it used a manim skill to turn a complex technical concept into an animated video. Meaning it can now explain things visually, not just through text."* - An X-posting workflow that "writes inside its skill MD file all the feedback that you give it, and then it improves it next time, right?" **4. Persistent Pattern-Based Memory.** Beyond skills, Hermes maintains a multi-layer memory: - **Cross-session FTS5 search** — every prior conversation is indexed, queryable, and summarizable on demand. "Six months from now you can ask something as simple as like haven't we solved something like this in the past and it should be able to find that. It'll know, it will actually be able to remember." - **Honcho user model** — "Hermes does not just remember what you said, it builds a model of who you are, your work style, your preferences, your domain knowledge, and that model deepens over time." - **Memory nudges** — "It can suggest like you probably want a skill that's going to do X instead of Y. So you can approve it, you can reject it." See [[concepts/memory-system]]. **5. Compounding Reuse + Refinement.** Next time you ask for something similar, Hermes runs the existing skill, refines it on new feedback, and ratchets capability upward. "These skills, they are very alive and inside of your code. They're able to learn from each execution... over time, like your Hermes, it becomes a completely different tool than somebody else's Hermes. Like it's shaped by your workflows, your preferences, your patterns." **The v0.8.0 self-diagnosis case study.** In April 2026, the Hermes team shipped a feature flagged in the v0.8.0 release notes as **"Self-Optimized GPT/Codex Tool-Use Guidance — The agent diagnosed and patched 5 failure modes in GPT and Codex tool calling through automated behavioral benchmarking."** This is the loop turned on itself: Hermes ran trajectories against GPT/Codex backends, GAPA-style review identified five distinct failure modes in how those models invoked tools, and the agent generated patches to its own provider-specific guidance — without a human in the loop. It is the most concrete public demonstration that GAPA works on the harness itself, not just on user-level skills. ## Key Parameters **`config.yaml`:** ```yaml skills: creation_nudge_interval: 15 # GAPA review cadence (tool calls) external_dirs: [] memory: memory_enabled: true user_profile_enabled: true # Honcho-style user modeling memory_char_limit: 2200 user_char_limit: 1375 nudge_interval: 10 # memory-suggestion cadence flush_min_turns: 6 provider: honcho # or hindsight, holographic, etc. agent: max_turns: 60 ``` **Slash commands:** - `/skills` — browse, install, inspect, create - `/memory` — view what Hermes thinks it knows about you - `/yolo` — accept dangerous commands without prompt (so the loop runs uninterrupted) **Files written by the loop:** - `~/.hermes/skills/custom/<slug>/SKILL.md` — autonomously created skills - `~/.hermes/sessions/sessions.json` + `state.db` — trajectory + FTS5 index - `~/.hermes/MEMORY.md` and `USER.md` — markdown-readable memory ## When To Use - **You will use the agent more than once.** If you need a one-shot answer, the loop is overhead. The value compounds — the entire pitch is "compounding for you because it's getting better. It's going to get more tailored towards you." - **You have repeatable workflows.** Daily briefings, content pipelines, code reviews, research digests — anything that recurs becomes a skill you didn't write. - **You want to differentiate from stateless agents.** Compared to ChatGPT, Claude, OpenClaw — all of which "reset every time" — Hermes is the only mainstream agent harness with this built in. The "Switching to Hermes" video frames it as the architectural-bet difference. - **You are researching agent self-improvement.** Trajectories + GAPA review logs are first-class data for study. - **You want an "AI second brain"** that learns who you are over months, not just within one session. ## Risks & Pitfalls - **Skills only fire on complex tasks.** The Switching transcript warns: "in practice, like it only creates skills for very complex tasks. So, if you give it something simple, it is not going to be learning." Trivial requests bypass the loop entirely. - **LLM-generated skills can be wrong.** "The skill that it creates, it is LLM generated. So, it's not actually going to be guaranteed to work properly for you. So, you get a skill, you run it, it fails." Always inspect new skills (`hermes skills inspect <name>`) before relying on them in cron. - **First 7 days are rough.** "Be prepared for the first 7 days, it won't be what you want. It won't do anything perfectly. But, the point is it gets better every time." Premature judgment kills adoption. - **Context bloat from memory.** Long sessions accumulate user model + memory snippets that can blow context windows on smaller local models. The Gemma transcript: "it's actually very important to constantly flush that context as you work on a new task." Tune `session_reset.mode: both` and `idle_minutes`. - **Stuck-loop bug.** Multiple transcripts mention agents getting into iteration loops that ignore user input. v0.8.0's inactivity-based timeout (instead of wall-clock) helps, but the issue still recurs ("the V.4.0 change log, it has multiple fixed stuck agent loop entries, but it's one of those things that just keeps coming back in different forms"). - **The loop runs locally — security implications.** GAPA edits your prompts and writes new skills to disk autonomously. If you run with `terminal: backend: local` and `/yolo`, the agent has full shell access while self-modifying. Use [[entities/backend-docker]] for production. - **Auto-created skills can conflict.** Two related tasks may produce overlapping skill names; the slug normalizer handles collisions but you can end up with `morning-briefing` and `morning-briefing-1` both half-working. Periodic skill audit (`hermes skills audit`) recommended. - **Confidence: medium for this page** — much of the GAPA narrative comes from community video transcripts (Nick, Julian, the 24/7 Self-Evolving channel) rather than the canonical repo docs. The 15-tool-call interval and "back propagation for prompts" framing are widely repeated but should be verified against the source code in `agent/` for academic citation. ## Related Concepts - [[concepts/skills-system]] — the substrate the loop writes into - [[concepts/memory-system]] — Honcho user modeling, FTS5 session search - [[concepts/ml-research-pipeline]] — trajectories that feed GAPA also feed offline RL training - [[concepts/migration-from-openclaw]] — the headline "stateless OpenClaw vs. learning Hermes" framing - [[entities/hermes-self-evolution]] - [[entities/version-v0.8.0]] — the GPT/Codex self-diagnosis release - [[syntheses/hermes-vs-openclaw]] — full architectural comparison ## Sources - `raw/transcript-247-self-evolving.txt` — the canonical GAPA / 15-tool-call / "back propagation for prompts" framing, manim skill example - `raw/transcript-switching-to-hermes.txt` — full mechanical walk-through of the trajectory → skill → reuse loop, "becomes a completely different tool than somebody else's Hermes" - `raw/transcript-did-hermes-kill-openclaw.txt` — Hacker News briefing skill auto-creation example, transparency of the loop - `raw/transcript-hermes-full-course-2hr.txt` — practical feedback loop, X-posting skill self-improvement, compounding effect across multiple skills - `raw/03-skills-system.md` — `skills.creation_nudge_interval`, autonomous skill writing, frontmatter schema - `raw/release-v0.8.0.md` — v0.8.0 GPT/Codex self-diagnosis as "the agent diagnosed and patched 5 failure modes in GPT and Codex tool calling through automated behavioral benchmarking" <!-- ===== hermes/wiki/concepts/skills-system.md ===== --> --- title: "Skills System" type: concept tags: [skills, foundational, well-established, developer, intermediate] created: 2026-04-12 updated: 2026-06-04 sources: ["raw/03-skills-system.md", "raw/02-install-and-setup.md", "raw/05-deployment-and-platforms.md", "raw/transcript-247-self-evolving.txt", "raw/transcript-hermes-full-course-2hr.txt", "raw/transcript-switching-to-hermes.txt", "https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29"] confidence: high hermes_version: "v0.15.1" --- # Skills System ## Definition Skills are Hermes Agent's **procedural memory** — markdown documents that the agent loads on demand to learn how to do specific tasks. Each skill is a self-contained folder built around a `SKILL.md` file with YAML frontmatter and a markdown body, optionally accompanied by reference docs, templates, scripts, and assets. Skills are exposed to the model through a three-tier progressive disclosure scheme so that a large skill catalog only consumes ~3K tokens of system prompt by default. The format is compatible with the cross-agent `agentskills.io` open standard, meaning the same `SKILL.md` works in Hermes, Claude Code, OpenAI's skills, Vercel `skills.sh`, ClawHub, and LobeHub. ## How It Works ### Anatomy of a skill Canonical layout under `skills/<category>/<skill-name>/`: ``` SKILL.md # REQUIRED — YAML frontmatter + markdown body references/ # Optional — deep docs loaded on demand templates/ # Optional — output skeletons scripts/ # Optional — Python/bash helpers (called via execute_code or terminal) assets/ # Optional — binary/supporting files ``` The filename is case-sensitive: the loader walks the tree looking for the exact string `SKILL.md`. Scripts in `scripts/` are never imported by the agent runtime — the agent invokes them through `execute_code` or the `terminal` tool, the same way a human would. ### Three-tier progressive disclosure 1. **Tier 1 — name + description** appear in the system prompt for every enabled, platform-compatible skill (~3K tokens total). 2. **Tier 2 — full SKILL.md** is loaded when the agent calls `skill_view(name)`. 3. **Tier 3 — deep references** are loaded by `skill_view(name, "references/x.md")` only when needed. The `metadata.hermes.fallback_for_toolsets` and `requires_toolsets` fields filter the Tier 1 list so conditional skills auto-appear or disappear based on which toolsets are present. ### Three invocation paths 1. **Automatic trigger detection.** The LLM autonomously calls `skill_view("arxiv")` when a user request matches the description in the system prompt. No user action required. 2. **Skill-aware slash commands.** Every installed skill auto-registers as `/<slug>`. Typing `/gif-search funny cats` loads the full `SKILL.md` plus any explicitly linked files and injects `[SYSTEM: The user has invoked the "<name>" skill...]`. Works in the CLI and across all gateway surfaces (Telegram bot-command names auto-translate `-` ↔ `_`). See [[concepts/messaging-gateway]]. 3. **Explicit conversation.** `/skills`, plus the `hermes skills ...` family for browse, search, install, inspect, audit, publish. A session can also be launched pinned to a specific set of skills via `build_preloaded_skills_prompt()`. ### Frontmatter schema | Field | Purpose | |---|---| | `name` | Required. ≤64 chars, hyphenated slug. | | `description` | Required. ≤1024 chars. Shown in Tier 1. | | `version` | Optional semver. | | `author`, `license` | Optional. | | `platforms` | `[macos | linux | windows]`. Filtered against `sys.platform`. | | `compatibility` | Freeform `agentskills.io` hint. | | `prerequisites.env_vars` / `.commands` | Legacy, normalized into `required_environment_variables`. | | `required_environment_variables` | List of `{name, prompt, help, required_for}`. Prompted locally; the gateway will not collect secrets in chat. | | `setup.help` / `setup.collect_secrets` | Richer setup spec. | | `metadata.hermes.tags` | Free-form tag list. | | `metadata.hermes.related_skills` | Cross-links to sibling skills. | | `metadata.hermes.fallback_for_toolsets` | Show the skill ONLY when the listed toolsets are unavailable. | | `metadata.hermes.requires_toolsets` | Show ONLY when the listed toolsets are present. | | `metadata.hermes.fallback_for_tools` / `requires_tools` | Per-tool versions of the above. | | `metadata.hermes.config` | List of `{key, description, default, prompt}`. Stored in `config.yaml` under `skills.config.<key>`. | Hermes-specific fields live entirely under `metadata.hermes.*` so other agents reading the same file ignore them cleanly. ### Built-in skill categories (exhaustive catalog) | Category | Skills | |---|---| | `apple/` | apple-notes, apple-reminders, findmy, imessage | | `autonomous-ai-agents/` | claude-code, codex, hermes-agent, opencode | | `creative/` | ascii-art, ascii-video, creative-ideation, excalidraw, manim-video, p5js, popular-web-designs, songwriting-and-ai-music | | `data-science/` | jupyter-live-kernel | | `devops/` | webhook-subscriptions | | `diagramming/` | (placeholder) | | `dogfood/` | dogfood (QA web-app testing) | | `email/` | himalaya | | `gaming/` | minecraft-modpack-server, pokemon-player | | `github/` | codebase-inspection, github-auth, github-code-review, github-issues, github-pr-workflow, github-repo-management | | `leisure/` | find-nearby | | `mcp/` | mcporter, native-mcp | | `media/` | gif-search, heartmula, songsee, youtube-content | | `mlops/` | cloud/modal; evaluation/; huggingface-hub/; models/; research/; vector-databases/; training/axolotl, grpo-rl-training, peft, pytorch-fsdp, trl-fine-tuning, unsloth; inference/gguf, guidance, llama-cpp, obliteratus, outlines, vllm | | `note-taking/` | obsidian | | `productivity/` | google-workspace, linear, nano-pdf, notion, ocr-and-documents, powerpoint | | `red-teaming/` | godmode | | `research/` | arxiv, blogwatcher, llm-wiki, polymarket, research-paper-writing | | `smart-home/` | openhue | | `social-media/` | xitter | | `software-development/` | plan, requesting-code-review, subagent-driven-development, systematic-debugging, test-driven-development, writing-plans | Additionally, `optional-skills/` (installable via `official/...`) covers: autonomous-ai-agents, blockchain, communication, creative, devops, email, health, mcp, migration, mlops, productivity, research, security. ### Cross-agent ecosystem (agentskills.io) The same `SKILL.md` file is consumable by Claude Code (the originator of the SKILL.md format), OpenAI skills (default tap `openai/skills`), Anthropic skills (`anthropics/skills`), Vercel `skills.sh`, ClawHub, LobeHub, and any well-known endpoint serving `/.well-known/skills/index.json`. The `skills.external_dirs` config option is designed for shared `~/.agents/skills/` directories so multiple agent harnesses can read the same library. **skills.sh catalog growth (v0.15.1):** the Vercel `skills.sh` hub fetch now walks the full sitemap instead of pulling a partial index. Discovered skill count jumped from **858 → 19,932** entries after the fix, so a fresh `hermes skills list --source hub` enumerates the full hub on first refresh. The `agentskills.io` compatibility framing above is unchanged — the fix is purely in how Hermes enumerates the same hub, not in the `SKILL.md` format itself. ## Key Parameters ### Installing skills ```bash hermes skills browse # unified catalog, official first hermes skills browse --source official hermes skills search kubernetes hermes skills inspect openai/skills/k8s # preview + scan hints hermes skills install openai/skills/k8s hermes skills install official/security/1password hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify hermes skills list --source hub hermes skills check # upstream drift detection hermes skills update [name] hermes skills audit # re-scan for security hermes skills uninstall k8s hermes skills publish skills/my-skill --to github --repo owner/repo hermes skills snapshot export setup.json hermes skills tap add myorg/skills-repo # custom GitHub source ``` **Install pipeline:** resolve short name → fetch → quarantine to `~/.hermes/skills/.hub/quarantine/` → `tools/skills_guard.scan_skill` (detects exfiltration, prompt injection, destructive commands, supply-chain risks) → policy check → install. The `--force` flag overrides `caution` and `warn` verdicts but NOT `dangerous` (unbypassable). **Trust levels:** `builtin` (bundled), `official` (optional-skills/), `trusted` (openai/anthropics taps), `community` (anything else). ### External skill directories Configured under `skills.external_dirs` in `config.yaml`: ```yaml skills: external_dirs: - ~/.agents/skills - /home/shared/team-skills - ${SKILLS_REPO}/skills ``` Supports `~` and `${VAR}` expansion. Non-existent paths are silently skipped. External dirs are read-only — writes always go to `~/.hermes/skills/`. Local entries take precedence on collision. ### Disabling skills `hermes skills` (no args) opens a curses checklist with global and per-platform toggles. State persists to `skills.disabled` and `skills.platform_disabled.<platform>` in `config.yaml`. A skill disabled on Telegram remains live in the CLI. ### Writing custom skills 1. `mkdir -p ~/.hermes/skills/<category>/<slug>` 2. Create `SKILL.md` with mandatory `name` + `description`. 3. Body sections: When to Use, Quick Reference / Procedure, Pitfalls, Verification. 4. Reference Hermes tools as bash/python: `web_extract(urls=[...])`, `browser_navigate(url=...)`, `terminal`, `execute_code`. 5. Optional `scripts/*.py` invoked via `execute_code` or `terminal`. 6. Optional `references/*.md`, `templates/*.md`, `assets/*`. 7. For secrets: declare `required_environment_variables` — Hermes prompts on first CLI load and writes them to `~/.hermes/.env`. 8. Test locally: drop the file at `~/.hermes/skills/custom/<slug>/SKILL.md`, launch `hermes`, try `/<slug>`. 9. Publish: `hermes skills publish skills/my-skill --to github --repo owner/repo`. ## When To Use - **You repeat a procedure.** Any time you find yourself instructing the agent through the same multi-step workflow more than twice, codify it as a skill so the next invocation is one slash command. - **You need a domain wrapper.** Skills are the right place for API quirks, authentication patterns, query syntaxes (e.g. arxiv, polymarket), or platform-specific CLIs (e.g. `imsg` on macOS). - **You want to share procedural knowledge across agents.** Because the format is `agentskills.io`-compatible, a single `SKILL.md` doubles as documentation for Claude Code, OpenAI skills, Vercel `skills.sh`, etc. - **You want the agent to self-improve.** Hermes' self-evolution loop ([[concepts/self-improvement-loop]]) writes successful task patterns directly into new skill files. The agent literally gets smarter through experience, and the human can read and edit the artifact. ## Risks & Pitfalls - **Tier 1 token cost scales with installed-skill count.** A bloated catalog can push system prompts past 3K tokens. Disable skills you do not use via the curses TUI. - **`SKILL.md` is case-sensitive.** Naming the file `skill.md` makes the loader silently skip it. - **Scripts are NOT auto-imported.** Anything in `scripts/` runs only when the agent itself shells out via `execute_code` or `terminal` — the runtime never imports the module directly. - **Security scanner verdicts.** `scan_skill` returns clean / caution / warn / dangerous. The `dangerous` verdict is unbypassable even with `--force`. - **Path traversal protection.** `quarantine_bundle` raises `ValueError` on invalid paths and appends `BLOCKED` to the audit log BEFORE any files land. Custom taps from untrusted sources are still risky — always run `hermes skills inspect` first. - **Slug normalization.** Spaces and underscores become hyphens; invalid characters are stripped; multi-hyphens are collapsed. Telegram bot commands auto-translate `-` ↔ `_`. If your slug is non-ASCII, expect surprises. - **Excluded dirs.** `.git`, `.github`, `.hub` are always skipped during discovery — do not nest skills inside those directories. - **Platform isolation.** `skill_matches_platform` filters via `sys.platform` — macOS-only skills (e.g. `imessage`) never appear on Linux. - **External `external_dirs` are read-only from Hermes' perspective** — edits propagate only when the upstream source is updated independently. - **Hub deduplication prefers higher trust.** A community skill with the same slug as an official one is shadowed; check `hermes skills list --source` to disambiguate. - **First skills.sh hub fetch is now larger / slower (v0.15.1).** Because the catalog walk expanded from 858 to 19,932 entries, a cold `hermes skills browse --source hub` or `hermes skills list --source hub` runs against the full sitemap on first run. Cache it (the disk cache used by `/model` is the same pattern) or browse with `--source official` for snappier iteration; subsequent runs are disk-cached. ## Related Concepts - [[concepts/memory-system]] — episodic and semantic memory; complements skills (procedural memory). - [[concepts/migration-from-openclaw]] — `hermes claw migrate` carries OpenClaw skills across with conflict resolution. - [[concepts/messaging-gateway]] — slash commands surface skills inside Telegram, Discord, Slack, etc. - [[concepts/subagents-delegation]] — `delegate_task` blocks `skill_manage` writes from children but allows skill consumption. - [[concepts/self-improvement-loop]] — autonomous skill creation after complex tasks. - [[entities/community-awesome-hermes]] — community-curated skill index. ## Sources - `raw/03-skills-system.md` — primary, exhaustive deep dive - `raw/02-install-and-setup.md` — `hermes skills` CLI surface, config sections - `raw/05-deployment-and-platforms.md` — slash-command auto-registration across gateway platforms - `raw/transcript-247-self-evolving.txt` — autonomous skill creation framing - `raw/transcript-hermes-full-course-2hr.txt` — third-layer "skill system" framing in masterclass - `raw/transcript-switching-to-hermes.txt` — skills as the durable artifact of agent learning <!-- ===== hermes/wiki/concepts/subagents-delegation.md ===== --> --- title: "Subagents & Delegation" type: concept tags: [subagents, tools, agent-loop, advanced, well-established] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/04-tools-mcp-cron-subagents.md", "raw/release-v0.8.0.md"] confidence: high hermes_version: "v0.8.0" --- # Subagents & Delegation ## Definition Delegation in Hermes is the ability for a running agent to spawn child agents that each get their own fresh context window, tool surface, and iteration budget — then return only a summary to the parent. It is implemented by `tools/delegate_tool.py` (1103 lines) and exposed as the `delegate_task` tool. Delegation is how Hermes keeps long, multi-branch workloads from poisoning a single session's context, and how it fans work out across providers or models. ## How It Works The `delegate_task` tool takes the form: ``` delegate_task(goal=..., context=..., toolsets=..., tasks=[...], max_iterations=...) ``` Two modes: **single** (pass a `goal` string) or **batch** (pass a `tasks` list of dicts, each with its own goal/context). Each child is a fresh `AIAgent` instance with: - An ephemeral system prompt built from `task + context + workspace hint` - `parent_session_id` set — which keeps the child **hidden** from `hermes sessions list` - Toolsets intersected with the parent's (child can never expand beyond what parent had) - A fixed **blocked-tools set**: `{delegate_task, clarify, memory, send_message, execute_code}` — blocks recursion, user-interaction side effects, shared-memory writes, and code sandbox escape - `MAX_DEPTH = 2` — a grandchild attempt is rejected outright - `max_concurrent_children = 3` by default (configurable) - `DEFAULT_MAX_ITERATIONS = 50` per subagent — every child starts with a full fresh budget - Optional provider/model override via `delegation.provider` / `delegation.model` / `delegation.reasoning_effort` in config.yaml — use this to run children on cheaper models while the parent keeps a stronger model for orchestration Only the final summary plus a tool_trace comes back to the parent. Intermediate tool outputs, partial reasoning, and retries never enter the parent's context window — that's the whole point. **Parent / child relationships:** - `child._delegate_depth = parent._delegate_depth + 1` - `parent._active_children` is a lock-protected list used for interrupt propagation — Ctrl+C in the parent cancels every running child - A **heartbeat thread** pings `parent._touch_activity()` every 30s so the parent's gateway inactivity timeout does not fire while the child is grinding - Progress callbacks surface to the parent's display: the CLI renders a tree (`├─ <emoji> <tool> "<preview>"`); the gateway batches updates every 5 tools as `🔀 [idx] <tools>` **Credential pool sharing.** Child agents share the parent profile's credential pool — no duplicate auth, but also no isolated rate-limit budget. If the parent model routes through OpenRouter, so do the children; 401 / 429 / 402 rotation happens per-key across the whole tree. **`/batch_runner.py` (1287 lines) — separate path for dataset processing.** This is not the same thing as `delegate_task`; it is a standalone script for parallel offline workloads: ```bash python batch_runner.py --dataset_file=data.jsonl --batch_size=10 --run_name=my_run [--resume] [--distribution=image_gen] ``` Uses a multiprocessing `Pool`, is checkpoint-resumable, saves trajectories as from/value pairs for RL or fine-tuning, and normalizes per-tool success/failure stats via `_normalize_tool_stats()` so results drop cleanly into Arrow / Parquet / HuggingFace Datasets. Toolset mixes live in `/toolset_distributions.py`. Use this for benchmarking and trajectory generation, not for interactive work. **Background terminal tasks + `notify_on_complete` (v0.8.0).** A different kind of delegation — hand a long shell command to the OS, keep working, get pinged on exit. Implemented in `tools/terminal_tool.py` and `tools/process_registry.py` (~1172 lines): ``` terminal(command="...", background=True, notify_on_complete=True, watch_patterns=["PANIC", "OOM"]) ``` Returns immediately with a `proc_<id>` handle. Companion tool: ``` process(action="list" | "poll" | "log" | "wait" | "kill" | "write") ``` With `notify_on_complete=True` (added in v0.8.0), the gateway watcher detects process exit, queues a new agent turn via `ProcessRegistry.completion_queue`, and delivers it as an internal `MessageEvent`. The state is checkpoint-persisted, so a gateway restart does not lose pending notifications. Verbosity is `all | result | error | off`. `watch_patterns` trigger mid-run notifications when stdout matches any regex. The `execute_code` sandbox blocks `{background, pty, notify_on_complete, watch_patterns}` from user scripts — only the agent proper can use them. **`/bg` (`/background`) slash command.** In `hermes_cli/commands.py:81`. Forks a prompt into an independent session; the spinner keeps showing background activity while the chat REPL returns control to the user. Companions: `/queue` (`/q`) to enqueue work, `/btw` for an ephemeral side question that does not enter the main conversation context. ## Key Parameters | Parameter | Purpose | |---|---| | `goal` / `tasks` | Single-mode goal string, or list of per-child task dicts | | `context` | Shared preamble injected into each child's system prompt | | `toolsets` | Subset of parent toolsets to expose to the child | | `max_iterations` | Override `DEFAULT_MAX_ITERATIONS` (50) | | `delegation.provider/model/reasoning_effort` | config.yaml overrides for all children | | `max_concurrent_children` | Parallelism cap (default 3) | | `MAX_DEPTH` | Hard-coded 2 | | `notify_on_complete` | Auto-notify on background terminal exit (v0.8.0) | | `watch_patterns` | Regex list for mid-run stdout alerts | ## When To Use - **Subagents (`delegate_task`)** — parallel independent research, isolated context for long traces, cheap-model grunt work while the parent keeps a stronger model, enforced tool restrictions, budgets that must not eat the parent's 50 iterations. - **Single-agent loops (no delegation)** — sequential steps that depend on each other, work that needs parent `memory` / `clarify` / `send_message`, tasks under the 50-iteration cap, simpler debugging. - **`/bg`** — user wants to free the chat while a long task runs. - **`notify_on_complete`** — long-running shell command (build, training, deploy) where the agent should keep working and get pinged when it exits. - **Batch runner** — offline dataset processing, trajectory generation, benchmarking. Not interactive. ## Risks & Pitfalls - **Depth cap is silent beyond 2** — a child's `delegate_task` call is rejected; design your work to fit two levels. - **Blocked tools catch users by surprise** — a subagent cannot call `memory`, `send_message`, `clarify`, or `execute_code`. If your batch task needs these, do them in the parent. - **Credential pool is shared, not isolated** — a runaway batch can exhaust rate limits for the whole profile. - **Subagent results are summarized, not complete** — you get the child's final message plus a tool trace, nothing more. Log verbosely in the child if you need the raw intermediate steps. - **Interrupt propagation is lock-protected** but assumes children check cancellation between tool calls; a truly stuck child may need a process-level kill. - **`notify_on_complete` turns into an agent turn** — the agent is re-invoked asynchronously. If your conversation has moved on, the notification still arrives; verbosity `result` or `error` filters noise. ## Related Concepts - [[concepts/cron-scheduling]] — cron jobs can invoke `delegate_task` for fan-out work - [[concepts/skills-system]] — skills often include a `delegation-ready` goal template - [[concepts/model-switching]] — use `delegation.provider` / `model` to route children to cheaper models - [[concepts/approval-system]] — child tool calls still flow through the approval layer - [[concepts/ml-research-pipeline]] — `batch_runner.py` feeds RL/finetuning pipelines - [[entities/version-v0.8.0]] — `notify_on_complete` added here ## Sources - `raw/04-tools-mcp-cron-subagents.md` section D (D1–D5) - `raw/release-v0.8.0.md` — `notify_on_complete`, inactivity timeouts <!-- ===== hermes/wiki/entities/autonovel.md ===== --> --- title: "autonovel" type: entity tags: [agent-loop, ml-research, advanced, experimental, emerging] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/awesome-hermes-agent-readme.md", "raw/community-resources.md", "raw/01-community-resources.md"] confidence: medium hermes_version: "v0.8.0" --- ## Overview **autonovel** (`github.com/NousResearch/autonovel`, **467 stars** per get-hermes.ai, 2026-04-12) is an official [[entities/nous-research]] project: an **autonomous novel-writing pipeline built on Hermes** that "generates long-form manuscripts (100k+ words) end-to-end using the agent loop" (per `awesome-hermes-agent`). Beyond being a creative-writing tool, it functions as a public stress test of the Hermes agent loop: sustaining a single coherent deliverable across a 100k+ word horizon exercises long-running session management, memory, and planning far past what typical chat tasks demand. ## Characteristics - **Repo:** <https://github.com/NousResearch/autonovel> - **Maintainer:** Nous Research (official project — the smallest of the four official ecosystem repos by stars) - **Stars:** 467 (get-hermes.ai community page, 2026-04-12) - **Output:** complete long-form manuscripts, 100k+ words, generated end-to-end without per-chapter human prompting - **Built on:** the Hermes agent loop itself, not a separate generation framework This page is deliberately short: the only ingested sources are directory listings (the awesome list and the get-hermes.ai community page). No transcript or doc walks through autonovel's architecture, configuration, or output quality. ## How to Use No setup instructions exist in the ingested sources. Starting point: clone <https://github.com/NousResearch/autonovel> and follow its README on top of a working Hermes install. Anything more specific would be invented — flag for ingestion of the repo README. ## Related Entities - [[entities/nous-research]] — maintainer; sibling official projects: [[entities/hermes-self-evolution]], [[entities/hermes-paperclip-adapter]] - [[concepts/self-improvement-loop]] — the agent loop autonovel pushes to long horizons - [[entities/community-awesome-hermes]] — lists autonovel under Official Resources <!-- ===== hermes/wiki/entities/backend-daytona.md ===== --> --- title: "Daytona Managed Workspace Backend" type: entity tags: [backend, daytona, serverless, cloud, intermediate] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/05-deployment-and-platforms.md", "raw/docs-user-guide-configuration.md", "raw/docs-reference-environment-variables.md", "raw/release-v0.9.0.md"] confidence: high hermes_version: "v0.15.0" --- ## Overview The **Daytona backend** runs Hermes shell commands in a [Daytona](https://daytona.io) managed serverless workspace — a cloud dev container that hibernates when idle and resumes on the next session. It sits between [[entities/backend-modal]] and a dev-machine-in-the-cloud: like Modal it's metered and hibernation-friendly, but persistence is workspace-shaped — sandboxes are **stopped, not deleted**, on cleanup, so the same workspace (filesystem and all) comes back next session. Bulk upload, a config bridge, and the silent disk cap landed in [[entities/version-v0.9.0]]. ## Characteristics - **Setup:** `DAYTONA_API_KEY` environment variable (from daytona.io); the Daytona SDK handles server URL configuration - **Cost:** metered; hibernates when idle; requires a Daytona subscription - **Persistence:** with `container_persistent: true`, workspaces are stopped (not deleted) on cleanup and resumed next session. Persistence is filesystem-oriented — live processes/PID space are not promised to survive sandbox recreation. - **Sandbox naming:** workspaces follow the pattern `hermes-{task_id}` - **Disk cap:** **10 GiB maximum**, enforced by Daytona — requests above it are silently capped with a warning (v0.9.0) - **Resource units:** `container_memory` / `container_disk` are set in MB and converted to GiB - **Image:** `daytona_image` in config (default `nikolaik/python-nodejs:python3.11-nodejs20`), or `TERMINAL_DAYTONA_IMAGE` env var - **Skills + credentials:** auto-mounted, like all backends ### Limitations - 10 GiB disk ceiling — anything bigger needs [[entities/backend-modal]] (50 GiB default) or [[entities/backend-ssh]] - Requires an active subscription and network connectivity (no offline use) - Cloud-sandbox caveat: `container_persistent` preserves the filesystem, not background jobs ## How to Use Get an API key from daytona.io and set it: ```bash DAYTONA_API_KEY=your-key # in ~/.hermes/.env ``` Configure backend in `~/.hermes/config.yaml`: ```yaml terminal: backend: daytona container_cpu: 1 # CPU cores container_memory: 5120 # MB → converted to GiB container_disk: 10240 # MB → converted to GiB (max 10 GiB) container_persistent: true # Stop/resume instead of delete ``` Verify: ```bash hermes doctor ``` ### When to pick Daytona - Managed cloud dev environments and team collaboration - You want Modal-style hibernation economics but a persistent, workspace-shaped environment - You don't want to provision or patch a VPS ### When NOT to pick Daytona - Disk-heavy workloads (>10 GiB) — use Modal or SSH - Air-gapped / offline setups — use [[entities/backend-local]] or [[entities/backend-singularity]] ## Related Entities - [[entities/backend-modal]] — closest sibling: serverless, snapshot-based persistence, bigger disk - [[entities/backend-docker]] — free local-isolation alternative - [[entities/backend-ssh]] — always-on alternative without metering - [[entities/version-v0.9.0]] — bulk upload, config bridge, silent disk cap - [[concepts/deployment-backends]] - [[syntheses/deployment-backends-compared]] <!-- ===== hermes/wiki/entities/backend-docker.md ===== --> --- title: "Docker Container Backend" type: entity tags: [backend, docker, container, intermediate, isolation] created: 2026-04-12 updated: 2026-06-04 sources: ["raw/05-deployment-and-platforms.md", "raw/release-v0.6.0.md", "raw/release-v0.8.0.md", "https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29"] confidence: high hermes_version: "v0.15.1" --- ## Overview The **Docker terminal backend** runs every Hermes shell command and skill script inside a disposable container instead of on the host. It gives you process- and filesystem-level isolation without the overhead of a full VM, and is the recommended default for anyone running Hermes against an untrusted workload, on shared hardware, or with `/yolo`-style fast-iteration workflows. The official Docker container itself was added in [[entities/version-v0.6.0]]; `execute_code` support on remote Docker backends landed in [[entities/version-v0.8.0]]. ## Characteristics - **Setup:** Docker Desktop (Mac/Windows) or Docker Engine (Linux). Auto-detected by `hermes doctor`. - **Cost:** free (local Docker) - **Default image:** `nikolaik/python-nodejs:python3.11-nodejs20` (covers Python + Node toolchains) - **Lifecycle:** containers are ephemeral — roughly **2 hours per session** before recycling - **Hardening built in:** `--cap-drop ALL`, `--no-new-privileges`, PID limit 256, capped tmpfs - **Volume mounts:** workspace and read-only data dirs supported - **Browser tools:** require `--shm-size=1g` for Chromium-based skills - **Skills + credentials:** auto-mounted (added in v0.6.0) - **Remote `execute_code`:** supported (added in v0.8.0) ### Critical limitation **Never run two containers against the same `~/.hermes`.** Concurrent writes to the session store, profile config, or memory will corrupt state. Use [[concepts/profiles-multi-instance]] and a separate `HERMES_HOME` for each container. **Dashboard insecure mode is now an explicit env opt-in (v0.15.1):** if you intentionally expose the Hermes dashboard over Docker in insecure mode, set `HERMES_DASHBOARD_INSECURE=1` in the container environment. Binding to `0.0.0.0` no longer implies insecure access — the dashboard refuses / limits unauthenticated traffic by default. See [[concepts/deployment-backends]] for the cross-backend safety framing. ## How to Use Configure backend in `~/.hermes/config.yaml`: ```yaml terminal: backend: docker docker_image: "nikolaik/python-nodejs:python3.11-nodejs20" docker_forward_env: ["GITHUB_TOKEN"] docker_volumes: - "/home/user/projects:/workspace/projects" - "/home/user/data:/data:ro" container_memory: 5120 ``` **Dashboard insecure mode (v0.15.1):** if you intentionally expose the Hermes dashboard in insecure mode from inside the container, set `HERMES_DASHBOARD_INSECURE=1` in the container env. Do not rely on host binding to infer it. Run Hermes itself inside Docker as a long-lived gateway: ```bash docker run -d --name hermes --restart unless-stopped \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent gateway run ``` Verify isolation: ```bash hermes doctor ``` ## Related Entities - [[entities/backend-local]] — host-native alternative - [[entities/backend-modal]] — serverless container alternative - [[entities/version-v0.6.0]] — official Docker container shipped here - [[entities/version-v0.8.0]] — remote `execute_code` added here - [[concepts/deployment-backends]] - [[syntheses/deployment-backends-compared]] <!-- ===== hermes/wiki/entities/backend-local.md ===== --> --- title: "Local Terminal Backend" type: entity tags: [backend, local, foundational, beginner] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/05-deployment-and-platforms.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview The **local terminal backend** runs Hermes Agent commands directly on the host machine. It is the **default backend** — used unless you explicitly configure another. The agent has full access to your filesystem and shell at the privilege of the user running Hermes. It is the right choice for development, personal use, and any trusted single-user machine, and the wrong choice for any environment where the agent might run untrusted code or operate unattended without sandboxing. ## Characteristics - **Setup:** none — works out of the box on a fresh `pip install hermes-agent` - **Cost:** free - **Persistence:** anything written to the filesystem persists; no separate snapshot mechanism - **Isolation:** **none** — the agent inherits the user's full filesystem and process privileges - **Speed:** fastest backend — no container or network round-trip - **Mitigation:** use `hermes tools` to selectively disable destructive tools, or run Hermes inside a separate user account / VM if you want sandboxing without switching backends ## How to Use It is the default. To make it explicit in `~/.hermes/config.yaml`: ```yaml terminal: backend: local ``` Verify: ```bash hermes doctor ``` Recommended hardening for solo developer setups: 1. Run Hermes as a non-admin user. 2. Use `hermes tools` to disable destructive tools you don't need. 3. Use `/yolo` only inside scratch directories you can throw away. 4. Pair with [[concepts/approval-system]] — keep dangerous-command approvals on for unfamiliar workflows. ## Related Entities - [[entities/backend-docker]] — first step up if you want isolation - [[entities/backend-modal]] — serverless alternative for cloud workflows - [[concepts/deployment-backends]] - [[syntheses/deployment-backends-compared]] <!-- ===== hermes/wiki/entities/backend-modal.md ===== --> --- title: "Modal Serverless Backend" type: entity tags: [backend, modal, serverless, cloud, intermediate] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/05-deployment-and-platforms.md", "raw/release-v0.6.0.md", "raw/release-v0.8.0.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview The **Modal backend** runs Hermes shell commands and skills on Modal's serverless container platform — ephemeral compute that hibernates when idle and resumes near-instantly when called. It is Hermes's go-to choice for cloud-native workflows where you want zero infrastructure overhead, only pay for actual usage, and don't want to manage a VPS. Modal-mounted skills/credentials arrived in [[entities/version-v0.6.0]]; remote `execute_code` arrived in [[entities/version-v0.8.0]]. ## Characteristics - **Setup:** `MODAL_TOKEN_ID` + `MODAL_TOKEN_SECRET` env vars, or `~/.modal.toml` - **Cost:** approximately **$5/month baseline for hibernation**, plus metered CPU/memory/duration. The maintainers describe idle cost as "nearly nothing." - **Persistence:** filesystem snapshots restored across sessions, tracked in `~/.hermes/modal_snapshots.json`. **Live processes and background jobs are NOT preserved** between sessions. - **Credentials:** `~/.hermes/` files auto-mounted and re-synced before each command - **Cold start:** noticeable on first invocation; subsequent calls are fast - **Stateless by default** — except for the snapshot system - **Runaway killer:** `scripts/kill_modal.sh` for orphaned containers ## How to Use Install Modal CLI and authenticate: ```bash pip install modal modal token new ``` Configure backend in `~/.hermes/config.yaml`: ```yaml terminal: backend: modal container_cpu: 1 container_memory: 5120 container_disk: 51200 container_persistent: true ``` Verify: ```bash hermes doctor ``` Kill runaway containers if a job hangs: ```bash bash scripts/kill_modal.sh ``` ### When to pick Modal - Cloud evaluations and benchmarks where you spin up many short-lived runs - Background cron jobs that should not pin a local machine - Scenarios where you want compute close to a model API but not a long-running VPS ### When NOT to pick Modal - Workloads needing live background processes (use [[entities/backend-docker]] or SSH instead) - Latency-sensitive interactive sessions where cold starts annoy - Air-gapped or fully offline setups ## Related Entities - [[entities/backend-local]], [[entities/backend-docker]] — alternatives - [[entities/version-v0.6.0]] — skills + credentials on remote backends - [[entities/version-v0.8.0]] — `execute_code` on remote Modal - [[concepts/deployment-backends]] - [[syntheses/deployment-backends-compared]] <!-- ===== hermes/wiki/entities/backend-singularity.md ===== --> --- title: "Singularity / Apptainer HPC Backend" type: entity tags: [backend, singularity, container, advanced, ml-research] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/05-deployment-and-platforms.md", "raw/docs-user-guide-configuration.md", "raw/docs-reference-environment-variables.md", "raw/docs-developer-guide-environments.md"] confidence: high hermes_version: "v0.15.0" --- ## Overview The **Singularity / Apptainer backend** runs Hermes shell commands inside a Singularity (now Apptainer) container — the container runtime of choice on HPC clusters and shared research machines where Docker is forbidden because it requires a root daemon. If you are doing ML research on a university or lab cluster, this is often the *only* sandboxed option. It is also the standard sandbox for the RL/benchmark environment framework, which accepts `terminal_backend: "singularity"` alongside the other five backends. ## Characteristics - **Setup:** an `apptainer` or `singularity` binary in `$PATH` — usually pre-installed on clusters - **Cost:** free (uses your cluster allocation) - **Image handling:** Docker URLs (`docker://...`) are **automatically converted to SIF files and cached locally**; existing `.sif` files are used directly. First pull is slower than Docker because of the conversion. - **Isolation:** `--containall --no-home` — full namespace isolation without mounting the host home directory - **Scratch directory resolution order:** `TERMINAL_SCRATCH_DIR` → `TERMINAL_SANDBOX_DIR/singularity` → `/scratch/$USER/hermes-agent` (HPC convention) → `~/.hermes/sandboxes/singularity` - **Persistence:** `container_persistent: true` keeps a **writable overlay** across sessions - **Resource caps:** `container_cpu` / `container_memory` (defaults 1 core / 5120 MB, also settable via `TERMINAL_CONTAINER_CPU` / `TERMINAL_CONTAINER_MEMORY`) - **Env vars:** `TERMINAL_SINGULARITY_IMAGE` overrides the image; `TERMINAL_ENV=singularity` selects the backend at process level - **Skills + credentials:** auto-mounted (whitelisted), like all backends ### Limitations - **Slower image pulls than Docker** — the `docker://` → `.sif` conversion happens on first use - Browser tools support is limited compared to Docker - Only worth the friction if you're already on a cluster with Singularity installed ## How to Use Configure backend in `~/.hermes/config.yaml`: ```yaml terminal: backend: singularity singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20" container_cpu: 1 # CPU cores container_memory: 5120 # MB container_persistent: true # Writable overlay persists across sessions ``` Point the scratch space at your cluster's fast storage if the defaults don't fit: ```bash TERMINAL_SCRATCH_DIR=/scratch/$USER/hermes-agent ``` Verify: ```bash hermes doctor ``` ## Related Entities - [[entities/backend-docker]] — same container idea, requires a root daemon (banned on most HPC) - [[entities/backend-local]], [[entities/backend-ssh]] — non-container alternatives on cluster login/compute nodes - [[concepts/deployment-backends]] - [[syntheses/deployment-backends-compared]] <!-- ===== hermes/wiki/entities/backend-ssh.md ===== --> --- title: "SSH / VPS Backend" type: entity tags: [backend, ssh, cloud, intermediate, gateway] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/05-deployment-and-platforms.md", "raw/docs-user-guide-configuration.md", "raw/docs-reference-environment-variables.md", "raw/release-v0.8.0.md", "raw/release-v0.9.0.md", "raw/release-v0.12.0.md"] confidence: high hermes_version: "v0.15.0" --- ## Overview The **SSH backend** runs every Hermes shell command on a remote server over SSH — a $5 VPS, a remote GPU box, or any machine you can reach with a key. It is the cheapest way to keep an agent running 24/7 without your laptop on, and the natural home for a [[concepts/messaging-gateway]] deployment. Isolation is a *network boundary*, not a container: commands run with the remote user's full privileges on the remote host. Remote `execute_code` landed in [[entities/version-v0.8.0]]; bulk file sync via tar pipe (shared with Modal) landed in [[entities/version-v0.9.0]]. ## Characteristics - **Setup:** env vars `TERMINAL_SSH_HOST` + `TERMINAL_SSH_USER` (both required — Hermes logs a clear error if either is missing); optional `TERMINAL_SSH_PORT` (default 22), `TERMINAL_SSH_KEY` (path to private key), `TERMINAL_SSH_PERSISTENT` (default `true`) - **Cost:** hosting fees only — as low as **$5/month** for a VPS - **Connection:** OpenSSH **ControlMaster** with a 5-minute idle keepalive; connects at init time with `BatchMode=yes` and `StrictHostKeyChecking=accept-new` - **Persistent shell:** enabled by default — a single long-lived `bash -l` process on the remote host preserves cwd and env vars across commands, communicating via temporary files - **Persistence:** the remote host's filesystem — everything written stays - **File transfer:** bulk file sync via tar pipe (added in v0.9.0); a v0.12.0 fix prevents tar from overwriting remote home-directory permissions - **Isolation:** strong from *your* machine, none on the remote host itself ### Limitations - Commands needing `stdin_data` or `sudo` automatically **fall back to one-shot mode** (no persistent shell for that command) - Shell state (cwd, env) is **lost when the remote shell restarts** - Requires network connectivity — no offline use ## How to Use Configure backend in `~/.hermes/config.yaml`: ```yaml terminal: backend: ssh persistent_shell: true # Keep a long-lived bash session (default: true) ``` Set connection details in `~/.hermes/.env` (or your shell): ```bash TERMINAL_SSH_HOST=my-server.example.com TERMINAL_SSH_USER=ubuntu # Optional: TERMINAL_SSH_PORT=22 TERMINAL_SSH_KEY=~/.ssh/id_ed25519 TERMINAL_SSH_PERSISTENT=true ``` Or switch from the CLI: ```bash hermes config set terminal.backend ssh ``` Verify: ```bash hermes doctor ``` ### When to pick SSH - 24/7 gateway + cron deployments on a cheap always-on VPS - Remote GPU boxes and distributed compute - Near-native latency: ControlMaster + persistent shell is often competitive with local ## Related Entities - [[entities/backend-local]], [[entities/backend-docker]] — host-side alternatives - [[entities/backend-modal]], [[entities/backend-daytona]] — serverless alternatives when you don't want to manage a server - [[entities/version-v0.8.0]] — remote `execute_code` - [[entities/version-v0.9.0]] — bulk file sync via tar pipe - [[concepts/deployment-backends]] - [[concepts/messaging-gateway]] — the classic SSH-backend workload - [[syntheses/deployment-backends-compared]] <!-- ===== hermes/wiki/entities/community-agency-agents-zh.md ===== --> --- title: "agency-agents-zh" type: entity tags: [community, personas, agents, chinese, cross-agent, intermediate] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/community-resources.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview **agency-agents-zh** is the largest community persona library in the Hermes ecosystem at **5.8k stars**, maintained by **jnMetaCode**. It packages **193 plug-and-play AI expert roles** organized across **18 departments**, with **46 of them specialized for the China market**. The personas are cross-agent — they work with Hermes, Claude Code, OpenClaw, and other agents that consume the agentskills.io standard or accept system-prompt-style role definitions. ## Characteristics - **Repo:** <https://github.com/jnMetaCode/agency-agents-zh> - **Stars:** 5,800+ - **Personas:** 193 expert roles - **Departments:** 18 - **China-market specialized roles:** 46 - **Cross-agent:** works with Hermes Agent, Claude Code, OpenClaw, and other compatible harnesses - **Language:** Chinese, with role definitions usable in any language model ### What it gives you A ready-made "agency" of expert personas — product manager, marketer, legal reviewer, operations specialist, etc. — that you can drop into Hermes profiles, slash commands, or skill metadata to specialize an agent's behavior without writing prompts from scratch. ## How to Use 1. Clone or browse <https://github.com/jnMetaCode/agency-agents-zh>. 2. Pick the persona files relevant to your workflow. 3. Drop them into: - `~/.hermes/skills/personas/<role-slug>/SKILL.md` to expose each as a [[concepts/skills-system]] slash command, OR - your project's `MEMORY.md` to bias a single profile, OR - a [[concepts/profiles-multi-instance]] dedicated to that role 4. Verify with `hermes skills list`. Pairs well with `agency-agents-zh` + [[entities/community-orange-book]] for a fully Mandarin-language Hermes onboarding kit. ## Related Entities - [[entities/community-orange-book]] — sister Chinese-language guide (1.9k stars) - [[entities/community-gbrain]] — opinionated single-brain config (different model: one persona deeply, vs. 193 personas thinly) - [[entities/community-awesome-hermes]] - [[concepts/skills-system]], [[concepts/profiles-multi-instance]] <!-- ===== hermes/wiki/entities/community-awesome-hermes.md ===== --> --- title: "awesome-hermes-agent" type: entity tags: [community, awesome-list, directory, ecosystem, foundational] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/awesome-hermes-agent-readme.md", "raw/community-resources.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview **awesome-hermes-agent** is the canonical curated directory of the Hermes ecosystem — skills, plugins, tools, integrations, multi-agent frameworks, domain applications, forks, and guides. **1.1k stars**, maintained by **0xNyk** (also the author of the `openclaw-to-hermes` migration tool and the `lacp` control-plane harness). Every entry is tagged **production / beta / experimental** so readers know what they're getting into. ## Characteristics - **Repo:** <https://github.com/0xNyk/awesome-hermes-agent> - **Stars:** 1,100+ - **Last reviewed (per README):** 2026-04-03 - **Categorization:** Official Resources, Skills & Plugins (Community Skills / agentskills.io / Plugins / Registries), Tools & Utilities (incl. Deployment), Integrations & Bridges, Multi-Agent & Swarms, Domain Applications, Forks & Derivatives, Guides & Documentation, Operational Playbooks - **Maturity tagging:** - **production** — stable, documented, actively maintained - **beta** — works but evolving - **experimental** — proof of concept, learn from it but don't depend on it - **License:** CC BY 4.0 - **Submission flow:** open an issue at the repo ### "Where do I start?" path (from the README) 1. **Get running** — Official docs quickstart at <https://hermes-agent.nousresearch.com/docs/> 2. **Add first skills** — `wondelai/skills` (380+ stars) or `litprog-skill` (75+ stars) 3. **Get a GUI** — [[entities/community-webui]] or [[entities/community-mission-control]] (3.7k+ stars) ## How to Use Browse on GitHub: <https://github.com/0xNyk/awesome-hermes-agent>. Use it as the **first** stop when: - You want to know if there's already a skill / plugin / integration for X (search the README before building) - You're vetting a community project's maturity (the production/beta/experimental tag is a quick filter) - You're looking for operational playbooks (memory pressure, OpenClaw migration, USER.md curation patterns) ## Related Entities - [[entities/community-orange-book]] — Chinese-language guide - [[entities/community-mission-control]] — fleet orchestration dashboard - [[entities/community-webui]] — community web UI - [[entities/community-agency-agents-zh]], [[entities/community-gbrain]] - [[entities/nous-research]] <!-- ===== hermes/wiki/entities/community-gbrain.md ===== --> --- title: "gbrain" type: entity tags: [community, brain-config, opinionated, productivity, coding, intermediate] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/community-resources.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview **gbrain** is an **opinionated Hermes "brain" configuration** at **4.8k stars**, maintained by **garrytan**. Where [[entities/community-agency-agents-zh]] gives you 193 personas to choose from, gbrain takes the opposite approach: one carefully curated baseline tuned for **productivity and coding**. It is the closest thing the Hermes ecosystem has to a "starter pack" you can drop in and immediately get a sharp default agent without having to assemble personas, skills, and memory yourself. ## Characteristics - **Repo:** <https://github.com/garrytan/gbrain> - **Stars:** 4,800+ - **Style:** opinionated single config (not a persona library) - **Tuning focus:** productivity workflows + coding tasks - **Maintenance:** active community project ### What you get (typical for a "brain" config) - `MEMORY.md` baseline with sensible workflow conventions - `USER.md` template - Curated default skill set - Suggested provider/model defaults ## How to Use 1. Clone <https://github.com/garrytan/gbrain>. 2. Follow the repo README to merge the brain into your `~/.hermes/` directory (typically copying `MEMORY.md`, `USER.md`, and select skills). 3. Optional: dedicate a [[concepts/profiles-multi-instance]] profile to gbrain so it doesn't overwrite your existing config: ```bash hermes profile create gbrain # then drop gbrain files into the profile's HERMES_HOME hermes -p gbrain ``` 4. Run normally — Hermes will pick up the curated skills and memory baseline. ## Related Entities - [[entities/community-agency-agents-zh]] — opposite philosophy (193 personas to pick from) - [[entities/community-awesome-hermes]] — directory listing - [[concepts/skills-system]], [[concepts/memory-system]], [[concepts/profiles-multi-instance]] - [[entities/nous-research]] <!-- ===== hermes/wiki/entities/community-mission-control.md ===== --> --- title: "mission-control" type: entity tags: [community, dashboard, orchestration, fleet, multi-agent, intermediate] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/awesome-hermes-agent-readme.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview **mission-control** is the largest community-run dashboard for AI agent orchestration in the Hermes ecosystem at **3.7k+ stars**, maintained by **builderz-labs**. Unlike Hermes-only GUIs, mission-control is **broader** — it manages fleets of agents (Hermes among them), dispatches tasks, tracks costs across providers, and coordinates multi-agent workflows. It is the recommended GUI in `awesome-hermes-agent`'s "Where do I start?" path for users who want a fleet-level view rather than a chat UI. ## Characteristics - **Repo:** <https://github.com/builderz-labs/mission-control> - **Stars:** 3,700+ - **Maturity tag:** production - **Self-hosted:** yes - **Storage:** SQLite-powered (no external DB required) - **Scope:** agent fleet management, task dispatch, cost tracking, multi-agent coordination - **Hermes-native?** no — it's agent-agnostic with first-class Hermes support - **Maintainer's other Hermes work:** "Builderz" the company ships production AI systems (32+ products / 15 countries per the awesome list footer) ### What it adds over hermes-workspace / hermes-webui - Fleet-level: many agents, not just one Hermes instance - Cost dashboard across providers (relevant when running [[concepts/model-switching]] and credential pools) - Task dispatch as a first-class concept (queueing work to agents, not just chatting with one) ## How to Use 1. Clone <https://github.com/builderz-labs/mission-control>. 2. Follow the repo's setup README (Docker Compose typical). 3. Register your Hermes instance(s) by pointing mission-control at the gateway HTTP endpoint or Hermes API server. 4. Use the dashboard to dispatch tasks and monitor fleet status. It pairs well with multiple [[concepts/profiles-multi-instance]] Hermes profiles dedicated to different roles (one for coding, one for research, one for content), all visible from a single pane. ## Related Entities - [[entities/community-webui]] — single-instance web UI alternative - [[entities/community-awesome-hermes]] — listed it as one of the top GUI choices - [[concepts/profiles-multi-instance]] - [[concepts/model-switching]] - [[entities/nous-research]] <!-- ===== hermes/wiki/entities/community-orange-book.md ===== --> --- title: "hermes-agent-orange-book" type: entity tags: [community, guide, chinese, documentation, foundational] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/community-resources.md", "raw/01-community-resources.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview **hermes-agent-orange-book** is the most-starred community **guide** in the Hermes ecosystem at **1.9k stars** (maintainer: alchaincyf). It is a comprehensive **Chinese-language** beginner-to-expert handbook covering setup, skills, memory, scheduling, and advanced workflows. For Mandarin-speaking developers it is effectively the de facto entry point to Hermes — recommended in get-hermes.ai's official community page. ## Characteristics - **Repo:** <https://github.com/alchaincyf/hermes-agent-orange-book> - **Stars:** 1,900+ - **Language:** Chinese (Mandarin) - **Scope:** install / config / [[concepts/skills-system]] / [[concepts/memory-system]] / [[concepts/cron-scheduling]] / advanced workflows - **Maintenance:** actively updated; tracked alongside core release cadence - **Audience:** Chinese-speaking developers, beginner through expert ## How to Use 1. Browse <https://github.com/alchaincyf/hermes-agent-orange-book>. 2. Start with the install / quickstart chapters; the structure mirrors the official docs but adds Chinese-market context (China-specific deployment patterns, integration with [[entities/platform-telegram]] alternatives). 3. For Western audiences who don't read Chinese, GitHub's translation features render the markdown reasonably well, and the code blocks are language-neutral. ## Related Entities - [[entities/community-awesome-hermes]] — English-language curated directory - [[entities/community-agency-agents-zh]] — sister Chinese-language resource (193 personas, 5.8k stars) - [[entities/nous-research]] - [[concepts/skills-system]], [[concepts/memory-system]], [[concepts/cron-scheduling]] <!-- ===== hermes/wiki/entities/community-webui.md ===== --> --- title: "hermes-webui (nesquena)" type: entity tags: [community, web-ui, gui, intermediate] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/community-resources.md", "raw/awesome-hermes-agent-readme.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview **hermes-webui** (by **nesquena**) is the most-starred Python web UI for Hermes Agent at **1.3k stars** — a three-panel **Claude-style** interface with full CLI parity and **no build step required**. It is the simplest way to put a familiar chat interface on top of an existing Hermes install without spinning up a heavier workspace like `hermes-workspace`. > Naming note: there are two community projects called `hermes-webui`. This page covers the **nesquena/hermes-webui** Python implementation (1.3k stars, Claude-style three-panel). The other (`sanchomuzax/hermes-webui`) is a lightweight ops-focused process monitor — different project. ## Characteristics - **Repo:** <https://github.com/nesquena/hermes-webui> - **Stars:** 1,300+ - **Language:** Python - **Layout:** three-panel (Claude-style) — sidebar, main chat, inspector - **Build step:** none - **Parity:** full CLI parity — anything you can do in the Hermes CLI works here - **Maturity:** community-maintained; popular enough to be one of the top GUI options alongside hermes-workspace and mission-control ## How to Use 1. Install: ```bash git clone https://github.com/nesquena/hermes-webui cd hermes-webui pip install -r requirements.txt ``` 2. Launch (commands per the repo README): ```bash python -m hermes_webui ``` 3. Open the printed local URL in your browser. Pairs well with [[entities/backend-local]] for solo developer use, or run it on the same host as a [[entities/backend-docker]] gateway when you want a browser-based interface to a containerized Hermes. ## Related Entities - [[entities/community-mission-control]] — fleet-level alternative (broader scope) - [[entities/community-awesome-hermes]] — directory that lists all GUI options - [[concepts/messaging-gateway]] - [[entities/nous-research]] <!-- ===== hermes/wiki/entities/community-workspace.md ===== --> --- title: "hermes-workspace (outsourc-e)" type: entity tags: [community, web-ui, gui, memory, skills, intermediate] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/awesome-hermes-agent-readme.md", "raw/community-resources.md", "raw/01-community-resources.md", "raw/release-v0.7.0.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview **hermes-workspace** (by **outsourc-e**) is the Hermes-native web workspace the `awesome-hermes-agent` list calls "the most complete GUI for Hermes": chat, terminal, memory browser, skills manager, and inspector in one TypeScript web app. It was **built during the Nous Hackathon 2026** and is the recommended GUI in the awesome list's "Where do I start?" path for users who want a Hermes-dedicated workspace (vs. [[entities/community-mission-control]] for fleet-level orchestration). Stars grew from 500+ (awesome list review, 2026-04-03) to **1.1k** (get-hermes.ai, 2026-04-12). ## Characteristics - **Repo:** <https://github.com/outsourc-e/hermes-workspace> - **Stars:** 1,100+ (2026-04-12); 500+ at the 2026-04-03 awesome-list review — fast growth - **Language:** TypeScript (unlike the Python [[entities/community-webui]]) - **Maturity tag:** production (awesome list) - **Surfaces:** chat, embedded terminal, memory browser/inspector, skills manager, inspector - **Hermes-native:** yes — built specifically for Hermes, unlike agent-agnostic [[entities/community-mission-control]] - **Origin:** Nous Hackathon 2026 - **Platform fit:** v0.7.0's API-server upgrades (real-time tool progress streaming, `X-Hermes-Session-Id` persistent sessions — see [[entities/version-v0.7.0]]) meaningfully improved the experience for community web UIs like this one ### Where it sits among the GUIs - **vs. [[entities/community-webui]]** (1.3k stars, Python): webui is a lighter Claude-style chat with no build step; hermes-workspace is the fuller workspace (terminal + memory + skills management) - **vs. [[entities/community-mission-control]]** (3.7k+ stars): mission-control manages fleets of agents across providers; hermes-workspace is single-instance and Hermes-only - **vs. [[entities/hermes-desktop-app]]:** native desktop client rather than a browser workspace ## How to Use 1. Clone <https://github.com/outsourc-e/hermes-workspace>. 2. Follow the repo README for install (TypeScript app — expect a Node build step, unlike hermes-webui). 3. Point it at your running Hermes instance / API server, then drive chat, the [[concepts/memory-system]] browser, and the [[concepts/skills-system]] manager from the browser. Exact build commands are not in the ingested sources — verify against the repo README. ## Related Entities - [[entities/community-webui]] — lighter single-instance alternative - [[entities/community-mission-control]] — fleet-level alternative - [[entities/hermes-desktop-app]] — native desktop alternative - [[entities/community-awesome-hermes]] — recommends it in the "Where do I start?" path - [[entities/version-v0.7.0]] — API server improvements that benefit it - [[concepts/memory-system]], [[concepts/skills-system]] - [[entities/nous-research]] <!-- ===== hermes/wiki/entities/hermes-desktop-app.md ===== --> --- title: "Hermes Desktop App" type: entity tags: [desktop, interface, electron, well-established] created: 2026-06-06 updated: 2026-06-06 sources: - "https://hermes-agent.nousresearch.com/docs/user-guide/desktop" - "https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5" - "https://www.youtube.com/watch?v=EJm8Ka-gVOc" - "https://www.youtube.com/watch?v=tiFJmVhkF_s" - "https://www.youtube.com/watch?v=2pIihd3dpoA" - "https://www.youtube.com/watch?v=mHrLuqkP1gA" - "https://www.youtube.com/watch?v=hoAHIL5Trdw" confidence: high hermes_version: "v0.16.0" --- # Hermes Desktop App ## Overview Launched in v0.16.0 (2026-06-05). A native Electron desktop application for macOS, Linux, and Windows that gives Hermes a polished GUI without changing what Hermes is underneath. The architecture is important: **the desktop app is a front end, not a separate agent**. It drives the same Hermes runtime the CLI and TUI use — same sessions, same memories, same skills, same config. If you already use Hermes via Telegram or the terminal, the desktop app picks up exactly where you left off; nothing starts from zero. The Electron shell installs first, then downloads and installs the Hermes runtime into the standard `HERMES_HOME` directory on first launch — about 2–3 minutes from opening the installer to chatting. --- ## Installation ### Fresh install (no prior Hermes) 1. Download the installer from the Hermes desktop page on the Nous Research website 2. Open the installer → click **Install Hermes** 3. The app handles the Python venv, browser tool dependencies, and Hermes command — ~2–3 minutes 4. Click **Launch Hermes** when prompted ### Existing Hermes install ```bash hermes desktop ``` Launches the desktop app using your existing configuration, API keys, sessions, and skills. No re-setup needed. ### Platform notes - **macOS**: native installer, in-app self-update, microphone access prompt on first voice use - **Linux**: arm64 + x86 supported; configure Electron sandbox helper; GPU acceleration disabled automatically on remote displays to prevent flicker - **Windows**: standard installer; in-app update available; handles Electron cache corruption on recovery --- ## `hermes desktop` CLI flags | Flag | Purpose | |---|---| | `--cwd PATH` | Set initial project/working directory shown in file browser | | `--skip-build` | Skip npm/package steps; launch existing built app | | `--force-build` | Force full rebuild regardless of content-hash cache | | `--build-only` | Build without launching | | `--source` | Launch via `electron .` against source (dev mode) | | `--ignore-existing` | Ignore system `hermes` CLI during backend resolution | | `--fake-boot` | Deterministic startup delays for testing | Environment variable: `HERMES_DESKTOP_CWD` — sets initial working directory (same as `--cwd`). --- ## UI Layout ### Left sidebar - **Sessions** — all conversations, organized chronologically; supports pinning, renaming, archiving, and **folders** for grouping related threads - **Artifacts** — every file, image, and link the agent has created or received, across all sessions; organized by type (images / files / links) - **Messaging** — GUI setup for all gateway channels (Telegram, Discord, Slack, etc.) - **Skills & Tools** — toggle skills and tool sets on/off; shows auto-generated skills the agent wrote for itself - **Cron** — all scheduled jobs; create, edit, pause, test, view run history - **+ New session** button ### Main panel - Chat window with streaming responses, tool activity indicator, and structured summaries - Drag-and-drop file attachment directly into chat area - Clipboard image paste with deduplication - Right-hand **preview rail**: renders web pages, files, and tool outputs alongside the conversation ### Status bar (bottom) - **Gateway** indicator (connected / restarting) — click to restart messaging - **Agents** — live count of sub-agents currently running - **Cron** — quick-access cron overview - **Model** — currently active model; click to change inline ### Top bar / header - **Profile switcher** — click to jump between profiles (separate Hermes agents) - **Settings** gear — full settings panel - **Cmd+K** — command palette (slash commands, @ mentions, quick actions) --- ## Sessions Sessions are the core organizational unit. Each conversation is its own session; context from one session does not bleed into another. This is the single most impactful cost-saving feature in the desktop app. **Best practice (from community):** Create a dedicated session for each area of work — content, coding, research, finance, etc. Pin the ones you return to regularly (right-click → Pin). Use folders for grouping cron-generated sessions away from your active threads. With context isolated per session, each message only carries that thread's history — vs. one big "mono thread" where context balloons and API costs can run 3–4× higher than necessary. **Concurrent sessions**: multiple sessions can run simultaneously — you can have the agent working in session A while you start a new query in session B. --- ## Profiles Profiles are separate Hermes agents — each has its own skills, `soul.md` (personality), memories, session history, and model configuration. They appear in the bottom-left profile switcher. **Sub-agent vs profile:** - **Sub-agents** are spawned copies of the current agent — same skills, same memories, same tools. Use for parallel work within a task. - **Profiles** are independent agents with different skills, memories, personalities, and models. Use when you want an agent with a genuinely different configuration. **Recommended profile strategy (community-derived):** organize by **model strengths** rather than by job title/role. Example setup: - *Default* — Opus 4.8 for high-level thinking, strategy, planning - *Coder* — GPT-5.5 (Codex) for coding tasks; higher limits, strong at code - *Local* — Qwen on DGX Spark / local machine for free, unlimited research queries - *Librarian* / *Oracle* — specialized skill sets for specific domains Managing profiles in the desktop: top-right profile button → **Manage Profiles** → create, edit `soul.md`, set model, assign skills. Each profile's model is fully editable from the GUI without touching `config.yaml`. --- ## Skills & Tool Sets Skills and tool sets are manageable from **Skills & Tools** in the left sidebar. **Important:** ~109 skills are active by default. Every active skill adds tokens to each prompt — the agent carries the skill context whether or not it uses the skill. First-time setup recommendation: go through the list and turn off everything you won't use (iMessage, Find My, Apple Reminders, Spotify, etc.). This meaningfully reduces per-message cost and latency. **Auto-generated skills**: as the agent does work for you, it writes playbook skills for recurring patterns. These appear in the same Skills & Tools view — you can see the skills the agent created for itself (e.g., a custom Godot-modding skill if you've been building games with the agent). **New in v0.16**: `environments:` frontmatter gate — context-specific skills (kanban, docker, s6) are excluded from the index for users who won't use them. Curator can now prune unused built-in skills (not just agent-created). Blank-slate profiles: pass `--no-skills` to the installer (`install.sh ... -- --no-skills`), or post-install run `hermes skills opt-out` (`--remove` also deletes unmodified bundled skills). Note: this is NOT `hermes skills install --no-skills` — that subcommand installs a specific skill. **Tool sets** are groups of tools that can be toggled as a unit: - File operations (read/write files) - Vision (analyze images) - Memory (persistent memory layer) - Task delegation (spawn sub-agents) - Browser automation - Image generation - Video analysis / generation - Web search and scraping - Session search - Discord server admin - Text to speech - Spotify Each tool set that requires an API key shows a "needs key" indicator — plug in the key to enable. --- ## Artifacts The Artifacts panel aggregates everything the agent has created or received across all sessions, organized by type: - **Files** — documents, code files, PDFs, anything the agent wrote or processed - **Images** — every image generated or analyzed - **Links** — every URL sent to the agent in any session Use case: acts as a persistent bookmarking layer. Instead of bookmarking in a browser, send a link to the agent with a note; it shows up in Artifacts and never gets buried in an old chat thread. Files that would otherwise be lost as chat scrolls away are always findable here. --- ## Cron (Scheduled Jobs) The Cron panel shows all scheduled jobs. Previously, verifying that a cron job was set up correctly required inspecting config or watching terminal output. The GUI makes it visible and manageable. **Creating a cron job in the UI:** 1. Cron panel → **New Cron** 2. Name, prompt (what to do), frequency, delivery location, scheduled time 3. Save — appears in the cron list immediately **Managing existing jobs:** click any cron job to edit; use the pause button to disable without deleting; use Test to trigger a one-off run and verify it works. **Common mistake**: many users set up cron jobs through Telegram/Discord and can't tell if they were registered correctly. The cron panel removes that ambiguity — if it's listed with a next-run time, it's active. --- ## Messaging Setup (GUI) The Messaging panel replaces terminal-based messaging configuration. Choose a platform, follow the in-app guide, paste credentials, save, and restart the gateway from the status bar. **Telegram setup walkthrough:** 1. Messaging → Telegram → paste bot token (get from @BotFather via `/newbot`) 2. Set allowed Telegram user ID (get from @userinfobot — just message it "hi", it replies with your ID) 3. Save → status bar shows "Restart needed" → click Gateway in status bar → **Restart messaging** 4. In Telegram: start a conversation with your bot → type `/set_home` to register the chat **Available platforms in the GUI**: Discord, Telegram, Slack, WhatsApp, Signal, Matrix, Mattermost, WeChat/Weixin, Google Chat, Feishu, DingTalk, email (Twilio), and more. --- ## Remote Backend Connection The desktop app can connect to a remote Hermes instance instead of managing a local one. Useful for: homelab servers, VPS, Mini behind Tailscale, team setups. The practical model: thin GUI on the laptop/phone, heavy agent runs on the machine with your API keys and compute. ### Authentication options **OAuth via Nous Portal** (requires backend on Hermes v0.16+): - Register the dashboard: `hermes dashboard register` (writes `HERMES_DASHBOARD_OAUTH_CLIENT_ID` into `~/.hermes/.env`) or via https://portal.nousresearch.com/local-dashboards. Run `hermes setup` first if not logged into Nous. Do NOT also set the `BASIC_AUTH_*` lines. - Start the dashboard **bound to the specific reachable IP, not `0.0.0.0`** — e.g. `hermes dashboard --no-open --host <tailscale-ip> --port 9119`. This is critical: the OAuth callback (`redirect_uri`) is derived from the dashboard's own address, and bound to `0.0.0.0` it can't form a URL that matches the registered canonical URL → `redirect_uri_mismatch`. Bound to the exact Tailscale/host IP, the callback matches. (`HERMES_DASHBOARD_PUBLIC_URL` / `dashboard.public_url` can override the derived URL if needed.) - Desktop: Settings → Gateway → Remote gateway → enter `http://<tailscale-ip>:9119` → the app auto-detects the provider and shows **"Sign in with Nous Research"** → browser sign-in. - **Verified by doing (2026-06-07):** OAuth over a bare Tailscale IP works *only* when the dashboard binds to that exact IP; `--host 0.0.0.0` throws `redirect_uri_mismatch — redirect_uri does not match the agent's canonical URL or localhost carve-out`. The backend must also be v0.16+ — older builds ignore the OAuth client ID and refuse to bind ("no robust authentication"). **Username/Password** (for trusted network / VPN / LAN only — **not for public internet**): - Backend setup: ```bash # In ~/.hermes/.env on the host machine: HERMES_DASHBOARD_BASIC_AUTH_USERNAME=your_username HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=your_password # Optional — set for session persistence across gateway restarts: HERMES_DASHBOARD_BASIC_AUTH_SECRET=some_random_long_string ``` - Start the dashboard on the host: `hermes dashboard --no-open --host 0.0.0.0 --port 9119` - Desktop: Settings → Gateway → Remote gateway → enter `http://<host>:9119` → sign in with username/password ### Troubleshooting remote connections | Symptom | Likely cause | Fix | |---|---|---| | `redirect_uri_mismatch` (OAuth) | Dashboard bound to `0.0.0.0`, so the OAuth callback can't match the registered canonical URL | Bind to the specific reachable IP: `--host <tailscale-ip>` (or set `HERMES_DASHBOARD_PUBLIC_URL`) | | Refuses to bind / "no robust authentication" | Backend older than v0.16, or no OAuth client ID / basic-auth creds in `.env` | `hermes update` the backend; confirm `HERMES_DASHBOARD_OAUTH_CLIENT_ID` (or basic-auth lines) in `.env` | | 401 errors | Credentials mismatch | `curl -s http://<host>:9119/api/status \| jq '.auth_required, .auth_providers'` to verify what auth the backend expects | | No sign-in button | Provider inactive | OAuth: ensure `HERMES_DASHBOARD_OAUTH_CLIENT_ID` is set and dashboard restarted. Basic: ensure `HERMES_DASHBOARD_BASIC_AUTH_USERNAME` + password/hash in `.env` | | Session lost on gateway restart | Missing stable secret | Set `HERMES_DASHBOARD_BASIC_AUTH_SECRET` in `.env` (basic-auth path) | | Connection failure | Backend on loopback or firewall | Bind backend to the specific IP; check firewall | **Relationship to Tailscale+Termius video**: username/password auth over a Tailscale network is a cleaner alternative to the SSH+tmux+port-forward pattern covered in the standalone Tailscale video. Instead of port-forwarding `localhost:9119` through SSH every session, point the desktop app's remote gateway setting at `http://hermes-pc:9119` (via MagicDNS) with password auth — the dashboard handles the connection persistently. --- ## Settings Panels | Panel | Key settings | |---|---| | **Model / Providers** | Active model, API keys per provider — add keys here, never paste in chat | | **Chat** | Personality presets (Cat Girl, Shakespeare, etc.), custom persona | | **Appearance** | Theme: default light (icy blue), dark, cyberpunk, mono dark; language (`display.language` — Simplified Chinese available) | | **Memory & Contacts** | Compression threshold — recommended: lower to **0.5** for better memory retention (compacts more often but smaller chunks → less forgetting); contacts management | | **Workspace** | Initial working directory definition | | **Gateway** | Local vs remote backend; remote URL and credentials | | **API Keys** | Add/manage provider API keys through the GUI (not via chat — pasting API keys in chat is a security risk, they end up in the session log) | **Memory tuning note (community-validated):** default compression threshold causes noticeable forgetting for some users. Setting it to 0.5 (more frequent, smaller compressions) resolves most memory complaints without significantly increasing cost. --- ## Logs, Debugging & Resets **Logs:** ```bash hermes logs gui -f # tail desktop logs live # Log file: HERMES_HOME/logs/desktop.log # Also included in: hermes debug share / /debug ``` **Clean reinstall** (keeps config/sessions): ```bash rm ~/.hermes/hermes-agent/.hermes-bootstrap-complete # Re-open desktop app → triggers fresh install of runtime ``` **Python environment rebuild:** ```bash rm -rf ~/.hermes/hermes-agent/venv # Desktop app recreates it on next launch ``` **macOS microphone reset:** ```bash tccutil reset Microphone com.nousresearch.hermes ``` --- ## Uninstallation Three levels available in **Settings → About → Danger zone:** | Option | CLI equivalent | What's removed | |---|---|---| | Uninstall Chat GUI only | `hermes uninstall --gui` | Desktop app shell only; agent config/chats/secrets persist | | Uninstall GUI + agent, keep data | `hermes uninstall` | App + agent runtime; config/chats/secrets persist | | Uninstall everything | `hermes uninstall --full` | Complete removal including all user data | --- ## Cost Management Tips (Community-Derived) 1. **Session isolation** — keep each topic in its own session. With Opus (1M context), a polluted mono-thread can run 3–4× the cost of focused sessions. 2. **Turn off unused skills** — every active skill is context weight. Audit the ~109 defaults and disable anything you don't use. 3. **Profile-per-model** — use a cheap/local model profile for research and quick lookups; reserve expensive models (Opus) for high-level work. 4. **Add API keys through the UI** — never paste API keys into the chat window; they end up in session logs readable by anyone with access to your sessions. 5. **Tune compression threshold** — 0.5 gives better memory with acceptable cost; default is conservative and causes forgetting. --- ## Related Entities - [[entities/version-v0.16.0]] — release that introduced the desktop app - [[summaries/release-v0.16.0]] — full v0.16.0 release notes - [[concepts/profiles-multi-instance]] — profile system (separate agents with distinct configs) - [[concepts/skills-system]] — skills management (environments gate, curator pruning, NVIDIA tap) - [[concepts/cron-scheduling]] — cron jobs (now fully manageable in GUI) - [[concepts/messaging-gateway]] — messaging setup (Telegram, Discord, etc.) - [[concepts/deployment-backends]] — remote backend connect (local vs remote gateway) <!-- ===== hermes/wiki/entities/hermes-paperclip-adapter.md ===== --> --- title: "hermes-paperclip-adapter" type: entity tags: [multi-agent, tools, intermediate, emerging] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/awesome-hermes-agent-readme.md", "raw/community-resources.md", "raw/01-community-resources.md", "raw/transcript-hermes-full-course-2hr.txt", "raw/transcript-live-masterclass-browser-qwen.txt"] confidence: medium hermes_version: "v0.8.0" --- ## Overview **hermes-paperclip-adapter** (`github.com/NousResearch/hermes-paperclip-adapter`, **741 stars** per get-hermes.ai, 2026-04-12) is an official [[entities/nous-research]] project that lets you **run Hermes as a managed employee inside a Paperclip company**. Per the `awesome-hermes-agent` description, it "connects the agent to Paperclip's task management and governance system." **Paperclip** (as described in the live masterclass transcripts) is an open-source way to orchestrate *teams* of AI agents as a company: a CEO agent at the top of an org chart, worker agents below, all coordinating on tasks. The adapter is what slots a Hermes instance into that hierarchy — Paperclip handles structure, task assignment, and governance; Hermes does the work. ## Characteristics - **Repo:** <https://github.com/NousResearch/hermes-paperclip-adapter> - **Maintainer:** Nous Research (official project) - **Stars:** 741 (get-hermes.ai community page, 2026-04-12) - **Role split:** Paperclip = org chart / task management / governance layer; Hermes = the managed employee executing tasks - **Mixed-harness hierarchies:** the masterclass Q&A explicitly discusses setups like OpenClaw as CEO with Hermes agents as workers — Paperclip companies can mix agent harnesses, including [[entities/openclaw]] and Claude Code - **Important:** there are multiple Paperclip-related skills in the wild. The masterclass host stresses that the one to use for Hermes-in-Paperclip is specifically the **Hermes Paperclip Adapter**, not the generic Paperclip skill - **Use case from the full course:** structuring departmental teams (e.g., an accounting team vs. a marketing team) where "Paperclip would help you structure the whole setup" ## How to Use A verified step-by-step install is not present in the ingested sources; the pattern shown in the masterclass demos is: 1. Set up a Paperclip company (Paperclip is a separate open-source project with its own install). 2. Install the **Hermes Paperclip Adapter** — it is discoverable the same way other skills are (see [[concepts/skills-system]]; the host finds it by browsing Hermes-related repos/skills on GitHub). 3. Make sure the adapter is configured before expecting Paperclip to manage your Hermes agents — the transcript repeatedly warns "you need to make sure that you've got this set up." Treat exact commands as unverified until the repo README is ingested. ## Related Entities - [[entities/nous-research]] — maintainer; sibling official projects: [[entities/hermes-self-evolution]], [[entities/autonovel]] - [[entities/openclaw]] — can sit in the same Paperclip hierarchy (e.g., as CEO over Hermes workers) - [[concepts/skills-system]] — how the adapter is discovered and installed - [[entities/community-awesome-hermes]] — lists the adapter under Official Resources <!-- ===== hermes/wiki/entities/hermes-self-evolution.md ===== --> --- title: "hermes-agent-self-evolution" type: entity tags: [ml-research, skills, advanced, experimental, emerging, developer] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/awesome-hermes-agent-readme.md", "raw/community-resources.md", "raw/01-community-resources.md", "raw/transcript-247-self-evolving.txt"] confidence: medium hermes_version: "v0.8.0" --- ## Overview **hermes-agent-self-evolution** (`github.com/NousResearch/hermes-agent-self-evolution`, **893 stars** per get-hermes.ai, 2026-04-12) is an official [[entities/nous-research]] project: an **evolutionary self-improvement pipeline using DSPy and GEPA** (Genetic Evolution of Prompt Architectures). The `awesome-hermes-agent` list describes it as "the research pipeline for optimizing Hermes's own prompts and behaviors." It is the offline/research-grade counterpart to the [[concepts/self-improvement-loop]] that runs *inside* every Hermes session. The in-agent loop (the "GAPA" mechanism community videos describe as "back propagation but for prompts instead of model weights") fires continuously during normal use; this project packages the same idea as a standalone evolutionary optimization pipeline you run deliberately — e.g., on a schedule against your agent's accumulated trajectories. > Naming caution: the 24/7 Self-Evolving video spells the in-agent mechanism "GAPA," while this project's documentation says "GEPA." [[summaries/transcript-247-self-evolving]] treats them as the same approach. The exact relationship between the in-session loop and this repo's pipeline is **inferred, not confirmed from the repo itself** — low confidence on that mapping. ## Characteristics - **Repo:** <https://github.com/NousResearch/hermes-agent-self-evolution> - **Maintainer:** Nous Research (official project, not community) - **Stars:** 893 (get-hermes.ai community page, 2026-04-12) - **Approach:** DSPy + GEPA — evolutionary optimization of prompts/behaviors rather than weight updates - **Scope:** optimizes the Hermes harness's own prompts and behaviors; complements (does not replace) `tinker-atropos`, which does actual RL fine-tuning of model weights on agent trajectories (see [[concepts/ml-research-pipeline]]) - **Listed in:** [[entities/community-awesome-hermes]] under Official Resources, and on the get-hermes.ai community page under Official Nous Research Projects ## How to Use Concrete setup commands are not present in the sources ingested so far — the steps below are the operational pattern recommended by the `awesome-hermes-agent` "Operational Playbooks" section, not a verified walkthrough: 1. Clone <https://github.com/NousResearch/hermes-agent-self-evolution> and follow the repo README. 2. **Nightly self-evolution + guardrail evaluation** — run the pipeline on a schedule (Hermes cron), then run a *second* verification cron to score output quality and block optimization-loop gaming. This guardrail step is explicitly recommended; unguarded self-optimization can reward-hack its own metric. Until the repo README is ingested as a raw source, treat any specific CLI invocation as unverified. ## Related Entities - [[entities/nous-research]] — maintainer; this is one of four official ecosystem projects alongside [[entities/hermes-paperclip-adapter]] and [[entities/autonovel]] - [[concepts/self-improvement-loop]] — the in-session GAPA loop this project industrializes - [[concepts/ml-research-pipeline]] — trajectory capture and RL training infrastructure that feeds and complements it - [[concepts/skills-system]] — skills are the substrate that prompt-evolution outputs land in - [[summaries/transcript-247-self-evolving]] — community framing of the GAPA/GEPA mechanism - [[entities/community-awesome-hermes]] — source of the nightly-run operational playbook <!-- ===== hermes/wiki/entities/memory-byterover.md ===== --> --- title: "ByteRover Memory Provider" type: entity tags: [memory, byterover, provider, plugin, third-party] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-features-memory-providers.md", "raw/docs-user-guide-features-memory.md", "raw/docs-reference-cli-commands.md"] confidence: high hermes_version: "v0.9.0" --- ## Overview **ByteRover** brings persistent memory to Hermes via the **`brv` CLI** — a hierarchical knowledge tree with tiered retrieval (fuzzy text search first, escalating to LLM-driven search). It is **local-first with optional cloud sync**, which the official docs frame as "best for developers who want portable, local-first memory with a CLI." Its standout integration point is **automatic pre-compression extraction**: it hooks the moment before Hermes compresses context and saves insights that compression would otherwise discard (the `on_pre_compress` hook in the memory provider ABC — see [[concepts/memory-system]]). It is present in the official eight-provider roster as of the docs mirror dated 2026-04-13 (the v0.9.0 release day); the exact release that introduced it is not captured in this KB's release notes. ## Characteristics - **Hosting:** local by default; optional ByteRover Cloud sync (SOC2 Type II certified) - **Pricing:** free (local) / ByteRover pricing (cloud sync) - **Dependencies:** the ByteRover CLI itself — `npm install -g byterover-cli` or the install script - **Storage:** knowledge tree at `$HERMES_HOME/byterover/`, so it is profile-scoped automatically - **Retrieval:** tiered — cheap fuzzy text match first, LLM-driven search when needed - **Unique feature (per official comparison):** pre-compression extraction - **Tools added to the agent:** `brv_query` (search knowledge tree), `brv_curate` (store facts/decisions/patterns), `brv_status` (CLI version + tree stats) - **Portability:** the knowledge tree lives outside Hermes in `brv`'s own format, so the same memory can travel to other tools that speak ByteRover ## How to Use Setup verbatim from the official docs: ```bash # Install the CLI first curl -fsSL https://byterover.dev/install.sh | sh # Then configure Hermes hermes memory setup # select "byterover" # Or manually: hermes config set memory.provider byterover ``` No API key is needed for local mode — there is no `.env` step, unlike the cloud providers. Provider selection can also be set in `~/.hermes/config.yaml` (`memory.provider: byterover`, see [[concepts/configuration-reference]]) and managed with `hermes memory status` / `hermes memory off` ([[concepts/cli-reference]]). ## Related Entities - [[entities/memory-holographic]] — the other local-first option (SQLite, zero dependencies, no CLI install) - [[entities/memory-openviking]] — self-hosted with a similar hierarchical/tiered retrieval philosophy, but server-based - [[entities/memory-honcho]] — first-party reference plugin - [[concepts/memory-system]] - [[entities/version-v0.7.0]] — memory provider ABC (incl. the `on_pre_compress` hook ByteRover exploits) - [[syntheses/memory-providers-compared]] <!-- ===== hermes/wiki/entities/memory-hindsight.md ===== --> --- title: "Hindsight Memory Provider" type: entity tags: [memory, hindsight, provider, plugin, well-established] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-features-memory-providers.md", "raw/docs-user-guide-features-memory.md", "raw/awesome-hermes-agent-readme.md", "raw/release-v0.9.0.md", "raw/release-v0.11.0.md", "raw/release-v0.12.0.md", "raw/release-v0.13.0.md", "raw/release-v0.14.0.md"] confidence: high hermes_version: "v0.14.0" --- ## Overview **Hindsight** (`vectorize-io/hindsight`, by Vectorize) is the knowledge-graph memory provider for Hermes: long-term memory with **entity resolution, multi-strategy retrieval, and a retain/recall/reflect workflow**. Its `hindsight_reflect` tool provides **cross-memory synthesis that no other provider offers** (per official docs). It automatically retains full conversation turns — including tool calls — with session-level document tracking, and is the only provider besides Honcho that offers both a managed cloud and a free local mode (embedded PostgreSQL). The `awesome-hermes-agent` directory tags it **[production]**, and its operational playbook names Hindsight alongside Honcho as the answer to memory-pressure symptoms. Hindsight is also the most actively maintained third-party provider in the captured release history: feature parity + setup wizard in [[entities/version-v0.9.0]] (@nicoloboschi), richer session-scoped retain metadata in [[entities/version-v0.11.0]], clean embedded-async-client shutdown in [[entities/version-v0.12.0]], cross-process `update_mode='append'` dedup in [[entities/version-v0.13.0]], and lazy-install / optional-dependency packaging in [[entities/version-v0.14.0]]. ## Characteristics - **Hosting:** Hindsight Cloud (API key from `ui.hindsight.vectorize.io`) **or** local with embedded PostgreSQL — local mode needs an LLM API key (OpenAI, Groq, OpenRouter, etc.) for extraction - **Pricing:** Hindsight pricing (cloud) / free (local) - **Dependencies:** `hindsight-client >= 0.4.22` for cloud (auto-upgraded on session start if outdated), `hindsight-all` for local; the setup wizard installs only what the selected mode needs; lazy-installed on first use since v0.14.0 - **Retrieval:** semantic + graph + temporal, multi-strategy - **Tools added to the agent:** `hindsight_retain` (store with entity extraction), `hindsight_recall` (multi-strategy search), `hindsight_reflect` (cross-memory synthesis) - **Local mode UI:** `hindsight-embed -p hermes ui start` - **Also usable via MCP** instead of the memory plugin (per awesome-hermes-agent) ### Config — `$HERMES_HOME/hindsight/config.json` | Key | Default | Description | |---|---|---| | `mode` | `cloud` | `cloud` or `local` | | `bank_id` | `hermes` | Memory bank identifier | | `recall_budget` | `mid` | Recall thoroughness: `low` / `mid` / `high` | | `memory_mode` | `hybrid` | `hybrid` (context + tools), `context` (auto-inject only), `tools` (tools only) | | `auto_retain` | `true` | Automatically retain conversation turns | | `auto_recall` | `true` | Automatically recall memories before each turn | | `retain_async` | `true` | Process retain asynchronously on the server | | `tags` / `recall_tags` | — | Tags applied on store / filtered on recall | ## How to Use Setup verbatim from the official docs: ```bash hermes memory setup # select "hindsight" # Or manually: hermes config set memory.provider hindsight echo "HINDSIGHT_API_KEY=your-key" >> ~/.hermes/.env ``` Or in `~/.hermes/config.yaml` (see [[concepts/configuration-reference]]): `memory.provider: hindsight`. Manage via `hermes memory status` / `hermes memory off` ([[concepts/cli-reference]]). ## Related Entities - [[entities/memory-honcho]] — the other cloud-or-self-hosted option; dialectic user modeling instead of knowledge graph - [[entities/memory-openviking]] — the other strong self-hosted option (filesystem hierarchy instead of graph) - [[entities/memory-retaindb]], [[entities/memory-mem0]] — cloud retrieval-centric alternatives - [[concepts/memory-system]] - [[entities/version-v0.9.0]] — feature parity + setup wizard - [[entities/version-v0.14.0]] — lazy-install packaging - [[syntheses/memory-providers-compared]] <!-- ===== hermes/wiki/entities/memory-holographic.md ===== --> --- title: "Holographic Memory Provider" type: entity tags: [memory, holographic, provider, plugin, third-party] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-features-memory-providers.md", "raw/docs-user-guide-features-memory.md", "raw/docs-reference-cli-commands.md"] confidence: high hermes_version: "v0.9.0" --- ## Overview **Holographic** is the zero-dependency, fully local memory provider for Hermes: a **SQLite fact store with FTS5 full-text search, trust scoring, and HRR (Holographic Reduced Representations)** for compositional algebraic queries. It is the only provider that requires literally nothing to set up — no API key, no server, no pip install (SQLite is always available; NumPy is optional, enabling the HRR algebra). Official docs position it as "best for local-only memory with advanced retrieval, no external dependencies." Note: an earlier KB synthesis ([[syntheses/memory-providers-compared]], v0.8.0-era) characterized Holographic as an "experimental dense-retrieval store" with hard setup; the official v0.9.0-era docs supersede that — it is a documented, supported provider with trivial setup. It appears in the official roster as of the docs mirror dated 2026-04-13; the exact release that introduced it is not captured in this KB's release notes. ## Characteristics - **Hosting:** local only (SQLite at `$HERMES_HOME/memory_store.db` — profile-scoped by construction) - **Pricing:** free - **Dependencies:** none; NumPy optional for HRR algebra - **Retrieval:** FTS5 full-text + HRR compositional queries - **Tools added to the agent:** `fact_store` (9 actions: add, search, probe, related, reason, contradict, update, remove, list) and `fact_feedback` (helpful/unhelpful rating that trains trust scores) — only 2 tools, the smallest tool surface of any provider ### Unique capabilities (per official docs) - **`probe`** — entity-specific algebraic recall (all facts about a person/thing) - **`reason`** — compositional AND queries across multiple entities - **`contradict`** — automated detection of conflicting facts - **Trust scoring** with asymmetric feedback: +0.05 for helpful, -0.10 for unhelpful ### Config — `config.yaml` under `plugins.hermes-memory-store` | Key | Default | Description | |---|---|---| | `db_path` | `$HERMES_HOME/memory_store.db` | SQLite database path | | `auto_extract` | `false` | Auto-extract facts at session end | | `default_trust` | `0.5` | Default trust score (0.0–1.0) | Note the config namespace: unlike Honcho/Mem0/Hindsight/Supermemory (own JSON file in `$HERMES_HOME`), Holographic configures under the `plugins.hermes-memory-store` key in `config.yaml` (see [[concepts/configuration-reference]]). ## How to Use Setup verbatim from the official docs: ```bash hermes memory setup # select "holographic" # Or manually: hermes config set memory.provider holographic ``` That is the entire setup. Manage with `hermes memory status` / `hermes memory off` ([[concepts/cli-reference]]). Good default for air-gapped or privacy-sensitive machines where cloud providers are off the table and running an OpenViking server is overkill. ## Related Entities - [[entities/memory-byterover]] — the other local-first provider (CLI-based knowledge tree vs SQLite facts) - [[entities/memory-openviking]] — self-hosted server alternative for heavier local knowledge management - [[entities/memory-honcho]] — first-party reference plugin (cloud/self-hosted) - [[concepts/memory-system]] - [[entities/version-v0.7.0]] — memory provider ABC - [[syntheses/memory-providers-compared]] — note its holographic row is stale vs the official docs <!-- ===== hermes/wiki/entities/memory-honcho.md ===== --> --- title: "Honcho Memory Provider" type: entity tags: [memory, honcho, provider, plugin, foundational] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/02-install-and-setup.md", "raw/release-v0.7.0.md", "raw/awesome-hermes-agent-readme.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview **Honcho** is the flagship memory backend for Hermes Agent and the **reference plugin** for the pluggable memory provider interface introduced in [[entities/version-v0.7.0]]. It models conversation history dialectically — building per-peer (per-user) representations of who you are, what you prefer, and what you've discussed before, scoped per profile. Honcho is the backend Nous Research themselves recommend when built-in memory isn't enough, and it's first-party documented at `hermes-agent.nousresearch.com/docs/user-guide/features/honcho`. ## Characteristics - **Hosting:** managed cloud (default, requires `HONCHO_API_KEY`) or self-hosted (community-maintained recipe at `elkimek/honcho-self-hosted`, 137 stars) - **Pricing:** managed tier metered; self-hosted is free if you bring infra (typically OpenRouter or Venice for the LLM) - **Trust level:** reference plugin — first-party, full parity with built-in memory as of v0.7.0 - **Profile awareness:** profile-scoped host/peer resolution (each [[concepts/profiles-multi-instance]] gets its own Honcho session) - **Modeling style:** dialectic — explicit peer/host/agent identity model rather than vector dump - **Setup surface:** single CLI namespace `hermes honcho {setup, status, sessions, map, peer, mode, tokens, identity, migrate}` ### Why it's the flagship - **Maintained by Nous-aligned contributors** (Honcho plugin re-landed by community contributor @erosika in v0.7.0) - **Cross-session continuity is shared** — the gateway treats Honcho memory as one of the artifacts mirrored across [[entities/platform-telegram]], [[entities/platform-discord]], [[entities/platform-slack]] sessions - **Migration path exists** — `hermes honcho migrate` lets you move from built-in memory ## How to Use Cloud (managed) setup: ```bash hermes honcho setup # enter HONCHO_API_KEY when prompted hermes honcho status ``` Switch dialectic mode on/off: ```bash hermes honcho mode dialectic ``` Inspect session mapping for the active profile: ```bash hermes honcho sessions hermes honcho peer ``` Migrate from built-in memory: ```bash hermes honcho migrate ``` Self-hosted setup: clone `elkimek/honcho-self-hosted`, point `HONCHO_API_URL` at your instance, then run `hermes honcho setup` against it. ## Related Entities - [[entities/memory-supermemory]] — newer alternative (v0.8.0) - [[entities/memory-mem0]] — third-party alternative - [[concepts/memory-system]] - [[entities/version-v0.7.0]] — pluggable memory interface + Honcho parity restored - [[syntheses/memory-providers-compared]] <!-- ===== hermes/wiki/entities/memory-mem0.md ===== --> --- title: "Mem0 Memory Provider" type: entity tags: [memory, mem0, provider, plugin, third-party] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/release-v0.7.0.md", "raw/03-skills-system.md"] confidence: low hermes_version: "v0.8.0" --- ## Overview **Mem0** is a third-party memory layer available to Hermes via the pluggable memory provider interface that landed in [[entities/version-v0.7.0]]. It is one of the most widely-used open-source agent-memory libraries in the broader ecosystem (mem0.ai), with a vector-store-backed long-term memory model and a cloud-managed tier. In Hermes it is one of several alternatives to the built-in store and to [[entities/memory-honcho]]. ## Characteristics - **Hosting:** managed cloud (Mem0 Platform) or self-hosted (open source library) - **Pricing:** managed tier metered; self-hosted free if you bring vector storage - **Storage model:** vector-store + scoring layer for fact extraction; less explicit dialectic identity modeling than Honcho - **Trust level:** community-supported integration via Hermes's plugin ABC; not first-party maintained by Nous - **Strength:** broad ecosystem familiarity — engineers who have used Mem0 elsewhere can drop it into Hermes without learning a new API - **Weakness vs Honcho:** less profile-aware peer modeling out of the box > Confidence: low. The pluggable memory interface in v0.7.0 explicitly names "vector stores" as a category third-party plugins can register, but no Mem0-specific CLI commands are documented in the raw sources captured in this KB. Treat the setup details as illustrative rather than verbatim until verified against the official docs site. ## How to Use Typical pattern (verify against `hermes plugins list` and Mem0's own integration guide): 1. `pip install mem0ai` 2. Set `MEM0_API_KEY` in `~/.hermes/.env` for managed; or configure local vector store for self-hosted. 3. In `~/.hermes/config.yaml`: ```yaml memory: provider: mem0 # provider-specific config under `mem0:` namespace ``` 4. Restart `hermes gateway`. ## Related Entities - [[entities/memory-honcho]] — Nous reference plugin, more profile-aware - [[entities/memory-supermemory]] — newer paid alternative with multi-container - [[concepts/memory-system]] - [[entities/version-v0.7.0]] — pluggable memory interface - [[syntheses/memory-providers-compared]] <!-- ===== hermes/wiki/entities/memory-openviking.md ===== --> --- title: "OpenViking Memory Provider" type: entity tags: [memory, openviking, provider, plugin, third-party] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-features-memory-providers.md", "raw/docs-user-guide-features-memory.md", "raw/release-v0.11.0.md", "raw/release-v0.12.0.md"] confidence: high hermes_version: "v0.12.0" --- ## Overview **OpenViking** is a self-hosted **context database by Volcengine (ByteDance)**, integrated into Hermes as a memory provider. It organizes knowledge in a **filesystem-style hierarchy** (browsable via a `viking://` URI scheme), serves it with **tiered retrieval** — L0 abstract (~100 tokens) → L1 overview (~2k tokens) → L2 full content — and performs **automatic memory extraction into 6 categories** (profile, preferences, entities, events, cases, patterns) on session commit. It is free and open-source (AGPL-3.0), making it the heavyweight self-hosted option vs the lighter local providers. Notably, it is the example provider in the official docs' own config snippet (`memory: provider: openviking`). Release notes confirm active maintenance: [[entities/version-v0.11.0]] fixed the account default and added session commit on `/new` and compress; [[entities/version-v0.12.0]] fixed `viking_read` 500/412 errors on file URIs and pseudo-summary URIs. Note: an earlier KB synthesis described OpenViking as "community-built, experimental, hard setup" — the official docs supersede that: it is a Volcengine project with a documented, supported integration. It appears in the official roster as of the docs mirror dated 2026-04-13 (v0.9.0 release day); the exact release that introduced it is not captured in this KB's release notes. ## Characteristics - **Hosting:** self-hosted only — `pip install openviking` + a running `openviking-server` (local or your own cloud) - **Pricing:** free (open-source, AGPL-3.0) - **Configuration style:** env-var provider — configured via each profile's `.env` (`OPENVIKING_ENDPOINT`), not a JSON config file - **Retrieval:** tiered context loading L0 (~100 tokens) → L1 (~2k) → L2 (full), keeping recall token-cheap until depth is actually needed - **Knowledge organization:** filesystem-style hierarchy, navigable with `viking://` URIs - **Auto-extraction:** on session commit, into 6 categories — profile, preferences, entities, events, cases, patterns - **Tools added to the agent:** `viking_search` (semantic search), `viking_read` (tiered: abstract/overview/full), `viking_browse` (filesystem navigation), `viking_remember` (store facts), `viking_add_resource` (ingest URLs/docs) — 5 tools; `viking_add_resource` makes it the only provider with first-class document/URL ingestion ## How to Use Setup verbatim from the official docs: ```bash # Start the OpenViking server first pip install openviking openviking-server # Then configure Hermes hermes memory setup # select "openviking" # Or manually: hermes config set memory.provider openviking echo "OPENVIKING_ENDPOINT=http://localhost:1933" >> ~/.hermes/.env ``` Or in `~/.hermes/config.yaml` (see [[concepts/configuration-reference]]): ```yaml memory: provider: openviking # or honcho, mem0, hindsight, holographic, retaindb, byterover, supermemory ``` Manage with `hermes memory status` / `hermes memory off` ([[concepts/cli-reference]]). Pick OpenViking when data residency matters and you want structured, browsable knowledge rather than an opaque vector store. ## Related Entities - [[entities/memory-hindsight]] — the other strong self-hosted option (knowledge graph vs filesystem hierarchy) - [[entities/memory-holographic]] — zero-setup local alternative when running a server is overkill - [[entities/memory-byterover]] — local-first with a similar tiered-retrieval philosophy, CLI-based - [[concepts/memory-system]] - [[entities/version-v0.11.0]], [[entities/version-v0.12.0]] — OpenViking fixes - [[syntheses/memory-providers-compared]] — note its OpenViking row is stale vs the official docs <!-- ===== hermes/wiki/entities/memory-retaindb.md ===== --> --- title: "RetainDB Memory Provider" type: entity tags: [memory, retaindb, provider, plugin, third-party] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-features-memory-providers.md", "raw/docs-user-guide-features-memory.md", "raw/docs-reference-cli-commands.md"] confidence: high hermes_version: "v0.9.0" --- ## Overview **RetainDB** is a cloud-hosted memory API available to Hermes through the pluggable memory provider interface ([[entities/version-v0.7.0]] introduced the ABC). Its pitch is retrieval quality: hybrid search combining **Vector + BM25 + Reranking**, **7 memory types**, and **delta compression** for efficient storage. Official docs position it as "best for teams already using RetainDB's infrastructure." Like all external providers, it runs alongside — never replacing — the built-in MEMORY.md / USER.md layer (see [[concepts/memory-system]]). It is present in the official eight-provider roster as of the docs mirror dated 2026-04-13 (the v0.9.0 release day); the exact release that introduced it is not captured in this KB's release notes. ## Characteristics - **Hosting:** RetainDB Cloud only (no self-hosted mode documented) - **Pricing:** $20/month — the only provider with a flat published price in the official comparison table - **Dependencies:** just `requests` (lightest cloud-provider footprint) - **Retrieval:** hybrid search — vector embeddings + BM25 keyword + reranking - **Memory model:** 7 memory types with per-memory importance (the type list is not enumerated in the docs mirror) - **Unique feature (per official comparison):** delta compression - **Profile isolation:** auto-derives profile-scoped project names from the active Hermes profile (the docs single out RetainDB as the example of this cloud-side isolation pattern) - **Tools added to the agent:** `retaindb_profile` (user profile), `retaindb_search` (semantic search), `retaindb_context` (task-relevant context), `retaindb_remember` (store with type + importance), `retaindb_forget` (delete memories) — 5 tools, tied with OpenViking for the largest tool surface ## How to Use Requires a RetainDB account + API key. Setup verbatim from the official docs: ```bash hermes memory setup # select "retaindb" # Or manually: hermes config set memory.provider retaindb echo "RETAINDB_API_KEY=your-key" >> ~/.hermes/.env ``` Or set directly in `~/.hermes/config.yaml` (see [[concepts/configuration-reference]]): ```yaml memory: provider: retaindb ``` Check status / disable via the standard surface ([[concepts/cli-reference]]): `hermes memory status`, `hermes memory off`. Only one external provider can be active at a time. ## Related Entities - [[entities/memory-hindsight]] — alternative with knowledge graph + free local mode - [[entities/memory-mem0]] — the other "hands-off cloud extraction" option - [[entities/memory-supermemory]] — cloud alternative with multi-container partitioning - [[entities/memory-honcho]] — first-party reference plugin - [[concepts/memory-system]] - [[entities/version-v0.7.0]] — memory provider ABC - [[syntheses/memory-providers-compared]] <!-- ===== hermes/wiki/entities/memory-supermemory.md ===== --> --- title: "Supermemory Provider" type: entity tags: [memory, supermemory, provider, plugin, emerging] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/release-v0.8.0.md"] confidence: medium hermes_version: "v0.8.0" --- ## Overview **Supermemory** is the newest memory provider in Hermes, **added in [[entities/version-v0.8.0]]**. It is a multi-container memory backend with configurable search modes and an identity-template system for shaping how the agent remembers per-peer attributes. Its differentiator vs [[entities/memory-honcho]] is the multi-container model — you can partition memory into separate stores (e.g., work / personal / project) addressed independently by the same agent. ## Characteristics - **Hosting:** managed cloud (Supermemory.ai) - **Pricing:** metered (paid) - **Trust level:** new — added in latest release, parity with Honcho not yet field-verified - **Search modes:** configurable `search_mode` parameter (Supermemory exposes multiple retrieval strategies) - **Multi-container:** segregate memory into distinct containers; useful for keeping personal context out of work agent threads without spinning up separate [[concepts/profiles-multi-instance]] - **Identity template:** declarative template that shapes per-peer memory schema ## How to Use The exact CLI surface for Supermemory is shipped under the plugin system added in v0.8.0. Typical setup pattern follows other providers: 1. Sign up at supermemory.ai and obtain an API key. 2. Set `SUPERMEMORY_API_KEY` in `~/.hermes/.env` (variable name TBD — check `hermes plugins list`). 3. Configure provider in `~/.hermes/config.yaml`: ```yaml memory: provider: supermemory search_mode: hybrid # or other modes Supermemory exposes containers: - name: work - name: personal ``` 4. Restart `hermes gateway`. > Confidence: medium. The v0.8.0 release notes confirm Supermemory was added with multi-container, search_mode, and identity-template features, but full CLI documentation has not been re-verified in this KB. ## Related Entities - [[entities/memory-honcho]] — Nous reference plugin, the established alternative - [[entities/memory-mem0]] — another third-party alternative - [[concepts/memory-system]] - [[entities/version-v0.8.0]] — release that introduced Supermemory - [[syntheses/memory-providers-compared]] <!-- ===== hermes/wiki/entities/nous-research.md ===== --> --- title: "Nous Research" type: entity tags: [nous-research, organization, ai-lab, foundational] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/awesome-hermes-agent-readme.md", "raw/community-resources.md", "raw/release-v0.6.0.md", "raw/release-v0.7.0.md", "raw/release-v0.8.0.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview **Nous Research** is the AI lab behind Hermes Agent. They train the Hermes model family of open-weights LLMs and ship the Hermes Agent harness as the canonical runtime for self-improving agents built on those models. Their research focus is **self-improving agents** — agents that capture trajectories from real use, distill them into reusable skills, and feed those trajectories back into model fine-tuning. Hermes Agent is the operational embodiment of that thesis. ## Characteristics - **Website:** <https://nousresearch.com> - **Discord community:** <https://discord.gg/NousResearch> — primary support / discussion channel for Hermes Agent (no separate forum, newsletter, or podcast as of 2026-04) - **Co-founder presence:** @teknium1 is a Nous Research co-founder and the top single contributor across recent Hermes releases (90 PRs in the v0.6.0 cycle alone) - **Release cadence on Hermes Agent:** roughly every 3-5 days. v0.6.0 → v0.7.0 → v0.8.0 spanned March 30 → April 8, 2026. - **Stars:** Hermes Agent core repo is at 23k+ stars per the Awesome list (2026-04-03) and 56k+ per the get-hermes.ai community page (2026-04-12), reflecting fast growth - **Funding/context:** independent lab; pitches Hermes Agent as the open-source alternative to closed agent harnesses, with explicit support for open models that closed competitors (e.g., OpenClaw) explicitly do not recommend ## Official Nous Research projects in the Hermes ecosystem - **`hermes-agent`** — the core runtime (47 built-in tools, 15+ messaging platforms, 6 deployment backends) - **[[entities/hermes-self-evolution]]** (`hermes-agent-self-evolution`, 893 stars) — DSPy + GEPA evolutionary self-improvement pipeline - **[[entities/hermes-paperclip-adapter]]** (741 stars) — run Hermes as a managed employee inside a Paperclip company - **[[entities/autonovel]]** (467 stars) — autonomous novel-writing pipeline that generates 100k+ word manuscripts end-to-end - **`tinker-atropos`** — standalone Atropos integration with Thinking Machines' Tinker API; RL training infra for fine-tuning tool-calling models on real agent trajectories ## How to Use To engage with Nous Research as an ecosystem: 1. **Run Hermes Agent** — `pip install hermes-agent` 2. **Join the Discord** — bug reports, feature requests, ecosystem discussion 3. **Follow releases** — <https://github.com/NousResearch/hermes-agent/releases>; new release every few days 4. **Contribute upstream** — recent community contributors include @teknium1, @kshitijk4poor, @winglian, @binhnt92, @0xbyt4, @erosika, @pefontana, @SHL0MS, @alt-glitch, @nils010485 ## Related Entities - [[entities/version-v0.6.0]], [[entities/version-v0.7.0]], [[entities/version-v0.8.0]] - [[entities/hermes-self-evolution]], [[entities/hermes-paperclip-adapter]], [[entities/autonovel]] - [[entities/memory-honcho]] — recommended memory backend - [[concepts/self-improvement-loop]], [[concepts/skills-system]] <!-- ===== hermes/wiki/entities/openclaw.md ===== --> --- title: "OpenClaw" type: entity tags: [vs-openclaw, gateway, platform, foundational, well-established] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/transcript-switching-to-hermes.txt", "raw/transcript-did-hermes-kill-openclaw.txt", "raw/transcript-biggest-problem-openclaw.txt", "raw/migration-openclaw-official.md", "raw/docs-guides-migrate-from-openclaw.md", "raw/awesome-hermes-agent-readme.md", "raw/release-v0.12.0.md"] confidence: medium hermes_version: "v0.12.0" --- ## Overview **OpenClaw** is the open-source AI agent harness that Hermes Agent is most often compared against and migrated from. Built by **Peter Steinberger** as a weekend side project in 2025, it went from zero to **300,000+ GitHub stars in about 4 months** — beating React's all-time star record in 60 days — and Jensen Huang called it "probably the most important release of software ever" (per the Switching-to-Hermes transcript; treat the precise figures as community-video claims). Steinberger **joined OpenAI in February** (widely described as an acqui-hire), the project moved to an **independent foundation**, and Nvidia provides substantial development resources. Release cadence is daily to "every few hours." Architecturally, OpenClaw is a **TypeScript messaging-gateway control plane**: one agent routed across every platform in your life. Its bet is breadth and ecosystem; Hermes's bet is the learning loop. This page covers OpenClaw itself — for the head-to-head see [[syntheses/hermes-vs-openclaw]], and for moving off it see [[concepts/migration-from-openclaw]]. ## Characteristics - **Language:** TypeScript (Hermes: Python) - **Scale (community-video figures, medium confidence):** 300k+ GitHub stars, ~2 million monthly active users, **~13,000 community skills on ClawHub** - **Platforms:** ~24 messaging/integration platforms — WhatsApp, Telegram, iMessage (BlueBubbles), Teams, Discord, Slack, Signal, Google Chat, Line, Matrix, IRC, WeChat, and more (vs. Hermes's 12 — see [[concepts/messaging-gateway]]) - **Governance:** independent foundation; creator at OpenAI; Nvidia engineering investment - **Architecture vs. Hermes:** stateless per-session loop — no trajectory capture, no RL training pipeline, skills are human-maintained (installed/configured/updated by you). Memory works through plugins (file-backed memory, LanceDB vector search, "lossless Claw" full-conversation persistence), each installed and configured separately — contrast [[concepts/memory-system]] - **Open models:** maintainers explicitly do **not** recommend open models — the single sharpest philosophical split with [[entities/nous-research]] - **Lineage:** previously named **Clawdbot** and **Moltbot** — Hermes migration tooling still probes `~/.clawdbot/`, `~/.moltbot/`, `clawdbot.json`, `moltbot.json` (official migration docs, high confidence) - **On-disk layout (per official Hermes migration docs):** `~/.openclaw/` with `openclaw.json` config; workspace files `SOUL.md`, `MEMORY.md`, `USER.md`, `AGENTS.md`, `IDENTITY.md`, `TOOLS.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` under `workspace/` (renamed `workspace-main/` in recent versions, `workspace-{agentId}` for multi-agent) ## How to Use For this KB's audience the relevant workflows are migration and coexistence, not OpenClaw setup: 1. **Migrate to Hermes:** `hermes claw migrate` (preview-first; `--dry-run` to inspect). Auto-offered during `hermes setup` when `~/.openclaw/` is detected. Import was hardened in v0.12.0 (plan-first apply, redaction, pre-migration backup — see [[entities/version-v0.12.0]]). Full mechanics in [[concepts/migration-from-openclaw]]; CLI surface in [[concepts/cli-reference]]. 2. **Run side-by-side:** the dominant practitioner pattern — OpenClaw as orchestrator/IDE-side agent, Hermes as the always-on learning agent, connected via ACP; cut over once cron and routing behavior match ([[syntheses/hermes-vs-openclaw]]). 3. **Mix in a Paperclip hierarchy:** e.g., OpenClaw as CEO with Hermes workers via the [[entities/hermes-paperclip-adapter]]. ## Related Entities - [[syntheses/hermes-vs-openclaw]] — full architectural, feature, and ecosystem comparison - [[concepts/migration-from-openclaw]] — the migration command in depth - [[concepts/messaging-gateway]], [[concepts/memory-system]] — the two subsystems where designs diverge most - [[entities/nous-research]] — the rival lab and its open-model thesis - [[entities/hermes-paperclip-adapter]] — mixed OpenClaw/Hermes hierarchies - [[entities/version-v0.12.0]] — hardened OpenClaw import <!-- ===== hermes/wiki/entities/platform-dingtalk.md ===== --> --- title: "DingTalk Platform" type: entity tags: [platform, dingtalk, gateway, intermediate, well-established] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-dingtalk.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.9.0.md", "raw/release-v0.11.0.md", "raw/release-v0.13.0.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **DingTalk** (钉钉) connects Hermes to Alibaba's enterprise messenger as a chatbot for DMs and group chats. The adapter uses DingTalk's **Stream Mode** — a long-lived outbound WebSocket — so no public URL, domain, or webhook server is needed; it works behind NAT and firewalls. Replies are markdown-formatted and delivered through DingTalk's session webhook API, which caps messages at **20,000 characters**. v0.11.0 added `require_mention` + `allowed_users` gating (parity with Slack/Telegram/Discord) and QR-code device-flow authorization in the setup wizard; v0.13.0 added `allowed_chats` allowlists. ## Characteristics - **Prerequisites:** `pip install "hermes-agent[dingtalk]"` — pulls in `dingtalk-stream` (official Stream Mode SDK), `httpx` (async replies), and `alibabacloud-dingtalk` (OpenAPI SDK for AI Cards, emoji reactions, media downloads). - **App creation:** DingTalk Developer Console → Application Development → Custom Apps → create app → copy **Client ID** (AppKey) and **Client Secret** (AppSecret) from Credentials & Basic Info. The secret is shown only once. - **Robot capability:** enable **Robot** under Add Capability and select **Stream Mode** as the Message Reception Mode. - **Env vars:** `DINGTALK_CLIENT_ID`, `DINGTALK_CLIENT_SECRET` (required); `DINGTALK_ALLOWED_USERS=user-id-1,user-id-2` (default deny without it). Optional gating: `DINGTALK_REQUIRE_MENTION`, `DINGTALK_FREE_RESPONSE_CHATS`, `DINGTALK_MENTION_PATTERNS` (regex, e.g. `^小马`), `DINGTALK_HOME_CHANNEL`, `DINGTALK_ALLOW_ALL_USERS`. `dingtalk.extra.allowed_users` in `config.yaml` merges with the env allowlist. - **Finding user IDs:** ask your org admin (Contacts → Members), or send the bot a message and read the logged `sender_id`. - **Behavior:** DMs answered without mention; group chats require `@mention`; per-user session isolation in groups (`group_sessions_per_user: true` default). - **Reliability:** auto-reconnect with exponential backoff (2s → 5s → 10s → 30s → 60s); 5-minute message deduplication window. - **AI Cards:** set `platforms.dingtalk.extra.card_template_id` to reply with rich AI Cards instead of plain markdown — supports streaming text updates as the agent generates. - **Status reactions & media:** automatic 🤔Thinking/🥳Done emoji reactions in DMs and groups; inbound images/files are resolved automatically for vision/file tools. - **Reply constraint:** each inbound message provides a fresh session webhook — the bot can only reply to recently received messages ("No session_webhook available" means send a new message). - **Security hardening:** webhook URL origin validation and header-injection rejection (added in v0.9.0); `allowed_chats` allowlist (added in v0.13.0). - **Toolset:** `hermes-dingtalk` — full tools including terminal. ## How to Use 1. Install dependencies: ```bash pip install "hermes-agent[dingtalk]" # or: pip install dingtalk-stream httpx alibabacloud-dingtalk ``` 2. Create the app in the DingTalk Developer Console, enable the Robot capability with Stream Mode, and copy Client ID/Secret. 3. Configure — `hermes gateway setup` (select **DingTalk**; QR device-flow authorization added in v0.11.0 — note the consent screen currently shows an `openClaw` source string because DingTalk's API hardcodes that identity; the bot is still fully yours), or add to `~/.hermes/.env`: ``` DINGTALK_CLIENT_ID=your-app-key DINGTALK_CLIENT_SECRET=your-app-secret DINGTALK_ALLOWED_USERS=user-id-1 ``` 4. Start the gateway: ```bash hermes gateway ``` 5. DM the bot or `@mention` it in a group where it has been added. If the bot is silent, verify the Robot capability + Stream Mode are enabled and your User ID is in `DINGTALK_ALLOWED_USERS`, then restart the gateway. ## Related Entities - [[entities/platform-feishu]], [[entities/platform-wecom]] — sibling Chinese-ecosystem enterprise platforms (all use outbound WebSocket, NAT-friendly) - [[entities/platform-mattermost]] — sibling team-chat platform - [[concepts/messaging-gateway]] — gateway core, default-deny access control - [[entities/version-v0.11.0]] — `require_mention`/`allowed_users` gating + QR setup wizard - [[entities/version-v0.13.0]] — `allowed_chats` allowlist <!-- ===== hermes/wiki/entities/platform-discord.md ===== --> --- title: "Discord Platform" type: entity tags: [platform, discord, gateway, intermediate] created: 2026-04-12 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-discord.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.8.0.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **Discord** is the second-most-popular Hermes gateway platform and the natural choice for community-facing or team-facing bots — multi-user channels with per-user session isolation, skills that auto-register as native slash commands, voice-channel conversations, and proactive messages into a designated home channel. Messages flow through the full gateway pipeline (authorization → mention/free-response checks → session lookup → agent execution), not a stateless webhook. v0.8.0 added per-channel ignored-channels controls and the `/model` picker. ## Characteristics - **Setup:** create application at Discord Developer Portal → Bot tab → Reset Token. **Must enable: Server Members Intent + Message Content Intent** (a bot that's online but never responds almost always has Message Content Intent off). Set `DISCORD_BOT_TOKEN`. - **Invite URL:** scopes `bot` + `applications.commands`; permissions integer `274878286912` (recommended) or `117760` (minimal). The Installation-tab invite link requires Public Bot = ON; private bots must use the manual URL. - **Access control:** `DISCORD_ALLOWED_USERS` (IDs via Developer Mode → Copy User ID) and/or `DISCORD_ALLOWED_ROLES` (OR semantics; auto-enables Members intent; role-holders in any mutual guild are authorized in DMs too — ideal for churning mod teams). Admin/user slash-command split via `allow_admin_from` + `user_allowed_commands` under `gateway.platforms.discord.extra` (`/help`, `/whoami` always allowed). - **Mention gating:** `DISCORD_REQUIRE_MENTION=true` (default; DMs always answered); `DISCORD_IGNORE_NO_MENTION=true` (default) keeps the bot out of conversations @mentioning other people; `DISCORD_ALLOW_BOTS=none|mentions|all` (default `none`) for bot-to-bot traffic. - **Channel controls:** `DISCORD_FREE_RESPONSE_CHANNELS` (mention-free, replies inline and skips auto-threading), `DISCORD_IGNORED_CHANNELS` (never respond — highest priority), `DISCORD_ALLOWED_CHANNELS` (respond only here), `DISCORD_NO_THREAD_CHANNELS`, `DISCORD_AUTO_THREAD=true` (default: every channel @mention spawns an isolated thread; in-thread follow-ups need no mention — set `DISCORD_THREAD_REQUIRE_MENTION=true` in multi-bot threads). Per-channel ephemeral prompts via `discord.channel_prompts` (thread falls back to parent-channel entry). - **History backfill:** on each @mention the bot prepends channel scrollback since its last response (`DISCORD_HISTORY_BACKFILL=true` default, scan cap `DISCORD_HISTORY_BACKFILL_LIMIT=50`; skipped in DMs and free-response channels) — recovers context that mention gating would otherwise hide. - **Slash commands:** every installed skill auto-registers as a Discord Application Command (100/bot cap; extras skipped with a warning). `DISCORD_COMMAND_SYNC_POLICY=safe|bulk|off` controls startup sync; set `extra.slash_commands: false` on follower gateways sharing one Discord app so registrations don't flap. - **Media out:** `MEDIA:` tags / `send_message` deliver native attachments (`send_animation` for inline-playing GIFs, `send_video`, `send_voice`, `send_document`); upload limit follows server boost tier (25 MB free → 500 MB); HTTP 413 falls back to a local-cache link. - **Media in:** built-in allowlist (images/audio/video/PDF/text/office/zip; `.txt`/`.md`/`.log` auto-injected up to 100 KiB); `discord.allow_any_attachment: true` accepts arbitrary file types as cached paths (`application/octet-stream`, path-only — context window safe), size-capped by `max_attachment_bytes` (default 32 MiB). - **Voice:** incoming voice messages transcribed (faster-whisper / Groq / OpenAI); `/voice tts` for spoken replies; the bot can join voice channels, listen, and talk back. Optional `discord.voice_fx` (off by default) adds Grok-style verbal acknowledgements and a ducked ambient "thinking" bed via a software audio mixer. - **Forum channels:** auto-detected; every send creates a thread post (name from first message line, attachments ride the starter message) — no special agent handling needed. - **Reactions:** 👀 / ✅ / ❌ processing feedback, **on by default** (`DISCORD_REACTIONS=false` to disable; additive, unlike Telegram's replace-all). - **Mention safety:** the bot is blocked from pinging `@everyone`/`@here` and `@role` by default (`discord.allow_mentions` / `DISCORD_ALLOW_MENTION_*`); individual `@user` and reply-reference pings stay on. - **Model picker:** `/model` opens a dropdown picker (providers → models, 25 each, 120 s timeout; added in v0.8.0). `clarify` prompts render one button per choice (timeout `agent.clarify_timeout`, default 600 s). - **Proactive messages:** `DISCORD_HOME_CHANNEL` (+ `DISCORD_HOME_CHANNEL_NAME`) or `/sethome`. `DISCORD_PROXY` overrides generic proxy env vars (`http`/`https`/`socks5`). ## How to Use 1. Discord Developer Portal → New Application → Bot tab → Reset Token → copy. 2. Enable both Privileged Gateway Intents (Server Members + Message Content). 3. Use the OAuth2 URL Generator (scopes `bot` + `applications.commands`, permissions `274878286912`) to invite the bot. 4. Add to `~/.hermes/.env`: ``` DISCORD_BOT_TOKEN=MTE... DISCORD_ALLOWED_USERS=123456789012345678 ``` 5. Start the gateway: ```bash hermes gateway start ``` 6. In any channel where the bot is invited, mention it: `@Hermes summarize today's news`. If users in a shared channel unexpectedly share context, check `group_sessions_per_user: true` (the default per-user isolation) in `config.yaml`. ## Related Entities - [[entities/platform-telegram]], [[entities/platform-slack]] — sibling gateway platforms - [[concepts/messaging-gateway]] - [[concepts/skills-system]] — skills auto-register as Discord slash commands - [[entities/version-v0.8.0]] — channel-control and `/model` improvements <!-- ===== hermes/wiki/entities/platform-email.md ===== --> --- title: "Email Platform" type: entity tags: [platform, email, gateway, beginner, well-established] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-email.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.12.0.md", "raw/release-v0.13.0.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **Email** turns Hermes into an agent you can simply email: it polls an IMAP inbox for new mail and replies in-thread via SMTP. No bot API, no special client — works with Gmail, Outlook, Yahoo, Fastmail, or any IMAP/SMTP provider. The adapter uses only Python's built-in `imaplib`, `smtplib`, and `email` modules (zero extra dependencies). It is distinct from the bundled **Himalaya email skill** (agent manages a mailbox via the external `himalaya` CLI) — the gateway adapter is for *people emailing the agent*. Use a dedicated account, not your personal one: the agent stores the password in `.env` and has full inbox access. v0.12.0 added native multi-image sending; v0.13.0 made `/sethome` persist across restarts. ## Characteristics - **Setup:** dedicated account + IMAP enabled + app password (required for Gmail/Outlook with 2FA). Gmail: `imap.gmail.com` / `smtp.gmail.com`; Outlook: `outlook.office365.com` / `smtp.office365.com`. - **Env vars:** `EMAIL_ADDRESS`, `EMAIL_PASSWORD` (app password), `EMAIL_IMAP_HOST`, `EMAIL_SMTP_HOST` required; optional `EMAIL_IMAP_PORT=993` (SSL), `EMAIL_SMTP_PORT=587` (STARTTLS), `EMAIL_POLL_INTERVAL=15`, `EMAIL_ALLOWED_USERS`, `EMAIL_HOME_ADDRESS` (cron delivery target), `EMAIL_ALLOW_ALL_USERS=false` default. - **Polling:** checks for UNSEEN messages every 15 s by default (lower via `EMAIL_POLL_INTERVAL=5` at the cost of more IMAP connections). On startup it marks existing inbox mail as seen — only new mail is processed. - **Context handling:** subject line injected as `[Subject: ...]` (skipped on `Re:` replies); HTML-only mail stripped to plain text; self-messages filtered to prevent loops; automated senders (`noreply@`, `no-reply@`, `mailer-daemon@`, `bounce@`, `Auto-Submitted`, `Precedence: bulk`, `List-Unsubscribe`) silently ignored. - **Threading:** replies carry **In-Reply-To** and **References** headers, preserve subject with a single `Re:` prefix, and send as plain-text UTF-8. - **Attachments:** inbound images (JPEG/PNG/GIF/WebP) cached for the vision tool, documents (PDF/ZIP) cached for file access; outbound files attached via `MEDIA:/path/to/file` in the response. Native multi-image sending (added in v0.12.0). Set `platforms.email.skip_attachments: true` in `config.yaml` to ignore all incoming attachments (malware/bandwidth protection). - **Access control:** `EMAIL_ALLOWED_USERS` is critical — without it, anyone who knows the address could command an agent that has terminal access. Unknown senders get a pairing code by default. - **Toolset:** `hermes-email` — full tools including terminal. ## How to Use 1. Create a dedicated email account, enable IMAP, and generate an app password (Gmail: 2FA → App Passwords → "Mail"). 2. Configure — `hermes gateway setup` (select **Email**), or add to `~/.hermes/.env`: ``` EMAIL_ADDRESS=hermes@gmail.com EMAIL_PASSWORD=abcd efgh ijkl mnop # App password, not your real password EMAIL_IMAP_HOST=imap.gmail.com EMAIL_SMTP_HOST=smtp.gmail.com EMAIL_ALLOWED_USERS=your@email.com,colleague@work.com ``` 3. Start the gateway: ```bash hermes gateway # Foreground hermes gateway install # User service ``` 4. Email the agent's address; the reply arrives in the same thread. Protect `~/.hermes/.env` (`chmod 600`). "Authentication failed" on Gmail almost always means a regular password was used instead of an app password. Duplicate replies mean two gateway instances are running (`hermes gateway status`). ## Related Entities - [[entities/platform-telegram]], [[entities/platform-matrix]] — sibling gateway platforms with richer real-time features - [[concepts/messaging-gateway]] — gateway core, polling and session handling - [[entities/version-v0.12.0]] — native multi-image sending - [[entities/version-v0.13.0]] — `/sethome` persistence across restarts - [[concepts/cron-scheduling]] — `EMAIL_HOME_ADDRESS` as cron delivery target <!-- ===== hermes/wiki/entities/platform-feishu.md ===== --> --- title: "Feishu / Lark Platform" type: entity tags: [platform, feishu, gateway, intermediate, advanced, well-established] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-feishu.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.6.0.md", "raw/release-v0.9.0.md", "raw/release-v0.11.0.md", "raw/release-v0.13.0.md", "raw/release-v0.14.0.md", "raw/release-v0.15.0.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **Feishu / Lark** (飞书 in China, Lark internationally) is one of the most fully featured Hermes platforms: interactive approval cards, rich markdown posts, media in both directions, emoji-reaction state feedback, and per-group access policies. Platform support landed in v0.6.0; v0.9.0 added the standout **scan-to-create** onboarding — `hermes gateway setup` shows a QR code and auto-creates the bot app with correct permissions. Two connection modes: `websocket` (recommended, outbound connection, no public URL) and `webhook` (HTTP push with signature verification). ## Characteristics - **Credentials:** `FEISHU_APP_ID=cli_xxx`, `FEISHU_APP_SECRET=secret_xxx`; `FEISHU_DOMAIN=feishu` (China) or `lark` (international). Manual route: open.feishu.cn / open.larksuite.com → create app → enable Bot capability. - **Connection modes:** `FEISHU_CONNECTION_MODE=websocket` (Lark SDK maintains a persistent outbound connection; needs `websockets` package; tune `ws_reconnect_interval` (default 120 s) / `ws_ping_interval` under `platforms.feishu.extra`) or `webhook` (`aiohttp` server at `/feishu/webhook`, tunable via `FEISHU_WEBHOOK_HOST=127.0.0.1`, `FEISHU_WEBHOOK_PORT=8765`, `FEISHU_WEBHOOK_PATH`). URL-verification challenges are answered automatically. - **Access control:** `FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy` (open_ids); `FEISHU_GROUP_POLICY=open|allowlist|disabled` (default `allowlist`); fine-grained per-group `group_rules` in `config.yaml` (`open | allowlist | blacklist | admin_only | disabled` + global `admins` list, plus `default_group_policy` fallback). Groups require an `@mention` by default — disable globally with `FEISHU_REQUIRE_MENTION=false` or per-chat with `require_mention: false` on a `group_rules` entry; DMs bypass the gate. - **Bot-to-bot:** other bots' messages are ignored by default; `FEISHU_ALLOW_BOTS=none|mentions|all` (default `none`) opts into A2A orchestration — peer bots bypass the human allowlist; grant `application:bot.basic_info:read` to show peer bot names. - **Meeting invitations:** invite the bot to a Feishu/Lark video meeting like a human participant — the `vc.bot.meeting_invited_v1` event hands the agent the meeting number and it attempts to auto-join, provided the inviter passes normal allowlist/pairing checks. - **Webhook security:** `FEISHU_ENCRYPT_KEY` enables `SHA256(timestamp + nonce + encrypt_key + body)` signature checks against `x-lark-signature` (timing-safe); `FEISHU_VERIFICATION_TOKEN` checks the payload token — and gates URL-verification challenges too; both can be combined. Per-IP rate limiting (120 req/60 s window, HTTP 429), 1 MB body cap, 30 s read timeout, JSON-only, anomaly warning after 25 consecutive errors from one IP in 6 h. `require_webhook_auth_secret` (added in v0.15.0). - **Interactive cards / approvals:** approval prompts arrive as cards with Allow Once / Session / Always / Deny buttons; clicks route back as synthetic `/card` commands. **Three console steps are mandatory** — subscribe to `card.action.trigger`, enable the Interactive Card capability, and (webhook mode) set the Message Card Request URL — or button clicks fail with **error 200340**. - **Media:** inbound images/audio/video/files downloaded and cached (small `.txt`/`.md` content auto-injected into the message); outbound `send_image_file`, `send_document`, `send_voice`, `send_video`; markdown auto-sent as rich **post** messages with plain-text fallback. - **Feedback & batching:** processing-status reactions — `Typing` while working, cleared on reply or `CrossMark` on failure; disable with `FEISHU_REACTIONS=false` (added in v0.11.0). Text batching (0.6 s quiet period, 8 msgs / 4000 chars max, `HERMES_FEISHU_TEXT_BATCH_*` env vars) and media batching (0.8 s) with per-chat serialization; 24 h message dedup (cache size `HERMES_FEISHU_DEDUP_CACHE_SIZE=2048`) persisted to `~/.hermes/feishu_seen_message_ids.json`; card actions deduped over a 15-minute window. - **Bot identity for mention gating:** `FEISHU_BOT_OPEN_ID` / `FEISHU_BOT_USER_ID` / `FEISHU_BOT_NAME`, or auto-discovery with the `admin:app.info:readonly` scope. - **Home chat:** `/set-home` in a chat, or `FEISHU_HOME_CHANNEL=oc_xxx` for cron output and notifications. - **Later additions:** intelligent reply on document comments with 3-tier access control (added in v0.11.0); operator-configurable bot admission + mention policy (added in v0.13.0); native update prompt cards (added in v0.14.0); SDK lazy-installs (added in v0.14.0). - **Toolset:** `hermes-feishu` — same core tools as Telegram and other gateway platforms. ## How to Use 1. Run the wizard and scan the QR with the Feishu/Lark mobile app (scan-to-create builds the app with correct permissions automatically): ```bash hermes gateway setup ``` 2. Or configure manually in `~/.hermes/.env`: ``` FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=secret_xxx FEISHU_DOMAIN=feishu FEISHU_CONNECTION_MODE=websocket FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy FEISHU_HOME_CHANNEL=oc_xxx ``` 3. In the Feishu Developer Console: subscribe to `card.action.trigger`, enable Interactive Card, and grant `im:message` + `im:resource` scopes for media. 4. Start the gateway and message the bot: ```bash hermes gateway ``` Common gotchas: error 200340 on card buttons (missing console config above); only one local gateway can use the same app_id; missing SDK → `pip install lark-oapi`. ## Related Entities - [[entities/platform-dingtalk]], [[entities/platform-wecom]] — sibling Chinese-ecosystem enterprise platforms - [[entities/platform-slack]] — Western counterpart with similar approval-button UX - [[concepts/messaging-gateway]] — gateway core; Feishu card approvals are one of its three native approval-button platforms - [[concepts/approval-system]] — Allow Once / Session / Always / Deny card flow - [[entities/version-v0.6.0]] — Feishu/Lark platform support added - [[entities/version-v0.9.0]] — QR scan-to-create onboarding added <!-- ===== hermes/wiki/entities/platform-home-assistant.md ===== --> --- title: "Home Assistant Platform" type: entity tags: [platform, gateway, tools, intermediate, well-established] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-homeassistant.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **Home Assistant** is the odd one out among gateway platforms: instead of a chat app, it wires Hermes into your smart home. The integration works two ways at once — as a **gateway platform** that subscribes to real-time `state_changed` events over WebSocket (so the agent can *react* to your house), and as a **smart home toolset** of four LLM-callable tools (`ha_list_entities`, `ha_get_state`, `ha_list_services`, `ha_call_service`) that query and control devices via the REST API. Both activate from a single Long-Lived Access Token. ## Characteristics - **Setup:** HA Profile → Long-Lived Access Tokens → Create Token → `HASS_TOKEN` in `.env`; optional `HASS_URL` (default `http://homeassistant.local:8123`). The `homeassistant` toolset auto-enables when `HASS_TOKEN` is set. - **Tools:** `ha_list_entities` (filter by `domain`/`area`), `ha_get_state` (full attributes of one `entity_id`), `ha_list_services` (available actions per domain), `ha_call_service` (e.g. `ha_call_service(domain="light", service="turn_on", entity_id="light.living_room", data={"brightness": 128, "color_name": "blue"})`). - **Event filtering (required):** by default **no events are forwarded** — you must set at least one of `watch_domains`, `watch_entities`, or `watch_all: true` under `platforms.homeassistant.extra` in `config.yaml`. `ignore_entities` suppresses noisy sensors; `cooldown_seconds: 30` rate-limits per entity. Start with `climate`, `binary_sensor`, `alarm_control_panel`. - **Event formatting:** domain-aware human-readable messages, e.g. climate → "HVAC mode changed from 'off' to 'heat' (current: 21, target: 23)", binary_sensor → "triggered"/"cleared". - **Outbound:** agent replies arrive as HA **persistent notifications** (`persistent_notification.create`) titled "Hermes Agent" — there is no chat thread, voice, or attachment support on this platform. - **Connection:** WebSocket with 30 s heartbeat, auto-reconnect backoff 5s → 10s → 30s → 60s; separate REST session for notifications. No user allowlist needed — the `HASS_TOKEN` itself authorizes the connection. - **Security:** service domains `shell_command`, `command_line`, `python_script`, `pyscript`, `hassio`, and `rest_command` are **blocked** to prevent arbitrary code execution / SSRF on the HA host. Entity IDs validated against `^[a-z_][a-z0-9_]*\.[a-z0-9_]+$`. - **Toolset:** `hermes-homeassistant` — full tools plus the four HA device-control tools. ## How to Use 1. In Home Assistant, create a Long-Lived Access Token (Profile → Long-Lived Access Tokens → Create Token, name it "Hermes Agent"). 2. Add to `~/.hermes/.env`: ``` HASS_TOKEN=your-long-lived-access-token HASS_URL=http://192.168.1.100:8123 ``` 3. Configure event filters in `~/.hermes/config.yaml` (otherwise all state changes are silently dropped): ```yaml platforms: homeassistant: enabled: true extra: watch_domains: - climate - binary_sensor - alarm_control_panel ignore_entities: - sensor.uptime cooldown_seconds: 30 ``` 4. Start the gateway: ```bash hermes gateway ``` 5. Test from any chat platform: "List all lights in the living room" or "Set the thermostat to 22 degrees in heat mode". Reactive automation pattern: a `binary_sensor.front_door` "triggered" event reaches the agent, which calls `ha_get_state`, turns on `light.hallway` via `ha_call_service`, and notifies you. Troubleshooting: a `conversation entity not found` error means HA's Assist conversation agent isn't configured — add one under Settings → Voice assistants and set its entity ID in the adapter's `conversation_entity` setting (the default may not exist on your instance). A `401 Unauthorized` means a short-lived UI session token was used instead of a Long-Lived Access Token; verify with `curl -H "Authorization: Bearer <token>" <url>/api/` (expect `{"message": "API running."}`). Env changes apply only on gateway restart. ## Related Entities - [[entities/platform-telegram]], [[entities/platform-matrix]] — pair one of these with Home Assistant for voice control and alert delivery - [[concepts/messaging-gateway]] — gateway core; HA is one of its WebSocket adapters - [[concepts/cron-scheduling]] — combine scheduled jobs with HA tools for time-based automations - [[concepts/configuration-reference]] — `platforms.*.extra` config conventions <!-- ===== hermes/wiki/entities/platform-matrix.md ===== --> --- title: "Matrix Platform" type: entity tags: [platform, matrix, gateway, intermediate, advanced, well-established] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-matrix.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.8.0.md", "raw/release-v0.9.0.md", "raw/release-v0.13.0.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **Matrix** is the open, federated protocol option — run your own homeserver (Synapse, Conduit, Dendrite) or use matrix.org, and keep control of your communications. Hermes connects via the **mautrix** Python SDK (migrated from matrix-nio in v0.9.0, with a SQLite crypto store replacing pickle) and supports text, images, audio, video, file attachments, threads (MSC3440), native voice bubbles (MSC3245), and optional **end-to-end encryption**. Matrix reached "Tier 1" in v0.8.0: reactions, read receipts, rich formatting, and room management. v0.13.0 added `allowed_rooms` allowlists and persistent `/sethome`. ## Characteristics - **Auth:** `MATRIX_HOMESERVER=https://matrix.example.org` plus either `MATRIX_ACCESS_TOKEN` (recommended — grab it from Element Settings → Help & About → Advanced, or via the `/_matrix/client/v3/login` API) or `MATRIX_USER_ID` + `MATRIX_PASSWORD`. - **Access control:** `MATRIX_ALLOWED_USERS=@alice:matrix.org` (full `@user:server` format, comma-separated; federated users work too). Default deny without it. - **Behavior:** DMs always answered; rooms require `@mention` by default (`MATRIX_REQUIRE_MENTION=true`); exemptions via `MATRIX_FREE_RESPONSE_ROOMS=!abc123:matrix.org`; threads the bot has already joined need no mention. Auto-threads per response (`MATRIX_AUTO_THREAD=true` default); `MATRIX_DM_MENTION_THREADS=false` and `MATRIX_DM_AUTO_THREAD=false` defaults. Processing-lifecycle emoji reactions (👀/✅/❌) on by default — disable with `MATRIX_REACTIONS=false`. Room invites are auto-accepted — the bot joins and responds immediately. - **Room allowlist:** `matrix.allowed_rooms` in `config.yaml` or `MATRIX_ALLOWED_ROOMS` (comma-separated internal `!id:server` IDs, not aliases) restricts the bot to listed rooms — checked before mention/sender gating; DMs are exempt (added in v0.13.0). - **Commands:** full gateway command set works; clients that reserve `/` can use `!` aliases (`!model`, `!stop`, …) — Hermes normalizes only known commands, ordinary `!text` stays chat. - **Session isolation:** each DM, each thread, and each user inside a shared room gets its own session (`group_sessions_per_user: true` default; set `false` for one shared room transcript at the cost of shared context growth and interruptions). - **E2EE:** `MATRIX_ENCRYPTION=true` + `pip install 'mautrix[encryption]'` (or `pip install 'hermes-agent[matrix]'`) + system `libolm` (`sudo apt install libolm-dev` / `brew install libolm`). Keys stored in `~/.hermes/platforms/matrix/store/` — back it up; deleting it loses encryption identity. Falls back to a plain client automatically if extras are missing. - **Cross-signing:** set `MATRIX_RECOVERY_KEY=EsT...` (Element Settings → Security & Privacy → Encryption) so the bot self-signs its device on startup — idempotent, safe to leave enabled. Added with the E2EE migration work in v0.9.0. - **Home room:** `/sethome` in any room, or `MATRIX_HOME_ROOM=!abc123def456:matrix.example.org` (persists across restarts since v0.13.0). - **Voice:** outgoing TTS tagged `org.matrix.msc3245.voice` → renders as native voice bubbles in Element; incoming MSC3245 voice routed to STT automatically. - **Proxy mode (E2EE on macOS):** `libolm` doesn't build on Apple Silicon, so the `hermes-agent[matrix]` extra is Linux-only. Run a thin Matrix-only gateway in a Linux Docker container with `GATEWAY_PROXY_URL`/`GATEWAY_PROXY_KEY` pointing at the host's API server (`API_SERVER_ENABLED=true`, port 8642) — the container handles E2EE, the host runs the agent. Works for any platform adapter, not just Matrix; v1 limitation: tool progress and approval prompts aren't relayed. - **Reliability:** sync loop retries every 5 s on error. Inbound text batching with adaptive delay (added in v0.9.0). Known failure mode: a host clock set ahead of real time trips the 5-second startup-grace filter and the bot silently drops every live event — fix with NTP sync (log line: `dropped N live events as 'too old'`). - **Toolset:** `hermes-matrix` — full tools including terminal. ## How to Use 1. Create a bot account (own homeserver: `register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008`; or register on matrix.org via Element). 2. Get an access token (Element → Settings → Help & About → Advanced, or password login API). 3. Configure — `hermes gateway setup` (select **Matrix**), or add to `~/.hermes/.env`: ``` MATRIX_HOMESERVER=https://matrix.example.org MATRIX_ACCESS_TOKEN=*** MATRIX_ALLOWED_USERS=@alice:matrix.example.org # Optional E2EE: # MATRIX_ENCRYPTION=true # MATRIX_RECOVERY_KEY=EsT... ``` 4. Start the gateway and invite the bot to a room (it auto-joins): ```bash hermes gateway ``` Token validity check: `curl -H "Authorization: Bearer YOUR_TOKEN" https://your-server/_matrix/client/v3/account/whoami`. If upgrading an old E2EE install to the SQLite crypto store, you need a one-time migration: new access token (fresh device ID), delete `~/.hermes/platforms/matrix/store/crypto.db`, set `MATRIX_RECOVERY_KEY`, and `/discardsession` in Element. ## Related Entities - [[entities/platform-signal]], [[entities/platform-mattermost]] — sibling self-host-friendly gateway platforms - [[concepts/messaging-gateway]] — gateway core; Matrix inbound text batching - [[entities/version-v0.8.0]] — Matrix Tier 1 (reactions, read receipts, rich formatting, room management) - [[entities/version-v0.9.0]] — mautrix migration + SQLite crypto store + recovery-key verification - [[entities/version-v0.13.0]] — `allowed_rooms` allowlist, persistent `/sethome` - [[concepts/cron-scheduling]] — home room receives cron output <!-- ===== hermes/wiki/entities/platform-mattermost.md ===== --> --- title: "Mattermost Platform" type: entity tags: [platform, mattermost, gateway, intermediate, well-established] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-mattermost.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.8.0.md", "raw/release-v0.12.0.md", "raw/release-v0.13.0.md", "raw/release-v0.15.0.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **Mattermost** is the self-hosted, open-source Slack alternative — the natural Hermes platform for teams who keep chat on their own infrastructure. The adapter speaks Mattermost's **REST API v4** for actions and **WebSocket** for real-time events, with no extra dependency beyond `aiohttp` (already shipped with Hermes). Works with Team Edition (free) and Enterprise Edition; no Mattermost Cloud subscription required. File attachments arrived in v0.8.0, native multi-image sending in v0.12.0, and in v0.15.0 the adapter migrated to a bundled plugin. ## Characteristics - **Setup:** System Console → Integrations → Bot Accounts → enable creation → Add Bot Account (`hermes`, role Member) → copy the **bot token** (shown once). A personal access token works too if you want Hermes posting as your own user. - **Env vars:** `MATTERMOST_URL=https://mm.example.com`, `MATTERMOST_TOKEN`, `MATTERMOST_ALLOWED_USERS` (26-character User IDs — *not* `@usernames`; copy from Profile dialog or `curl -H "Authorization: Bearer YOUR_TOKEN" https://your-mattermost-server/api/v4/users/me | jq .id`). - **Behavior:** DMs always answered; channels require `@mention` (`MATTERMOST_REQUIRE_MENTION=true` default, mention auto-stripped); `MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2` exempts specific channels; per-user session isolation in shared channels (`group_sessions_per_user: true` default). - **Reply mode:** `MATTERMOST_REPLY_MODE=thread` nests replies under the originating message (default `off` = flat channel messages). Thread context stays isolated. - **Home channel:** `/sethome` in any channel, or `MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn` (channel name → View Info for the ID) — receives cron output and proactive messages. - **Channel membership:** the bot must be added to every channel where it should respond (channel name → Add Members). - **Reliability:** WebSocket auto-reconnect with exponential backoff (2 s → 60 s). Reverse proxies need WebSocket upgrade headers (nginx: `proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";` on `/api/v4/websocket`). - **Channel allowlist:** `mattermost.allowed_channels` in `config.yaml` or `MATTERMOST_ALLOWED_CHANNELS` (comma-separated channel IDs) restricts the bot to listed channels — checked before mention gating; DMs are exempt (added in v0.13.0). - **Per-channel prompts:** `mattermost.channel_prompts` maps channel IDs to ephemeral system prompts injected at runtime every turn, never persisted to transcript history (added in v0.11.0). - **Later additions:** file attachments (added in v0.8.0); native multi-image sending (added in v0.12.0); bundled-plugin migration (added in v0.15.0). - **Toolset:** `hermes-mattermost` — full tools including terminal. ## How to Use 1. As System Admin: System Console → Integrations → Bot Accounts → **Enable Bot Account Creation** → true. 2. ☰ menu → Integrations → Bot Accounts → **Add Bot Account** → copy the token immediately. 3. Add the bot to the channels where it should respond. 4. Configure — `hermes gateway setup` (select **Mattermost**), or add to `~/.hermes/.env`: ``` MATTERMOST_URL=https://mm.example.com MATTERMOST_TOKEN=*** MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c # Optional: # MATTERMOST_REPLY_MODE=thread # MATTERMOST_REQUIRE_MENTION=false ``` 5. Start the gateway: ```bash hermes gateway ``` 6. DM the bot, or `@mention` it in a channel. 403 errors mean a bad/deactivated token or the bot isn't in the channel. Verify the token with `curl -H "Authorization: Bearer YOUR_TOKEN" https://your-server/api/v4/users/me`. ## Related Entities - [[entities/platform-slack]], [[entities/platform-matrix]] — sibling team-chat platforms (hosted vs federated) - [[entities/platform-dingtalk]] — sibling enterprise platform - [[concepts/messaging-gateway]] — gateway core, session reset, default-deny - [[entities/version-v0.8.0]] — file attachments added - [[entities/version-v0.13.0]] — `allowed_channels` allowlist - [[concepts/cron-scheduling]] — home channel receives cron output <!-- ===== hermes/wiki/entities/platform-signal.md ===== --> --- title: "Signal Platform" type: entity tags: [platform, signal, gateway, intermediate, well-established] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-signal.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.8.0.md", "raw/release-v0.11.0.md", "raw/release-v0.12.0.md", "raw/release-v0.15.0.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **Signal** is the privacy-focused option among Hermes gateway platforms — end-to-end encrypted by default, open-source protocol, minimal metadata. Hermes connects through the **signal-cli** daemon running in HTTP mode: messages stream in via SSE and replies go out via JSON-RPC. signal-cli acts as a *linked secondary device* (like WhatsApp Web), so your phone stays primary. The adapter needs no new Python packages (it uses `httpx`, already a core dependency) — only signal-cli + Java 17+ installed externally. Full `MEDIA:` tag delivery arrived in v0.8.0; v0.12.0 added native formatting (markdown → bodyRanges, reply quotes, reactions) and multi-image sending. ## Characteristics - **Prerequisites:** signal-cli (Java 17+). `brew install signal-cli` on macOS; on Linux download from GitHub releases (not in apt/snap). - **Linking:** `signal-cli link -n "HermesAgent"` → scan QR via Signal **Settings → Linked Devices → Link New Device**. - **Daemon:** `signal-cli --account +1234567890 daemon --http 127.0.0.1:8080`; verify with `curl http://127.0.0.1:8080/api/v1/check`. - **Env vars:** `SIGNAL_HTTP_URL=http://127.0.0.1:8080` and `SIGNAL_ACCOUNT=+1234567890` (E.164) required; `SIGNAL_ALLOWED_USERS` (E.164 numbers or UUIDs), `SIGNAL_GROUP_ALLOWED_USERS` (group IDs, `*` for all, omit to disable groups), `SIGNAL_HOME_CHANNEL` (cron delivery target), `SIGNAL_ALLOW_ALL_USERS=false` default. - **Access control:** allowlist, or DM pairing (`hermes pairing approve signal CODE`). **Groups are disabled by default** — all group messages ignored unless `SIGNAL_GROUP_ALLOWED_USERS` is set. - **Attachments:** bidirectional, **100 MB limit**. Inbound images/audio/documents; outbound via `MEDIA:` tags → `send_multiple_images`, `send_image_file`, `send_voice`, `send_video`, `send_document` (full MEDIA: delivery added in v0.8.0; `send_message` media delivery added in v0.11.0; native multi-image added in v0.12.0). Multi-image sends are batched in groups of 32 and throttled to respect Signal's attachment-upload rate limits. - **Native formatting:** markdown (`**bold**`, `*italic*`, code, `~~strike~~`, `||spoiler||`, headings) → bodyRanges, reply quotes, reactions (added in v0.12.0); falls back to plaintext with a one-time warning if signal-cli is too old. `require_mention` option (added in v0.15.0). - **Typing indicators** refresh every 8 s while processing. Signal can't edit sent messages, so gateway tool-progress bubbles are suppressed on Signal even with `/verbose` — use the CLI (or an editing-capable platform) for live per-tool progress. - **Phone redaction:** numbers auto-redacted in all logs (`+15551234567` → `+155****4567`). - **Note to Self:** with signal-cli linked on your own number, messaging yourself reaches the agent — `syncMessage.sentMessage` envelopes are detected automatically, with echo-back protection. No extra config. - **Health monitoring:** SSE auto-reconnect with exponential backoff (2 s → 60 s); pings signal-cli after 120 s of silence. - **Toolset:** `hermes-signal` — full tools including terminal. ## How to Use 1. Install signal-cli and link your account: ```bash brew install signal-cli # macOS signal-cli link -n "HermesAgent" # scan QR from phone ``` 2. Start the daemon (keep it running via systemd/tmux): ```bash signal-cli --account +1234567890 daemon --http 127.0.0.1:8080 ``` 3. Configure — `hermes gateway setup` (select **Signal**), or add to `~/.hermes/.env`: ``` SIGNAL_HTTP_URL=http://127.0.0.1:8080 SIGNAL_ACCOUNT=+1234567890 SIGNAL_ALLOWED_USERS=+1234567890,+0987654321 ``` 4. Start the gateway: ```bash hermes gateway # Foreground hermes gateway install # User service ``` The signal-cli session data in `~/.local/share/signal-cli/` contains account credentials — protect it like a password. Duplicate messages usually mean two signal-cli instances are listening on the same number. ## Related Entities - [[entities/platform-whatsapp]], [[entities/platform-matrix]] — sibling privacy-leaning gateway platforms - [[concepts/messaging-gateway]] — gateway core, pairing, default-deny - [[entities/version-v0.8.0]] — full `MEDIA:` tag delivery added - [[entities/version-v0.12.0]] — native formatting + multi-image sending - [[concepts/cron-scheduling]] — `SIGNAL_HOME_CHANNEL` as cron delivery target <!-- ===== hermes/wiki/entities/platform-slack.md ===== --> --- title: "Slack Platform" type: entity tags: [platform, slack, gateway, intermediate, work] created: 2026-04-12 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-slack.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.6.0.md", "raw/release-v0.8.0.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **Slack** is the workplace-focused Hermes gateway platform — most useful for teams that already live in Slack, want thread-based agent conversations, or need a single Hermes instance to serve multiple workspaces. Built on the modern Bolt SDK in **Socket Mode** (WebSocket, no public URL; classic RTM apps were fully deprecated March 2025). The fastest setup is now a Hermes-generated **app manifest** (`hermes slack manifest --write`) that declares every scope, event, and slash command in one paste. Multi-workspace OAuth landed in [[entities/version-v0.6.0]]; native thread-preserving approval buttons landed in [[entities/version-v0.8.0]]. ## Characteristics - **Setup:** `hermes slack manifest --write` → api.slack.com/apps → Create New App → **From an app manifest** → paste `~/.hermes/slack-manifest.json` (or build from scratch with the scopes/events below). - **Required OAuth scopes:** `chat:write`, `app_mentions:read`, `channels:history`, `channels:read`, `groups:history`, `im:history`, `im:read`, `im:write`, `users:read`, `files:read`, `files:write` (optional: `groups:read`). Missing `channels:history`/`groups:history` = DM-only bot; missing `files:read` = can't read uploaded attachments. **Reinstall the app after any scope/event change.** - **Event subscriptions:** `message.im`, `message.channels`, `message.groups`, `app_mention` — forgetting `message.channels`/`message.groups` is the #1 "works in DMs but not channels" cause. - **Connection mode:** Socket Mode — needs an app token (`xapp-...`) with `connections:write` alongside the `xoxb-` bot token. - **Access control:** `SLACK_ALLOWED_USERS=U01ABC2DEF3,...` (Member IDs, not handles; profile → ⋮ → Copy member ID). Unauthorized DMs get a pairing code by default (`slack.unauthorized_dm_behavior: pair|ignore`). Channel allowlist via `slack.allowed_channels` / `SLACK_ALLOWED_CHANNELS` (DMs exempt; checked before all other gating). Admin/user slash-command split via `allow_admin_from` + `user_allowed_commands`. - **Slash commands:** every Hermes command (`/btw`, `/stop`, `/model`, …) is a native Slack slash command declared by the manifest — regenerate with `hermes slack manifest --write` after updates and re-paste. Legacy `/hermes <subcommand>` still routes. Slack blocks slash commands inside threads, so Hermes accepts a `!cmd` prefix (`!queue`, `!model gpt-5.4`) as a thread-safe alias — only known first tokens are treated as commands. - **Mention behavior:** channels require @mention; once the bot is active in a thread, follow-ups need no mention ("auto-engage") — set `slack.strict_mention: true` to require a fresh @mention on every channel message. Custom wake words via `slack.mention_patterns` (e.g. `"hey hermes"`); mention-free channels via `SLACK_FREE_RESPONSE_CHANNELS`. DMs always answered. - **Threading:** `reply_in_thread` (default true), `reply_broadcast` (also post to channel), `reply_to_mode` (`first` default / `off` / `all`). - **Multi-workspace:** `SLACK_BOT_TOKEN=xoxb-ws1,xoxb-ws2` comma-separated, merged with `~/.hermes/slack_tokens.json` (team-ID → token map, deduped). First token is primary and owns the Socket Mode connection; each token is `auth.test`-verified and mapped to its own client + bot user ID. A single `SLACK_APP_TOKEN` covers all. - **Per-channel customization:** `slack.channel_prompts` (ephemeral system prompts injected every turn, never persisted) and `slack.channel_skill_bindings` (auto-load skills at session start for a channel/DM — e.g. a dedicated flashcards DM; threads inherit the parent channel's binding; takes effect on `/new` or auto-reset). - **Voice:** incoming voice/audio auto-transcribed (faster-whisper / Groq / OpenAI); outgoing TTS sent as audio file attachments. - **DMs:** Messages Tab must be enabled in App Home (else "Sending messages to this app has been turned off"). - **Channel admission:** must `/invite @Hermes Agent` per channel — the bot never auto-joins. - **Home channel:** `SLACK_HOME_CHANNEL=C01234567890` (+ optional `SLACK_HOME_CHANNEL_NAME`) for cron/proactive messages; bot must be invited there. - **Approval buttons:** native, **thread-context preserving** (added in v0.8.0). ## How to Use 1. `hermes slack manifest --write`, then <https://api.slack.com/apps> → Create New App → From an app manifest → paste the JSON (handles scopes, events, and slash commands at once). 2. Settings → Install App → Install to Workspace → copy the `xoxb-` Bot User OAuth Token. 3. Socket Mode → Enable → generate the `xapp-` app-level token with `connections:write`. 4. App Home → enable the Messages Tab (and allow messages from it). 5. Add to `~/.hermes/.env`: ``` SLACK_BOT_TOKEN=xoxb-... SLACK_APP_TOKEN=xapp-... SLACK_ALLOWED_USERS=U01ABC2DEF3 ``` 6. `hermes gateway start`, then `/invite @Hermes Agent` in any channel where you want it to listen. For multiple workspaces, comma-separate `SLACK_BOT_TOKEN` or use `~/.hermes/slack_tokens.json`. If scopes or events change later, the app must be reinstalled to the workspace. ## Related Entities - [[entities/platform-telegram]], [[entities/platform-discord]] — sibling gateway platforms - [[entities/platform-mattermost]] — self-hosted Slack alternative - [[concepts/messaging-gateway]] - [[concepts/approval-system]] — Slack uses thread-preserving approval buttons - [[entities/version-v0.6.0]] — multi-workspace OAuth - [[entities/version-v0.8.0]] — native approval buttons <!-- ===== hermes/wiki/entities/platform-telegram.md ===== --> --- title: "Telegram Platform" type: entity tags: [platform, telegram, gateway, foundational, beginner] created: 2026-04-12 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-telegram.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.6.0.md", "raw/release-v0.8.0.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **Telegram** is the most-used Hermes gateway platform — it's the one shown in nearly every tutorial, the easiest to pair with a phone, and the platform with the most polished feature set (voice STT/TTS, native streaming drafts, model-picker pagination, forum topics with per-topic skill binding, ChatGPT-style multi-session DMs via `/topic`). Built on **python-telegram-bot**, it supports both long polling (default) and webhook mode (added in [[entities/version-v0.6.0]]); webhook mode enables sleep-when-idle cloud deployments because Telegram pushes inbound HTTPS instead of the gateway polling outbound. ## Characteristics - **Setup:** create bot via `/newbot` at @BotFather → grab token → set `TELEGRAM_BOT_TOKEN` in `.env`, or run `hermes gateway setup`. - **Access control:** `TELEGRAM_ALLOWED_USERS=123,456` (numeric IDs from @userinfobot — covers DMs and groups). Group-only gates: `TELEGRAM_GROUP_ALLOWED_USERS` (senders, no DM access) and `TELEGRAM_GROUP_ALLOWED_CHATS` (whole groups; negative `-100…` IDs). `TELEGRAM_GUEST_MODE=true` lets non-allowlisted groups reach the bot on explicit @mention only. Admin/user slash-command split via `allow_admin_from` + `user_allowed_commands` (`/help` and `/whoami` always allowed; inspect with `/whoami`). - **Group triggers:** `telegram.require_mention: true` in `config.yaml` plus regex wake words `mention_patterns: ["^\\s*chompy\\b"]` (case-insensitive, also matched on captions); replies to the bot and `/command@botusername` also trigger. `exclusive_bot_mentions: true` (default) keeps multi-bot groups deterministic; `ignored_threads` silences specific forum topics; `observe_unmentioned_group_messages: true` logs unmentioned chatter into the session as context without dispatching the agent. Disable BotFather Privacy Mode (or make the bot a group admin) and **remove + re-add the bot** for group delivery to work. - **Webhook mode:** `TELEGRAM_WEBHOOK_URL` plus **mandatory** `TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)` — the gateway refuses to start a webhook without the secret (security advisory GHSA-3vpc-7q5r-276h); optional `TELEGRAM_WEBHOOK_PORT=8443`. Unset URL = long polling. - **Voice in:** STT via faster-whisper (local) / Groq (`GROQ_API_KEY`) / OpenAI (`VOICE_TOOLS_OPENAI_KEY`); set `stt.enabled: false` to skip transcription and hand the agent the raw cached audio path instead (diarization/custom pipelines). - **Voice out:** TTS as native Opus voice bubbles; Edge TTS (default free provider) requires `ffmpeg` for MP3→Opus conversion, else falls back to a regular audio file. - **Large files:** public Bot API caps `getFile` at 20 MB; pointing `platforms.telegram.extra.base_url` at a self-hosted **telegram-bot-api** server (with `local_mode: true`) lifts it to 2 GB. - **Streaming:** progressive `editMessageText` by default; `gateway.streaming.transport: auto|draft|edit|off` opts DMs into Telegram's native `sendMessageDraft` token-by-token drafts (Bot API 9.5; groups always fall back to edit). - **Reactions:** 👀 / ✅ / ❌ processing feedback — **disabled by default**; enable with `telegram.reactions: true` or `TELEGRAM_REACTIONS=true`. - **Approvals & prompts:** dangerous commands ask for a typed "yes"/"no" reply in chat; the `clarify` tool renders **inline keyboard buttons** (timeout `agent.clarify_timeout`, default 600 s); `/model` with no args opens a paginated inline model picker (added in v0.8.0). - **Topics:** operator-curated DM topics via `platforms.telegram.extra.dm_topics` (Bot API 9.4 Private Chat Topics; per-topic `skill` binding, `ignore_root_dm` lobby option); user-driven multi-session DM mode via `/topic` (unlimited user-created topics, auto-renamed to session titles, `/topic off` to disable); group forum topics via `extra.group_topics` with manual `thread_id` + skill binding. - **Mobile-tuned display:** `tool_progress` and `busy_ack_detail` default **off** on Telegram; push notifications default to `important` mode (only final responses, approvals, and command confirmations ring — `HERMES_TELEGRAM_NOTIFICATIONS=all` for legacy behavior); recurring status callbacks edit one bubble in place; the triggering user message is pinned (silently) for the duration of the turn. - **Rendering:** markdown tables auto-normalized (row-group bullets or aligned code block; `telegram.pretty_tables: false` for legacy); `extra.disable_link_previews: true` suppresses link previews. Per-chat ephemeral prompts via `telegram.channel_prompts` (topic-level overrides group-level). - **Restricted networks:** `TELEGRAM_PROXY` / `telegram.proxy_url` (`http`, `https`, `socks5`) takes priority over `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`; DNS-over-HTTPS fallback-IP discovery is automatic, `TELEGRAM_FALLBACK_IPS` only needed if DoH is blocked too. - **Home channel:** `/sethome` in any chat, or `TELEGRAM_HOME_CHANNEL=-1001234567890`; `TELEGRAM_CRON_THREAD_ID` routes cron output to a specific forum topic in topic mode. ## How to Use 1. Talk to @BotFather, run `/newbot`, name your bot, copy the token. 2. Add to `~/.hermes/.env`: ``` TELEGRAM_BOT_TOKEN=8123456789:ABC... TELEGRAM_ALLOWED_USERS=123456789 ``` 3. Start the gateway: ```bash hermes gateway setup # interactive wizard hermes gateway # foreground # or hermes gateway install # systemd / launchd service hermes gateway start ``` 4. Open your bot in Telegram and send `/start`. For groups, set `telegram.require_mention: true` in `~/.hermes/config.yaml` and disable BotFather Privacy Mode (then remove and re-add the bot). With a Docker terminal backend, `MEDIA:` paths must be host-visible — mount a shared volume (e.g. `~/.hermes/cache/documents:/output`) and emit the host path, or attachment delivery fails. ## Related Entities - [[entities/platform-discord]], [[entities/platform-slack]] — sibling gateway platforms - [[concepts/messaging-gateway]] — gateway core mechanics - [[entities/version-v0.6.0]] — webhook mode added - [[entities/version-v0.8.0]] — `/model` picker added - [[concepts/model-switching]] - [[concepts/approval-system]] <!-- ===== hermes/wiki/entities/platform-wecom.md ===== --> --- title: "WeCom Platform" type: entity tags: [platform, wecom, gateway, intermediate, well-established] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-wecom.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.6.0.md", "raw/release-v0.9.0.md", "raw/release-v0.11.0.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **WeCom** (企业微信, Enterprise WeChat) connects Hermes to Tencent's enterprise messaging platform through WeCom's **AI Bot WebSocket gateway** (`wss://openws.work.weixin.qq.com`) — a persistent bidirectional connection that needs no public endpoint, webhook, Corp ID, or Agent ID. Platform support landed in v0.6.0; v0.9.0 added the separate **WeCom Callback** adapter for self-built enterprise apps (a distinct platform — this page covers the AI Bot adapter); v0.11.0 added QR-scan bot creation in the setup wizard. Notable for transparent **AES-256-CBC decryption** of encrypted inbound media and reply-mode response correlation. ## Characteristics - **Prerequisites:** WeCom organization account, an AI Bot created in the Admin Console (Applications → Create Application → AI Bot), and Python packages `aiohttp` + `httpx` (`cryptography` for encrypted media). - **Env vars:** `WECOM_BOT_ID`, `WECOM_SECRET` (required); `WECOM_ALLOWED_USERS=user_id_1,user_id_2`; `WECOM_HOME_CHANNEL=chat_id` (cron/notification target); `WECOM_WEBSOCKET_URL` (default `wss://openws.work.weixin.qq.com`); `WECOM_DM_POLICY` and `WECOM_GROUP_POLICY` (both default `open`). - **Access policies:** `dm_policy` = `open | allowlist | disabled | pairing`; `group_policy` = `open | allowlist | disabled` with `group_allow_from` group IDs. Per-group **sender** allowlists via `platforms.wecom.extra.groups.<group_id>.allow_from` in `config.yaml`, with `"*"` as a wildcard default group; entries are case-insensitive and accept optional `wecom:user:` / `wecom:group:` prefixes. - **Media:** inbound images (URL or base64), files, voice transcriptions, and mixed text+image messages cached locally — including media from quoted messages. Inbound attachments with an `aeskey` field are AES-256-CBC decrypted transparently (needs `pip install cryptography`). - **Outbound limits:** text/markdown 4000 chars; images and video 10 MB native; voice 2 MB (AMR format only); absolute file cap 20 MB. Oversized or non-AMR media auto-downgrades to a generic file attachment; >20 MB is rejected. Files upload in 512 KB chunks (init → chunks → finish). - **Reply-mode correlation:** while the inbound request context is live, replies (including media) use `aibot_respond_msg`, correlated to the originating message; otherwise the adapter falls back to proactive `aibot_send_msg`. Each response is delivered as a single complete message — **no token streaming and no typing indicator** on WeCom. - **Connection lifecycle:** `aibot_subscribe` auth frame on connect, 30 s application-level heartbeats, reconnect backoff 2s → 5s → 10s → 30s → 60s (reset after success), pending futures failed on disconnect. 5-minute / 1000-entry message dedup. - **Inbound text batching** with adaptive delay (added in v0.9.0); QR-scan bot creation + interactive setup wizard (added in v0.11.0). - **Toolset:** `hermes-wecom` — full tools including terminal. ## How to Use 1. In the WeCom Admin Console: **Applications → Create Application → AI Bot**, then copy the **Bot ID** and **Secret** from the credentials page. 2. Configure — `hermes gateway setup` (select **WeCom**; QR-scan creation available since v0.11.0), or add to `~/.hermes/.env`: ``` WECOM_BOT_ID=your-bot-id WECOM_SECRET=your-secret WECOM_ALLOWED_USERS=user_id_1,user_id_2 WECOM_HOME_CHANNEL=chat_id ``` 3. Start the gateway: ```bash hermes gateway ``` `invalid secret (errcode=40013)` means the secret doesn't match the bot's credentials; "Timed out waiting for subscribe acknowledgement" means `openws.work.weixin.qq.com` is unreachable; media decryption errors mean `cryptography` isn't installed. ## Related Entities - [[entities/platform-feishu]], [[entities/platform-dingtalk]] — sibling Chinese-ecosystem enterprise platforms, all NAT-friendly outbound WebSocket - [[entities/platform-mattermost]] — sibling team-chat platform - [[concepts/messaging-gateway]] — gateway core; WeCom Callback (v0.9.0) is a separate sixteenth-platform adapter for self-built apps - [[entities/version-v0.6.0]] — WeCom platform support added - [[entities/version-v0.11.0]] — QR-scan bot creation + setup wizard - [[concepts/cron-scheduling]] — `WECOM_HOME_CHANNEL` receives cron output <!-- ===== hermes/wiki/entities/platform-whatsapp.md ===== --> --- title: "WhatsApp Platform" type: entity tags: [platform, whatsapp, gateway, beginner, well-established] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-user-guide-messaging-whatsapp.md", "raw/docs-user-guide-messaging.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.11.0.md", "raw/release-v0.13.0.md", "raw/release-v0.14.0.md"] confidence: high hermes_version: "v0.16.0" --- ## Overview **WhatsApp** connects to Hermes through a built-in bridge based on **Baileys**, which emulates a WhatsApp Web session — **not** the official WhatsApp Business API. No Meta developer account or Business verification is needed, but it is unofficial, so there is a small ban risk: use a dedicated phone number, keep usage conversational, and avoid bulk or unsolicited outbound messaging. Pairing is a one-command QR flow (`hermes whatsapp`), or pick WhatsApp inside the interactive `hermes gateway setup` wizard. v0.11.0 added `dm_policy`/`group_policy` gating; v0.13.0 made WhatsApp reject strangers by default as part of a security wave. ## Characteristics - **Setup:** `hermes whatsapp` wizard → scan QR via WhatsApp **Settings → Linked Devices → Link a Device**. Requires **Node.js v18+** and npm (the bridge is a Node process; no Chromium/Puppeteer needed). - **Two modes:** `WHATSAPP_MODE=bot` (dedicated bot number — recommended: clean UX, multiple users, lower ban risk) or `self-chat` (message yourself on your own number; quick single-user testing). - **Access control:** `WHATSAPP_ALLOWED_USERS=15551234567` (comma-separated, country code, **no `+`**). `WHATSAPP_ALLOWED_USERS=*` or `WHATSAPP_ALLOW_ALL_USERS=true` allows everyone. With none set, the gateway denies all incoming messages. - **Unauthorized DMs:** global default `unauthorized_dm_behavior: pair` sends strangers a pairing code; set `whatsapp.unauthorized_dm_behavior: ignore` in `config.yaml` to stay silent. Stranger rejection became the hardened default in v0.13.0 ("WhatsApp rejects strangers by default"). - **Session persistence:** saved under `~/.hermes/platforms/whatsapp/session` — survives restarts, contains full device credentials. `chmod 700` it, never share or commit it. Re-pair with `hermes whatsapp` if the session breaks (QR codes refresh every ~20 s). - **Voice in:** `.ogg` opus voice notes auto-transcribed via faster-whisper, Groq Whisper (`GROQ_API_KEY`), or OpenAI Whisper (`VOICE_TOOLS_OPENAI_KEY`). **Voice out:** TTS sent as MP3 audio file attachment. - **Delivery:** streaming (progressive edit-in-place) responses; internally a TIER_MEDIUM delivery platform. Long replies auto-chunk at 4,096 chars. Standard Markdown is auto-converted to WhatsApp formatting (`**bold**` → `*bold*`, headings → bold, links → `text (url)`); code blocks pass through unchanged. - **Message batching:** rapid bursts from one chat are debounced into a single agent request — quiet period 5 s (10 s near the split threshold), tunable via `gateway.platforms.whatsapp.extra.text_batch_delay_seconds` / `text_batch_split_delay_seconds`; `0` disables batching. - **Reply prefix:** responses are prefixed "⚕ **Hermes Agent**" by default; disable with `whatsapp.reply_prefix: ""` in `config.yaml`. - **Later additions:** `dm_policy`/`group_policy` parity with WeCom/Weixin adapters (added in v0.11.0); home channel from env overrides (added in v0.13.0); quoted-reply metadata from Baileys (added in v0.14.0). - **Debugging:** `WHATSAPP_DEBUG=true` logs raw message events to `bridge.log`. - **Toolset:** `hermes-whatsapp` — full tools including terminal. ## How to Use 1. Run the setup wizard and scan the QR code: ```bash hermes whatsapp ``` (Phone: WhatsApp → Settings → Linked Devices → Link a Device. Terminal must be 60+ columns for the QR to render.) 2. For bot mode, register a second number first (Google Voice, prepaid SIM, or VoIP) and scan from that account. 3. Add to `~/.hermes/.env`: ``` WHATSAPP_ENABLED=true WHATSAPP_MODE=bot # "bot" or "self-chat" WHATSAPP_ALLOWED_USERS=15551234567 ``` 4. Start the gateway (it launches the bridge automatically from the saved session): ```bash hermes gateway # Foreground hermes gateway install # User service sudo hermes gateway install --system # Linux boot-time system service ``` If the bot stops working after a WhatsApp Web protocol update, update Hermes and re-pair with `hermes whatsapp`. On macOS, if launchd reports "Node.js not installed", re-run `hermes gateway install` to re-snapshot your PATH. ## Related Entities - [[entities/platform-signal]], [[entities/platform-telegram]] — sibling phone-based gateway platforms - [[concepts/messaging-gateway]] — gateway core mechanics and default-deny access control - [[entities/version-v0.11.0]] — `send_voice` + `dm_policy`/`group_policy` added - [[entities/version-v0.13.0]] — stranger rejection by default, home channel env overrides - [[concepts/configuration-reference]] — `config.yaml` / `.env` conventions <!-- ===== hermes/wiki/entities/provider-anthropic.md ===== --> --- title: "Anthropic Native Provider" type: entity tags: [provider, model-switching, well-established, intermediate] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-integrations-providers.md", "raw/docs-user-guide-features-credential-pools.md", "raw/docs-user-guide-features-fallback-providers.md", "raw/docs-reference-environment-variables.md", "raw/release-v0.9.0.md", "raw/release-v0.11.0.md", "raw/release-v0.12.0.md", "raw/release-v0.14.0.md"] confidence: high hermes_version: "v0.15.0" --- ## Overview The **Anthropic native provider** connects Hermes to Claude models directly through the Anthropic API — no OpenRouter proxy in the middle. Provider id: `anthropic` (aliases: `claude`, `claude-code`). Its standout feature is auth flexibility: it works with a pay-per-token API key, with a **Claude Pro/Max subscription via Claude Code's own credential store** (auto-discovered from `~/.claude/.credentials.json`), or with a manual setup-token. Since [[entities/version-v0.11.0]] requests ride a dedicated **AnthropicTransport** speaking the Anthropic Messages API natively. ## Characteristics - **Auth methods (three):** 1. `ANTHROPIC_API_KEY` — Anthropic Console API key (console.anthropic.com), pay-per-token 2. OAuth via `hermes model` — Hermes prefers **Claude Code's credential store directly** rather than copying the token into `~/.hermes/.env`, keeping refreshable credentials refreshable. Claude Code credentials are auto-discovered and auto-seeded into the credential pool. 3. `ANTHROPIC_TOKEN` — manual setup-token / legacy OAuth override; `CLAUDE_CODE_OAUTH_TOKEN` exists as an explicit Claude Code token override - **Model id format:** bare Claude slugs, e.g. `claude-sonnet-4-6` (vs. `anthropic/claude-sonnet-4` when going through OpenRouter) - **Credential pools:** API keys and OAuth credentials coexist in one pool (`hermes auth add anthropic --type api-key` / `--type oauth`); on 401 Hermes tries an OAuth refresh before rotating - **Fast Mode:** `/fast` routes through Anthropic's priority/fast tier (added in [[entities/version-v0.9.0]]; whitelist broadened to all Anthropic models in [[entities/version-v0.12.0]]) - **Prompt caching:** cross-session 1-hour Claude prompt-prefix cache (system, skills, memory) when using Claude on Anthropic, OpenRouter, or Nous Portal ([[entities/version-v0.14.0]]) - **Auxiliary use:** `provider: "anthropic"` is a valid forced value for auxiliary tasks; Anthropic sits in the vision auto-detection chain ## How to Use ```bash # With an API key (pay-per-token) export ANTHROPIC_API_KEY=*** hermes chat --provider anthropic --model claude-sonnet-4-6 # Preferred: authenticate through `hermes model` # Hermes will use Claude Code's credential store directly when available hermes model # Manual override with a setup-token (fallback / legacy) export ANTHROPIC_TOKEN=*** hermes chat --provider anthropic # Auto-detect Claude Code credentials (if you already use Claude Code) hermes chat --provider anthropic # reads Claude Code credential files automatically ``` Permanent config in `~/.hermes/config.yaml`: ```yaml model: provider: "anthropic" default: "claude-sonnet-4-6" ``` Pool a subscription credential with an API key: ```bash hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key hermes auth add anthropic --type oauth # opens browser for OAuth login hermes auth list anthropic ``` Pair with OpenRouter for failover: ```yaml fallback_model: provider: openrouter model: anthropic/claude-sonnet-4 ``` ## Related Entities - [[entities/provider-openrouter]] — reaches the same Claude models via the aggregator; natural fallback pairing - [[entities/provider-nous-portal]], [[entities/provider-openai-codex]] — the other OAuth-capable providers (`hermes auth` handles all three) - [[entities/version-v0.9.0]] — Fast Mode; [[entities/version-v0.11.0]] — AnthropicTransport; [[entities/version-v0.14.0]] — 1h prompt cache - [[concepts/model-switching]] — pools, fallback, `/model` - [[concepts/auxiliary-models]] — Anthropic in the vision chain <!-- ===== hermes/wiki/entities/provider-google-ai-studio.md ===== --> --- title: "Google AI Studio (Gemini) Provider" type: entity tags: [provider, model-switching, well-established, intermediate] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-integrations-providers.md", "raw/docs-reference-environment-variables.md", "raw/02-install-and-setup.md", "raw/release-v0.8.0.md", "raw/release-v0.11.0.md", "raw/release-v0.12.0.md", "raw/release-v0.13.0.md"] confidence: high hermes_version: "v0.15.0" --- ## Overview The **Google AI Studio provider** gives Hermes direct access to Gemini models through Google's AI Studio API — no OpenRouter proxy. Provider id: `gemini`. The native provider shipped in [[entities/version-v0.8.0]] with automatic models.dev registry integration; [[entities/version-v0.11.0]] routed Gemini through the native AI Studio API and added a separate **Google Gemini CLI OAuth** inference provider plus a Gemini TTS provider. Gemini models matter beyond the main slot: `google/gemini-3-flash-preview` is the default context-compression summary model, and Gemini Flash via OpenRouter is the default auxiliary model for vision and web summarization. ## Characteristics - **Setup:** `GOOGLE_API_KEY` in `~/.hermes/.env` — get one at aistudio.google.com/app/apikey. `GEMINI_API_KEY` is an alias; `GEMINI_BASE_URL` overrides the endpoint. - **Provider id:** `gemini` (one of the 28 `plugins/model-providers/` plugins as of [[entities/version-v0.15.0]]) - **Free-tier guard:** Gemini free-tier keys are **blocked at setup** with 429 guidance surfacing ([[entities/version-v0.12.0]]) — free keys rate-limit too aggressively for agent use; use a paid/billing-enabled key - **Multimodal:** `video_analyze` — native video understanding — runs on Gemini and compatible multimodal models ([[entities/version-v0.13.0]]); `vision_analyze` returns raw pixels to Gemini as a vision-capable model (v0.14.0) - **OAuth alternative:** Google Gemini CLI OAuth inference provider (added v0.11.0) for subscription-style auth instead of an API key - **Auxiliary role:** default compression summary model is `google/gemini-3-flash-preview`; the setup wizard's Context Compression defaults to it ## How to Use ```bash # Set the key (auto-saves to ~/.hermes/.env) hermes config set GOOGLE_API_KEY your-ai-studio-key # Then pick Gemini in the interactive picker hermes model ``` Permanent config in `~/.hermes/config.yaml` (same pattern as other providers): ```yaml model: provider: "gemini" default: "gemini-3-flash-preview" ``` Use Gemini Flash as the dedicated compression model while a different provider runs the main loop: ```yaml compression: summary_provider: openrouter summary_model: google/gemini-3-flash-preview ``` Note: a model id like `google/gemini-3-flash-preview` is the OpenRouter-format slug; on the native `gemini` provider, use the bare model name. ## Related Entities - [[entities/provider-openrouter]] — reaches Gemini models via the aggregator, and is the default path for Gemini-Flash auxiliary tasks - [[entities/provider-anthropic]], [[entities/provider-openai-codex]] — sibling frontier providers - [[entities/version-v0.8.0]] — native provider added; [[entities/version-v0.11.0]] — native AI Studio routing + Gemini CLI OAuth; [[entities/version-v0.12.0]] — free-tier key block; [[entities/version-v0.13.0]] — `video_analyze` - [[concepts/model-switching]] - [[concepts/auxiliary-models]] — where Gemini Flash does most of its work in practice <!-- ===== hermes/wiki/entities/provider-nous-portal.md ===== --> --- title: "Nous Portal Provider" type: entity tags: [provider, model-switching, foundational, well-established, beginner] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-integrations-providers.md", "raw/docs-getting-started-quickstart.md", "raw/02-install-and-setup.md", "raw/docs-reference-environment-variables.md", "raw/docs-reference-cli-commands.md", "raw/docs-user-guide-features-credential-pools.md", "raw/release-v0.8.0.md", "raw/release-v0.10.0.md", "raw/release-v0.12.0.md", "raw/release-v0.14.0.md", "raw/release-v0.15.0.md", "https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5"] confidence: high hermes_version: "v0.16.0" --- ## Overview **Nous Portal** (portal.nousresearch.com) is [[entities/nous-research]]'s own subscription-based inference service and the "zero-config" path into Hermes: OAuth login via `hermes model`, no API key juggling. Provider id: `nous`. Beyond inference, paid subscribers get the **Nous Tool Gateway** (added in [[entities/version-v0.10.0]]) — web search (Firecrawl), image generation (FAL / FLUX 2 Pro), text-to-speech (OpenAI TTS), and browser automation (Browser Use) through the subscription with zero additional API keys. Since [[entities/version-v0.8.0]] the Portal also hosts a **free-tier Xiaomi MiMo v2 Pro** model used for auxiliary tasks (compression, vision, summarization). ## Characteristics - **Auth:** OAuth (device-code flow) via `hermes model` or `hermes auth add nous --type oauth`; credentials stored in `~/.hermes/auth.json`. `NOUS_API_KEY` also exists as a standard env-var key. `hermes login` is deprecated — use `hermes auth`. - **Billing:** subscription-based (vs. pay-per-token APIs) - **Catalog:** pulled from a remote manifest since [[entities/version-v0.12.0]], so new models appear without a Hermes release; Nous Portal became the model-metadata authority in [[entities/version-v0.14.0]]; the catalog includes frontier models (e.g. Claude Opus 4.7 added in [[entities/version-v0.11.0]]) alongside Nous's Hermes models - **Tool Gateway (v0.10.0):** per-tool opt-in via `use_gateway` config; integrates with `hermes tools` and `hermes status`; the runtime prefers the gateway even when direct API keys exist - **Prompt caching:** cross-session 1-hour Claude prompt-prefix cache works when using Claude via Nous Portal (v0.14.0) - **Hardening (v0.15.0):** one-shot setup with JWT token inference; `base_url` validated against an allowlist - **Quick Setup:** `hermes portal` is a first-time-setup alias (added in [[entities/version-v0.16.0]]) - **Dev/test env vars:** `HERMES_PORTAL_BASE_URL` (override Portal URL), `NOUS_INFERENCE_BASE_URL` (override inference API URL), `HERMES_NOUS_MIN_KEY_TTL_SECONDS` (min agent-key TTL before re-mint, default 1800 = 30 min), `HERMES_NOUS_TIMEOUT_SECONDS` ## How to Use Interactive setup (recommended): ```bash hermes model # select Nous Portal → OAuth login in browser # or, since v0.16.0: hermes portal # Quick Setup via Nous Portal ``` Use as a fallback or auxiliary provider in `~/.hermes/config.yaml`: ```yaml fallback_model: provider: nous model: nous-hermes-3 auxiliary: vision: provider: nous # "nous" forces Nous Portal for auxiliary tasks model: xiaomi/mimo-v2-pro ``` Check pool status (OAuth credentials show up in the credential pool like any key): ```bash hermes auth list nous ``` In the auxiliary auto-detection chain, Nous Portal is tried second, right after OpenRouter, for both text and vision tasks. ## Related Entities - [[entities/nous-research]] — the lab behind the Portal - [[entities/provider-openrouter]] — the other aggregator-style option; typical fallback pairing - [[entities/provider-anthropic]], [[entities/provider-openai-codex]] — direct frontier providers reachable through or alongside the Portal - [[entities/version-v0.8.0]] — free MiMo v2 Pro; [[entities/version-v0.10.0]] — Tool Gateway; [[entities/version-v0.15.0]] — JWT one-shot setup; [[entities/version-v0.16.0]] — `hermes portal` - [[entities/hermes-desktop-app]] — desktop surface that can ride the same OAuth login - [[concepts/model-switching]] — `/model` aggregator-aware resolution keeps you on Nous/OpenRouter when possible - [[concepts/auxiliary-models]] — where the free MiMo tier matters most <!-- ===== hermes/wiki/entities/provider-ollama-local.md ===== --> --- title: "Ollama Local Provider" type: entity tags: [provider, local-models, model-switching, well-established, beginner] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-integrations-providers.md", "raw/docs-guides-local-llm-on-mac.md", "raw/docs-user-guide-features-fallback-providers.md", "raw/02-install-and-setup.md", "raw/release-v0.11.0.md", "raw/release-v0.15.0.md"] confidence: high hermes_version: "v0.15.0" --- ## Overview **Ollama** runs open-weight models locally with one command and is the lowest-friction local provider for Hermes: full privacy, zero API cost, offline operation. Hermes talks to it through the **custom endpoint** path — Ollama exposes an OpenAI-compatible API at `http://localhost:11434/v1` with tool-calling support, and any server implementing `/v1/chat/completions` works. The #1 integration pitfall is Ollama's **default context length** (as low as 4,096 tokens), which is too small for an agent whose system prompt + tool schemas alone can fill the window. [[entities/version-v0.11.0]] shipped a batch of Ollama improvements: Cloud provider support, GLM continuation, `think=false` control, surrogate sanitization, and a `/v1` hint. ## Characteristics - **Setup:** `ollama pull <model>` + `ollama serve` (port **11434**); no API key required for local use - **Hermes side:** custom endpoint — `base_url: http://localhost:11434/v1`, `provider: custom`; configured via `hermes model` → "Custom endpoint" or directly in `config.yaml` - **Context defaults (per VRAM):** <24 GB → **4,096 tokens**; 24-48 GB → 32,768; 48+ GB → 256,000. For agent use with tools you need **at least 16k-32k**. Context length **cannot** be set through the OpenAI-compatible API — it must be set server-side (`OLLAMA_CONTEXT_LENGTH`) or baked into a Modelfile (`PARAMETER num_ctx`). - **Timeouts:** Hermes auto-detects local endpoints (localhost, LAN IPs) and relaxes streaming timeouts — stream read raised 120s → 1800s, stale-stream detection disabled. Manual override: `HERMES_STREAM_READ_TIMEOUT=1800` in `.env`. - **Credential pools:** custom endpoints get their own pools keyed by the auto-generated endpoint name (stored under a `custom:` prefix in `auth.json`) - **Ollama Cloud:** `OLLAMA_API_KEY` is a recognized provider key, and an `ollama-cloud` plugin exists among the 28 provider plugins ([[entities/version-v0.15.0]]). The exact setup flow for the hosted Ollama Cloud path is not documented in current sources (confidence: medium for that flow; the env var and plugin existence are confirmed). - **GPU offloading:** automatic — no configuration for most setups ## How to Use ```bash # Install and run a model ollama pull qwen2.5-coder:32b ollama serve # Starts on port 11434 # Fix the context window FIRST (pick one): OLLAMA_CONTEXT_LENGTH=32768 ollama serve # server-wide # or bake it into a model: echo -e "FROM qwen2.5-coder:32b\nPARAMETER num_ctx 32768" > Modelfile ollama create qwen2.5-coder-32k -f Modelfile # Verify the CONTEXT column shows your value ollama ps ``` Then configure Hermes: ```bash hermes model # Select "Custom endpoint (self-hosted / VLLM / etc.)" # Enter URL: http://localhost:11434/v1 # Skip API key (Ollama doesn't need one) # Enter model name (e.g. qwen2.5-coder:32b) ``` Or in `~/.hermes/config.yaml`: ```yaml model: default: qwen2.5-coder:32b provider: custom base_url: http://localhost:11434/v1 context_length: 32768 ``` Mid-session switching: `/model custom:qwen2.5-coder:32b`, or bare `/model custom` to auto-detect when the server has exactly one model loaded. With named custom providers, use the triple syntax: `/model custom:local:qwen-2.5`. As an airplane-mode fallback for a cloud primary: ```yaml fallback_model: provider: custom model: qwen2.5-coder:32b base_url: http://localhost:11434/v1 ``` ## Related Entities - [[entities/provider-openrouter]], [[entities/provider-nous-portal]] — cloud primaries that Ollama typically backs up - [[entities/version-v0.11.0]] — Ollama improvements batch - [[concepts/local-models-airplane-mode]] — the full local-stack concept - [[concepts/model-switching]] — custom providers, pools, `/model` syntax - [[syntheses/local-stack-playbook]] — end-to-end local recipe (see also the llama.cpp/omlx Mac guide it draws on) - [[entities/backend-local]] — pair a local model with the local backend for a fully offline agent <!-- ===== hermes/wiki/entities/provider-openai-codex.md ===== --> --- title: "OpenAI Codex Provider" type: entity tags: [provider, model-switching, well-established, intermediate] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-integrations-providers.md", "raw/docs-user-guide-features-fallback-providers.md", "raw/docs-user-guide-configuration.md", "raw/release-v0.8.0.md", "raw/release-v0.9.0.md", "raw/release-v0.11.0.md", "raw/release-v0.12.0.md", "raw/release-v0.14.0.md", "raw/release-v0.15.0.md"] confidence: high hermes_version: "v0.15.0" --- ## Overview The **OpenAI Codex provider** lets Hermes use your **ChatGPT subscription** (via Codex OAuth) instead of a pay-per-token OpenAI API key. Provider id: `openai-codex` (auxiliary-task value: `codex`). Authentication is a device-code flow — open a URL, enter a code — and Hermes stores the resulting credentials in its own auth store at `~/.hermes/auth.json`, importing existing Codex CLI credentials from `~/.codex/auth.json` when present. Since [[entities/version-v0.15.0]], the plain OpenAI API is a separate first-class provider (picker key `openai-api`) — distinct from the Codex runtime described here. ## Characteristics - **Auth:** ChatGPT OAuth via `hermes model` (device-code flow); no env-var API key. Credentials live in `~/.hermes/auth.json`; `~/.codex/auth.json` is imported when present. - **Models:** Codex-family models, e.g. `gpt-5.3-codex`; **GPT-5.5 over Codex OAuth** with live model discovery in the picker (added in [[entities/version-v0.11.0]]); `gpt-5.3-codex-spark` restored for ChatGPT Pro accounts ([[entities/version-v0.14.0]]) - **Transport:** **ResponsesApiTransport** — OpenAI Responses API with Codex `build_kwargs` wiring (v0.11.0); a dedicated **Codex app-server runtime** with session reuse, wedged-session retirement, and OAuth refresh classification arrived in v0.14.0 - **Fast Mode:** `/fast` priority-queue routing covers Codex models (added in [[entities/version-v0.9.0]]; whitelist broadened to all OpenAI models in v0.12.0) - **Tool-use tuning:** the v0.8.0 "self-optimized GPT/Codex tool-use guidance" patched 5 failure modes in GPT/Codex tool calling via automated behavioral benchmarking - **Reliability:** terminal-refresh error quarantine for dead OAuth tokens ([[entities/version-v0.15.0]]); `auxiliary.extra_body.reasoning` translates into the Codex Responses API (v0.12.0) - **Auxiliary use:** `provider: "codex"` forces Codex OAuth for auxiliary tasks; it supports vision (gpt-5.3-codex) and sits in both the text and vision auto-detection chains - **Aux warning:** even with Codex as the main provider, vision/web-summarization/MoA default to Gemini Flash via OpenRouter — an `OPENROUTER_API_KEY` enables those automatically ## How to Use ```bash hermes model # Select "OpenAI Codex" → device code flow: open URL, enter code ``` Permanent config in `~/.hermes/config.yaml`: ```yaml model: provider: "openai-codex" default: "gpt-5.3-codex" ``` As a fallback for another primary: ```yaml fallback_model: provider: openai-codex model: gpt-5.3-codex ``` Force Codex for an auxiliary task: ```yaml auxiliary: vision: provider: "codex" # vision-capable via gpt-5.3-codex ``` Check the OAuth credential (Codex device-code tokens are auto-seeded into the credential pool from `auth.json`): ```bash hermes auth list ``` ## Related Entities - [[entities/provider-anthropic]] — the equivalent "use your subscription" path on the Claude side - [[entities/provider-nous-portal]] — the other OAuth-first provider - [[entities/provider-openrouter]] — covers the auxiliary-model gap when Codex is primary - [[entities/version-v0.8.0]] — self-optimized GPT/Codex guidance; [[entities/version-v0.11.0]] — GPT-5.5 over Codex OAuth; [[entities/version-v0.14.0]] — app-server runtime; [[entities/version-v0.15.0]] — `openai-api` split + token quarantine - [[concepts/model-switching]] — pin OAuth providers to `fill_first` so pool rotation doesn't burn keys on a stale token - [[concepts/auxiliary-models]] <!-- ===== hermes/wiki/entities/provider-openrouter.md ===== --> --- title: "OpenRouter Provider" type: entity tags: [provider, model-switching, foundational, well-established, beginner] created: 2026-06-10 updated: 2026-06-10 sources: ["raw/docs-integrations-providers.md", "raw/docs-user-guide-features-provider-routing.md", "raw/docs-user-guide-features-credential-pools.md", "raw/docs-reference-environment-variables.md", "raw/docs-getting-started-installation.md", "raw/release-v0.9.0.md", "raw/release-v0.12.0.md", "raw/release-v0.13.0.md", "raw/release-v0.14.0.md", "raw/release-v0.15.0.md"] confidence: high hermes_version: "v0.15.0" --- ## Overview **OpenRouter** is the most-recommended single key for Hermes: an aggregator that fronts hundreds of models (Anthropic, Google, Meta, DeepSeek, …) behind one OpenAI-compatible API. Provider id: `openrouter`. One `OPENROUTER_API_KEY` unlocks the main model *and* — importantly — the default auxiliary model path: vision, web summarization, and MoA tools default to Gemini Flash **via OpenRouter**, so an OpenRouter key "enables these tools automatically" even when your primary provider is Nous Portal, Codex, or a custom endpoint. It is also the only provider with sub-provider routing controls ([[concepts/model-switching]] covers the broader switching machinery). ## Characteristics - **Setup:** `OPENROUTER_API_KEY` in `~/.hermes/.env` (keys look like `sk-or-v1-...`); `OPENROUTER_BASE_URL` overrides the endpoint - **Model id format:** `vendor/model`, e.g. `anthropic/claude-sonnet-4`, `meta-llama/llama-3.1-70b-instruct`; with an explicit provider prefix on the CLI: `openrouter/meta-llama/llama-3.1-70b-instruct` - **Variant tags:** `:free`, `:extended`, `:fast` suffixes are preserved across `/model` switches (added in [[entities/version-v0.9.0]]) - **Provider routing** (OpenRouter only): `provider_routing` in `config.yaml` — `sort` (`price` / `throughput` / `latency`), `only`, `ignore`, `order`, `require_parameters`, `data_collection` (`allow`/`deny`) — passed via `extra_body.provider` on every call - **Catalog:** live catalog refresh (v0.9.0); pulled from a remote manifest since [[entities/version-v0.12.0]] - **Response caching:** explicit cache control on supporting models ([[entities/version-v0.13.0]]); 1-hour cross-session Claude prompt cache also applies on OpenRouter ([[entities/version-v0.14.0]]) - **Pareto Code router:** `min_coding_score` knob routes to the cheapest model meeting your coding-quality bar (v0.14.0) - **Sticky routing:** session_id passed in `extra_body` for in-session provider stickiness ([[entities/version-v0.15.0]]) - **Credential pools:** multiple OpenRouter keys rotate on 429/402/401 (`hermes auth add openrouter`) ## How to Use ```bash # Set the key (auto-saves to ~/.hermes/.env) hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-here # Pick a model interactively hermes model # Or per-session hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct ``` Permanent config in `~/.hermes/config.yaml`: ```yaml model: provider: openrouter default: anthropic/claude-sonnet-4 provider_routing: sort: "price" # cheapest sub-provider first ignore: ["Together"] # never route to these require_parameters: true # only sub-providers supporting all params (tools, temperature, ...) data_collection: "deny" ``` Add a second key to the pool: ```bash hermes auth add openrouter --api-key sk-or-v1-your-second-key ``` Switch mid-session: `/model openrouter:claude-sonnet-4`. Aggregator-aware resolution keeps you on OpenRouter when the requested model is reachable through it. ## Related Entities - [[entities/provider-nous-portal]] — the other aggregator-style choice; common fallback pairing in either direction - [[entities/provider-anthropic]], [[entities/provider-google-ai-studio]] — direct connections to models also reachable via OpenRouter (note: `provider_routing` has no effect on direct connections) - [[entities/provider-ollama-local]] — local last-resort fallback in a typical chain - [[entities/version-v0.9.0]] — variant tags; [[entities/version-v0.14.0]] — Pareto Code router; [[entities/version-v0.15.0]] — sticky routing - [[concepts/model-switching]] — credential pools, fallback chains, `/model` - [[concepts/auxiliary-models]] — OpenRouter is the default auxiliary path - [[concepts/configuration-reference]] — `provider_routing` lives in `config.yaml` <!-- ===== hermes/wiki/entities/version-v0.10.0.md ===== --> --- title: "Hermes Agent v0.10.0 (v2026.4.16)" type: entity tags: [version, well-established] created: 2026-04-28 updated: 2026-04-28 sources: ["raw/release-v0.10.0.md"] confidence: high hermes_version: "v0.10.0" --- # Hermes Agent v0.10.0 (v2026.4.16) ## Overview The "Tool Gateway release" (2026-04-16). A small, single-feature drop: paid Nous Portal subscribers gain access to web search, image generation, text-to-speech, and browser automation through their existing subscription, with no additional API keys. Most other work in this window was deferred and shipped in v0.11.0. ## Characteristics | Attribute | Value | |---|---| | Released | 2026-04-16 | | Previous version | [[entities/version-v0.9.0]] (2026-04-13) | | Headline | "The Tool Gateway release" | | Stats | ~180 commits (full window stats rolled into v0.11.0) | | Days since previous | 3 | ### Tool Gateway scope | Tool category | Backed by | Replaces (per-user setup) | |---|---|---| | Web search | Firecrawl | Firecrawl API key | | Image generation | FAL / FLUX 2 Pro | FAL API key | | Text-to-speech | OpenAI TTS | OpenAI API key for TTS | | Browser automation | Browser Use | Browser Use API key | ## How to Use ### Upgrading from v0.9.0 ```bash hermes update ``` Non-breaking. The Tool Gateway is opt-in per tool via `use_gateway` config flag. ### Enabling the Tool Gateway 1. Have an active paid Nous Portal subscription 2. `hermes model` → select **Nous Portal** 3. `hermes tools` → toggle which gateway-backed tools to enable 4. Hermes prefers the gateway path even when direct API keys are configured ### Behavior change The hidden env var `HERMES_ENABLE_NOUS_MANAGED_TOOLS` is removed. Detection is now subscription-based — the runtime checks your Nous Portal account state directly. ## Related Entities - [[entities/version-v0.9.0]] — prior release (2026-04-13) - [[entities/version-v0.11.0]] — next release (2026-04-23) - [[entities/nous-research]] — Nous Portal subscription provider - [[summaries/release-v0.10.0]] — detailed release notes summary <!-- ===== hermes/wiki/entities/version-v0.11.0.md ===== --> --- title: "Hermes Agent v0.11.0 (v2026.4.23)" type: entity tags: [version, well-established] created: 2026-04-28 updated: 2026-04-28 sources: ["raw/release-v0.11.0.md"] confidence: high hermes_version: "v0.11.0" --- # Hermes Agent v0.11.0 (v2026.4.23) ## Overview The "Interface release" (2026-04-23). The largest single release in the project's history: a full React/Ink rewrite of the interactive CLI, a pluggable transport architecture under every provider, native AWS Bedrock, five new inference paths, a 17th messaging platform (QQBot), a dramatically expanded plugin surface, and GPT-5.5 via Codex OAuth. Folds in everything deferred from v0.10.0 — covers ~10 days of work across the whole stack. ## Characteristics | Attribute | Value | |---|---| | Released | 2026-04-23 | | Previous version | [[entities/version-v0.10.0]] (2026-04-16) | | Headline | "The Interface release" | | Commits (since v0.9.0) | 1,556 | | PRs merged (since v0.9.0) | 761 | | Files changed | 1,314 | | Insertions | 224,174 | | Community contributors | 29 (290 including co-authors) | | Days since previous | 7 | ### Platform count milestone Hermes now supports **17 messaging platforms**: Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, DingTalk, Feishu, WeCom, Mattermost, Home Assistant, Webhooks, BlueBubbles (iMessage), Weixin (WeChat), WeCom Callback, plus the new **QQBot**. ### Auxiliary auto-routing — behavior change `auto` routing for auxiliary tasks now defaults to **the main model** for all users. Previously, aggregator users (OpenRouter, Nous Portal, etc.) were silently routed to a cheap provider-side default (e.g., Gemini Flash). Users who explicitly configure aux models in their `auxiliary.<task>` block are unaffected — that path always wins. ## How to Use ### Upgrading from v0.10.0 ```bash hermes update ``` Largely non-breaking. Notable behavior changes: - Auxiliary `auto` defaults to main model — see above. If you'd been relying on the implicit cheap-provider routing, set `auxiliary.<task>.provider` and `.model` explicitly. - TUI is opt-in via `hermes --tui` or `HERMES_TUI=1` — the classic CLI is unchanged unless you toggle. - New transport layer changes nothing for users who don't care; provider configs read identically. ### Opt-in new features - **TUI:** `hermes --tui` or `HERMES_TUI=1` - **`/steer <prompt>`** — type during a running turn to nudge the agent on its next tool call - **Shell hooks:** drop scripts into `~/.hermes/hooks/` and wire them to lifecycle events without writing a plugin - **Configure aux models from UI:** `hermes model` → "Configure auxiliary models" - **AWS Bedrock provider:** `hermes setup` → providers → AWS Bedrock - **GPT-5.5 (Codex OAuth):** `/model` after authenticating Codex - **Webhook direct-delivery:** subscribe a webhook with `direct_delivery: true` to forward payloads to chat without invoking the agent - **Cron `wakeAgent` gate:** mark cron jobs that should run their script without spinning up the agent - **Cron per-job toolsets:** cap token overhead per scheduled job ### New platform setup - **QQBot:** install + `hermes setup` → Messaging → QQBot → QR scan to configure ### Plugin surface (for plugin authors) New plugin hooks available: - `register_command(...)` — add slash commands - `dispatch_tool(...)` — invoke tools from plugin code - `pre_tool_call(...)` — return blocking decision to veto a tool call - `transform_tool_result(...)` — rewrite tool results - `transform_terminal_output(...)` — rewrite terminal tool output - `image_gen` backend interface — ship custom image-gen providers - Dashboard tab/widget/view registration ## Related Entities - [[entities/version-v0.10.0]] — prior release (2026-04-16) - [[entities/version-v0.9.0]] — (2026-04-13) - [[entities/version-v0.8.0]] — (2026-04-08) - [[entities/nous-research]] — the lab shipping these releases - [[summaries/release-v0.11.0]] — detailed release notes summary <!-- ===== hermes/wiki/entities/version-v0.12.0.md ===== --> --- title: "Hermes Agent v0.12.0 (v2026.4.30)" type: entity tags: [version, well-established] created: 2026-05-01 updated: 2026-05-01 sources: ["raw/release-v0.12.0.md"] confidence: high hermes_version: "v0.12.0" --- # Hermes Agent v0.12.0 (v2026.4.30) ## Overview The "Curator release" (2026-04-30). The agent now actively maintains itself: an autonomous background Curator runs on a 7-day cycle, grading the skill library, pruning dead skills, and consolidating related ones. The self-improvement loop that decides what to save after each turn was substantially upgraded — class-first/rubric-based grading, scoped to memory + skills only, runtime inheritance fixed. Four new inference providers, a 19th messaging platform via the new plugin-host gateway architecture, ComfyUI + TouchDesigner-MCP promoted to bundled-by-default, and a ~57% TUI cold-start cut. ## Characteristics | Attribute | Value | |---|---| | Released | 2026-04-30 | | Previous version | [[entities/version-v0.11.0]] (2026-04-23) | | Headline | "The Curator release" | | Commits (since v0.11.0) | 1,096 | | PRs merged (since v0.11.0) | 550 | | Files changed | 1,270 | | Insertions | 217,776 | | Community contributors | 213 (including co-authors) | | Days since previous | 7 | ### Platform count milestone Hermes now supports **19 messaging platforms**: Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, DingTalk, Feishu, WeCom, Mattermost, Home Assistant, Webhooks, BlueBubbles (iMessage), Weixin (WeChat), WeCom Callback, QQBot, plus the new **Yuanbao (元宝)** and **Microsoft Teams** (Teams ships as a plugin via the new gateway plugin-host architecture). ### Auxiliary task slot added Auxiliary models now expose a **9th task slot — `curator`** — for the autonomous skill-maintenance background agent. Pick the model in `hermes model` or via `auxiliary.curator` config. (v0.11.0 had 8 slots: vision, web_extract, compression, approval, session_search, skills_hub, mcp, flush_memories. v0.12.0 removes `flush_memories` entirely and adds `curator`, so the net count is still 8 — but the surface changed.) ## How to Use ### Upgrading from v0.11.0 ```bash hermes update ``` Largely non-breaking. Notable behavior changes: - **Curator runs by default** on the 7-day cycle once you upgrade. Reports land in `logs/curator/run.json` + `REPORT.md`. To stop: disable via `hermes curator` config / dashboard. Bundled and hub skills are gated, so the curator can't accidentally delete those — but it can prune your custom skills if it judges them dead. Pin with `skill_manage` to lock a skill from any modification. - **Secret redaction is now off by default.** Patch corruption from fake-key substitutions stops. Re-enable with `redaction.enabled: true` in config.yaml if you need it for a regulated workflow. - **`flush_memories` is gone.** If you had explicit `auxiliary.flush_memories` config, it is no longer a recognized slot. Drop the block. - **`/provider` and `/plan` slash commands dropped.** Use `/model` or `hermes model` instead. - **BOOT.md built-in hook removed.** The hooks tutorial (#17202) shows how to rebuild the same workflow with a shell hook. ### Opt-in new features - **Curator on a different cadence:** edit cron interval under `auxiliary.curator` config - **`hermes -z <prompt>`** — one-shot, non-interactive runs (use for cron / scripts) - **`hermes update --check`** — preflight check before actually pulling updates - **Direct-URL skill install:** `hermes skills install https://example.com/skill.zip` - **`/reload-skills`** — pick up skill edits without restarting - **`prompt_caching.cache_ttl: 1h`** — for bursty sessions that keep cache warm - **Models dashboard tab** — open the dashboard, navigate to Models for per-model analytics + in-browser model switching - **Vercel Sandbox backend:** configure under `execute_code` to run in Vercel's sandbox instead of Docker/local - **Spotify integration:** `hermes setup` → tools → Spotify → PKCE OAuth flow - **Google Meet plugin:** join calls, transcribe, follow up — bundled plugin, opt-in - **Piper local TTS:** native local TTS provider — no cloud dependency - **LM Studio first-class:** `hermes setup` → providers → LM Studio (no longer a custom-endpoint workaround) ### New platform setup - **Microsoft Teams:** install the Teams plugin (it ships as a plugin, not core), then `hermes setup` → Messaging → Microsoft Teams - **Yuanbao:** `hermes setup` → Messaging → Yuanbao ### Curator config sketch ```yaml auxiliary: curator: provider: openrouter model: anthropic/claude-haiku-4-5 # cron interval lives in the gateway config — default is weekly ``` `hermes curator status` ranks skills by usage. The output is your at-a-glance view of what the curator has been seeing. ## Related Entities - [[entities/version-v0.11.0]] — prior release (2026-04-23) - [[entities/version-v0.10.0]] — (2026-04-16) - [[entities/version-v0.9.0]] — (2026-04-13) - [[entities/nous-research]] — the lab shipping these releases - [[summaries/release-v0.12.0]] — detailed release notes summary <!-- ===== hermes/wiki/entities/version-v0.13.0.md ===== --> --- title: "Hermes Agent v0.13.0 (v2026.5.7)" type: entity tags: [version, well-established] created: 2026-05-23 updated: 2026-05-23 sources: ["raw/release-v0.13.0.md"] confidence: high hermes_version: "v0.13.0" --- # Hermes Agent v0.13.0 (v2026.5.7) ## Overview The "Tenacity Release" (2026-05-07). The agent finishes what it starts: durable multi-agent Kanban (heartbeat, reclaim, zombie detection, retry budgets, hallucination gate), `/goal` Ralph loop for cross-turn goal lock, sessions auto-resume after gateway restart, Checkpoints v2 with real pruning. Curator gains subcommands (`archive`, `prune`, `list-archived`) and a synchronous manual `run`. Google Chat is the 20th platform. Providers become pluggable. 8 P0 security closures (redaction back ON by default, cross-guild DM bypass closed, WhatsApp strangers rejected). 7 i18n locales ship. ## Characteristics | Attribute | Value | |---|---| | Released | 2026-05-07 | | Previous version | [[entities/version-v0.12.0]] (2026-04-30) | | Headline | "The Tenacity Release" | | Commits (since v0.12.0) | 864 | | PRs merged | 588 | | Files changed | 829 | | Insertions | 128,366 | | Issues closed | 282 (13 P0, 36 P1) | | Community contributors | 295 (with co-authors) | | Days since previous | 7 | ### Platform count **20 messaging platforms.** Added: Google Chat. Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, DingTalk, Feishu, WeCom, Mattermost, Home Assistant, Webhooks, BlueBubbles, Weixin, WeCom Callback, QQBot, Yuanbao, Microsoft Teams (plugin), Google Chat. ## How to Use ### Upgrading from v0.12.0 ```bash hermes update ``` Notable behavior changes: - **Redaction is ON by default again.** v0.12 flipped it off; v0.13's security wave flipped it back. If you previously enabled redaction explicitly, no change. If you were relying on it being off (raw patches/tool outputs), set `redaction.enabled: false` to keep that behavior. - **`/provider` slash command removed.** Use `/model` or `hermes model`. - **Sessions auto-resume after gateway restart.** If you depend on `/new` semantics after a crash, the agent will now pick up where it left off instead of starting clean. - **Discord allow-lists scoped to originating guild.** If you have `DISCORD_ALLOWED_ROLES` set, the role check now applies only to that guild; cross-guild DM bypass closed. - **WhatsApp rejects strangers by default.** Set allowlist explicitly or set `whatsapp.allow_strangers: true` to revert. - **MCP OAuth + auth.json TOCTOU windows closed** — no user-visible change, but credential reads/writes are now atomic. ### Opt-in new features - **Multi-agent Kanban:** `hermes kanban` or `/kanban` — see docs for the orchestrator + worker pattern - **`/goal <criteria>`** — Ralph loop, agent stays on target across turns until judge marks done - **`hermes curator run`** — synchronous manual curator pass, see results immediately - **`hermes curator archive` / `prune` / `list-archived`** — manual skill maintenance subcommands - **`no_agent` cron mode** — cron jobs that skip the agent entirely, just run a script (watchdog pattern) - **Platform allowlists:** `allowed_channels` / `allowed_chats` / `allowed_rooms` per platform - **`[[as_document]]`** — directive in skill output to force document delivery - **Google Chat:** `hermes setup` → Messaging → Google Chat - **TUI status bar context compression count** — visible by default - **TUI collapsible startup banner sections** — collapse skills / system prompt / MCP details - **`/sessions`** TUI slash command for browsing and resuming previous sessions - **Dashboard Plugins page** + Profiles page - **OpenRouter response caching** — explicit cache control on supporting models ### New auxiliary task slots No new auxiliary task slot in v0.13 itself (Curator slot landed in v0.12). The Curator gains operator-facing subcommands but `auxiliary.curator` config surface is unchanged. ### Curator config sketch (unchanged) ```yaml auxiliary: curator: provider: openrouter model: anthropic/claude-haiku-4-5 ``` New CLI surface: ```bash hermes curator run # synchronous manual pass — see output now hermes curator archive <name> # manually archive a skill hermes curator prune # manually prune all dead skills hermes curator list-archived # see what's been archived hermes curator status # usage rankings (v0.12) hermes curator pin <name> # lock skill from any modification ``` ## Related Entities - [[entities/version-v0.12.0]] — prior release (2026-04-30) - [[entities/version-v0.11.0]] — (2026-04-23) - [[entities/nous-research]] — the lab shipping these releases - [[summaries/release-v0.13.0]] — detailed release notes summary <!-- ===== hermes/wiki/entities/version-v0.14.0.md ===== --> --- title: "Hermes Agent v0.14.0 (v2026.5.16)" type: entity tags: [version, well-established] created: 2026-05-23 updated: 2026-05-23 sources: ["raw/release-v0.14.0.md"] confidence: high hermes_version: "v0.14.0" --- # Hermes Agent v0.14.0 (v2026.5.16) ## Overview The "Foundation Release" (2026-05-16). Hermes ships on PyPI and runs natively on Windows. xAI Grok lands as a SuperGrok OAuth provider with grok-4.3 at 1M context. A new OpenAI-compatible local proxy turns any OAuth-authed Hermes provider into an endpoint that Codex / Aider / Cline / Continue can hit — one subscription powers every tool. A debloating wave makes installs dramatically lighter, the cold-start wave shaves ~19 seconds off `hermes` launch, and `browser_console` calls are 180x faster. Microsoft Teams ships end-to-end. LINE + SimpleX Chat join, bringing the platform total to 22. 9 new optional skills. `huggingface/skills` as trusted default tap. ## Characteristics | Attribute | Value | |---|---| | Released | 2026-05-16 | | Previous version | [[entities/version-v0.13.0]] (2026-05-07) | | Headline | "The Foundation Release" | | Commits (since v0.13.0) | 808 | | PRs merged | 633 | | Files changed | 1,393 | | Insertions | 165,061 | | Issues closed | 545 (12 P0, 50 P1) | | Community contributors | 215 (with co-authors) | | Days since previous | 9 | ### Platform count **22 messaging platforms.** Added: LINE Messaging API, SimpleX Chat. Microsoft Teams now actually wired end-to-end (was a plugin shell in v0.12). Full list: Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, DingTalk, Feishu, WeCom, Mattermost, Home Assistant, Webhooks, BlueBubbles, Weixin, WeCom Callback, QQBot, Yuanbao, Microsoft Teams, Google Chat, LINE, SimpleX Chat. ### Install path change **Canonical install is now `pip install hermes-agent`.** Previously: clone the repo and run the installer. The PyPI wheel ships with the Ink TUI bundle + shell launcher. ## How to Use ### Upgrading from v0.13.0 ```bash hermes update ``` OR, for fresh installs: ```bash pip install hermes-agent hermes ``` Notable behavior changes: - **Heavyweight backends are lazy-installed.** First time you use Slack / Matrix / Feishu / DingTalk / hindsight / codex app-server / image-gen / voice/TTS, Hermes will install the missing dependency on demand. Speeds up clean installs. - **`[all]` extras drops anything covered by lazy-deps.** If you were doing `pip install hermes-agent[all]` and expecting a heavy install, you'll get a lighter one. Optional extras still available individually. - **Cold start ~19s faster.** Defer-import, disk-cached model catalogs. - **Cross-session 1h Claude prefix cache.** Sessions resumed within an hour land faster + cheaper. No config required. - **Native Windows beta.** If you've been WSL2-only, native `cmd.exe` / PowerShell now works. Some rough edges remain (~40 follow-up Windows-only fixes already landed). - **Alibaba Cloud → Qwen Cloud rename.** Config keys still work; UI text changes. - **Tool error strings sanitized** before re-injection — closes prompt-injection vector via malicious file/service error output. ### Opt-in new features - **PyPI install:** `pip install hermes-agent && hermes` - **xAI Grok OAuth:** `hermes setup` → providers → xAI → SuperGrok OAuth (needs paid SuperGrok subscription) - **OpenAI-compatible proxy:** `hermes proxy` → exposes `http://localhost:port` speaking OpenAI API, backed by whichever OAuth provider you're signed into. Point Codex/Aider/Cline/Continue at it. - **`x_search`** — first-class X (Twitter) tool, OAuth or API key - **`/handoff`** — live session transfer mid-conversation between model/persona/profile - **`/subgoal <criteria>`** — append criteria to active `/goal` Ralph loop - **`vision_analyze`** — pass image, get model's actual visual reasoning (not text-summary roundtrip) on vision-capable models - **Per-turn file-mutation verifier footer** — agent gets disk delta summary after every turn that writes files - **LSP diagnostics on write** — type errors / undefined symbols surfaced before next turn - **`computer_use` cua-driver** — GUI-driving with non-Anthropic providers now - **OSC8 hyperlinks** — clickable URLs in iTerm2 / Kitty / Ghostty / Windows Terminal - **Microsoft Teams:** install Teams plugin → `hermes setup` → Messaging → Microsoft Teams → Graph auth flow - **LINE / SimpleX Chat:** `hermes setup` → Messaging → LINE or SimpleX - **Brave Search / DDGS:** `hermes tools` → Web Search → pick Brave (free tier) or DDGS (no key) - **Codex app-server runtime** — optional runtime under OpenAI/Codex provider paths for long agentic runs - **Zed integration:** install via Zed's ACP Registry one-click (uvx-based) - **`hermes acp --setup-browser`** — bootstrap browser tools for registry installs ### OpenAI-compatible proxy config sketch ```bash hermes proxy --port 8765 # or as a service: hermes proxy start # point your other tool at it: export OPENAI_API_KEY=anything export OPENAI_BASE_URL=http://localhost:8765/v1 codex # or aider, cline, continue, etc. ``` ### SuperGrok OAuth config sketch ```yaml providers: xai: auth_mode: oauth # vs api_key ``` Then `hermes auth login xai` and complete the OAuth flow. Use `--ssh-tunnel` doc if completing OAuth from a remote box. ## Related Entities - [[entities/version-v0.13.0]] — prior release (2026-05-07) - [[entities/version-v0.12.0]] — (2026-04-30) - [[entities/nous-research]] — the lab shipping these releases - [[summaries/release-v0.14.0]] — detailed release notes summary <!-- ===== hermes/wiki/entities/version-v0.15.0.md ===== --> --- title: "Hermes Agent v0.15.0 (v2026.5.28)" type: entity tags: [version, well-established] created: 2026-06-01 updated: 2026-06-04 sources: ["raw/release-v0.15.0.md", "https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29", "https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29.2", "https://github.com/NousResearch/hermes-agent/commit/827f7f07825be57108cbea18325e8f5e9fb5d2f2"] confidence: high hermes_version: "v0.15.2" --- # Hermes Agent v0.15.0 (v2026.5.28) ## Overview The "Velocity Release" (2026-05-28). Hermes gets dramatically faster across the board: the 16,083-line `run_agent.py` collapses to 3,821 (-76%) across 14 `agent/*` modules, `hermes --version` flips the benchmark against Codex CLI, and `session_search` becomes a free, no-LLM, ~20ms FTS5 tool (4,500× faster). Kanban grows into a real multi-agent platform (orchestrator auto-decomposition, swarm topology, per-task model/worktree overrides). Promptware defense lands against Brainworm-class attacks. Bitwarden Secrets Manager replaces N per-provider keys with one bootstrap token. OpenAI API becomes a first-class provider distinct from Codex; Vercel AI Gateway is removed (provider plugins 29 → 28). A deep xAI round backs `hermes proxy` with SuperGrok and adds `hermes migrate xai` for the May-15 Grok retirement. Two same-day patches followed: **v0.15.1 / v2026.5.29** ("The Patch Release" — 28 commits, 21 PRs; dashboard 401 reload-loop fix, explicit Docker insecure-mode opt-in, Docker MCP bare-command resolution, dashboard skills page/category sidebar restoration, skills.sh catalog 858→19,932, Kanban worker SIGTERM termination, `/model` picker/listing unification, `/yolo` mid-session bypass, `.md` media delivery restoration) and **v0.15.2 / v2026.5.29.2** (packaging fix — bundled `plugin.yaml`/`plugin.yml` manifests now ship in both wheel and sdist distributions). ## Characteristics | Attribute | Value | |---|---| | Released | 2026-05-28 | | Previous version | [[entities/version-v0.14.0]] (2026-05-16) | | Headline | "The Velocity Release" | | Commits (since v0.14.0) | 1,302 | | PRs merged | 747 | | Files changed | 1,746 | | Insertions | 282,712 | | Issues closed | 560+ (15 P0, 65 P1, 19 security) | | Community contributors | 321 | | Days since previous | 12 | | Patches | v0.15.1 / v2026.5.29 (2026-05-29, "The Patch Release" — dashboard 401 reload-loop + skills.sh catalog 858→19,932 + Docker insecure opt-in + Docker MCP bare-command resolution + skills page/sidebar restore + Kanban SIGTERM + `/model` picker unification + `/yolo` mid-session), v0.15.2 / v2026.5.29.2 (2026-05-29, wheel + sdist plugin-manifest packaging fix — `MANIFEST.in` + `pyproject.toml` `plugins` package-data globs `**/plugin.yaml` `**/plugin.yml`; regression test in `tests/test_packaging_metadata.py`; bundled manifest count 0 → 69) | ### Provider count change **`plugins/model-providers/` = 28 provider plugins** (was 29 in v0.14). Vercel AI Gateway + Vercel Sandbox removed. OpenAI API is now first-class (picker key `openai-api`) but is a core/picker ID, not a separate plugin dir. Current dirs: alibaba-coding-plan, alibaba, anthropic, arcee, azure-foundry, bedrock, copilot-acp, copilot, custom, deepseek, gemini, gmi, huggingface, kilocode, kimi-coding, minimax, nous, novita, nvidia, ollama-cloud, openai-codex, opencode-zen, openrouter, qwen-oauth, stepfun, xai, xiaomi, zai. ### Auxiliary task roster change Built-in aux task keys (8): `vision`, `compression`, `web_extract`, `approval`, `mcp`, `title_generation`, `skills_hub`, `curator`. `session_search` left the roster (now a free no-LLM FTS5 tool); `title_generation` is the new 8th. Plugins can register custom aux tasks via `register_auxiliary_task()`. ### xAI / Grok migration May-15 retirement: `grok-4-0709`, `grok-4-fast-reasoning`, `grok-4-fast-non-reasoning`, `grok-4-1-fast-*`, `grok-code-fast-1`, `grok-3` → all map to **`grok-4.3`** (reasons by default, 1M context). `grok-imagine-image-pro` → `grok-imagine-image-quality`. Run `hermes migrate xai`. `grok-4.3` remains the canonical xAI model to point at. ## How to Use ### Upgrading from v0.14.0 ```bash hermes update # then, if you use xAI/Grok and had older slugs pinned: hermes migrate xai ``` Notable behavior changes: - **`session_search` is free and instant now** — no aux-LLM, no `mode` param, no config knob. Three modes (discovery/scroll/browse) inferred from args. - **`title_generation` is a new aux slot** — auto-names your sessions; configure under `auxiliary.title_generation` like any other slot. - **Vercel AI Gateway / Sandbox removed** — if you used a `vercel` provider, migrate to OpenRouter or a direct provider. - **OpenAI API is first-class** — pick `openai-api` (vs `openai-codex`) in `hermes model`. - **Auxiliary layered fallback** — aux tasks now degrade primary → chain → main agent → graceful fail on 402/429/connection errors. - **Control-plane files are write-protected** — `auth.json`, `config.yaml`, `webhook_subscriptions.json`, `mcp-tokens/` are guarded; under profile mode the root `.env` is write-deny. ### Opt-in new features - **`hermes proxy` backed by SuperGrok:** the OpenAI-compatible localhost endpoint can now run on xAI OAuth (no PKCE-refresh code in your client). - **`hermes kanban swarm`** — generate a Swarm v1 multi-agent topology (root → parallel workers → gated verifier → synthesizer → blackboard). - **`hermes audit`** — OSV.dev on-demand supply-chain audit. - **`hermes mcp`** — interactive Nous-approved MCP catalog picker; mTLS for HTTP/SSE servers. - **Skill bundles** — `/<name>` loads a whole workflow of skills at once. - **Bitwarden Secrets Manager** — one bootstrap token for all provider keys (`secrets.bitwarden.*`). - **Multi-session orchestrator** in the Ink TUI — list/switch/refresh/close live sessions. ### Patch upgrades - **v0.15.0 → v0.15.1 (v2026.5.29) "The Patch Release" hotfix round:** users on v0.15.0 should upgrade to v0.15.1 (or later) if they hit any of: dashboard reload loops on `/api/auth/me` 401s; Docker dashboard `--insecure` ambiguity when binding to `0.0.0.0`; Docker MCP servers configured with bare `npx` / `npm` / `node` commands failing to launch (now resolve against `/usr/local/bin` inside the image); stuck Kanban worker termination (SIGTERM handling fixed, closes #28181); `/model` picker/listing drift between in-session and out-of-session selection (unified via disk cache); `/yolo` not being toggleable mid-session; `.md` media delivery regression; or stale skills page source pills / category sidebar. The patch is small (28 commits, 21 PRs) but broad — every Hermes surface shipped at least one fix. **Breaking change to be aware of:** Docker dashboard insecure mode is now an **explicit opt-in** via `HERMES_DASHBOARD_INSECURE=1`; binding to `0.0.0.0` no longer implies it. No config migration is required for the other fixes. See [release notes v2026.5.29](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29). - **v0.15.1 → v0.15.2 (v2026.5.29.2) packaging fix:** if you or a downstream packager installed v0.15.0 or v0.15.1 and saw bundled-plugin manifest discovery failures (e.g. `plugin.yaml` / `plugin.yml` files from installed plugins were not picked up at runtime), upgrade to v0.15.2. The fix ships the bundled `plugins/**/plugin.yaml` and `plugins/**/plugin.yml` manifests in both the wheel (via `pyproject.toml` `plugins` package-data globs) and the sdist (via `MANIFEST.in` `recursive-include plugins plugin.yaml plugin.yml`); a regression test was added in `tests/test_packaging_metadata.py`. No config migration is required — `hermes update` is sufficient. See [release notes](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29.2) / [commit 827f7f07](https://github.com/NousResearch/hermes-agent/commit/827f7f07825be57108cbea18325e8f5e9fb5d2f2). ## Related Entities - [[entities/version-v0.14.0]] — prior release (2026-05-16) - [[entities/version-v0.13.0]] — (2026-05-07) - [[entities/nous-research]] — the lab shipping these releases - [[summaries/release-v0.15.0]] — detailed release notes summary - [[concepts/auxiliary-models]] — roster updated this release (session_search out, title_generation in) <!-- ===== hermes/wiki/entities/version-v0.16.0.md ===== --> --- title: "Hermes Agent v0.16.0 (v2026.6.5)" type: entity tags: [version, well-established] created: 2026-06-06 updated: 2026-06-06 sources: ["https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5"] confidence: high hermes_version: "v0.16.0" --- # Hermes Agent v0.16.0 (v2026.6.5) ## Overview The "Surface Release" (2026-06-05). Hermes meets you wherever you work. A native Electron desktop app (macOS / Linux / Windows) — built in one week across 100 PRs — installs like any desktop app, self-updates, and connects to a remote Hermes gateway over OAuth or username/password. The web dashboard became a full administration panel: configure messaging channels, MCP servers, credentials, webhooks, memory, and gateway settings from the browser — no more `config.yaml` edits over SSH for messaging setup. First-time setup got a Quick Setup / `hermes portal` path. The model picker went fuzzy everywhere. `/undo [N]` landed. The default skill set was deliberately trimmed. NVIDIA/skills joined the trusted Skills Hub. Security: CVE-2026-48710 (Starlette BadHost) patched; SSRF off-loop hardening; subprocess credential stripping. ## Characteristics | Attribute | Value | |---|---| | Released | 2026-06-05 | | Previous version | [[entities/version-v0.15.0]] (2026-05-28, patches v0.15.1/v0.15.2 on 2026-05-29) | | Headline | "The Surface Release" | | Commits (since v0.15.2) | 874 | | PRs merged | 542 | | Files changed | 1,962 | | Insertions | 205,216 | | Deletions | 46,217 | | Issues closed | 399 (2 P0, 62 P1, 16 security) | | Community contributors | 170 | | Days since previous | 8 (since v0.15.2 on 2026-05-29) | | Patches | none yet | ### Provider count **`plugins/model-providers/` = 28** (unchanged from v0.15). No providers added or removed. New model *slugs* added: `deepseek-v4-flash`, `MiniMax-M3` (1M context), `qwen3.7-plus`, `gemini-3.5-flash`. Model catalog now refreshes hourly instead of daily. ### Auxiliary-task roster **No change from v0.15**: 8 built-in slots — `vision`, `compression`, `web_extract`, `approval`, `mcp`, `title_generation`, `skills_hub`, `curator`. `register_auxiliary_task()` plugin hook unchanged. ### Desktop app surfaces The `apps/desktop/` Electron app is the new primary surface for non-terminal users: - **Local mode**: runs Hermes locally, full feature parity with CLI/TUI - **Remote-gateway mode**: connects to any Hermes gateway over authenticated WebSocket (OAuth or username/password); thin GUI on the device, heavy agent runs elsewhere - **Platforms**: macOS (installer + in-app self-update), Linux (arm64 + x86), Windows - **Features**: drag-and-drop / clipboard image paste, Cmd+K palette, session list with archive/search, inline model picker in the status bar, YOLO toggle, Simplified Chinese (简体中文, `display.language`), approval/sudo/secret prompt rendering ### Skills changes (v0.16.0) Removed from defaults (redundant / dead): - `spotify` → use native Spotify plugin's 7 tools instead - `linear` → use `hermes mcp install linear` - `kanban-codex-lane`, `debugging-hermes-tui-commands`, stale `domain` orphan - Empty category markers: `diagramming`, `gifs`, `inference-sh`, `mlops/training`, `mlops/vector-databases` Moved bundled → optional (still available via `hermes skills install`): - `baoyu-article-illustrator`, `baoyu-comic`, `creative-ideation`, `pixel-art`, `dspy`, `subagent-driven-development`, `minecraft-modpack-server`, `pokemon-player`, `hermes-s6-container-supervision` Consolidated: - `webhook-subscriptions` + `native-mcp` → folded into `hermes-agent` skill as on-demand references - `writing-plans` → merged into `plan` (v2.0.0) New mechanism: - `environments:` frontmatter gate (`kanban` / `docker` / `s6`) — context-specific skills excluded from the index for users who won't use them; still load on explicit request - Curator can prune unused **built-in** skills (previously only agent-created), with usage tracked per skill - `--no-skills` flag on the installer for blank-slate profiles; `hermes skills opt-out` / `opt-in` for the default profile (NOT `hermes skills install --no-skills`) ## How to Use ### Upgrading from v0.15.x ```bash hermes update ``` Notable behavior changes: - **Web dashboard is now an admin panel** — the Channels page replaces manual `config.yaml` edits for messaging setup. MCP admin panel replaces `hermes mcp` CLI-only flow. - **Dashboard Docker insecure mode** — still requires explicit `HERMES_DASHBOARD_INSECURE=1` (introduced in v0.15.1). Binding to `0.0.0.0` does not imply insecure mode. - **Default skill set is smaller** — if you relied on `spotify`, `linear`, or the Baoyu creative skills by default, they are now optional; `hermes skills install <name>` to restore. - **`hermes chat` default interface** — configure whether it opens CLI or TUI; `--cli` flag forces CLI per-invocation. - **Model picker is fuzzy** — type partial model names across all surfaces; catalog refreshes hourly now. - **`/undo [N]`** — backs up N user turns in CLI, TUI, and messaging platforms. ### New commands / flags - `hermes portal` — Quick Setup via Nous Portal (human-readable alias) - `hermes sessions optimize` — FTS5 segment merge + VACUUM for search performance - `hermes prompt-size` — diagnostic: show how large your current prompt context is - `--no-skills` (installer flag) / `hermes skills opt-out` — blank-slate skill profile - `/undo [N]` — take back the last N turns (prefills last message, soft-deletes in-between) - `--cli` flag on `hermes chat` — force CLI interface regardless of configured default ### Desktop app install macOS: download installer → drag to Applications → in-app updates from there on. Linux: download arm64 or x86 binary; configure Electron sandbox helper; GPU acceleration disabled automatically on remote displays. Windows: download installer; `hermes update` handles in-app update. ## Related Entities - [[entities/version-v0.15.0]] — prior release (v0.15.2 / v2026.5.29.2) - [[entities/nous-research]] — the lab shipping these releases - [[summaries/release-v0.16.0]] — detailed release notes summary - [[concepts/skills-system]] — skills trim + environments gate changed this release - [[concepts/model-switching]] — fuzzy picker + hourly refresh changed this release - [[concepts/subagents-delegation]] — Kanban goal_mode + file attachments changed this release <!-- ===== hermes/wiki/entities/version-v0.6.0.md ===== --> --- title: "Hermes Agent v0.6.0" type: entity tags: [version, multi-instance, mcp, docker, gateway] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/release-v0.6.0.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview Hermes Agent **v0.6.0** (internal tag `v2026.3.30`) shipped on **2026-03-30** as the "multi-instance release." Headline themes: isolated agent instances via Profiles, MCP server mode for exposing Hermes to external clients, an official Docker container, fallback provider chains, and two new Chinese-market messaging platforms (Feishu/Lark and WeCom). 95 PRs merged and 16 community issues resolved in two days. ## Characteristics - **Profiles — Multi-instance Hermes**: Run multiple isolated Hermes installs from one binary. Each profile has its own config, memory, sessions, skills, and gateway service. Token-lock isolation prevents two profiles from clashing on the same bot credential. Commands: `hermes profile create / list / switch / delete / export / import / rename`. - **MCP Server Mode** (`hermes mcp serve`): Exposes Hermes conversations, sessions, and attachments to MCP-compatible clients (Claude Desktop, Cursor, VS Code). Supports stdio and Streamable HTTP transports. Dynamic tool discovery via `notifications/tools/list_changed`. - **Docker Container**: Official Dockerfile supports both CLI and gateway modes with volume-mounted config. - **Ordered Fallback Provider Chain**: Configure multiple inference providers; primary failure auto-fails over to the next. Configured under `fallback_providers` in `config.yaml`. - **Feishu/Lark and WeCom platforms**: Full gateway adapters with event subs, message cards, group chat, callbacks. WeCom uses persistent WebSocket. - **Slack Multi-workspace OAuth**: Single Hermes gateway → multiple workspaces via OAuth token file. - **Telegram Webhook Mode** + group mention gating controls (alternative to long polling). - **Exa Search Backend** added alongside Firecrawl and DuckDuckGo. - **Skills & Credentials on Remote Backends**: Mount skill dirs and credentials into Modal and Docker containers. - **OpenClaw migration guide** expanded into a comprehensive step-by-step doc. ## How to Use Upgrade and create a profile: ```bash pip install -U hermes-agent hermes profile create work hermes -p work ``` Start MCP server for use in Claude Desktop: ```bash hermes mcp serve ``` Run Hermes inside Docker as a long-running gateway: ```bash docker run -d --name hermes --restart unless-stopped \ -v ~/.hermes:/opt/data \ nousresearch/hermes-agent gateway run ``` Release URL: <https://github.com/NousResearch/hermes-agent/releases/tag/v2026.3.30> ## Related Entities - [[entities/version-v0.7.0]] — next release (resilience) - [[entities/version-v0.8.0]] — current release (intelligence) - [[entities/backend-docker]] — Docker backend matured here - [[entities/platform-telegram]], [[entities/platform-slack]] — adapters extended - [[entities/nous-research]] - [[concepts/profiles-multi-instance]], [[concepts/mcp-integration]] <!-- ===== hermes/wiki/entities/version-v0.7.0.md ===== --> --- title: "Hermes Agent v0.7.0" type: entity tags: [version, memory, plugins, security, gateway] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/release-v0.7.0.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview Hermes Agent **v0.7.0** (internal tag `v2026.4.3`) shipped on **2026-04-03** as the "resilience release." Headline themes: a pluggable memory provider interface, credential pool rotation, the Camofox anti-detection browser backend, inline diff previews, and a deep gateway/security hardening pass. 168 PRs merged and 46 issues resolved. ## Characteristics - **Pluggable Memory Provider Interface**: Memory is now an extensible plugin system. Third-party backends (Honcho, vector stores, custom DBs) implement a provider ABC and register via the plugin system. Built-in memory remains the default; [[entities/memory-honcho]] returned to full parity as the reference plugin with profile-scoped host/peer resolution. - **Same-Provider Credential Pools**: Multiple API keys per provider with thread-safe `least_used` rotation. 401 failures trigger automatic key rotation. - **Camofox Anti-Detection Browser Backend**: Local stealth browsing via Camoufox. Persistent sessions, VNC URL discovery for visual debugging, configurable SSRF bypass, auto-install via `hermes tools`. - **Inline Diff Previews**: File write and patch operations show diffs in the tool activity feed. - **API Server Session Continuity & Tool Streaming**: Open WebUI integration streams tool progress in real time and supports `X-Hermes-Session-Id` for persistent sessions. - **ACP Client-Provided MCP Servers**: Editor integrations (VS Code, Zed, JetBrains) can register their own MCP servers, picked up by Hermes as additional tools. - **Gateway Hardening Pass**: Race conditions, photo media delivery, flood control, stuck sessions, approval routing, compression death spirals — all addressed. - **Security: Secret Exfiltration Blocking**: Browser URLs and LLM responses scanned for secret patterns, blocking exfil via URL encoding, base64, or prompt injection. ### New slash commands - `/yolo` — toggle dangerous-command approvals for the session - `/btw` — ephemeral side questions that don't pollute main context - `/profile` — show active profile info without leaving the session ## How to Use Upgrade: ```bash pip install -U hermes-agent ``` Switch memory backend to Honcho via plugin: ```bash hermes honcho setup hermes honcho mode dialectic ``` Configure credential pool in `~/.hermes/config.yaml`: ```yaml providers: openrouter: api_keys: - sk-or-v1-aaa... - sk-or-v1-bbb... rotation: least_used ``` Release URL: <https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.3> ## Related Entities - [[entities/version-v0.6.0]] — prior release (multi-instance) - [[entities/version-v0.8.0]] — next release (intelligence) - [[entities/memory-honcho]] — reference memory plugin restored here - [[concepts/memory-system]] - [[entities/nous-research]] <!-- ===== hermes/wiki/entities/version-v0.8.0.md ===== --> --- title: "Hermes Agent v0.8.0" type: entity tags: [version, model-switching, mcp, oauth, gateway, memory] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/release-v0.8.0.md"] confidence: high hermes_version: "v0.8.0" --- ## Overview Hermes Agent **v0.8.0** (internal tag `v2026.4.8`) shipped on **2026-04-08** as the "intelligence release." Headline themes: background-task auto-notifications, free MiMo v2 Pro on Nous Portal, live model switching across all gateway platforms, native Google AI Studio provider, smart inactivity-based timeouts, native approval buttons, and MCP OAuth 2.1. 209 PRs merged and 82 issues resolved. This is the **current latest release** at the time of writing. ## Characteristics - **Background Process Auto-Notifications (`notify_on_complete`)**: Background tasks (training, test suites, deployments) automatically notify the agent on completion — no polling needed. - **Free Xiaomi MiMo v2 Pro on Nous Portal**: Free-tier model for auxiliary tasks (compression, vision, summarization). - **Live Model Switching (`/model`)**: Switch models and providers mid-session from CLI, Telegram, Discord, Slack, or any gateway. Aggregator-aware resolution prefers OpenRouter/Nous when available. Interactive pickers on Telegram and Discord with inline buttons. - **Self-Optimized GPT/Codex Tool-Use Guidance**: The agent diagnosed and patched 5 GPT/Codex tool-calling failure modes via automated behavioral benchmarking. - **Google AI Studio (Gemini) Native Provider**: Direct Gemini access via Google's AI Studio API with automatic models.dev registry integration. - **Inactivity-Based Agent Timeouts**: Gateway and cron timeouts now track real tool activity, not wall-clock — long active tasks are never killed mid-flight. - **Approval Buttons on Slack & Telegram**: Native platform buttons replace typing `/approve`. Slack preserves thread context; Telegram uses emoji reactions. - **MCP OAuth 2.1 PKCE + OSV Malware Scanning**: Standards-compliant OAuth for MCP servers; automatic malware scanning of MCP extension packages via OSV vulnerability database. - **Centralized Logging & Config Validation**: Structured logging to `~/.hermes/logs/` via `hermes logs`; YAML structure validation at startup. - **Plugin System Expansion**: Plugins can register CLI subcommands, get request-scoped API hooks, prompt for env vars during install, and hook into session lifecycle events. - **Matrix Tier 1**: Reactions, read receipts, rich formatting, room management. Discord adds channel controls and ignored channels. Signal gets full `MEDIA:` tag delivery. Mattermost gets file attachments. - **Security Pass**: SSRF protections, timing attack mitigation, tar traversal prevention, credential leakage guards, cron path-traversal hardening. ### Other notable additions - [[entities/memory-supermemory]] memory provider (multi-container, search_mode, identity template) - Shared thread sessions by default (multi-user thread support across gateway platforms) - Cron pre-run script injection - `execute_code` on remote backends ([[entities/backend-docker]], SSH, [[entities/backend-modal]]) - Browser providers: switched default from Browserbase → Browser Use - MiniMax TTS provider (speech-2.8) - xAI (Grok) prompt caching ## How to Use Upgrade: ```bash pip install -U hermes-agent ``` Switch model mid-session: ``` /model claude-opus-4-6 ``` Run a long task that pings you when done: ``` /background train the LoRA on the corpus, notify_on_complete ``` Release URL: <https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.8> ## Related Entities - [[entities/version-v0.7.0]] — prior release (resilience) - [[entities/version-v0.6.0]] — multi-instance release - [[entities/memory-supermemory]] — added in this release - [[concepts/model-switching]], [[concepts/mcp-integration]] - [[entities/platform-telegram]], [[entities/platform-slack]], [[entities/platform-discord]] - [[entities/nous-research]] <!-- ===== hermes/wiki/entities/version-v0.9.0.md ===== --> --- title: "Hermes Agent v0.9.0 (v2026.4.13)" type: entity tags: [version, well-established] created: 2026-04-13 updated: 2026-04-13 sources: ["raw/release-v0.9.0.md"] confidence: high hermes_version: "v0.9.0" --- # Hermes Agent v0.9.0 (v2026.4.13) ## Overview The "everywhere release" (2026-04-13). Hermes crosses the threshold from a CLI-first tool to a multi-surface platform: browser dashboard, mobile (Termux/Android), iMessage, WeChat. Plus Fast Mode for priority model routing, pluggable context engines, and a security hardening pass. 5-day turnaround from v0.8.0 at an unusually high pace (269 PRs). ## Characteristics | Attribute | Value | |---|---| | Released | 2026-04-13 | | Previous version | [[entities/version-v0.8.0]] (2026-04-08) | | Headline | "The everywhere release" | | PRs merged | 269 | | Issues resolved | 167 | | Commits | 487 | | Files changed | 493 | | Contributors | 24 | | Days since previous | 5 | ### Platform count milestone Hermes now supports **16 messaging platforms**: Telegram, Discord, Slack, WhatsApp, Signal, Email, SMS, DingTalk, Feishu, WeCom, Mattermost, Home Assistant, Webhooks, plus the new **BlueBubbles (iMessage)**, **Weixin (WeChat)**, and **WeCom Callback**. Chinese ecosystem coverage is now complete; Apple ecosystem coverage now matches Android/Windows. ## How to Use ### Upgrading from v0.8.0 ```bash hermes update ``` Expected to be non-breaking for most users. Notable behavior changes: - Credential exhaustion TTL reduced from 24h to 1h — if you have credential pools, rate-limited keys recover ~24x faster. - Config.yaml now takes priority over env vars for auxiliary settings (inverted from v0.8.0 on edge cases). - Matrix users migrate automatically from matrix-nio to mautrix-python — watch for transient E2EE re-trust prompts. ### Opt-in new features - **Web Dashboard:** `hermes dashboard` or access at `http://localhost:<port>` (check docs for port) - **Fast Mode:** toggle with `/fast` in chat (OpenAI Priority Processing + Anthropic fast tier) - **Background watch patterns:** pass `watch_patterns=["PANIC", "listening on"]` to background `terminal(...)` or `process(...)` calls - **Backup your setup:** `hermes backup` → tar.gz you can carry to another machine - **Debug share:** `hermes debug share` → pastebin URL with sanitized report for troubleshooting ### New platform setup - **iMessage (BlueBubbles):** install BlueBubbles server on a Mac, configure in `hermes setup` → Messaging - **WeChat (Weixin):** requires iLink Bot API credentials; setup wizard - **WeCom Callback:** for self-built enterprise apps; configure via setup wizard ## Related Entities - [[entities/version-v0.8.0]] — prior release (2026-04-08) - [[entities/version-v0.7.0]] — (2026-04-03) - [[entities/version-v0.6.0]] — (2026-03-30) - [[entities/nous-research]] — the lab shipping these releases - [[summaries/release-v0.9.0]] — detailed release notes summary <!-- ===== hermes/wiki/log.md ===== --> --- title: "Activity Log" type: log --- # Activity Log Append-only log of KB changes. --- ## 2026-06-10 — removed Obsidian scaffolding from the served wiki Deleted `analytics.md`, `dashboard.md`, `flashcards.md` (Obsidian plugin pages — Dataview/Charts View/Spaced Repetition markup, unusable when served as plain Markdown to agents) and the `journal/` scaffold (template only). `CLAUDE.md` directory layout updated: production/planning material lives at repo root, never under `wiki/` (everything under `wiki/` is served publicly). --- ## 2026-06-10 — docs mirrors refreshed to v0.16.0-era; platform pages + CLI reference bumped; memory synthesis fixed **Mirror refresh:** rebuilt `fetch_docs.py` (the original was lost) — re-fetches every `raw/docs-*.md` from its embedded Source URL, markdownify-based Docusaurus extraction. 106/109 refreshed (Fetched: 2026-06-10, v0.16.0-era); 3 now 404 upstream (`docs-developer-guide-environments`, `docs-user-guide-features-rl-training`, `docs-user-guide-skills-godmode` — old 2026-04-13 copies retained). **Platform pages (12) re-verified against refreshed mirrors, all bumped to v0.16.0:** notable corrections — Telegram reactions now off by default + webhook secret mandatory (GHSA-3vpc-7q5r-276h) + typed approval replaced inline approval buttons; Feishu mention requirement now configurable + reaction flow corrected; WeCom has no token streaming (claim removed); WhatsApp native `send_voice` claim removed (docs document MP3-attachment TTS only); DingTalk install path now `pip install "hermes-agent[dingtalk]"`. Major feature additions integrated across Telegram/Discord/Slack (group allowlist split, RBAC roles, manifest setup, channel skill bindings, voice channels, etc.). **`concepts/cli-reference.md` re-verified, v0.9.0 addendum fully dissolved:** corrections include `hermes web` → `hermes dashboard`, `hermes audit` → `hermes security audit`, `claw migrate --migrate-secrets` now required even with `--preset full`; added lsp, slack manifest, secrets bitwarden, kanban, hooks, backup, checkpoints, bundles, computer-use, postinstall, profile distributions; dropped `sessions optimize` and `kanban swarm` (absent from v0.16.0 docs). **`syntheses/memory-providers-compared.md` rewritten (closes the flagged contradiction):** Holographic corrected to official zero-dependency SQLite FTS5+HRR store (easiest setup); OpenViking corrected to Volcengine/ByteDance AGPL project; ByteRover corrected to local-first free CLI; Mem0 integration is Cloud-only per docs; Hindsight has a free local embedded-Postgres mode. **New finding:** docs now list a ninth provider, **Memori** — included docs-only/unverified; entity page queued in Gaps/TODO. **Index:** Gaps/TODO updated (contradiction closed, Memori + honcho/mem0/supermemory refresh queued, mirror-refresh state recorded). --- ## 2026-06-10 — video-production planning moved out of the served wiki **Triggered by:** owner review — the wiki is served to external agents via the Agent Wikis MCP server, and video-production planning (course outlines, curriculum, slide/script notes, errata tracking) is internal material, not Hermes knowledge. **Moved out of `wiki/` (10 pages → repo-root `presentations/`, not served):** all 9 presentation outlines + `syntheses/masterclass-curriculum.md`. **Scrubbed planning content from served pages:** "features that could become masterclass topics" sections in `summaries/release-v0.9.0.md` and `summaries/release-v0.10.0.md`; "Curriculum impact" section in `summaries/release-v0.12.0.md`; planning framing in `syntheses/hermes-vs-openclaw.md`; outline link in `entities/hermes-desktop-app.md`; planning narratives in this log (two entries redacted to stubs, curriculum/errata blocks removed from ingest entries — KB-maintenance facts retained). **Kept (released content):** video transcript summaries and their raw transcripts, including the 2-hour full course and live masterclass — these document published videos. **Index:** Presentations section removed; counts 118 → 108; syntheses 7 → 6. `CLAUDE.md` updated so future planning docs are written to repo-root `presentations/`, never under `wiki/`. --- ## 2026-06-10 — dangling-wikilink remediation: 28 entity pages built, CLI reference + gateway page refreshed **Triggered by:** an agent consuming the wiki through the Agent Wikis MCP server hit a dead `[[entities/platform-whatsapp]]` link while answering a WhatsApp-setup question, and had to mine a presentation outline for commands because `concepts/cli-reference.md` was a 4-command stub. A full link audit found 28 dangling entity targets (~150 references). **Added wiki pages (28, all `wiki/entities/`):** - Platforms (9): `platform-whatsapp`, `platform-signal`, `platform-email`, `platform-matrix`, `platform-home-assistant`, `platform-dingtalk`, `platform-mattermost`, `platform-feishu`, `platform-wecom` — from the per-platform official docs mirrors (fetched 2026-04-13, v0.9.0-era) + release notes for "(added in vX.Y.Z)" deltas; `hermes_version: v0.9.0`, confidence high. - Backends (3): `backend-ssh`, `backend-singularity`, `backend-daytona` — verified through v0.15.0 release notes. - Inference providers (6): `provider-nous-portal` (v0.16.0), `provider-openrouter`, `provider-anthropic`, `provider-openai-codex`, `provider-google-ai-studio`, `provider-ollama-local` (v0.15.0). - Memory providers (5): `memory-retaindb`, `memory-hindsight` (v0.14.0), `memory-byterover`, `memory-holographic`, `memory-openviking` (v0.12.0). - Nous projects & ecosystem (5): `hermes-self-evolution`, `hermes-paperclip-adapter`, `autonovel` (thin sources, confidence medium, honest gaps flagged inline), `community-workspace`, `openclaw`. **Updated:** - `concepts/cli-reference.md` — rewritten from stub to full grouped command reference from `raw/docs-reference-cli-commands.md` + CLI user guide: gateway service, `hermes whatsapp` QR pairing, `hermes pairing`, auth/model, profiles export/import, skills, cron, diagnostics; post-v0.9 commands listed in a clearly-marked addendum. - `concepts/messaging-gateway.md` — folded the "v0.9.0 additions" banner into the body, platform table expanded 12 → 16, added v0.10–v0.16 gateway-change digest; bumped to v0.16.0. - `concepts/ml-research-pipeline.md` — the raw/ml-research-recipe wikilink (unservable: `raw/` is outside the wiki content dir) converted to a plain-text path reference. - `index.md` — all pending→built moves; counts corrected (KB pages 77 → 118; summaries 22, concepts 18, syntheses 7); registered previously-orphaned `concepts/onchain-workflows` and `syntheses/onchain-stack-recipe`; Gaps/TODO rewritten (10 platform entities remain, v0.8.0 staleness backlog noted). **Contradiction flagged (not fixed):** `syntheses/memory-providers-compared.md` (v0.8.0-era) mischaracterizes Holographic and OpenViking vs the official memory-provider docs — refresh queued in index Gaps/TODO. **Link audit result:** zero dangling wikilinks (remaining `[[as_document]]` and `[[concepts/concept-name]]` occurrences are literal syntax examples inside code spans/fences, not links). --- ## 2026-05-24 — standalone outline added (production planning) Entry redacted 2026-06-10: video-production planning material was moved out of the served wiki to the repo-root `presentations/` directory. One outline page was added on this date; `index.md` counts were bumped accordingly (70 -> 71). --- ## 2026-05-23 — v0.13.0 + v0.14.0 release ingest **Triggered by:** user flagged that the KB had drifted (last ingested 2026-05-01 at v0.12.0). Three weeks elapsed, two releases shipped — v0.13.0 "Tenacity" (2026-05-07) and v0.14.0 "Foundation" (2026-05-16). **Added raw sources (2):** - `raw/release-v0.13.0.md` - `raw/release-v0.14.0.md` **Added wiki pages (4):** - `summaries/release-v0.13.0.md` - `summaries/release-v0.14.0.md` - `entities/version-v0.13.0.md` - `entities/version-v0.14.0.md` **Updated:** - `index.md` — bumped `hermes_version` v0.12.0 → v0.14.0; "Latest verified" → v0.14.0; release notes section now lists 9; versions entity row extended (+2); messaging platforms count 19 → 22 (Google Chat, LINE, SimpleX Chat added to pending); KB page total 66 → 70; summaries count 17 → 19 **Release highlights:** **v0.13.0 (Tenacity) highlights:** - Multi-agent Kanban — durable, multi-profile collaboration board (post-v0.12-revert reimplementation) - `/goal` Ralph loop primitive - Sessions auto-resume after gateway restart - Checkpoints v2 (real pruning, disk guardrails) - Curator subcommands: `archive`, `prune`, `list-archived`; synchronous `hermes curator run` - Post-write delta lint (Python, JSON, YAML, TOML) - `no_agent` cron mode (script-only watchdog) - Google Chat = 20th platform; platform-plugin hooks; IRC + Teams migrated - Providers pluggable (`ProviderProfile` ABC) - `[[as_document]]` skill directive - `transform_llm_output` plugin hook - 7 i18n locales (zh / ja / de / es / fr / uk / tr) - 6 new optional skills (Shopify, here.now, shop-app, Anthropic finance, kanban-video-orchestrator, searxng-search) - Security wave: 8 P0 closures (redaction back ON by default, Discord cross-guild bypass CVSS 8.1, WhatsApp stranger rejection, TOCTOU windows closed) **v0.14.0 (Foundation) highlights:** - `pip install hermes-agent` (PyPI wheel) — canonical install path change for M1 - Native Windows support (early beta) — no WSL required - xAI Grok SuperGrok OAuth provider; grok-4.3 jumps to 1M context window - **OpenAI-compatible local proxy** — `hermes proxy` exposes Claude Pro / ChatGPT Pro / SuperGrok as OpenAI-compatible endpoints (flagship feature) - `x_search` X (Twitter) tool - Microsoft Teams wired end-to-end (Graph auth + webhook + pipeline + outbound) - Debloating wave — lazy-install heavyweight backends - Cold-start cut ~19s; `browser_console` 180x faster; cross-session 1h Claude prompt cache - LINE + SimpleX Chat = 22 platforms total - `/handoff` live session transfer; `/subgoal` appends to active `/goal` - Native button UI for `clarify` on Telegram + Discord - Discord channel history backfill (default on) - `vision_analyze` returns pixels; LSP semantic diagnostics on every write; per-turn file-mutation verifier - Unified `video_generate`; `computer_use` cua-driver works with non-Anthropic providers - Clickable URLs (OSC8); Zed ACP Registry one-click install via uvx - OpenRouter Pareto Code router with `min_coding_score` - NovitaAI new provider; Codex app-server runtime - `huggingface/skills` as trusted default Hub tap - 9 new optional skills (Hyperliquid, Yahoo Finance, api-testing, EVM-multichain, darwinian-evolver, osint-investigation, pinggy-tunnel, watchers, Notion overhaul) - Plugin surface: `ctx.llm`, `tool_override` - Brave Search + DDGS web-search providers - Sudo brute-force block, 3 dangerous-command bypasses closed, tool-error sanitization - Alibaba Cloud → Qwen Cloud rename - i18n total 16 locales (gateway + dashboard + CLI) **NOT updated this pass** (deliberate): - Concept pages (all 14) - Synthesis pages - Per-platform / per-provider entity pages --- ## 2026-05-01 — v0.12.0 release ingest **Triggered by:** v0.12.0 dropped 2026-04-30 ("the Curator release"). User flagged it for ingest. **Added raw source:** - `raw/release-v0.12.0.md` **Added wiki pages (2):** - `summaries/release-v0.12.0.md` - `entities/version-v0.12.0.md` **Updated:** - `index.md` — bumped `hermes_version` v0.11.0 → v0.12.0; "Latest verified" → v0.12.0; release notes section now lists 7; versions entity row extended; messaging platforms count 17 → 19 (Yuanbao, Microsoft Teams added to pending); KB page total 64 → 66; summaries count 16 → 17 **Notable changes flagged in v0.12.0 summary** (concept pages NOT yet rewritten — left for the relevant module's recording session): - **Autonomous Curator** (`hermes curator`, 7-day cycle, `auxiliary.curator` slot, `hermes curator status`, reports at `logs/curator/`) - Self-improvement loop substantially upgraded (rubric-based, scoped to memory+skills, runtime inheritance fixed) - Skills UX: `hermes skills install <url>`, `/reload-skills`, `skill_manage` pinning + external_dirs editing, `hermes skills list` enabled/disabled status - ComfyUI v5 + TouchDesigner-MCP moved from optional to bundled-by-default - New community-bundled skills: Humanizer, claude-design, design-md, airtable, pretext, spike, sketch - 4 new providers: GMI Cloud, Azure AI Foundry, MiniMax OAuth, Tencent Tokenhub; LM Studio upgraded to first-class - 19 platforms (added Yuanbao + Microsoft Teams via plugin-host architecture) - New auxiliary slot: `curator` (and `flush_memories` was removed entirely) - Spotify (7 native tools + bundled skill) and Google Meet (bundled plugin) integrations - `hermes -z <prompt>` non-interactive one-shot mode - Models dashboard tab + in-browser model config - Remote model catalog manifest - Configurable `prompt_caching.cache_ttl` (5m default, 1h opt-in) - Bundled Langfuse + hermes-achievements plugins - TTS provider registry + Piper local TTS - Vercel Sandbox backend for `execute_code` - Secret redaction off by default (was a footgun, opt-in via `redaction.enabled: true`) - TUI cold start ~57% faster + LaTeX rendering, `/reload`, light-terminal auto-detect, voice mode parity **NOT updated this pass** (deliberate): - Concept pages (`skills-system`, `self-improvement-loop`, `auxiliary-models`, `messaging-gateway`, `model-switching`, `memory-system`, `cron-scheduling`) - Synthesis pages - Per-platform/provider entity pages --- ## 2026-04-28 — v0.10.0 + v0.11.0 release ingest **Triggered by:** KB review surfaced that the KB was pinned at v0.9.0 while live releases had moved on to v0.11.0. **Added raw sources (2):** - `raw/release-v0.10.0.md` — Tool Gateway release (2026-04-16) - `raw/release-v0.11.0.md` — Interface release (2026-04-23) **Added wiki pages (4):** - `summaries/release-v0.10.0.md` - `summaries/release-v0.11.0.md` - `entities/version-v0.10.0.md` - `entities/version-v0.11.0.md` **Updated:** - `index.md` — bumped `hermes_version` v0.8.0 → v0.11.0; "Latest verified" → v0.11.0; release notes section now lists 6; versions entity row extended; messaging platforms count 12 → 17 (QQBot, BlueBubbles, Weixin, WeCom Callback, SMS added to pending); KB page total 60 → 64 **Notable changes flagged in v0.11.0 summary** (concept pages NOT yet rewritten — left for the relevant module's recording session): - Auxiliary `auto` routing now defaults to main model for all users (was provider-side cheap default for aggregator users) - 17th platform: QQBot - TUI rewrite (`hermes --tui`) — Ink/React with JSON-RPC backend - New slash commands: `/steer` - Plugin surface expansion: `register_command`, `dispatch_tool`, `pre_tool_call` veto, `transform_tool_result`, `transform_terminal_output`, image_gen backends, dashboard plugins - Shell hooks (no-Python lifecycle hook scripts) - Webhook direct-delivery mode (zero-LLM push) - Subagent orchestrator role + `max_spawn_depth` + cross-agent file coordination - Cron `wakeAgent` gate + per-job `enabled_toolsets` - 5 new providers: NVIDIA NIM, Arcee AI, Step Plan, Gemini CLI OAuth, Vercel ai-gateway - AWS Bedrock native via Transport ABC layer - GPT-5.5 over Codex OAuth - Honcho overhaul (context injection, 5-tool surface, session isolation) **NOT updated this pass** (deliberate): - Concept pages (`auxiliary-models`, `model-switching`, `messaging-gateway`, `skills-system`, `subagents-delegation`, `cron-scheduling`, `memory-system`) - Synthesis pages --- ## 2026-04-12 — Full ingest complete **Added raw sources (19 total):** - 8 YouTube video transcripts (txt, cleaned from auto-captions) - 3 release notes (v0.6.0, v0.7.0, v0.8.0 as md) - 2 community inventories (get-hermes.ai community page, awesome-hermes-agent README) - 5 pre-KB research dumps from `D:/youtube/16 - Hermes/research/` (install/setup, skills, tools/MCP/cron/subagents, deployment/platforms, community) - 1 official OpenClaw migration doc from the NousResearch/hermes-agent repo **Ingest run (8 parallel agents):** Summaries (13 pages written): - All 8 video transcripts summarized - All 3 release notes summarized - Community resources + awesome-hermes-agent inventories summarized Concepts (14 pages written): - Core features: skills-system, memory-system, cron-scheduling, subagents-delegation, mcp-integration, model-switching, migration-from-openclaw, self-improvement-loop - Infrastructure: deployment-backends, messaging-gateway, profiles-multi-instance, approval-system - Research & ML: ml-research-pipeline, local-models-airplane-mode Entities (19 pages written): - Versions: v0.6.0, v0.7.0, v0.8.0 - Backends (3 of 6): local, docker, modal - Platforms (3 of 12): telegram, discord, slack - Memory providers (3 of 8): honcho, supermemory, mem0 - Nous Research lab + 6 top community projects (orange-book, awesome-hermes, mission-control, webui, agency-agents-zh, gbrain) Syntheses (5 pages written): - hermes-vs-openclaw (feature comparison, "pick X if" recommendations) - memory-providers-compared (8 backends matrix) - deployment-backends-compared (6 backends, cost/isolation/persistence tradeoffs) - local-stack-playbook (end-to-end offline recipe) - one production-planning synthesis (moved out of the served wiki 2026-06-10) **Issues / notes:** - `memory-mem0` entity set to `confidence: low` — mem0 isn't directly named in raw sources, inferred from v0.7.0 pluggable memory ABC - `memory-supermemory` set to `confidence: medium` — only a paragraph in v0.8.0 release notes - `concepts/self-improvement-loop` set to `confidence: medium` — much of the GAPA framing came from community transcripts rather than the official repo; re-verify in a future pass - `concepts/migration-from-openclaw` was written from conversation-provided specifics before the official doc was saved to raw; now backed by `raw/migration-openclaw-official.md` — confidence justified as high - Forward-compatible wiki links exist to ~25 pending entity pages (see index.md Gaps/TODO) **Next actions:** - Fill pending entity pages on-demand as modules get produced - Watch for Hermes v0.9.0 release; ingest when it drops and bump affected pages --- ## 2026-04-12 (later) — production-planning synthesis revised Entry redacted 2026-06-10: production-planning content moved out of the served wiki to repo-root `presentations/`. --- ## 2026-04-13 — Backfill ingest (docs mirror, ML research, onchain) **Added raw sources:** Official documentation mirror — **109 pages total** from `hermes-agent.nousresearch.com/docs`: - Developer guide (17 pages): acp-internals, adding-platform-adapters, adding-providers, adding-tools, agent-loop, architecture, context-compression-and-caching, context-engine-plugin, contributing, cron-internals, environments, gateway-internals, memory-provider-plugin, prompt-assembly, provider-runtime, session-storage, tools-runtime, trajectory-format - Getting started (7 pages): index, installation, learning-path, nix-setup, quickstart, termux, updating - User guide root (8 pages): configuration, sessions, profiles, git-worktrees, docker, security, checkpoints-and-rollback, cli - User guide features (29 pages): overview, tools, skills, memory, memory-providers, context-files, context-references, personality, skins, plugins, cron, voice-mode, web-dashboard, rl-training, mcp, acp, api-server, honcho, provider-routing, fallback-providers, delegation, code-execution, hooks, batch-processing, browser, vision, image-generation, tts, credential-pools - User guide messaging (19 pages): index + telegram, discord, slack, whatsapp, signal, email, sms, homeassistant, mattermost, matrix, dingtalk, feishu, wecom, wecom-callback, weixin, bluebubbles, open-webui, webhooks - User guide skills (1 page): godmode - Reference (9 pages): cli-commands, slash-commands, profile-commands, environment-variables, tools-reference, toolsets-reference, mcp-config-reference, skills-catalog, optional-skills-catalog - Guides / tutorials (14 pages): tips, local-llm-on-mac, daily-briefing-bot, team-telegram-assistant, python-library, use-mcp-with-hermes, use-soul-with-hermes, use-voice-mode-with-hermes, build-a-hermes-plugin, automate-with-cron, cron-troubleshooting, work-with-skills, delegation-patterns, migrate-from-openclaw - Integrations (2 pages): index, providers - Reference-faq, skills-index, docs-index Mirror done via `D:/hermes-kb/fetch_docs.py` (stdlib Python, 8-thread parallel fetch + Docusaurus HTML extraction → markdown). **ML research deep-dive** — added `raw/ml-research-recipe.md` with: - Tinker signup/access path (auth.thinkingmachines.ai) - End-to-end Tinker + Atropos fine-tune recipe with verbatim commands and YAML configs - Non-Tinker fallback (Axolotl/Unsloth/TRL) for users without Tinker access - Real artifacts verified (Qwen3-8B default, LoRA rank 32, lr 4e-5, 2500 steps, SGLang :8001, Atropos :8000) - Updated `concepts/ml-research-pipeline.md` to replace hand-wavy sections with concrete recipes; bumped `updated` to 2026-04-13 - Flagged: Tinker pricing not verified (requires auth to fetch rate card) **Onchain ecosystem research** — added: - `raw/onchain-ecosystem.md` — comprehensive inventory: Hermes's 2 first-party blockchain skills (solana, base), 6 community onchain projects, 100+ relevant MCP servers across Solana + EVM ecosystems - `wiki/concepts/onchain-workflows.md` — new concept page, `confidence: medium` - `wiki/syntheses/onchain-stack-recipe.md` — 6 practical recipes (A-F) by chain and use case - Key finding: Hermes first-party blockchain footprint is tiny (2 skills), but third-party MCP servers are abundant. Read-workflows are production-ready; write/trading workflows are all experimental with external-signer patterns. **Still pending:** - Update `wiki/index.md` to catalog the 81 new docs mirror pages (they exist in raw/ only; not yet cross-referenced in summary pages) - Could ingest the mirror into proper summary pages on next pass — lots of material now, could easily generate another 20-30 summary pages from the docs site alone - Main gap remaining: none critical --- ## 2026-04-13 — Added `concepts/auxiliary-models.md` User flagged auxiliary models as an under-documented topic. Verified details from `docs-user-guide-configuration.md` § Auxiliary Models and `docs-developer-guide-provider-runtime.md`. **Key verified facts:** - 8 task slots: vision, web_extract, compression, approval, session_search, skills_hub, mcp, flush_memories - 5 config knobs per slot: provider, model, base_url, api_key, timeout (+ `download_timeout` for vision) - Default auto-chain: OpenRouter → Nous → Codex, with Gemini Flash as the default model - Default timeouts: vision 30s, web_extract 360s, approval 30s, compression 120s, others 30s - `"main"` is a special value usable only in auxiliary/compression/fallback_model blocks - Env var overrides are vision + web_extract only (the other 6 are config.yaml-only) **Major footgun documented:** there are TWO compression configs — top-level `compression:` (sets the summary model) vs. `auxiliary.compression:` (timeout only). Setting model under auxiliary.compression does nothing. Also added `concepts/auxiliary-models` link to `wiki/index.md`. --- ## 2026-04-13 — Ingested Hermes v0.9.0 release New Hermes release dropped today — v0.9.0 (tag v2026.4.13). The "everywhere release": 487 commits, 269 PRs, 167 issues resolved, 24 contributors, 5 days since v0.8.0. **Added raw source:** - `raw/release-v0.9.0.md` — full release notes **Added wiki pages:** - `wiki/summaries/release-v0.9.0.md` — structured summary - `wiki/entities/version-v0.9.0.md` — version entity **Updated existing pages** (bumped `hermes_version` to v0.9.0, added "v0.9.0 additions" section at top for visibility): - `wiki/concepts/messaging-gateway.md` — platform count now 16 (adds BlueBubbles/iMessage, Weixin/WeChat, WeCom Callback), unified proxy support, WSL-aware gateway, per-platform verbosity, Matrix migration to mautrix-python - `wiki/concepts/model-switching.md` — Fast Mode (`/fast`), native xAI (Grok) and Xiaomi MiMo providers elevated, credential TTL reduced 24h→1h, `/model` switch persistence fix, native model picker modal **Updated index:** version number, PR summary counts, added links to new summary + entity. **Major v0.9.0 headline features:** - Local Web Dashboard (browser UI — pitched as easiest on-ramp to Hermes) - Fast Mode (priority routing for OpenAI + Anthropic) - iMessage via BlueBubbles (Apple ecosystem) - Termux/Android (Hermes on your phone) - Background Process Monitoring (`watch_patterns`) - Pluggable Context Engine **Concept pages NOT yet updated** but affected at the edges (flag for future pass): - `concepts/mcp-integration` — `hermes mcp add --env/--preset`, tool name deconfliction - `concepts/subagents-delegation` — `watch_patterns` is more prominent now - `concepts/migration-from-openclaw` — dry-run preview before executing (was a UX bug fix) - `concepts/auxiliary-models` — config.yaml takes priority over env vars - `syntheses/hermes-vs-openclaw` — platform count deltas (16 vs 24) **Still pending** from prior passes: - Entity pages for remaining backends, platforms, memory providers, inference providers, community projects --- ## 2026-06-04 — v0.15.2 (v2026.5.29.2) patch ingest **Triggered by:** kb-scout flagged the v2026.5.29.2 patch release (score 89/100, classification `update` → ingest path). Patch is a small but real packaging fix on top of the v0.15.0 release; treated as a low-risk augmentation of existing v0.15.0 KB coverage, not a standalone release. **Source:** - v2026.5.29.2 release notes: https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29.2 - Compare v2026.5.29…v2026.5.29.2: https://github.com/NousResearch/hermes-agent/compare/v2026.5.29...v2026.5.29.2 - Commit 827f7f07: https://github.com/NousResearch/hermes-agent/commit/827f7f07825be57108cbea18325e8f5e9fb5d2f2 - Issue #34034: https://github.com/NousResearch/hermes-agent/issues/34034 **Updated wiki pages (2):** - `wiki/entities/version-v0.15.0.md` — expanded v0.15.2 mention in Overview; Patches row in Characteristics table now names v0.15.2 as the wheel + sdist plugin-manifest packaging fix with `MANIFEST.in` + `pyproject.toml` detail and bundled manifest count 0 → 69; new `### Patch upgrades` subsection in How to Use with the v0.15.1 → v0.15.2 upgrade note; bumped `hermes_version` v0.15.0 → v0.15.2, `updated` 2026-06-01 → 2026-06-04, sources extended with v2026.5.29.2 release + commit URLs. - `wiki/summaries/release-v0.15.0.md` — Key Points sentence now names v0.15.2 / v2026.5.29.2 with the wheel + sdist distribution detail; new `### Patch detail — v0.15.2 (v2026.5.29.2)` subsection with cause/regression, fix channels (wheel package-data + sdist MANIFEST.in), regression test coverage, files changed, measured impact (manifest count 0 → 69), and release/compare/commit/issue links; Source Metadata extended with patch evidence URLs; bumped `hermes_version` v0.15.0 → v0.15.2, `updated` 2026-06-01 → 2026-06-04. **Pages NOT updated (per approved plan):** - `wiki/index.md` — the master index already names v0.15.1/v0.15.2 as same-day patches; adding wheel/sdist detail there would overfit the catalog and is intentionally deferred. - `wiki/entities/version-v0.15.2.md` and `wiki/summaries/release-v0.15.2.md` — **not** created; this ingest is an update to v0.15.0 coverage, not a new major release or concept. - `raw/` — not mutated; cited GitHub URLs as primary source. **Verified facts preserved:** - Wheel packaging adds `plugins` package-data globs for `**/plugin.yaml` and `**/plugin.yml`. - sdist packaging adds `MANIFEST.in` `recursive-include plugins plugin.yaml plugin.yml`. - Files changed: `MANIFEST.in`, `pyproject.toml`, `tests/test_packaging_metadata.py`. - Before/after wheel build: bundled plugin manifest count 0 → 69. - v0.15.2 is a patch on top of v0.15.0; no functional change beyond packaging. - No config migration required for upgrade. **Kanban chain:** - Item: `hermes-agent-v0-15-2-v2026-5-29-2-patch-release` (status: `approved`) - Stage: `write_pages` (this task, t_797ca87d) → `verify_lint` (t_1f37d717) → `commit` (t_ac15c401) - Branch: `ingest/hermes-agent-v0-15-2-v2026-5-29-2-patch-release` (created from `main`) --- ## 2026-06-04 — v0.15.1 (v2026.5.29) "The Patch Release" ingest **Triggered by:** kb-scout flagged the v2026.5.29 patch release (score 95/100, classification `update` → ingest path). Patch is a broad hotfix round on top of the v0.15.0 release covering dashboard 401 reload loop, explicit Docker insecure opt-in, Docker MCP bare-command resolution, dashboard skills page/category sidebar restoration, skills.sh catalog 858→19,932, Kanban worker SIGTERM, `/model` picker/listing unification, `/yolo` mid-session bypass, and `.md` media delivery restoration. 28 commits, 21 PRs, 9 contributors. Treated as a low-risk augmentation of existing v0.15.0 KB coverage, not a standalone release. **Source:** - v2026.5.29 release notes: https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29 **Updated wiki pages (6):** - `wiki/concepts/skills-system.md` — added v0.15.1 note in the cross-agent ecosystem section explaining the skills.sh sitemap walk (catalog 858→19,932) and a matching "first fetch is larger / slower" risk note; bumped `hermes_version` v0.8.0 → v0.15.1, `updated` 2026-04-12 → 2026-06-04, sources extended with v2026.5.29 URL. - `wiki/concepts/deployment-backends.md` — added Docker dashboard insecure-mode safety note in Risks & Pitfalls (binding to `0.0.0.0` no longer implies insecure access; requires `HERMES_DASHBOARD_INSECURE=1` opt-in) with cross-link to `[[entities/backend-docker]]`; bumped `hermes_version` v0.8.0 → v0.15.1, `updated` 2026-04-12 → 2026-06-04, sources extended with v2026.5.29 URL. - `wiki/entities/backend-docker.md` — added `HERMES_DASHBOARD_INSECURE=1` setup/security note in `How to Use` and a parallel note in `Critical limitation` (without duplicating the concept page); bumped `hermes_version` v0.8.0 → v0.15.1, `updated` 2026-04-12 → 2026-06-04, sources extended with v2026.5.29 URL. - `wiki/concepts/mcp-integration.md` — added Docker stdio command-resolution note (bare `npx` / `npm` / `node` now resolve against `/usr/local/bin` inside the Docker image); bumped `hermes_version` v0.8.0 → v0.15.1, `updated` 2026-04-12 → 2026-06-04, sources extended with v2026.5.29 URL. - `wiki/concepts/model-switching.md` — added v0.15.1 section at top with `/model` picker/listing disk-cache unification and `/yolo` mid-session bypass (with cross-link to `[[concepts/approval-system]]` for the deeper approval framing); bumped `hermes_version` v0.9.0 → v0.15.1, `updated` 2026-04-13 → 2026-06-04, sources extended with v2026.5.29 URL. - `wiki/entities/version-v0.15.0.md` — expanded Overview patch sentence to name all v0.15.1 hotfix areas (dashboard 401 loop, Docker insecure opt-in, Docker MCP bare-command resolution, skills page/catalog restore, Kanban SIGTERM, `/model` unification, `/yolo` mid-session); expanded the Patches row in Characteristics; added v0.15.0 → v0.15.1 upgrade bullet in the Patch upgrades section with the explicit `HERMES_DASHBOARD_INSECURE=1` opt-in note; sources extended with v2026.5.29 URL; `hermes_version` **left at v0.15.2** (the value v0.15.2 patch set) per the plan's "coordinate so the final value does not move backward" rule. **Pages NOT updated (per approved plan):** - `wiki/summaries/release-v0.15.0.md` — plan says do not rewrite; v0.15.1 is already named at summary level and the v0.15.2 patch owns the patch-detail expansion there. - `wiki/index.md` — master catalog already names v0.15.1/v0.15.2 as same-day patches; no count change expected. - `raw/` — not mutated; cited the official GitHub release as primary source. **Lint note (read by verify_lint stage):** the kb_lint check on the 6 modified pages reports 12 dead-link errors, all in `concepts/deployment-backends.md` and `concepts/model-switching.md`. All 12 are PRE-EXISTING on main (verified by stashing my changes and re-running kb_lint on the unchanged main state — same 12 errors). They reference pending entity pages (`entities/backend-ssh`, `entities/backend-singularity`, `entities/backend-daytona`, `entities/provider-nous-portal`, `entities/provider-openrouter`, `entities/provider-anthropic`, `entities/provider-openai-codex`, `entities/provider-google-ai-studio`, `entities/provider-ollama-local`) that the KB Gaps/TODO list already tracks. None of the 12 were introduced by v0.15.1. The v0.15.1 plan does not authorize adding those entity pages, so the proper resolution is either to add a separate backlog task for them, or to treat the dead links as known out-of-scope debt and unblock. My v0.15.1-added cross-links (`[[entities/backend-docker]]`, `[[concepts/deployment-backends]]`, `[[concepts/approval-system]]`) all resolve. **Verified facts preserved:** - Dashboard 401 reload-loop fix (closes #34206, #34202; PR #30698). - Docker dashboard insecure opt-in via `HERMES_DASHBOARD_INSECURE=1` (PRs #34188, #34204) — explicit env, never derived from bind host. - Docker MCP bare-command resolution against `/usr/local/bin` for `npx`/`npm`/`node` (PR #34186). - Dashboard skills page source pills and category sidebar restoration (PR #34194). - skills.sh catalog 858 → 19,932 via sitemap walk (PR #34025). - Kanban worker SIGTERM termination fix, closes #28181 (PR #34045). - `/yolo` mid-session bypass (PR #33931). - `/model` picker/listing unified with disk cache (PR #33867). - `.md` media delivery restored (PR #34022). - v0.15.1 is a patch on top of v0.15.0; no new features, only fixes. - Breaking change to be aware of: Docker dashboard insecure mode requires explicit `HERMES_DASHBOARD_INSECURE=1`; binding to `0.0.0.0` no longer implies it. **Kanban chain:** - Item: `hermes-agent-v0-15-1-v2026-5-29-the-patch-release` (status: `approved`) - Stage: `write_pages` (this task, t_6320a968) → `verify_lint` (t_6342f622) → `commit` (t_8937d720) - Branch: `ingest/hermes-agent-v0-15-1-v2026-5-29-the-patch-release` (created from `ingest/hermes-agent-v0-15-2-v2026-5-29-2-patch-release` so v0.15.2 patches are inherited as the base) ## 2026-06-09 — medium-ring/operator-docs merged (cyberbrain retention ladder) - Added: concepts/cli-reference, concepts/configuration-reference, summaries/skills-catalog, syntheses/cron-troubleshooting-checklist (operator/developer ring; medium = default rung per cyberbrain retention experiment). - Index entries added; committed via branch merge e996688. <!-- ===== hermes/wiki/summaries/awesome-hermes-agent.md ===== --> --- title: "Awesome Hermes Agent — Ecosystem Inventory" type: summary tags: [skills, mcp, tools, local-models, well-established, foundational, developer] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/awesome-hermes-agent-readme.md"] confidence: high hermes_version: "v0.8.0" --- # Awesome Hermes Agent — Ecosystem Inventory The [`awesome-hermes-agent`](https://github.com/0xNyk/awesome-hermes-agent) README is a curated directory of every known skill, plugin, tool, integration, fork, deployment helper, guide, and operational playbook in the Hermes ecosystem. Maintained by 0xNyk/Builderz. Licensed CC BY 4.0. Last ecosystem review dated 2026-04-03 at Hermes v0.6.0 (v2026.3.30) with the core repo reported at **23k+ GitHub stars**. Each resource is tagged `production` (stable, safe to depend on), `beta` (works but evolving), or `experimental` (learn from, don't depend on). ## Key Points ### Recommended three-step onboarding path The README opens with a "Where do I start?" path for new users: 1. **Get running** — follow the Official Docs quickstart at `hermes-agent.nousresearch.com/docs/`. 2. **Add your first skills** — install `wondelai/skills` (380+ stars, production, cross-platform) or try `litprog-skill` (75+ stars, beta) for literate-programming flows. 3. **Get a GUI** — either `hermes-workspace` (500+ stars, production — Hermes-native chat/terminal/memory/skills manager) or `mission-control` by builderz-labs (3.7k+ stars, production — broader agent orchestration dashboard with fleet management, task dispatch, cost tracking). ### Official Resources (maintained by Nous Research) - **Hermes Agent** — the core repo, `NousResearch/hermes-agent`, 23k+ stars. Self-improving agent with closed learning loop, multi-platform gateway (Telegram, Discord, Slack, WhatsApp, Signal, Feishu/Lark, WeCom), six terminal backends, cron scheduling, MCP, profiles, fallback providers, native `hermes claw migrate` from OpenClaw. - **autonovel** — autonomous novel-writing pipeline built on Hermes; generates 100k+ word manuscripts end-to-end. See [[entities/autonovel]]. - **hermes-paperclip-adapter** — run Hermes as a managed employee inside a Paperclip company. See [[entities/hermes-paperclip-adapter]]. - **hermes-agent-self-evolution** — evolutionary self-improvement using DSPy and GEPA (Genetic Evolution of Prompt Architectures). See [[entities/hermes-self-evolution]]. - **Official Documentation** — at `hermes-agent.nousresearch.com/docs/`. Covers quickstart, CLI, config, messaging gateway, security, tools, skills, memory, MCP, cron, ACP, API server, architecture. - **Release Notes** — on the GitHub releases page. - **tinker-atropos** — standalone Atropos integration with Thinking Machines' Tinker API. RL training infrastructure for fine-tuning tool-calling models on real agent trajectories. - **Skills Hub** — `agentskills.io`, the open standard for agent skills. Compatible across Hermes, Claude Code, Cursor, Codex, and other agents. - **Discord** — `discord.gg/NousResearch` for bug reports and community. ### Skills & Plugins — Community Skills (9 projects) - **hermes-plugins** by 42-evey *(beta)* — goal management, inter-agent bridge, model selection, cost control — four plugins covering operational needs. - **hermes-skill-factory** by Romanescu11 *(beta)* — meta-skill that auto-generates reusable skills from your repeated workflows. - **litprog-skill** by tlehman *(beta, 75+ stars)* — literate programming across Claude Code, OpenCode, Hermes. - **Wizards-of-the-Ghosts** by Hmbown *(experimental)* — fantasy-themed wrapper over refactor/lint/test operations. - **super-hermes** by Cranot *(experimental)* — adds meta-reasoning that makes Hermes write its own analytical prompts. - **hermes-life-os** by Lethe044 *(experimental)* — personal OS agent tracking daily routines. - **hermes-incident-commander** by Lethe044 *(beta)* — autonomous SRE agent for production incident detection and self-healing. - **hermes-dojo** by Yonkoo11 *(beta)* — self-improvement monitor that identifies weak skills and iterates on them. - **hermes-skill-marketplace** by Lethe044 *(experimental)* — agent that writes, tests, and publishes new skills autonomously. ### Skills & Plugins — agentskills.io Ecosystem (12 projects) - **wondelai/skills** *(production)* — cross-platform skills for Claude Code and agentskills.io-compatible platforms. The recommended first install for new users. - **Anthropic-Cybersecurity-Skills** by mukul975 *(production, 4k+ stars)* — 753+ structured cybersecurity skills mapped to MITRE ATT&CK. The most comprehensive security skills collection available. - **chainlink-agent-skills** by Chainlink / smartcontractkit *(production)* — official Chainlink skills: oracle network data, CCIP, smart contract interaction. - **black-forest-labs/skills** by Black Forest Labs *(production)* — official FLUX image generation skills. - **pydantic-ai-skills** by DougTrajano *(production)* — Pydantic AI with agentskills.io support; type-safe schema validation for skill I/O. - **cognify-skills** by Yarmoluk *(beta)* — 19 business-operations skills: CRM, invoicing, project management. - **execplan-skill** by tiann *(beta)* — long-running task lifecycle with progress tracking, checkpoints, failure recovery. - **maestro** by ReinaMacCredy *(beta)* — skill orchestration with Conductor planning + Beads tracking. - **bmad-module-skill-forge** by armelhbobdad *(beta)* — converts repos/docs into agentskills.io-compliant skills. - **Agentic-MCP-Skill** by cablate *(beta)* — MCP client with agentskills.io validation; bridges MCP tool servers to the skills standard. - **ripley-xmr-gateway** by KYC-rip *(experimental)* — Monero (XMR) blockchain gateway for private crypto transactions from agent workflows. - **skillsdotnet** by PederHP *(beta)* — C# implementation of agentskills.io with MCP integration. ### Skills & Plugins — Plugins (8 projects) - **plur** by plur-ai *(beta)* — shared memory layer with open YAML engram format. - **hermes-payguard** by nativ3ai *(experimental)* — safe USDC and x402 payments with spending limits and approval flows. - **hermes-web-search-plus** by robbyczgw-cla *(beta)* — multi-provider web search across Serper, Tavily, Exa with intelligent routing. - **hermes-weather-plugin** by FahrenheitResearch *(beta)* — NWS model imagery, NEXRAD radar, meteorological calculations. - **hermes-wxtrain-plugin** by FahrenheitResearch *(experimental)* — ML pipeline for building training datasets from HRRR/GFS/ERA5 weather models. - **hermes-plugin-chrome-profiles** by anpicasso *(experimental)* — switch browser tools between Chrome profiles via CDP. - **hermes-cloudflare** by raulvidis *(experimental)* — headless browsing through Cloudflare's infrastructure. - **evey-bridge-plugin** by 42-evey *(beta)* — Claude Code plugin bridging with Evey/Hermes so they share context and hand off tasks. ### Skill Registries & Discovery (2 projects) - **hermeshub** by amanning3390 *(beta)* — community hub for browsing, sharing, and installing Hermes skills. - **skilldock.io** by chigwell *(production)* — registry of reusable AI skills compatible with OpenClaw, Claude Code, Hermes. Established cross-platform marketplace. ### Tools & Utilities (11 projects) - **hermes-workspace** by outsourc-e *(production, 500+ stars)* — web workspace with chat, terminal, memory browser, skills manager, inspector. Most complete GUI for Hermes. Built during the Nous Hackathon 2026. See [[entities/community-workspace]]. - **mission-control** by builderz-labs *(production, 3.7k+ stars)* — open-source agent-orchestration dashboard: fleet management, task dispatch, cost tracking, multi-agent coordination. Self-hosted, SQLite-powered. - **hermes-neurovision** by Tranquil-Flow *(experimental)* — terminal neurovisualizer with 42 animated themes; decorative agent-activity overlays. - **lintlang** by roli-lpci *(beta)* — static linter for AI agent configs and prompts with HERM v1.1 scoring. - **nix-hermes-agent** by 0xrsydn *(beta)* — Nix package and NixOS module for fully reproducible deployments via Nix flakes. - **openclaw-to-hermes** by 0xNyk *(beta)* — community migration tool from OpenClaw. Built when the native `hermes-migrate` had critical bugs; for Hermes v0.3.0+, prefer the native `hermes claw migrate` command. - **vessel-browser** by unmodeled-tyler *(experimental)* — AI-native Linux browser with MCP control and autonomous browsing. Full browser built for agent use. - **portable-hermes-agent** by rookiemann *(beta)* — Windows desktop app bundling 100 tools, GUI, local models, ComfyUI, workflows in one portable package. - **hermes-webui** by sanchomuzax *(beta)* — lightweight process-monitoring and config dashboard; ops-focused alternative to hermes-workspace. See [[entities/community-webui]]. - **evey-setup** by 42-evey *(beta)* — one-command setup for the full hermes-agent stack with free models and 29 plugins. - **flowstate-qmd** by amanning3390 *(beta)* — anticipatory memory with RAG and vector search; pre-fetches context before queries hit the agent. ### Tools & Utilities — Deployment (4 projects) - **hermes-agent-docker** by xmbshwll *(beta)* — minimal Docker sandbox image. - **hermes-agent-template** by Crustocean *(beta)* — production-ready Docker image for Crustocean cloud deployments. - **portainer-stack-hermes** by ellickjohnson *(experimental)* — Docker Compose + Portainer + ttyd web terminal. - **hermes-autonomous-server** by JackTheGit *(experimental)* — headless Hermes with systemd and cron on Linux. ### Integrations & Bridges (10 projects) - **hermes-android** by raulvidis *(beta)* — Android device bridge with full Python toolset. - **hermes-miniverse** by teknium1 *(beta)* — Miniverse pixel-worlds bridge. By a Nous Research co-founder. - **hindsight** by Vectorize *(production)* — long-term memory layer with retain/recall/reflect workflows, integrated via plugin or MCP; supports semantic, graph, and temporal retrieval. See [[entities/memory-hindsight]]. - **honcho-self-hosted** by elkimek *(beta)* — self-hosted Honcho memory backend for Hermes. See [[entities/memory-honcho]]. - **zouroboros-swarm-executors** by marlandoj *(experimental)* — local executor bridge for Claude Code + Hermes task handoff. - **reina** by Crustocean *(beta)* — autonomous Hermes-powered agent for the Crustocean platform. - **hermes-agent-acp-skill** by Rainhoole *(beta)* — multi-agent delegation skill bridging Hermes, Codex, Claude Code; routes subtasks to the best-suited agent. - **hermes-blockchain-oracle** by gizdusum *(experimental)* — Solana intelligence MCP server with on-chain analytics and wallet data. - **hermes-council** by Ridwannurudeen *(experimental)* — adversarial multi-perspective council MCP server; multiple AI viewpoints debate before commitment. - **NemoHermes** by Hmbown *(experimental)* — NVIDIA capability registry and Spark-aware routing layer for routing compute-heavy tasks to GPU infrastructure. ### Multi-Agent & Swarms (4 projects) - **Ankh.md** by Abruptive *(experimental)* — TAW Agent x Hermes multi-agent swarm framework. - **gladiator** by runtimenoteslabs *(experimental)* — two autonomous AI companies compete for GitHub stars. Hackathon project. - **bigiron** by supermodeltools *(beta)* — AI-native SDLC with Hermes and Supermodel code graph. - **opencode-hermes-multiagent** by 1ilkhamov *(beta)* — 17 specialised agents for OpenCode with structured interfaces. ### Domain Applications (11 projects) - **hermes-embodied** by bryercowan *(experimental)* — self-improving robotics via VLA-model fine-tuning. Nous Hackathon. - **hermescraft** by bigph00t *(beta)* — embodied Minecraft AI companion with persistent memory. - **Hermes-mars-rover** by Snehal707 *(experimental)* — Mars rover simulator with ROS2 + Gazebo; uses skill-creation loop for nav improvement. - **anihermes** by rodmarkun *(beta)* — local anime server/tracker with NL interface. - **job-scout-agent** by Christabel337 *(beta)* — autonomous job-hunting agent. - **hermes-ai-infrastructure-monitoring-toolkit** by JackTheGit *(beta)* — infra monitoring, cost forecasting, Telegram alerts via cron. - **hermes-genesis** by Ridwannurudeen *(experimental)* — procedural autonomous living-world engine. - **hermes-legal** by Lethe044 *(experimental)* — English/Turkish contract risk analysis. - **hermes-startup-architect** by dlkakbs *(beta)* — investor-ready kit generator: market analysis, pitch deck, financials. - **mercury** by hxsteric *(beta)* — multi-chain blockchain cash-flow analyzer with WebGL dashboard. - **hermes-research-agent** by Aum08Desai *(experimental)* — autonomous LLM research agent handling literature review, hypothesis generation, experiment design. ### Forks & Derivatives (4 projects) - **hermes-agent-camel** by nativ3ai *(beta)* — Hermes with integrated CaMeL trust boundaries for safety-critical deployments. - **orahermes-agent** by jasperan *(experimental)* — Oracle OCI GenAI + Oracle 26ai enterprise integration. - **hermes-alpha** by kaminocorp *(beta)* — cloud-deployed Hermes with pre-configured infrastructure templates. - **hermes-skill-distillation** by beardthelion *(experimental)* — generates agentic training trajectories from real-world tasks for fine-tuning data. ### Guides & Documentation (3 projects) - **hermes-agent-docs** by mudrii *(beta)* — community documentation covering v0.2.0 in detail; supplements official docs for deployment patterns. - **hermes-wsl-ubuntu** by metantonio *(production)* — step-by-step WSL2 Ubuntu setup for Windows. - **HermesWiki** by martymcenroe *(beta)* — community-maintained wiki for autonomous-agent patterns. ### Operational Playbooks (5 patterns) 1. **Nightly self-evolution + guardrail evaluation** — run `hermes-agent-self-evolution` on a schedule, then a second verification cron to score quality and block optimization-loop gaming. 2. **Memory pressure handling with Honcho/Hindsight** — if you're repeating context or losing long-term recall, review Honcho docs, evaluate Hindsight or self-hosted memory backends. 3. **Tune session timeout/expiry early** — adjust session retention for slower-moving threads so context is kept when needed. 4. **OpenClaw side-by-side migration** — keep both systems running during migration using `openclaw-to-hermes` and native migration paths, cut over once cron and routing behavior match. 5. **Curate USER.md and MEMORY.md intentionally** — treat profile memory as high-signal infrastructure: concise, durable, preference-focused entries, not raw notes. ### Maturity taxonomy (used throughout) - **production** — stable, documented, actively maintained — safe to build on. - **beta** — works but still evolving — expect some rough edges. - **experimental** — proof of concept or early-stage — learn from it, don't depend on it. ### Inclusion criteria Resource must be directly related to the Hermes Agent ecosystem or the `agentskills.io` standard, have a clear README, and be reasonably maintained. Contributions via GitHub issue at `0xNyk/awesome-hermes-agent`. ### Category totals (as of 2026-04-03 snapshot) | Category | Count | |---|---| | Official Resources | 9 | | Community Skills | 9 | | agentskills.io Ecosystem | 12 | | Plugins | 8 | | Skill Registries & Discovery | 2 | | Tools & Utilities | 11 | | Deployment | 4 | | Integrations & Bridges | 10 | | Multi-Agent & Swarms | 4 | | Domain Applications | 11 | | Forks & Derivatives | 4 | | Guides & Documentation | 3 | | Operational Playbooks | 5 | **Total tracked resources:** ~90 across the ecosystem (excluding the 9 official Nous resources and 5 operational playbooks). ## Relevant Concepts - [[concepts/skills-system]] - [[concepts/memory-system]] - [[concepts/mcp-integration]] - [[concepts/deployment-backends]] - [[concepts/messaging-gateway]] - [[concepts/migration-from-openclaw]] - [[concepts/self-improvement-loop]] - [[concepts/ml-research-pipeline]] - [[entities/nous-research]] - [[entities/hermes-self-evolution]] - [[entities/hermes-paperclip-adapter]] - [[entities/autonovel]] - [[entities/community-awesome-hermes]] - [[entities/community-workspace]] - [[entities/community-webui]] - [[entities/memory-honcho]] - [[entities/memory-hindsight]] ## Source Metadata - **Type:** Curated "awesome list" README (Markdown) - **Title:** Awesome Hermes Agent - **Maintainer:** 0xNyk / Builderz (`builderz.dev`) - **URL:** `https://github.com/0xNyk/awesome-hermes-agent` - **License:** CC BY 4.0 - **Last ecosystem review date:** 2026-04-03 - **Hermes version at snapshot:** v0.6.0 (v2026.3.30) - **Core repo star count at snapshot:** 23k+ on `NousResearch/hermes-agent` - **File:** `raw/awesome-hermes-agent-readme.md` - **Confidence:** high — directly mirrors the authoritative community directory; star counts and tags reproduced verbatim <!-- ===== hermes/wiki/summaries/community-resources.md ===== --> --- title: "Community Resources — get-hermes.ai community page inventory" type: summary tags: [community, foundational, well-established] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/community-resources.md"] confidence: high hermes_version: "v0.8.0" --- ## Key Points - **Source**: `get-hermes.ai/community/` — the official community directory curated by Nous Research. Scraped 2026-04-12. - **Headline stats**: **25 community projects**, **7 categories**, **50+ star minimum threshold** for listing. No Discord, forums, newsletters, podcasts, or hackathons are listed on the page — the official community surface is the project directory plus the core repo. ### Category 1 — Curated Lists & Guides (5 projects) - **hermes-agent-orange-book** — 1.9k stars, by alchaincyf. Chinese beginner-to-expert guide covering setup, skills, memory, scheduling, advanced workflows. See [[entities/community-orange-book]]. - **awesome-hermes-agent** — 1.1k stars, by 0xNyk. Curated list of skills, tools, integrations, resources. See [[entities/community-awesome-hermes]]. - **hermes-ecosystem** — 180 stars, by ksimback. "Hermes Atlas" — visual community map. - **hermes-optimization-guide** — 97 stars, by OnlyTerp. Setup, migration, LightRAG integration, Telegram config, skill creation. - **Hermes-Wiki** — 78 stars, by cclank. Complete wiki with source-code walkthroughs. ### Category 2 — Agent Personas & Configurations (2 projects) - **agency-agents-zh** — 5.8k stars, by jnMetaCode. **193 plug-and-play AI expert roles across 18 departments**; 46 are China-market-specialized. Cross-agent (not Hermes-only). See [[entities/community-agency-agents-zh]]. - **gbrain** — 4.8k stars, by garrytan. Opinionated Hermes brain config tuned for productivity + coding. See [[entities/community-gbrain]]. ### Category 3 — Web Interfaces & Desktop Clients (7 projects) - **hermes-webui** — 1.3k stars, Python, by nesquena. Three-panel Claude-style web UI with full CLI parity, no build step. See [[entities/community-webui]]. - **hermes-workspace** — 1.1k stars, TypeScript, by outsourc-e. Native web workspace: chat, terminal, memory inspector, skills manager. See [[entities/community-workspace]]. - **hermes-hudui** — 571 stars, Python, by joeynyc. Web UI "consciousness monitor" — real-time memory and tool-usage view. - **hermes-desktop** (dodo-reach) — 225 stars, Swift. Native Mac workspace with real SSH + terminal. - **hermes-skins** — 152 stars, Python, by joeynyc. Custom visual themes for the CLI. - **hermes-desktop** (fathah) — 144 stars, TypeScript. Desktop GUI for install/config/chat. macOS + Linux. - **scarf** — 92 stars, Swift, by awizemann. Native macOS GUI — dashboard + session browser + embedded terminal. ### Category 4 — Skills & Plugins (4 projects) - **avoid-ai-writing** — 896 stars, by conorbronsdon. Audits and rewrites content to remove AI writing patterns. Cross-agent. - **drawio-skill** — 160 stars, by Agents365-ai. Generates professional diagrams from text. - **litprog-skill** — 88 stars, by tlehman. Literate programming skill. Cross-agent. - **Wizards-of-the-Ghosts** — 60 stars, by Hmbown. Fantasy-themed skill pack. ### Category 5 — Tools, Extensions & Orchestration (2 projects) - **autocontext** — 726 stars, Python, by greyhaven-ai. Recursive self-improving harness; supports Hermes CLI. - **lacp** — 187 stars, Shell, by 0xNyk. Control-plane-grade harness for Claude/Codex/Hermes with policy gates and audit trails. ### Category 6 — Memory Providers (1 project) - **honcho-self-hosted** — 137 stars, by elkimek. Self-hosted Honcho memory layer, pre-configured with OpenRouter and Venice. See [[entities/memory-honcho]]. ### Category 7 — Official Nous Research Projects (4 projects) - **hermes-agent** — 56k+ stars. The core repo. - **hermes-agent-self-evolution** — 893 stars. Evolutionary self-improvement using **DSPy + GEPA**. See [[entities/hermes-self-evolution]]. - **hermes-paperclip-adapter** — 741 stars. Run Hermes as a managed employee inside the Paperclip environment. See [[entities/hermes-paperclip-adapter]]. - **autonovel** — 467 stars. Autonomous novel-writing pipeline. See [[entities/autonovel]]. ## Observed Patterns - **Ecosystem shape is heavily UI-first**: 7 of 25 projects are web or desktop clients wrapping the CLI. Signals that the bundled CLI is capable but users want richer surfaces (memory inspectors, session browsers, themes). - **Cross-agent tooling is overrepresented**: `avoid-ai-writing`, `litprog-skill`, `agency-agents-zh`, `autocontext`, and `lacp` all support multiple agent harnesses — Hermes is treated as one of several compatible runtimes, which matches the [[syntheses/hermes-vs-openclaw]] "use both" story. - **Official directory gates on quality**: 50+ star minimum means the page deliberately excludes long-tail projects. Actual community footprint is larger than what's listed. - **No official Discord / forum / newsletter surfaced on the community page** — community coordination appears to happen in individual project repos and the Nous Research social channels. ## Official Links - Getting Started docs: `hermes-agent.nousresearch.com/docs/getting-started/installation` - Main GitHub: `github.com/NousResearch/hermes-agent` ## Relevant Concepts - [[concepts/skills-system]] — drawio, litprog, avoid-ai-writing, Wizards-of-the-Ghosts all extend this - [[concepts/memory-system]] — honcho-self-hosted, hermes-hudui (memory inspector) - [[concepts/self-improvement-loop]] — hermes-agent-self-evolution (DSPy + GEPA), autocontext - [[concepts/mcp-integration]] - [[entities/nous-research]] - [[entities/community-orange-book]], [[entities/community-awesome-hermes]], [[entities/community-webui]], [[entities/community-workspace]], [[entities/community-gbrain]], [[entities/community-agency-agents-zh]] - [[entities/memory-honcho]], [[entities/hermes-self-evolution]], [[entities/hermes-paperclip-adapter]], [[entities/autonovel]] ## Source Metadata - **Type**: Scraped web page inventory (Markdown dump) - **Source URL**: https://get-hermes.ai/community/ - **Scrape date**: 2026-04-12 - **Maintainer**: Nous Research (official directory) - **Confidence**: high — this is a first-party curated list with concrete metrics (stars, authors, descriptions) <!-- ===== hermes/wiki/summaries/release-v0.10.0.md ===== --> --- title: "Release Notes — Hermes Agent v0.10.0 (v2026.4.16)" type: summary tags: [release-notes, foundational, well-established] created: 2026-04-28 updated: 2026-04-28 sources: ["raw/release-v0.10.0.md"] confidence: high hermes_version: "v0.10.0" --- # Release Notes — Hermes Agent v0.10.0 (v2026.4.16) ## Key Points **Tagline:** "The Tool Gateway release" — small, focused drop. ~180 commits in 3 days (v0.9.0 → v0.10.0). Most non-Tool-Gateway work in this window was deferred to the v0.11.0 changelog. ### Headline feature - **Nous Tool Gateway** — Paid Nous Portal subscribers now get automatic access to four hosted tools through their existing subscription with **zero additional API keys**: - **Web search** (Firecrawl) - **Image generation** (FAL / FLUX 2 Pro) - **Text-to-speech** (OpenAI TTS) - **Browser automation** (Browser Use) - Per-tool opt-in via `use_gateway` config flag - Full integration with `hermes tools` and `hermes status` - Runtime prefers the gateway even when direct API keys are configured - Replaces the prior hidden `HERMES_ENABLE_NOUS_MANAGED_TOOLS` env var with proper subscription detection - Workflow: `hermes model` → select Nous Portal → pick tools to enable ### Why this matters Removes the largest "extra setup" pain point for tool-heavy users. Web search and image gen are two of the most-asked-for capabilities; previously each required separate paid keys (Firecrawl, FAL, OpenAI). Nous Portal subscribers now get them as part of the base subscription. ## Relevant Concepts - [[concepts/model-switching]] — Nous Portal subscription detection now flows into provider/tool routing - [[concepts/mcp-integration]] — alternative path to web search / image gen that doesn't require MCP setup - [[concepts/auxiliary-models]] — vision / TTS auxiliary tasks can now route through Nous Portal subscription ## Source Metadata - **Type:** Official release notes - **Version:** v0.10.0 - **Tag:** v2026.4.16 - **Released:** 2026-04-16 - **URL:** https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.16 - **Stats:** ~180 commits (full release stats rolled into v0.11.0 changelog) - **Days since prior release:** 3 (v0.9.0 was 2026-04-13) <!-- ===== hermes/wiki/summaries/release-v0.11.0.md ===== --> --- title: "Release Notes — Hermes Agent v0.11.0 (v2026.4.23)" type: summary tags: [release-notes, foundational, well-established] created: 2026-04-28 updated: 2026-04-28 sources: ["raw/release-v0.11.0.md"] confidence: high hermes_version: "v0.11.0" --- # Release Notes — Hermes Agent v0.11.0 (v2026.4.23) ## Key Points **Tagline:** "The Interface release" — 1,556 commits · 761 merged PRs · 1,314 files changed · 224,174 insertions · 29 community contributors (290 including co-authors) over 10 days (v0.9.0 → v0.11.0). Folds in everything deferred from v0.10.0. ### Headline features - **New Ink-based TUI (`hermes --tui`)** — full React/Ink rewrite of the interactive CLI with a Python JSON-RPC backend (`tui_gateway`). Sticky composer, live streaming with OSC-52 clipboard, stable picker keys, status bar with per-turn stopwatch + git branch, `/clear` confirm, light-theme preset, subagent spawn observability overlay. ~310 commits to `ui-tui/` + `tui_gateway/`. - **Transport ABC + Native AWS Bedrock** — format conversion + HTTP transport extracted from `run_agent.py` into a pluggable `agent/transports/` layer. `AnthropicTransport`, `ChatCompletionsTransport`, `ResponsesApiTransport`, `BedrockTransport`. Native AWS Bedrock support via the Converse API ships on top of the new abstraction. - **Five new inference paths** — NVIDIA NIM, Arcee AI, Step Plan, Google Gemini CLI OAuth, Vercel ai-gateway (with pricing + dynamic discovery). Plus Gemini routed through native AI Studio API. - **GPT-5.5 over Codex OAuth** — OpenAI's new GPT-5.5 reasoning model accessible through ChatGPT Codex OAuth, with live model discovery wired into the picker. - **QQBot — 17th platform** — native QQ Official API v2 adapter with QR scan-to-configure, streaming cursor, emoji reactions, DM/group policy gating. - **Plugin surface massively expanded** — plugins can now `register_command` (slash commands), `dispatch_tool` (invoke tools from plugin code), block tool execution via `pre_tool_call` veto, rewrite tool results via `transform_tool_result`, transform terminal output, ship `image_gen` backends, and add custom dashboard tabs. Bundled disk-cleanup plugin opt-in by default as a reference implementation. - **`/steer <prompt>`** — mid-run agent nudges. Injects a note the running agent sees after its next tool call without interrupting the turn or breaking prompt cache. Course-correction in-flight. - **Shell hooks** — wire any shell script as a Hermes lifecycle hook (`pre_tool_call`, `post_tool_call`, `on_session_start`, etc.) without writing a Python plugin. - **Webhook direct-delivery mode** — webhook subscriptions can forward payloads straight to a platform chat without going through the agent. Zero-LLM push notifications for alerting, uptime checks, event streams. - **Smarter delegation** — subagents have an explicit `orchestrator` role that can spawn their own workers, with configurable `max_spawn_depth` (default flat). Concurrent siblings share filesystem state through a file-coordination layer. - **Auxiliary models — configurable UI + main-model-first** — `hermes model` has a dedicated "Configure auxiliary models" screen for per-task overrides (compression, vision, session_search, title_generation). **`auto` routing now defaults to the main model for side tasks across all users**, replacing the prior behavior where aggregator users got silently routed to a cheap provider-side default. - **Dashboard plugin system + live theme switching** — web dashboard now extensible. Third-party plugins add custom tabs, widgets, views without forking. Live-switching themes control colors, fonts, layout, density. - **Dashboard polish** — i18n (English + Chinese), react-router sidebar layout, mobile-responsive, Vercel deployment, real per-session API call tracking, one-click update + gateway restart. ### Notable refinements - **Compression model falls back to main model** on permanent 503/404 errors - **Compression summaries respect the conversation's language** (multilingual aux improvement) - **Compressor smart collapse, dedup, anti-thrashing**, template upgrade, hardening - **Auto-prune old sessions + VACUUM state.db** at startup - **Honcho overhaul** — context injection, 5-tool surface, cost safety, session isolation - **Auto-continue interrupted agent work** after gateway restart - **Activity heartbeats** prevent false gateway inactivity timeouts - **Per-provider + per-model `request_timeout_seconds`** config - **Configurable API retry count** via `agent.api_max_retries` - **`hermes skills reset`** to un-stick bundled skills - **Skills guard opt-in** via `config.skills.guard_agent_created` (default off) - **`xitter` skill replaced with `xurl`** (official X API CLI) - **Cron `wakeAgent` gate** — scripts can skip the agent entirely - **Cron per-job `enabled_toolsets`** — cap token overhead + cost per job - **Browser `browser_cdp` raw DevTools Protocol passthrough** - **Multi-model FAL** with picker in `hermes tools`; Recraft V3→V4 Pro, Nano Banana→Pro - **Google Gemini TTS provider**, **xAI Grok STT**, **xAI image generation**, **KittenTTS local provider** - **`patch` "did you mean?" feedback** when patch fails to match - **Stream `/v1/responses` SSE tool events**, **inline image inputs** on `/v1/chat/completions` and `/v1/responses` - **Entry-level Podman support** + add docker-cli to Docker image + file-sync back to host on teardown - **Dynamic shell completion** for bash, zsh, fish - **Light-mode skins** + skin-aware completion menus - **Numbered keyboard shortcuts** on approval and clarify prompts - **Markdown stripping, compact multiline previews, external editor** in input handling - **`--ignore-user-config` and `--ignore-rules` flags** - **Account limits section in `/usage`** ### Platform updates - **17 platforms now** (up from 16) — QQBot added - **Telegram:** dedicated `TELEGRAM_PROXY` env var + config.yaml proxy support, `ignored_threads` for groups, disable-link-previews config, auto-wrap markdown tables in code blocks - **Discord:** forum channel support, `DISCORD_ALLOWED_ROLES` for role-based gating, disable slash commands option, native `send_animation` for inline GIFs, `send_message` media attachments, `/skill` command group, extract reply text from message references - **Feishu:** intelligent reply on document comments with 3-tier access control, processing-state reactions, preserve @mention context - **DingTalk:** `require_mention` + `allowed_users` (parity with Slack/Telegram/Discord), QR-code device-flow setup, AI Cards streaming - **WhatsApp:** `send_voice` native audio, `dm_policy`/`group_policy` parity with WeCom/Weixin/QQ - **WeCom:** QR-scan bot creation + interactive setup wizard - **Signal:** media delivery via `send_message` - **Slack:** per-thread sessions for DMs by default - **BlueBubbles:** group chat session separation, webhook auth fixes - **Gateway core:** gateway proxy mode (forward to remote API server), per-channel ephemeral prompts (Discord/Telegram/Slack/Mattermost), `--all` flag for `gateway start`/`restart`, surface plugin slash commands natively on all platforms ### New skills - **concept-diagrams**, **architecture-diagram** (Cocoon AI port), **pixel-art** (with hardware palettes + video animation), **baoyu-comic**, **baoyu-infographic** (21 layouts × 21 styles), **page-agent** (embed Alibaba's in-page GUI agent), **fitness-nutrition**, **drug-discovery** (ChEMBL/PubChem/OpenFDA/ADMET), **touchdesigner-mcp**, **adversarial-ux-test**, **maps** updates, **llm-wiki** (port provenance, source hashing, quality signals) ### Provider catalog updates - **Kimi K2.6** across OpenRouter, Nous Portal, native, HuggingFace - **Kimi K2.5** promoted to first position in all model suggestion lists - **Xiaomi MiMo v2.5-pro + v2.5** on OpenRouter, Nous Portal, native - **GLM-5V-Turbo** for coding plan - **Claude Opus 4.7** in Nous Portal catalog - **OpenRouter elephant-alpha** in curated lists - **OpenCode-Go** — Kimi K2.6, Qwen3.5/3.6 Plus - **minimax/minimax-m2.5:free** in OpenRouter catalog - **`/model` merges models.dev entries** for lesser-loved providers ### Security hardening - Global toggle to allow private/internal URL resolution - Block agent from self-destructing the gateway via terminal (closes #6666) - Telegram callback authorization on update prompts - SECURITY.md added - Warn about legacy hermes.service units during `hermes update` - Complete ASCII-locale UnicodeEncodeError recovery (closes #6843) - Prevent stale `os.environ` leak after `clear_session_vars` ## Relevant Concepts - [[concepts/model-switching]] — 5 new providers, AWS Bedrock, GPT-5.5, transport ABC, Kimi K2.6, MiMo v2.5 - [[concepts/auxiliary-models]] — UI overhaul + auto-routing default change (now main model for all users) - [[concepts/messaging-gateway]] — 17 platforms, gateway proxy mode, per-channel ephemeral prompts, plugin slash commands surfaced - [[concepts/skills-system]] — namespaced skill registration, `hermes skills reset`, skills guard opt-in, plugin-bundled skills - [[concepts/mcp-integration]] — 12 MCP improvements - [[concepts/subagents-delegation]] — orchestrator role, configurable spawn depth, cross-agent file coordination - [[concepts/cron-scheduling]] — `wakeAgent` gate, per-job `enabled_toolsets`, webhook direct-delivery - [[concepts/memory-system]] — Honcho overhaul, auto-prune + VACUUM, on_memory_write bridge - [[concepts/approval-system]] — block agent from self-destructing gateway, Telegram callback auth ## Source Metadata - **Type:** Official release notes - **Version:** v0.11.0 - **Tag:** v2026.4.23 - **Released:** 2026-04-23 - **URL:** https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.23 - **Stats (since v0.9.0):** 1,556 commits, 761 PRs, 1,314 files changed, 224,174 insertions, 29 community contributors (290 with co-authors) - **Days since prior release:** 7 (v0.10.0 was 2026-04-16) <!-- ===== hermes/wiki/summaries/release-v0.12.0.md ===== --> --- title: "Release Notes — Hermes Agent v0.12.0 (v2026.4.30)" type: summary tags: [release-notes, foundational, well-established] created: 2026-05-01 updated: 2026-05-01 sources: ["raw/release-v0.12.0.md"] confidence: high hermes_version: "v0.12.0" --- # Release Notes — Hermes Agent v0.12.0 (v2026.4.30) ## Key Points **Tagline:** "The Curator release" — 1,096 commits · 550 merged PRs · 1,270 files changed · 217,776 insertions · 213 community contributors over 7 days (v0.11.0 → v0.12.0). The agent now actively maintains its own skill library on a schedule. ### Headline features - **Autonomous Curator** — `hermes curator` runs as a background agent on the gateway's cron ticker, default 7-day cycle. Grades the skill library, prunes dead skills, consolidates related ones, writes per-run reports to `logs/curator/run.json` + `REPORT.md`. Bundled and hub skills are gated against mutation. Pinned skills cannot be edited or removed by the curator. `hermes curator status` ranks skills by usage (most-used / least-used). Configured under `auxiliary.curator` — pick the model in `hermes model`. ([#17277](https://github.com/NousResearch/hermes-agent/pull/17277), [#17307](https://github.com/NousResearch/hermes-agent/pull/17307), [#17941](https://github.com/NousResearch/hermes-agent/pull/17941), [#17868](https://github.com/NousResearch/hermes-agent/pull/17868), [#18033](https://github.com/NousResearch/hermes-agent/pull/18033)) - **Self-improvement loop substantially upgraded** — the background review fork (decides what memories/skills to save after each turn) is now class-first / rubric-based, biased toward updating skills the agent just loaded, handles `references/` + `templates/` sub-files, properly inherits parent runtime (provider, model, credentials), and is restricted to memory + skills toolsets so it can't sprawl into shell or web. ([#16026](https://github.com/NousResearch/hermes-agent/pull/16026), [#17213](https://github.com/NousResearch/hermes-agent/pull/17213), [#16099](https://github.com/NousResearch/hermes-agent/pull/16099), [#16569](https://github.com/NousResearch/hermes-agent/pull/16569)) - **ComfyUI v5 + TouchDesigner-MCP — bundled by default** — both moved from optional to built-in. ComfyUI ships with official CLI + REST + hardware-gated local install. TouchDesigner-MCP gets GLSL, post-FX, audio, geometry references, and 9 new reference docs. - **Direct-URL skill install** — `hermes skills install <url>` installs a skill from any HTTPS URL. ([#16323](https://github.com/NousResearch/hermes-agent/pull/16323)) - **`/reload-skills` slash command** — pick up skill edits without restarting the agent. ([#17744](https://github.com/NousResearch/hermes-agent/pull/17744)) - **Skill pinning + external-dirs editing** — `skill_manage` refuses writes on pinned skills (also blocks curator); now edits `external_dirs` skills in place. ([#17562](https://github.com/NousResearch/hermes-agent/pull/17562), [#17512](https://github.com/NousResearch/hermes-agent/pull/17512)) - **Four new inference providers** — GMI Cloud (first-class API-key), Azure AI Foundry (auto-detection), MiniMax OAuth (PKCE browser flow), Tencent Tokenhub. Plus LM Studio upgraded from custom-endpoint alias to a full first-class provider with dedicated auth, doctor checks, and live `/models` listing. - **Pluggable gateway platforms + Microsoft Teams (19th platform)** — the gateway is now a plugin host. Drop-in messaging adapters live outside the core. Microsoft Teams is the first plugin-shipped platform. - **Yuanbao (Tencent 元宝) — 18th platform** — native gateway adapter with text + media delivery. - **Spotify native tools + bundled skill** — 7 tools (play, search, queue, playlists, devices) behind PKCE OAuth, interactive setup wizard, cron usage documented. - **Google Meet plugin** — join calls, transcribe, speak, follow up. Realtime OpenAI transport + Node bot server. - **`hermes -z <prompt>` non-interactive one-shot mode** with `--model`/`--provider`/`HERMES_INFERENCE_MODEL` env support. Plus `hermes update --check` preflight and opt-in pre-update HERMES_HOME backup. - **Models dashboard tab** — rich per-model analytics; configure main + auxiliary models from the dashboard. - **Remote model catalog manifest** — OpenRouter + Nous Portal catalogs pulled from a remote manifest so new models surface without a release. - **Configurable prompt cache TTL** — `prompt_caching.cache_ttl`, 5m default with 1h opt-in for bursty sessions. - **Bundled observability + achievements plugins** — Langfuse plugin and hermes-achievements (scans full session history) ship bundled. - **TTS provider registry + Piper local TTS** — pluggable `tts.providers.<name>` registry; Piper as native local TTS provider. - **Vercel Sandbox backend** — Vercel sandboxes as an `execute_code` / terminal backend. - **Secret redaction off by default** — flips a long-standing footgun where fake secret-shaped substrings corrupted patches and tool outputs. Opt in via `redaction.enabled: true` when needed. - **TUI cold start cut ~57%** via lazy agent init, lazy provider imports, mtime-cached config reads, memoized tool definitions, precompiled command patterns. ### TUI catches up to the classic CLI - **LaTeX rendering** in TUI - **`/reload`** .env hot-reload ported from classic CLI - **Pluggable busy-indicator styles** - **Opt-in auto-resume of last session** - **Light-terminal auto-detection** with `HERMES_TUI_THEME` + background hex - **Session delete from `/resume` picker** with `d` key - **`/mouse` toggle** kills ConPTY's phantom mouse injection (WSL2 fix) - **Voice mode parity** — VAD loop + TTS + crash forensics ### Removed / reverted - Kanban multi-profile collaboration board (landed in #16081, reverted in #16098) - computer-use cua-driver (3 preparatory PRs reverted in #16927) - BOOT.md built-in hook removed (#17093); replaced with a hooks tutorial showing how to build the same workflow with a shell hook - `/provider` + `/plan` slash commands dropped - `flush_memories` removed entirely ## Relevant Concepts - [[concepts/skills-system]] — Curator is the headline addition. Direct-URL install, `/reload-skills`, pinning, external_dirs editing. Bundled skills count grew via ComfyUI + TouchDesigner-MCP promotion plus several community additions. - [[concepts/self-improvement-loop]] — review fork is now rubric-based, scoped, runtime-inheriting. The single biggest set of fixes for self-improvement to date. - [[concepts/auxiliary-models]] — new `auxiliary.curator` slot. 8 → 9 task slots. - [[concepts/messaging-gateway]] — 19 platforms; plugin-host architecture means platforms can ship outside the core. - [[concepts/model-switching]] — 4 new providers, LM Studio upgrade, remote catalog manifest, configurable cache TTL. - [[concepts/memory-system]] — `flush_memories` removed; FTS5 indexes `tool_name` + `tool_calls` now; CJK trigram support. - [[concepts/cron-scheduling]] — `hermes -z` one-shot mode; per-job `workdir`; `context_from` chaining. ## Source Metadata - **Type:** Official release notes - **Version:** v0.12.0 - **Tag:** v2026.4.30 - **Released:** 2026-04-30 - **URL:** https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.30 - **Stats (since v0.11.0):** 1,096 commits, 550 PRs, 1,270 files changed, 217,776 insertions, 213 community contributors (with co-authors) - **Days since prior release:** 7 (v0.11.0 was 2026-04-23) <!-- ===== hermes/wiki/summaries/release-v0.13.0.md ===== --> --- title: "Release Notes — Hermes Agent v0.13.0 (v2026.5.7)" type: summary tags: [release-notes, foundational, well-established] created: 2026-05-23 updated: 2026-05-23 sources: ["raw/release-v0.13.0.md"] confidence: high hermes_version: "v0.13.0" --- # Release Notes — Hermes Agent v0.13.0 (v2026.5.7) ## Key Points **Tagline:** "The Tenacity Release" — 864 commits · 588 merged PRs · 829 files changed · 128,366 insertions · 282 issues closed (13 P0, 36 P1) · 295 community contributors over 7 days (v0.12.0 → v0.13.0). The agent now finishes what it starts: durable multi-agent Kanban, `/goal` Ralph loop, session auto-resume across restarts. ### Headline features - **Multi-agent Kanban — durable, multi-profile collaboration board** — `feat(kanban):` resurrected after the v0.12 revert. Multiple Hermes workers pick tasks from a shared board, hand off, and close out. Heartbeats prove workers are alive, reclaim detects dead workers, zombie-worker detection catches deadlocks, retry budgets cap loop cost, hallucination gate prevents worker-fabricated card claims. One install can run many kanbans. ([#17805](https://github.com/NousResearch/hermes-agent/pull/17805), [#19653](https://github.com/NousResearch/hermes-agent/pull/19653), [#20232](https://github.com/NousResearch/hermes-agent/pull/20232), [#21183](https://github.com/NousResearch/hermes-agent/pull/21183), [#21214](https://github.com/NousResearch/hermes-agent/pull/21214)) - **`/goal` — persistent cross-turn goals (Ralph loop)** — lock the agent onto a target and it stays on task across turns until a judge model marks the criteria met. ([#18262](https://github.com/NousResearch/hermes-agent/pull/18262), [#18275](https://github.com/NousResearch/hermes-agent/pull/18275)) - **Sessions auto-resume after gateway restart** — gateway bounces, `/update` runs, source-file reloads — conversations come back from where they left off. ([#21192](https://github.com/NousResearch/hermes-agent/pull/21192)) - **Checkpoints v2** — state persistence rewritten with real pruning, disk guardrails, no orphan shadow repos. ([#20709](https://github.com/NousResearch/hermes-agent/pull/20709)) - **Curator subcommands** — `hermes curator archive`, `prune`, `list-archived`. **Manual `hermes curator run` is synchronous** — no polling, you see results immediately. ([#20200](https://github.com/NousResearch/hermes-agent/pull/20200), [#21216](https://github.com/NousResearch/hermes-agent/pull/21216), [#21236](https://github.com/NousResearch/hermes-agent/pull/21236)) - **Post-write delta lint** — `write_file` + `patch` get in-proc linters for Python, JSON, YAML, TOML. Syntax errors surface to the agent immediately. ([#20191](https://github.com/NousResearch/hermes-agent/pull/20191)) - **`no_agent` cron mode** — cron jobs can skip the agent entirely and just run a script. Watchdog pattern: empty stdout silent, non-empty delivered verbatim. ([#19709](https://github.com/NousResearch/hermes-agent/pull/19709)) - **Google Chat — 20th messaging platform** + generic platform-plugin hooks surface so third-party adapters drop in without touching core (IRC + Teams migrated). ([#21306](https://github.com/NousResearch/hermes-agent/pull/21306), [#21331](https://github.com/NousResearch/hermes-agent/pull/21331)) - **Providers are now plugins** — `ProviderProfile` ABC + `plugins/model-providers/`. Drop in third-party providers without touching core. ([#20324](https://github.com/NousResearch/hermes-agent/pull/20324)) - **`video_analyze`** — native video understanding tool on Gemini and compatible multimodal models. (@alt-glitch) ([#19301](https://github.com/NousResearch/hermes-agent/pull/19301)) - **`[[as_document]]` skill directive** — skills can force the gateway to deliver output as a document on supporting platforms. ([#21210](https://github.com/NousResearch/hermes-agent/pull/21210)) - **`transform_llm_output` plugin hook** — new lifecycle hook to reshape/filter LLM output before it hits the conversation. ([#21235](https://github.com/NousResearch/hermes-agent/pull/21235)) - **xAI Custom Voices TTS** — voice cloning support. (@alt-glitch) ([#18776](https://github.com/NousResearch/hermes-agent/pull/18776)) - **7 i18n locales** — Chinese, Japanese, German, Spanish, French, Ukrainian, Turkish. Docs site gains zh-Hans. - **Platform allowlists** — `allowed_channels` / `allowed_chats` / `allowed_rooms` across Slack, Telegram, Mattermost, Matrix, DingTalk. ([#21251](https://github.com/NousResearch/hermes-agent/pull/21251)) - **MCP levels up** — SSE transport with OAuth forwarding, stale-pipe retries, image results as MEDIA tags, keepalive on long-lived lifecycles. - **SearXNG + split web tools** — native search-only backend; pick different backends per capability (search vs extract vs browse). (@kshitijk4poor) - **OpenRouter response caching** — explicit cache control on supporting models. (@kshitijk4poor) - **Security wave — 8 P0 closures** — redaction ON by default (re-flipped from v0.11), Discord role-allowlists guild-scoped (CVSS 8.1 cross-guild DM bypass closed), WhatsApp rejects strangers by default, TOCTOU windows closed across `auth.json` and MCP OAuth, browser cloud-metadata SSRF floor, cron prompt-injection scans skill content, `hermes debug share` redacts at upload. - **TUI glow-up** — `/model` picker overhaul with inline auth, collapsible startup banner sections, context-compression counter in status bar. - **Dashboard grows up** — Plugins page (manage, enable/disable, auth status), Profiles management page, sortable analytics tables, `X-Forwarded-Prefix` reverse-proxy support, new `default-large` 18px theme. - **ACP `/steer` and `/queue`** — direct or queue-up the in-flight agent from Zed, VS Code, JetBrains. (@HenkDz) - **QQBot native approval keyboards** — parity with Telegram/Discord approval UX. Chunked upload, quoted attachments. ### New skills (v0.13, all optional) - **Shopify** (Admin + Storefront GraphQL) - **here.now** - **shop-app** — personal shopping assistant - **Anthropic financial-services bundle** - **kanban-video-orchestrator** (@SHL0MS) - **searxng-search** (@kshitijk4poor) ### Provider catalog updates - `deepseek/deepseek-v4-pro` added to OpenRouter + Nous Portal - `x-ai/grok-4.3` added to OpenRouter + Nous Portal - `openrouter/owl-alpha` (free tier) added - `tencent/hy3-preview` paid route on OpenRouter - Arcee Trinity Large Thinking — temperature + compression overrides ### Removed / dropped - `/provider` alias for `/model` removed ## Relevant Concepts - [[concepts/skills-system]] — Curator subcommands, `[[as_document]]` directive, 6 new optional skills - [[concepts/self-improvement-loop]] — Curator now has full subcommand surface and synchronous manual run - [[concepts/cron-scheduling]] — `no_agent` mode is genuinely new; security: prompt-injection scan covers assembled skill content - [[concepts/messaging-gateway]] — 20 platforms; platform-plugin hooks surface; allowlists everywhere; QQBot UX - [[concepts/model-switching]] — Providers are pluggable now; new models; OpenRouter response caching - [[concepts/subagents-delegation]] — Multi-agent Kanban is the durable, multi-worker primitive - [[concepts/memory-system]] — Hindsight `update_mode='append'` dedup; checkpoints v2; session auto-resume - [[concepts/approval-system]] — security wave hardening (redaction ON, TOCTOU closures) ## Source Metadata - **Type:** Official release notes - **Version:** v0.13.0 - **Tag:** v2026.5.7 - **Released:** 2026-05-07 - **URL:** https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.7 - **Stats (since v0.12.0):** 864 commits, 588 PRs, 829 files changed, 128,366 insertions, 282 issues closed (13 P0, 36 P1), 295 community contributors (with co-authors) - **Days since prior release:** 7 (v0.12.0 was 2026-04-30) <!-- ===== hermes/wiki/summaries/release-v0.14.0.md ===== --> --- title: "Release Notes — Hermes Agent v0.14.0 (v2026.5.16)" type: summary tags: [release-notes, foundational, well-established] created: 2026-05-23 updated: 2026-05-23 sources: ["raw/release-v0.14.0.md"] confidence: high hermes_version: "v0.14.0" --- # Release Notes — Hermes Agent v0.14.0 (v2026.5.16) ## Key Points **Tagline:** "The Foundation Release" — 808 commits · 633 merged PRs · 1,393 files changed · 165,061 insertions · 545 issues closed (12 P0, 50 P1) · 215 community contributors over 9 days (v0.13.0 → v0.14.0). Hermes installs and runs anywhere, ships with what you want, stops shipping what you don't. ### Headline features - **`pip install hermes-agent`** — Hermes is now a real PyPI package. No more cloning the repo or shell installers. Wheel ships with the Ink TUI bundle and shell launcher. ([#26593](https://github.com/NousResearch/hermes-agent/pull/26593), [#26148](https://github.com/NousResearch/hermes-agent/pull/26148)) - **Native Windows support (early beta)** — Hermes runs natively on cmd.exe and PowerShell, no WSL required. Full PowerShell installer handles MinGit auto-install, Microsoft Store python stub detection, foreground Ctrl+C. ~40 follow-up Windows-only fixes already landed in the window. ([#21561](https://github.com/NousResearch/hermes-agent/pull/21561)) - **xAI Grok via SuperGrok OAuth + grok-4.3 jumps to 1M context** — sign in with xAI subscription, no separate API key. grok-4.3 now takes 1M token contexts. ([#26534](https://github.com/NousResearch/hermes-agent/pull/26534), [#26664](https://github.com/NousResearch/hermes-agent/pull/26664)) - **OpenAI-compatible local proxy for OAuth providers** — `hermes proxy` exposes a `localhost:port` endpoint speaking OpenAI API backed by your OAuth provider (Claude Pro, ChatGPT Pro, SuperGrok). Codex CLI, Aider, Cline, Continue all "just work" against your existing subscription. ([#25969](https://github.com/NousResearch/hermes-agent/pull/25969)) - **`x_search`** — first-class X (Twitter) search tool with OAuth-or-API-key auth. ([#26763](https://github.com/NousResearch/hermes-agent/pull/26763)) - **Microsoft Teams end-to-end** — full Microsoft Graph stack (auth + webhook listener + pipeline runtime + outbound delivery). The v0.12 plugin shell is now actually wired. ([#21922](https://github.com/NousResearch/hermes-agent/pull/21922), [#21969](https://github.com/NousResearch/hermes-agent/pull/21969), [#22007](https://github.com/NousResearch/hermes-agent/pull/22007), [#22024](https://github.com/NousResearch/hermes-agent/pull/22024)) - **Debloating wave — lighter installs** — heavyweight backends (Slack/Matrix/Feishu/DingTalk SDKs, hindsight client, codex app-server, image-gen, voice/TTS) install automatically the first time you actually use them. `[all]` extras drops everything covered by lazy-deps. Tiered install fallback when wheels reject. Supply-chain advisory checker. Faster installs, smaller disk footprint. - **Cold-start wave — ~19s off `hermes` launch** — lazy adapter imports, disk-cached model catalogs, parallel `hermes doctor` checks, `chat -q` skips welcome banner. `hermes tools` All-Platforms screen went from 14s to <1.5s. - **180x faster `browser_console`** — persistent CDP WebSocket. Sub-second tool calls where seconds were typical. - **Cross-session 1h Claude prefix cache** — Anthropic / OpenRouter / Nous Portal cache the prompt prefix (system, skills, memory) for an hour across sessions. Background review fork hits cache too. - **`/handoff` actually transfers the session live** — switch model, persona, or profile mid-conversation without dropping any context. - **LINE + SimpleX Chat — 22 platforms total** — LINE Messaging API (huge in JP/KR/TW), SimpleX privacy-focused decentralized messenger. - **Native button UI for `clarify`** — Telegram + Discord show real platform buttons for multiple-choice clarify; tap to answer. - **Discord channel history backfill (default on)** — joining a channel/thread reads recent history so the agent has the context that's already on screen. - **`vision_analyze` returns pixels to vision-capable models** — GPT-5, Claude, Gemini, Grok-vision get raw pixels, not text summaries. - **Per-turn file-mutation verifier footer** — after every turn that wrote/edited files, the agent gets a footer summarizing exactly what changed on disk. Catches silent write failures. - **LSP semantic diagnostics on every write** — real language server runs on `write_file`/`patch`, surfaces type errors / undefined symbols / missing imports back to the agent before the next turn. Goes beyond v0.13's basic syntax linting. - **Unified `video_generate`** with pluggable provider backends. (#25126) - **`computer_use` cua-driver** — works with non-Anthropic providers now. Focus-safe ops. Refreshes on `hermes update`. - **Clickable URLs in any terminal** — OSC8 hyperlinks. Works in iTerm2, Kitty, Ghostty, modern Windows Terminal. (@OutThisLife) - **Zed ACP Registry — `uvx` install in one click** — Hermes listed in Zed's Agent Client Protocol registry. No npm dependency. - **OpenRouter Pareto Code router with `min_coding_score` knob** — auto-route to cheapest model meeting your coding-quality bar. - **NovitaAI provider** (open-source model hosting). (@kshitijk4poor) - **Codex app-server runtime** for OpenAI/Codex — session reuse, wedged-session retirement, OAuth refresh classification. - **`huggingface/skills` as trusted default tap** — community skills index from huggingface.co/skills wired into Skills Hub by default. - **Plugins: `ctx.llm` + `tool_override`** — plugins make LLM calls through active provider/credentials; `tool_override` swaps out built-in tools. - **Brave Search (free tier) + DDGS** as web-search providers. - **API server exposes run approval events** — long-running runs no longer silently hang on approval-required commands. - **Sudo brute-force block + 3 dangerous-command bypasses closed + tool-error sanitization** — approval gate hardening. Tool error strings sanitized before re-injection (closes injection vector via malicious file/service error output). - **`/subgoal <text>`** — append user criteria to active `/goal` mid-run; judge factors it in without restarting the loop. - **Provider rename — Alibaba Cloud → Qwen Cloud** — existing config keys still work, UI matches the brand. - **i18n — 16 locales total** (gateway + dashboard + CLI). ### New skills (v0.14, all optional) - **Hyperliquid** — perp + spot trading via SDK + REST - **Yahoo Finance** — live market data, fundamentals, historicals - **api-testing** — REST + GraphQL debug recipes - **Unified EVM multi-chain** — Ethereum + L2s + Base in one skill - **darwinian-evolver** — evolutionary prompt/skill tuning - **osint-investigation** — OSINT recipes (people / domains / orgs) - **pinggy-tunnel** — expose local services to the public internet - **watchers** — RSS / HTTP JSON / GitHub change detection via `no_agent` cron mode - **Notion overhaul** for the May 2026 Developer Platform ### Removed / reverts - `/goal` checklist + first `/subgoal` rolled back; simpler `/subgoal` re-added via #25449 - Scrollback box width clamp rolled back ## Relevant Concepts - [[concepts/skills-system]] — `huggingface/skills` trusted default tap; 9 new optional skills; LSP diagnostics on write - [[concepts/messaging-gateway]] — 22 platforms (LINE + SimpleX Chat + Teams fully wired); per-platform circuit breaker; clarify native buttons - [[concepts/model-switching]] — SuperGrok OAuth, OpenAI-compatible proxy, NovitaAI, Pareto router, Codex app-server, Alibaba→Qwen rename - [[concepts/auxiliary-models]] — cross-session 1h prompt cache benefits aux side - [[concepts/approval-system]] — sudo brute-force block, 3 dangerous-command bypasses, tool-error sanitization - [[concepts/cron-scheduling]] — `watchers` skill exemplifies the v0.13 `no_agent` mode - [[concepts/deployment-backends]] — PyPI install, native Windows, debloating wave, Docker bootstrap auth.json from env - [[concepts/mcp-integration]] — `supports_parallel_tool_calls`, Codex preset, stop retrying initial auth failures ## Source Metadata - **Type:** Official release notes - **Version:** v0.14.0 - **Tag:** v2026.5.16 - **Released:** 2026-05-16 - **URL:** https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.16 - **Stats (since v0.13.0):** 808 commits, 633 PRs, 1,393 files changed, 165,061 insertions, 545 issues closed (12 P0, 50 P1), 215 community contributors (with co-authors) - **Days since prior release:** 9 (v0.13.0 was 2026-05-07) <!-- ===== hermes/wiki/summaries/release-v0.15.0.md ===== --> --- title: "Release Notes — Hermes Agent v0.15.0 (v2026.5.28)" type: summary tags: [release-notes, foundational, well-established] created: 2026-06-01 updated: 2026-06-04 sources: ["raw/release-v0.15.0.md", "https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29.2", "https://github.com/NousResearch/hermes-agent/compare/v2026.5.29...v2026.5.29.2", "https://github.com/NousResearch/hermes-agent/commit/827f7f07825be57108cbea18325e8f5e9fb5d2f2"] confidence: high hermes_version: "v0.15.2" --- # Release Notes — Hermes Agent v0.15.0 (v2026.5.28) ## Key Points **Tagline:** "The Velocity Release" — 1,302 commits · 747 merged PRs · 1,746 files changed · 282,712 insertions · 560+ issues closed (15 P0, 65 P1, 19 security-tagged) · 321 community contributors over 12 days (v0.14.0 → v0.15.0). Hermes gets dramatically faster to start, run, ship work, and grow; Kanban becomes a real multi-agent platform; promptware defense lands. Two same-day patches followed: **v0.15.1** (dashboard reload-loop hotfix + skills.sh catalog 858→19,932) and **v0.15.2 / v2026.5.29.2** (packaging fix — bundled `plugin.yaml`/`plugin.yml` manifests now ship in both wheel and sdist distributions). ### Patch detail — v0.15.2 (v2026.5.29.2) - **Cause / regression:** v0.15.0 dropped the bundled `plugin.yaml` / `plugin.yml` manifests from the wheel and sdist. Installed plugins shipped their code but their manifest files were absent from the distribution, so runtime manifest discovery silently failed. - **Fix channels:** - **Wheel:** `pyproject.toml` `plugins` package-data globs now include `**/plugin.yaml` and `**/plugin.yml`. - **sdist:** `MANIFEST.in` adds `recursive-include plugins plugin.yaml plugin.yml`. - **Regression coverage:** new test in `tests/test_packaging_metadata.py` asserts the manifests are present in both built artifacts. - **Measured impact:** wheel build evidence showed bundled plugin manifest count go from **0 → 69** after the fix. - **Files changed:** `MANIFEST.in`, `pyproject.toml`, `tests/test_packaging_metadata.py`. - **No config migration required** — `hermes update` is sufficient; downstream packagers who vendored v0.15.0/v0.15.1 should re-vendor the new artifacts. - **Links:** [release notes v2026.5.29.2](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29.2) · [compare v2026.5.29…v2026.5.29.2](https://github.com/NousResearch/hermes-agent/compare/v2026.5.29...v2026.5.29.2) · [commit 827f7f07](https://github.com/NousResearch/hermes-agent/commit/827f7f07825be57108cbea18325e8f5e9fb5d2f2) · [issue #34034](https://github.com/NousResearch/hermes-agent/issues/34034). ### Headline features - **Agent core refactor** — `run_agent.py` collapses **16,083 → 3,821 lines (-76%)** across 14 `agent/*` modules. External interfaces unchanged. - **`session_search` rebuilt — no LLM, free, ~20ms (4,500× faster)** — was a ~$0.30/call aux-LLM tool taking ~30s; now a single three-mode (discovery/scroll/browse) FTS5 tool with no aux-LLM, no config knob, no companion skill. **Consequence: `session_search` is no longer an auxiliary-model slot.** ([#27590](https://github.com/NousResearch/hermes-agent/pull/27590)) - **OpenAI API is now a first-class provider** distinct from the Codex runtime (picker key `openai-api`). ([#31898](https://github.com/NousResearch/hermes-agent/pull/31898)) - **Vercel AI Gateway + Vercel Sandbox removed** — drops the `plugins/model-providers/` count from 29 to **28**. - **Deep xAI integration round** — Web Search plugin (`plugins/web/xai/`); **`hermes proxy` can now be backed by SuperGrok OAuth**; **May-15 Grok retirement detection + `hermes migrate xai`** (retired slugs auto-map to `grok-4.3`); base_url leak guard; OpenAI-style execution guidance for Grok; xAI TTS `auto_speech_tags`. ([#28356](https://github.com/NousResearch/hermes-agent/pull/28356)) - **Kanban → real multi-agent platform** (104 PRs) — orchestrator auto-decomposition, `hermes kanban swarm` (Swarm v1 topology), per-task `model_override`, per-task worktree, scheduled task start times, `claim_ttl` / `max_in_progress` / `auto_promote_children`, crash-fingerprinting, worker visibility endpoints. - **Promptware defense** — threat-pattern scanning across context/memory/tools chokepoints; tool-result delimiter markers; expanded Brainworm memory-scan patterns. - **Bitwarden Secrets Manager** — one bootstrap token replaces N per-provider API keys (EU Cloud + self-hosted; `secrets.bitwarden.override_existing`). - **Skill bundles** — `/<name>` loads a whole workflow of skills at once; Skills Hub health checks + freshness badge; new skills `openhands`, `code-wiki`, `web-pentest`. - **Plugin API gains** `register_tts_provider()`, `register_transcription_provider()`, **`register_auxiliary_task()`** (plugins can register custom aux tasks; built-in keys reserved); new bundled `security-guidance` plugin; Discord + Mattermost migrated to bundled plugins. - **Performance wave** — `hermes --version` 63% faster (now beats Codex CLI head-to-head), 47% fewer agent-loop function calls, ~195ms/tool-call subprocess polling win, Termux cold start 2.9s→0.8s. - **ntfy** = 23rd messaging platform. **Krea 2** + **FAL.ai** image_gen providers. - **`hermes audit`** (OSV.dev supply-chain audit) + `hermes update` syntax validation with auto-rollback. - **Multi-session orchestrator** in the Ink TUI (list/switch/refresh/close live sessions). ### Auxiliary-task roster change (important for M5 + aux concept) Canonical built-in auxiliary task keys are now **8**: `vision`, `compression`, `web_extract`, `approval`, `mcp`, **`title_generation`** (new), `skills_hub`, `curator`. This replaces the v0.14-era roster where `session_search` held a slot (and the older KB note that still listed `flush_memories`, swapped for `curator` back in v0.12). Verified in `hermes_cli/plugins.py` + `tests/hermes_cli/test_plugin_auxiliary_tasks.py`. ## Relevant Concepts - [[concepts/auxiliary-models]] — **roster updated:** session_search out (now free FTS5), title_generation in; `register_auxiliary_task()` makes the set extensible; layered fallback (primary → chain → main → graceful fail) - [[concepts/model-switching]] — OpenAI-API first-class, Vercel removed, xAI proxy upstream + `hermes migrate xai`, OpenRouter sticky routing - [[concepts/skills-system]] — skill bundles, Skills Hub health/freshness, new skills, AST diagnostics, skills.sh ~20k catalog - [[concepts/mcp-integration]] — Nous-approved MCP catalog + picker, mTLS, headless-OAuth paste-back - [[concepts/subagents-delegation]] — Kanban multi-agent platform (auto-decompose, swarm topology, per-task overrides) - [[concepts/approval-system]] — promptware defense, control-plane file protection ## Source Metadata - **Type:** Official release notes (+ two same-day patches) - **Version:** v0.15.0 (patches v0.15.1, v0.15.2 / v2026.5.29.2) - **Tag:** v2026.5.28 (patches v2026.5.29, v2026.5.29.2) - **Released:** 2026-05-28 - **URL:** https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.28 - **Patch evidence (v0.15.2):** https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29.2 · compare https://github.com/NousResearch/hermes-agent/compare/v2026.5.29...v2026.5.29.2 · commit https://github.com/NousResearch/hermes-agent/commit/827f7f07825be57108cbea18325e8f5e9fb5d2f2 · issue https://github.com/NousResearch/hermes-agent/issues/34034 - **Stats (since v0.14.0):** 1,302 commits, 747 PRs, 1,746 files changed, 282,712 insertions, 560+ issues closed (15 P0, 65 P1, 19 security), 321 community contributors - **Days since prior release:** 12 (v0.14.0 was 2026-05-16) <!-- ===== hermes/wiki/summaries/release-v0.16.0.md ===== --> --- title: "Release Notes — Hermes Agent v0.16.0 (v2026.6.5)" type: summary tags: [release-notes, foundational, well-established] created: 2026-06-06 updated: 2026-06-06 sources: ["https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5"] confidence: high hermes_version: "v0.16.0" --- # Release Notes — Hermes Agent v0.16.0 (v2026.6.5) ## Key Points **Tagline:** "The Surface Release" — 874 commits · 542 merged PRs · 1,962 files changed · 205,216 insertions · 46,217 deletions · 399 issues closed (2 P0, 62 P1, 16 security-tagged) · 170 community contributors (including co-authors), since v0.15.2. Released 2026-06-05 (published 2026-06-06 00:55 UTC). The headliner is a brand-new **native Electron desktop app** — built across 100 PRs and 159 commits in a single week — that installs like any native app on macOS, Linux, and Windows, self-updates in place, and lets you connect to a remote Hermes gateway over OAuth or username/password. Alongside it: the **web dashboard became a full admin panel** (channels, MCP, credentials, webhooks, memory, OIDC/password auth, system check-before-update). First-time setup got a streamlined **Quick Setup via Nous Portal** path. The **model picker went fuzzy everywhere** (desktop, web, TUI, CLI). `/undo [N]` landed. The **default skill set was deliberately trimmed**. **NVIDIA/skills** joined the trusted Skills Hub taps. Security: **CVE-2026-48710** (Starlette BadHost) patched; SSRF off-loop hardening; subprocess credential stripping. ### Headline features - **Hermes Desktop (Electron) — macOS / Linux / Windows native app** — Chat window with streaming, session list (archive, search), drag-and-drop / clipboard image paste, Cmd+K palette, inline model picker in the status bar, YOLO toggle, Simplified Chinese (简体中文) translation (typed i18n layer, `display.language`). Built by @OutThisLife across 52 PRs. ([#20059](https://github.com/NousResearch/hermes-agent/pull/20059), [#35607](https://github.com/NousResearch/hermes-agent/pull/35607), [#37379](https://github.com/NousResearch/hermes-agent/pull/37379)) - **Remote-gateway connect in the desktop app** — Point the desktop at any remote Hermes gateway (homelab, hosted box, teammate's server); authenticate via OAuth or username/password over secure WebSocket. Concurrent multi-profile sessions, cross-profile `@session` links. Practical upshot: thin GUI on the laptop, heavy agent wherever API keys and compute live. ([#37888](https://github.com/NousResearch/hermes-agent/pull/37888), [#38851](https://github.com/NousResearch/hermes-agent/pull/38851), [#39330](https://github.com/NousResearch/hermes-agent/pull/39330)) - **Web dashboard → full administration panel** — Channels page (configure every gateway messaging platform from the browser), MCP catalog admin (enable/disable toggles), credential management, webhook/hook creation, memory configuration, gateway controls, System page (check-before-update + Debug Share). No more SSH-in-and-edit-`config.yaml` to wire up a new channel or MCP server. ([#36704](https://github.com/NousResearch/hermes-agent/pull/36704), [#37211](https://github.com/NousResearch/hermes-agent/pull/37211), [#38205](https://github.com/NousResearch/hermes-agent/pull/38205)) - **Dashboard auth: pluggable OIDC + username/password login** — Self-hosted OIDC provider + multi-provider verify. `hermes dashboard register` for self-hosted OAuth client. Refresh-token rotation. ([#38819](https://github.com/NousResearch/hermes-agent/pull/38819), [#38917](https://github.com/NousResearch/hermes-agent/pull/38917)) - **Leaner default skill set** — Removed: `spotify` (→ native Spotify plugin's 7 tools), `linear` (→ `hermes mcp install linear`), `kanban-codex-lane`, `debugging-hermes-tui-commands`, stale `domain` orphan, empty category markers. Moved bundled → optional: Baoyu creative set, `dspy`, `subagent-driven-development`, `minecraft-modpack-server`, `pokemon-player`, `hermes-s6-container-supervision`. Consolidated: `webhook-subscriptions` + `native-mcp` folded into `hermes-agent` skill; `writing-plans` merged into `plan` (v2.0.0). New `environments:` frontmatter gate (`kanban` / `docker` / `s6`) keeps context-specific skills out of the index without removing them. Curator can now prune unused **built-in** skills (not just agent-created). ([#39028](https://github.com/NousResearch/hermes-agent/pull/39028), [#36701](https://github.com/NousResearch/hermes-agent/pull/36701)) - **`install --no-skills` + opt-out/opt-in for the default profile** — Blank-slate skills install. ([#36228](https://github.com/NousResearch/hermes-agent/pull/36228)) - **NVIDIA/skills trusted tap** — `NVIDIA/skills` joins OpenAI, Anthropic, and HuggingFace as a default trusted tap. `skills.sh.json` sidecar provides real category labels. ([#34333](https://github.com/NousResearch/hermes-agent/pull/34333)) - **Quick Setup via Nous Portal** — Two-path first-run: Quick Setup (Nous Portal sign-in, model picker, chat immediately) vs Full Setup (detailed wizard). `hermes portal` alias for the quick-setup Nous flow. Goal: new user sends first message without reading docs. ([#35723](https://github.com/NousResearch/hermes-agent/pull/35723), [#38449](https://github.com/NousResearch/hermes-agent/pull/38449)) - **Fuzzy model picker everywhere** — Fuzzy search across desktop, web dashboard, TUI, and CLI. Multi-endpoint providers grouped under one row. Descriptions per row. Catalog refreshes hourly. New models: `deepseek-v4-flash`, `MiniMax-M3` (1M context), `qwen3.7-plus`, `gemini-3.5-flash`. ([#36928](https://github.com/NousResearch/hermes-agent/pull/36928), [#35659](https://github.com/NousResearch/hermes-agent/pull/35659), [#36214](https://github.com/NousResearch/hermes-agent/pull/36214)) - **`/undo [N]`** — Backs up N user turns, prefills last message, soft-deletes turns in between. CLI, TUI, and messaging-platform parity. Closes long-standing issue [#21910](https://github.com/NousResearch/hermes-agent/issues/21910). ([#36229](https://github.com/NousResearch/hermes-agent/pull/36229)) - **Configurable default interface** — `hermes chat` can default to CLI or TUI; `--cli` flag overrides per-invocation. TUI gained a single unified `/model` command + Sessions overlay for switching live sessions. ([#37782](https://github.com/NousResearch/hermes-agent/pull/37782)) - **Progressive tool disclosure** — MCP and plugin tools now scoped/disclosed progressively; universal task-completion guidance + local Python toolchain probe. ([#34493](https://github.com/NousResearch/hermes-agent/pull/34493)) - **`perf(read_file)`: compact line-number gutter** — ~14% fewer tokens per file read (now the only format). ([#35368](https://github.com/NousResearch/hermes-agent/pull/35368)) - **`hermes sessions optimize`** — FTS5 segment merge + VACUUM for search performance. ([#34596](https://github.com/NousResearch/hermes-agent/pull/34596)) - **Kanban: `goal_mode` cards + file attachments** — Workers run in a `/goal` loop; file attachments and image vision on tasks; `default_assignee` fallback + per-profile concurrency cap; `POST /runs/{run_id}/terminate`. ([#35710](https://github.com/NousResearch/hermes-agent/pull/35710), [#34244](https://github.com/NousResearch/hermes-agent/pull/34244)) - **Messaging: structured stream-event protocol** — Telegram draft formatting parity; per-platform streaming defaults (Telegram on, Discord off) + dashboard toggles. Discord voice-channel mixer: ambient idle bed + verbal acks overlapping TTS. ([#37250](https://github.com/NousResearch/hermes-agent/pull/37250), [#39659](https://github.com/NousResearch/hermes-agent/pull/39659)) - **Security — CVE-2026-48710**: pin patched Starlette ≥1.0.1. SSRF URL checks moved off event loop in async paths. Bedrock inference bearer token stripped from subprocess env. `bws_cache.json` added to file-safety read guard. Invisible unicode sanitized in vetted skill content. ([#35118](https://github.com/NousResearch/hermes-agent/pull/35118), [#39046](https://github.com/NousResearch/hermes-agent/pull/39046)) ## Auxiliary-task roster **No change from v0.15**: still 8 built-in slots — `vision`, `compression`, `web_extract`, `approval`, `mcp`, `title_generation`, `skills_hub`, `curator`. The `register_auxiliary_task()` plugin hook remains available for custom tasks. ## Provider / model count **Provider plugin count: 28** (unchanged from v0.15). No providers added or removed this window. New model *slugs* added to existing providers: `deepseek-v4-flash`, `MiniMax-M3`, `qwen3.7-plus`, `gemini-3.5-flash`. Model catalog now refreshes hourly (was daily). ## Desktop app reference Full entity with CLI flags, remote backend setup, troubleshooting, uninstall options, cost tips, and video outline: [[entities/hermes-desktop-app]] ## Relevant Concepts - [[concepts/skills-system]] — `environments:` gate, leaner defaults, `install --no-skills`, curator can prune built-in skills, NVIDIA trusted tap - [[concepts/model-switching]] — fuzzy picker everywhere, hourly refresh, new model slugs, MiniMax-M3 1M - [[concepts/subagents-delegation]] — Kanban `goal_mode`, file attachments, `default_assignee`, per-profile concurrency - [[concepts/deployment-backends]] — Docker container-reuse + orphan-reaper improvements - [[concepts/messaging-gateway]] — structured stream-event protocol, per-platform streaming defaults, Discord voice-channel mixer ## Source Metadata - **Type:** Official release notes - **Version:** v0.16.0 - **Tag:** v2026.6.5 - **Released:** 2026-06-05 (published 2026-06-06 00:55 UTC) - **URL:** https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5 - **Full changelog:** https://github.com/NousResearch/hermes-agent/compare/v2026.5.29.2...v2026.6.5 - **Stats (since v0.15.2):** 874 commits, 542 PRs, 1,962 files changed, 205,216 insertions, 46,217 deletions, 399 issues closed (2 P0, 62 P1, 16 security), 170 community contributors <!-- ===== hermes/wiki/summaries/release-v0.6.0.md ===== --> --- title: "Release v0.6.0 — Multi-Instance Release" type: summary tags: [mcp, gateway, platform, provider, profiles, foundational, well-established] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/release-v0.6.0.md"] confidence: high hermes_version: "v0.6.0" --- # Release v0.6.0 — Multi-Instance Release Hermes Agent v0.6.0 (calendar tag `v2026.3.30`) shipped March 30, 2026. Billed as the **multi-instance release**: profiles for isolated agent instances, MCP server mode to expose Hermes to other MCP clients, official Docker container, ordered provider fallback chains, two new Chinese-enterprise messaging platforms (Feishu/Lark and WeCom), Telegram webhook mode, Slack multi-workspace OAuth. 95 PRs merged and 16 issues resolved in a 2-day window. ## Key Points - **Profiles — multi-instance Hermes**: run multiple fully isolated Hermes instances from a single install. Each profile gets its own config, memory, sessions, skills, and gateway service. - Commands: `hermes profile create`, `hermes profile list`, `hermes profile switch`, `hermes profile delete`, `hermes profile export`, `hermes profile import`, `hermes profile rename` - `hermes -p <name>` runs a one-shot against a specific profile - Each profile has isolated `HERMES_HOME`, gateway service, CLI wrapper - **Token locks** prevent two profiles from using the same bot credential simultaneously (no accidental double-registrations of the same Telegram bot token) - Tab completion for profile names - Export/import lets you share a profile's skills+config with teammates or move to a new machine - See [[concepts/profiles-multi-instance]] - **MCP server mode** — `hermes mcp serve` exposes Hermes conversations, sessions, and attachments to any MCP-compatible client (Claude Desktop, Cursor, VS Code, Zed, etc.). - Browse conversations, read messages, search across sessions, manage attachments — all via the Model Context Protocol - Both stdio and Streamable HTTP transports supported - Dynamic tool discovery: Hermes responds to `notifications/tools/list_changed` events, so new tools from connected MCP servers are picked up without reconnecting - See [[concepts/mcp-integration]] - **Official Docker container** — first-class Dockerfile, supports both CLI mode and gateway mode with volume-mounted config. See [[entities/backend-docker]]. - **Ordered fallback provider chain** — configure multiple inference providers with automatic failover. When the primary errors or is unreachable, Hermes tries the next provider in order. - Configured via `fallback_providers` in `config.yaml` - See [[concepts/model-switching]] - **Feishu / Lark (飞书) platform support** — full gateway adapter with event subscriptions, message cards, group chat, image/file attachments, and interactive card callbacks. See [[entities/platform-feishu]]. - **WeCom (企业微信 / Enterprise WeChat) platform support** — new gateway adapter: text/image/voice messages, group chats, callback verification. See [[entities/platform-wecom]]. - **Slack multi-workspace OAuth** — one Hermes gateway can connect to multiple Slack workspaces via an OAuth token file. Useful for agencies and consultants operating across client tenants. See [[entities/platform-slack]]. - **Telegram webhook mode & group controls** — Telegram adapter can now run in webhook mode as an alternative to long-polling. New group mention gating controls when the bot responds in group chats (vs always listening). See [[entities/platform-telegram]]. - **Exa search backend** — added as an alternative web search + content extraction backend alongside Firecrawl and DuckDuckGo. See [[concepts/skills-system]]. - **Skills & credentials on remote backends** — Modal and Docker can now mount skill directories and credential files into the agent container, so cloud-run agents have parity with local skill access. - **Documentation: comprehensive OpenClaw migration guide** — step-by-step from OpenClaw/Claw3D to Hermes. Companion to the `hermes claw migrate` command. See [[concepts/migration-from-openclaw]]. ## Key Details by Area ### Profiles & Multi-Instance - Full CRUD + export/import + rename lifecycle - Token-lock isolation prevents credential collisions - Each profile gets its own systemd/gateway service - See [[concepts/profiles-multi-instance]] ### MCP - `hermes mcp serve` with stdio + Streamable HTTP - Exposes conversations, sessions, attachments - Dynamic `tools/list_changed` handling - See [[concepts/mcp-integration]] ### Contributor Stats - **@teknium1** — 90 PRs across all subsystems (the release workhorse) - Community: - @kshitijk4poor — Signal fix, parallel-cli move, status-bar wrap fix - @winglian — plugin message injection - @binhnt92 — audio download retry - @0xbyt4 — OpenClaw migration fix - **95 PRs merged, 16 community issues resolved** ## Relevant Concepts - [[concepts/profiles-multi-instance]] — the headline feature of v0.6.0 - [[concepts/mcp-integration]] — new `hermes mcp serve` makes Hermes a server, not just a client - [[concepts/deployment-backends]] — Docker graduates to official - [[concepts/messaging-gateway]] — two new platforms + Slack multi-workspace + Telegram webhook - [[concepts/model-switching]] — fallback provider chain added here - [[concepts/migration-from-openclaw]] — dedicated migration guide docs - [[entities/backend-docker]] — official Dockerfile - [[entities/platform-feishu]], [[entities/platform-wecom]] — new adapters - [[entities/platform-telegram]], [[entities/platform-slack]] — major adapter upgrades - [[entities/version-v0.6.0]] — version entity page - [[summaries/release-v0.7.0]], [[summaries/release-v0.8.0]] — subsequent releases ## Source Metadata - **Type**: Official release notes (authoritative) - **Version**: v0.6.0 / calendar tag `v2026.3.30` - **Release date**: 2026-03-30 - **Source file**: `raw/release-v0.6.0.md` - **URL**: https://github.com/NousResearch/hermes-agent/releases/tag/v2026.3.30 - **Confidence**: high (official release notes from Nous Research) <!-- ===== hermes/wiki/summaries/release-v0.7.0.md ===== --> --- title: "Release v0.7.0 — Resilience Release" type: summary tags: [memory, provider, gateway, mcp, tools, security, well-established] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/release-v0.7.0.md"] confidence: high hermes_version: "v0.7.0" --- # Release v0.7.0 — Resilience Release Hermes Agent v0.7.0 (calendar tag `v2026.4.3`) shipped April 3, 2026 — four days after v0.6.0. Billed as the **resilience release**: the memory system becomes a pluggable plugin interface, same-provider credential pools with rotation, Camofox anti-detection browser, inline diff previews, and a major gateway-hardening pass alongside deep security fixes. **168 PRs merged and 46 issues resolved.** ## Key Points - **Pluggable memory provider interface** — memory stops being monolithic. Third-party memory backends (Honcho, vector stores, custom DBs) implement a simple provider ABC and register via the plugin system. - Built-in memory remains the default provider - **Honcho integration restored to full parity** as the reference plugin, with profile-scoped host/peer resolution (plays nicely with v0.6.0 profiles) - Opens the door to [[entities/memory-mem0]], [[entities/memory-supermemory]], [[entities/memory-retaindb]], [[entities/memory-hindsight]], [[entities/memory-byterover]], [[entities/memory-holographic]], [[entities/memory-openviking]] as first-class plug-ins - See [[concepts/memory-system]] and [[entities/memory-honcho]] - **Same-provider credential pools** — configure multiple API keys for the same provider with automatic rotation. - Thread-safe `least_used` strategy distributes load across keys (not just round-robin — balances actual usage) - 401 failures trigger automatic rotation to the next credential - Lets you stack e.g. three Anthropic keys across three accounts to multiply effective rate limits without switching provider - See [[concepts/model-switching]] - **Camofox anti-detection browser backend** — new local browser backend using Camoufox for stealth browsing. - Persistent sessions with VNC URL discovery for visual debugging (watch the browser live) - Configurable SSRF bypass for local backends - Auto-install via `hermes tools` - Matters for web-scraping skills that hit bot-detection walls - See [[concepts/skills-system]] - **Inline diff previews** — file write and patch operations now show inline diffs in the tool activity feed. Makes it easy to see what the agent is actually changing before approving. - Pairs naturally with [[concepts/approval-system]] - **API server session continuity & tool streaming** — the API server (Open WebUI integration) now: - Streams tool progress events in real time - Supports `X-Hermes-Session-Id` headers for persistent sessions across requests - Community web UI projects get a meaningfully better experience ([[entities/community-webui]], [[entities/community-workspace]]) - **ACP: client-provided MCP servers** — editor integrations (VS Code, Zed, JetBrains) can now register their own MCP servers, which Hermes picks up as additional agent tools. Complements the `hermes mcp serve` direction from v0.6.0 — Hermes can now be either side of MCP. See [[concepts/mcp-integration]]. - **Gateway hardening pass** — major stability work across: - Race conditions - Photo media delivery - Flood control - Stuck sessions (one of the recurring pain points called out in community videos) - Approval routing - Compression death spirals - See [[concepts/messaging-gateway]] - **Security: secret exfiltration blocking** — browser URLs and LLM responses are scanned for secret patterns, blocking exfiltration via URL encoding, base64, or prompt injection. Meaningful defense against crafted-prompt attacks that try to smuggle credentials out through a browser fetch. ## Key New Slash Commands - `/yolo` — toggle dangerous command approvals on/off for the session (all-in mode for low-risk sandboxes) - `/btw` — ephemeral side questions that don't pollute the main conversation context - `/profile` — show active profile info without leaving the chat session (companion to v0.6.0 profiles) ## Contributor Stats - **168 PRs merged, 46 issues resolved** (up from 95/16 in v0.6.0 — big jump in community activity) - Community highlights: - @erosika — Honcho plugin (the reference memory provider implementation) - @pefontana — Telegram E2E tests - @SHL0MS — research-paper-writing and ascii-video skills - @alt-glitch — Firecrawl cloud browser - @nils010485 — SSRF config ## Relevant Concepts - [[concepts/memory-system]] — now a pluggable interface - [[concepts/model-switching]] — credential-pool rotation added - [[concepts/mcp-integration]] — client-provided MCP servers (ACP) - [[concepts/messaging-gateway]] — stability pass - [[concepts/approval-system]] — inline diffs + `/yolo` toggle - [[concepts/skills-system]] — Camofox as a new browser tool - [[entities/memory-honcho]] — reference memory plugin - [[entities/version-v0.7.0]] — version entity - [[summaries/release-v0.6.0]] — predecessor - [[summaries/release-v0.8.0]] — successor ## Source Metadata - **Type**: Official release notes (authoritative) - **Version**: v0.7.0 / calendar tag `v2026.4.3` - **Release date**: 2026-04-03 - **Source file**: `raw/release-v0.7.0.md` - **URL**: https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.3 - **Confidence**: high (official release notes from Nous Research) <!-- ===== hermes/wiki/summaries/release-v0.8.0.md ===== --> --- title: "Release v0.8.0 — Intelligence Release" type: summary tags: [model-switching, mcp, gateway, provider, cron, subagents, security, well-established] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/release-v0.8.0.md"] confidence: high hermes_version: "v0.8.0" --- # Release v0.8.0 — Intelligence Release Hermes Agent v0.8.0 (calendar tag `v2026.4.8`) shipped April 8, 2026 — five days after v0.7.0. Billed as the **intelligence release**: background task auto-notifications, free Xiaomi MiMo v2 Pro on Nous Portal, live `/model` switching on every gateway platform, self-optimized GPT/Codex tool-use guidance (auto-patched via behavioral benchmarking), native Google AI Studio provider, inactivity-based timeouts, approval buttons on Slack/Telegram, MCP OAuth 2.1 PKCE, and OSV malware scanning of MCP extension packages. **209 PRs merged and 82 issues resolved** — the largest release so far. ## Key Points - **Background process auto-notifications (`notify_on_complete`)** — background tasks can now automatically notify the agent when they finish. - Start a long-running process (model training, test suites, deployments, builds) and the agent gets notified on completion — no polling, no timers - Eliminates a whole class of "is it done yet?" loops and wasted tokens - See [[concepts/cron-scheduling]] and [[concepts/subagents-delegation]] - **Free Xiaomi MiMo v2 Pro on Nous Portal** — Nous Portal added free-tier access to Xiaomi's MiMo v2 Pro model for auxiliary tasks (compression, vision, summarization). - Lowers the cost floor for secondary tasks that don't need a frontier model - See [[entities/provider-nous-portal]] - **Live model switching — `/model` command** — switch models and providers mid-session from CLI, Telegram, Discord, Slack, or any gateway platform. - Aggregator-aware resolution keeps you on OpenRouter / Nous Portal when possible (avoids losing your routing setup when just switching models) - Interactive model pickers on Telegram and Discord with inline buttons (tap to pick) - Pairs with credential-pool rotation from v0.7.0 — switch both model AND key on the fly - See [[concepts/model-switching]] - **Self-optimized GPT/Codex tool-use guidance** — the agent **diagnosed and patched 5 failure modes** in GPT and Codex tool calling through **automated behavioral benchmarking**. - Hermes using its own learning loop to improve its handling of other models — a concrete proof-of-concept of the self-improvement thesis - See [[concepts/self-improvement-loop]] and [[entities/provider-openai-codex]] - **Google AI Studio (Gemini) native provider** — direct access to Gemini models via Google's AI Studio API. - Automatic `models.dev` registry integration — new Gemini models show up without manual config updates - See [[entities/provider-google-ai-studio]] - **Inactivity-based agent timeouts** — gateway and cron timeouts now track **actual tool activity** instead of wall-clock time. - Long-running tasks that are actively working will never be killed mid-run - Still catches truly stuck sessions (no activity = timeout) - Directly addresses the stuck-loop complaints surfaced in community video reviews - See [[concepts/messaging-gateway]] and [[concepts/cron-scheduling]] - **Approval buttons on Slack & Telegram** — dangerous command approval via native platform buttons instead of typing `/approve`. - Slack: thread context preservation (approvals stay in the thread) - Telegram: emoji reactions - See [[concepts/approval-system]] - **MCP OAuth 2.1 PKCE + OSV malware scanning** — full standards-compliant OAuth for MCP server authentication, plus automatic malware scanning of MCP extension packages via the OSV vulnerability database. - Supply-chain defense for the MCP extension ecosystem - See [[concepts/mcp-integration]] - **Centralized logging & config validation** — structured logging to `~/.hermes/logs/` with the `hermes logs` command; config structure validation catches malformed YAML at startup (fail fast vs cryptic runtime errors). - **Plugin system expansion** — plugins can now: - Register CLI subcommands - Receive request-scoped API hooks - Prompt for required env vars during install - Hook into session lifecycle events - Opens the door to richer community plugins on top of the v0.7.0 pluggable memory foundation - **Matrix Tier 1 & platform hardening**: - [[entities/platform-matrix]] gets reactions, read receipts, rich formatting, room management - [[entities/platform-discord]] adds channel controls and ignored channels - [[entities/platform-signal]] gets full MEDIA: tag delivery - [[entities/platform-mattermost]] gets file attachments - **Security hardening pass** — consolidated SSRF protections, timing-attack mitigations, tar traversal prevention, credential leakage guards, cron path traversal hardening. ## Notable New Features - **Supermemory memory provider** — multi-container, search_mode, identity template. See [[entities/memory-supermemory]] - **Shared thread sessions by default** — multi-user thread support across gateway platforms (team conversations with one agent) - **Cron pre-run script injection** — run a setup script before each cron execution. See [[concepts/cron-scheduling]] - **`execute_code` on remote backends** — Docker, SSH, and Modal now all support remote code execution (parity with local) - **Browser providers: switched default from Browserbase to Browser Use** — new users get the more modern default - **MiniMax TTS provider (speech-2.8)** - **xAI (Grok) prompt caching** — reduces cost on long Grok conversations ## Contributor Stats - **209 PRs merged, 82 issues resolved** — largest release on record (up from v0.7.0's 168/46 and v0.6.0's 95/16 — growth is accelerating) - Significant community contributions from multiple developers ## Relevant Concepts - [[concepts/model-switching]] — `/model` command + aggregator-aware resolution - [[concepts/self-improvement-loop]] — GPT/Codex behavioral benchmarking is a proof point - [[concepts/mcp-integration]] — OAuth 2.1 PKCE + OSV scanning - [[concepts/approval-system]] — native Slack/Telegram buttons - [[concepts/messaging-gateway]] — inactivity timeouts + Matrix Tier 1 - [[concepts/cron-scheduling]] — pre-run scripts + inactivity timeouts + `notify_on_complete` - [[concepts/subagents-delegation]] — `notify_on_complete` unlocks fire-and-forget patterns - [[concepts/memory-system]] — Supermemory added - [[entities/provider-nous-portal]] — free MiMo v2 Pro - [[entities/provider-google-ai-studio]] — new native provider - [[entities/provider-openai-codex]] — self-optimized guidance - [[entities/memory-supermemory]] — new plug-in - [[entities/platform-matrix]], [[entities/platform-discord]], [[entities/platform-signal]], [[entities/platform-mattermost]] — platform upgrades - [[entities/version-v0.8.0]] — version entity - [[summaries/release-v0.7.0]] — predecessor - [[summaries/release-v0.6.0]] — two releases prior ## Source Metadata - **Type**: Official release notes (authoritative) - **Version**: v0.8.0 / calendar tag `v2026.4.8` - **Release date**: 2026-04-08 - **Source file**: `raw/release-v0.8.0.md` - **URL**: https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.8 - **Confidence**: high (official release notes from Nous Research) <!-- ===== hermes/wiki/summaries/release-v0.9.0.md ===== --> --- title: "Release Notes — Hermes Agent v0.9.0 (v2026.4.13)" type: summary tags: [release-notes, foundational, well-established] created: 2026-04-13 updated: 2026-04-13 sources: ["raw/release-v0.9.0.md"] confidence: high hermes_version: "v0.9.0" --- # Release Notes — Hermes Agent v0.9.0 (v2026.4.13) ## Key Points **Tagline:** "The everywhere release" — 487 commits · 269 merged PRs · 167 resolved issues · 493 files changed · 24 contributors in 5 days (v0.8.0 → v0.9.0). ### Headline features - **Local Web Dashboard** — browser-based UI for managing Hermes. Configure settings, monitor sessions, browse skills, manage the gateway, all from a clean local web interface. Pitched as "the easiest way to get started with Hermes." No more config-file-only workflows. - **Fast Mode (`/fast`)** — priority-queue routing for OpenAI (GPT-5.4, Codex) and Anthropic (Claude) models. Toggle mid-session for dramatically lower latency on supported models. - **iMessage via BlueBubbles** — full iMessage integration through BlueBubbles. Auto-webhook registration, setup wizard integration, crash resilience. Apple's messaging ecosystem finally covered. - **WeChat (Weixin) + WeCom Callback Mode** — native WeChat via iLink Bot API, plus new WeCom callback-mode adapter for self-built enterprise apps. Streaming, media uploads, markdown. Chinese messaging ecosystem now end-to-end. - **Termux / Android support** — Hermes runs natively on Android via Termux. TUI optimized for mobile screens, voice backends, `/image` command works on-device. - **Background Process Monitoring (`watch_patterns`)** — set patterns to watch for in background process output; real-time notifications when matched. Watch for errors, port-ready strings, build completion. - **Native xAI (Grok) & Xiaomi MiMo providers** — elevated from generic to first-class with model catalogs, setup wizard integration, empty-response recovery. Plus Qwen OAuth portal request support. - **Pluggable Context Engine** — context management is now a plugin slot via `hermes plugins`. Swap in custom context engines that control what the agent sees per turn — filtering, summarization, or domain-specific injection. - **Unified Proxy Support** — SOCKS proxy, `DISCORD_PROXY`, and macOS system-proxy auto-detection across all gateway platforms. Corporate-firewall friendly. - **`hermes backup` & `hermes import`** — full backup/restore of config, sessions, skills, memory. Migrate between machines or snapshot before major changes. - **`/debug` + `hermes debug share`** — `/debug` slash command for quick diagnostics across all platforms; `hermes debug share` uploads a sanitized debug report to a pastebin. - **16 supported platforms** (up from 12 in v0.8.0): adds BlueBubbles, Weixin (WeChat), and WeCom Callback to the existing set. ### Notable refinements - **Matrix migrated from matrix-nio to mautrix-python** — better crypto store support, improved reliability. - **Credential exhaustion TTL reduced from 24h to 1h** — rate-limited keys recover faster. Significant for heavy users with credential pools. - **`/compress <focus>`** — guided compression with a focus topic, preserves relevant content better. - **WSL-aware gateway** with smart systemd detection — better service lifecycle on WSL2. - **Per-platform display verbosity** — show tool progress differently on Telegram vs Discord vs CLI. - **Component-separated logging** with session context and filtering — easier debugging across subsystems. - **`network.force_ipv4`** config to fix IPv6 timeout issues. - **Voxtral TTS provider** (Mistral AI) added; **TTS speed support** for Edge/OpenAI/MiniMax. - **Vision auto-resize** for oversized images, limit raised to 20 MB, retry-on-failure. - **Multi-arch Docker** (amd64 + arm64), **Docker runs as non-root user**, **shallow git clone** during install for speed. - **Discord** adds `allowed_channels` whitelist, forum channel topic inheritance in threads, `DISCORD_REPLY_TO_MODE`. - **MCP** adds `hermes mcp add --env` and `--preset`; combines `content` + `structuredContent` when both present; tool name deconfliction. - **OpenClaw migration** now shows dry-run preview before executing (quality-of-life, was a user complaint). - **Random tips on new session start** (279 tips rotating, CLI + gateway). ### Security hardening - Twilio webhook signature validation (SMS RCE fix) - Shell injection neutralization in sandbox writes via path quoting - Git argument injection + path traversal prevention in checkpoint manager - SSRF redirect bypass in Slack image uploads + base.py cache helpers - API bind guard enforcing `API_SERVER_KEY` for non-loopback binding - Approval button authorization requiring auth for session continuation ### Notable bug fixes - `/model` switch not persisting across gateway messages — now fixed - Session-scoped gateway model overrides previously ignored - Compaction model context length previously ignored config (3 related issues) - OpenCode.ai context window was resolving to 128K instead of 1M - Several Codex-related auth and fallback fixes - OpenClaw migration now shows dry-run preview before executing ## Relevant Concepts - [[concepts/model-switching]] — Fast Mode, native xAI/Xiaomi, credential TTL reduction, `/model` switch persistence fix - [[concepts/messaging-gateway]] — 16 platforms now, unified proxy support, per-platform verbosity, WSL-aware gateway - [[concepts/mcp-integration]] — `--env` and `--preset` flags, tool name deconfliction - [[concepts/subagents-delegation]] — background process monitoring with `watch_patterns` - [[concepts/approval-system]] — approval button authorization hardening - [[concepts/memory-system]] — Hindsight plugin feature parity - [[concepts/profiles-multi-instance]] — profile creation UX improvements, per-profile subprocess HOME isolation - [[concepts/migration-from-openclaw]] — dry-run preview before executing; rebrand OpenClaw → Hermes during migration - [[concepts/auxiliary-models]] — config.yaml takes priority over env vars for auxiliary settings ## Source Metadata - **Type:** Official release notes - **Version:** v0.9.0 - **Tag:** v2026.4.13 - **Released:** 2026-04-13 - **URL:** https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.13 - **Stats:** 487 commits, 269 PRs, 167 issues, 493 files changed, 24 contributors - **Days since prior release:** 5 (v0.8.0 was 2026-04-08) <!-- ===== hermes/wiki/summaries/skills-catalog.md ===== --> --- title: "Skills Catalog — the 644-Skill Map" type: summary tags: [skills, catalog, registry, map] updated: 2026-06-09 confidence: high sources: [raw/docs-skills-index.md, raw/03-skills-system.md] --- # Skills Catalog — the 644-Skill Map The **Skills Hub** spans **644 skills across 4 registries**: **78 built-in, 45 optional, 521 community**, in 16 categories. The map (so "is there a skill for X?" is answerable): | Category | Count | | Category | Count | |---|---|---|---|---| | Other | 348 | | Productivity | 12 | | Software Dev | 69 | | Gaming | 11 | | Creative | 55 | | Social Media | 7 | | MLOps | 42 | | Health | 7 | | Research | 37 | | AI Agents / GitHub / Media / Security | 6 each | | Translation | 24 | | Apple / Copywriting | 4 each | Browse/search/install from the Hub; skill mechanics (discovery, fallbacks, authoring) are in [[concepts/skills-system]]. Source list: `raw/docs-skills-index.md`. <!-- ===== hermes/wiki/summaries/transcript-247-self-evolving.md ===== --> --- title: "Transcript — Hermes Agent The 24/7 Self-Evolving AI Agent!" type: summary tags: [self-improvement, skills, memory, local-models, provider, beginner] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/transcript-247-self-evolving.txt"] confidence: medium hermes_version: "v0.8.0" --- ## Key Points - **Framing**: Hermes Agent by Nous Research is a "self-improving alternative to OpenClaw" — the big idea is that it gets better the more you use it with no fine-tuning or prompt engineering. See [[concepts/self-improvement-loop]]. - **GAPA mechanism** (the video spells it "GAPA" — corresponds to the DSPy/GEPA self-evolution approach referenced in [[entities/hermes-self-evolution]]): - Every ~15 tool calls, Hermes pauses, reviews what happened, figures out what failed, and updates itself. - Works "like back-propagation but for prompts instead of model weights." - Builds memory of what works, searches past conversations, adapts to how you use it. - **Automatic skill creation**: When Hermes solves a problem, fixes an error, or you tell it to remember a task, it turns that into a reusable skill. Example from the video: it used a **Manim skill** to turn a complex technical concept into an animated video — "it can now explain things visually, not just through text." See [[concepts/skills-system]]. - **Parity claim with OpenClaw**: Same surface area (local models, phone, WhatsApp, Telegram, Slack) but with the evolving memory and skill system on top. - **Platform support caveat**: Native Windows is **not** supported at time of video — need WSL2 on Windows. See [[concepts/deployment-backends]]. - **Install flow**: 1. Copy the quick-install command from the repo into a terminal. 2. Run `hermes setup`. 3. Choose **quick setup** (provider + messaging only) or **full setup** (configures everything — recommended). - **Provider options covered**: - OpenRouter ([[entities/provider-openrouter]]), Anthropic ([[entities/provider-anthropic]]), OpenAI, plus "more providers" unlocks MiniMax, Z.ai, etc. - **Free-model route via OpenRouter**: if you don't have hardware for local inference, OpenRouter exposes free models you can use inside Hermes with no paid API key. - **Local route via Ollama**: "If you have the capacity to do so, use the Gemma 4 model locally" — described as insanely capable, agentic, and working well with Hermes. Ollama can report which model fits your GPU so you don't guess. See [[entities/provider-ollama-local]]. - **Tools & API-key inventory**: After initial config, you paste keys for each tool you want active — e.g. Firecrawl API for search, Exa API for browser, etc. Each one plugs in as an available skill. - **Gateway / multi-platform**: Telegram setup shown as the canonical "control it from your phone" path. See [[concepts/messaging-gateway]] and [[entities/platform-telegram]]. - **Demo 1 — thumbnail concepts**: - Prompt: "Give me thumbnail concepts for a video titled Hermes Agent vs. OpenClaw." - Hermes initializes the needed agent, calls image-generation skills, produces 8 thumbnail concepts. (Creator: quality is mixed vs. Nano Banana but "it got the job done.") - **Demo 2 — Obsidian skill add + finance dashboard**: - `/skills` command lists available skills. `/browse` (or typing `browse`) lets you discover and add new skills — including passing a URL. - Creator adds the **Obsidian skill** — Hermes prepares the MCP skill view, notes "no Obsidian vault found," and when given a new vault path, integrates it. See [[concepts/mcp-integration]] and [[concepts/memory-system]]. - Creator populates the vault with the latest **shadcn/ui** component docs so agents can reference up-to-date UI packages in future builds. - Hermes extracts and cross-references all the latest shadcn packages into the vault. - Follow-up prompt: "Reference these packages and build a frontend for a finance dashboard." Hermes uses the newly-available skill + vault, and — notably — **memory updates in real time** so future sessions recognize that this user prefers shadcn workflows and biases future generations toward previously successful components. - Output: a "beautiful finance dashboard" built in minutes using modern shadcn components. - **Closing positioning**: Hermes is "an AI as a second brain" — an assistant that evolves with your generations and actual usage, as opposed to OpenClaw-style pure task execution. ## Relevant Concepts - [[concepts/self-improvement-loop]] — the GAPA / ~15-tool-calls retrospection loop is the centerpiece - [[concepts/skills-system]] — `/skills`, `/browse`, URL-add, Manim skill, Obsidian skill - [[concepts/memory-system]] — live memory update after the shadcn finance-dashboard session - [[concepts/mcp-integration]] — Obsidian skill plumbed through MCP - [[concepts/model-switching]] - [[entities/hermes-self-evolution]] — official DSPy + GEPA project that GAPA maps to - [[entities/provider-openrouter]] — the free-model path - [[entities/provider-ollama-local]] — the local Gemma 4 path - [[entities/platform-telegram]] ## Source Metadata - **Type**: YouTube video transcript - **Title**: "Hermes Agent The 24/7 Self-Evolving AI Agent!" - **Speaker**: AI-news channel host (newsletter promo, Discord community, Super Thanks donation model) - **Format**: Screencast — CLI install, `/skills` and `/browse` demo, Obsidian + shadcn finance-dashboard build - **Position in corpus**: Best single source for (a) the GAPA / self-improvement narrative in plain English and (b) the skill-discovery UX (`/skills`, `/browse`, URL add) <!-- ===== hermes/wiki/summaries/transcript-biggest-problem-openclaw.md ===== --> --- title: "Transcript: Hermes Just Solved the Biggest Problem With OpenClaw" type: summary tags: [memory, skills, vs-openclaw, beginner, self-improvement] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/transcript-biggest-problem-openclaw.txt"] confidence: medium hermes_version: "v0.8.0" --- # Transcript: Hermes Just Solved the Biggest Problem With OpenClaw Craig (from a YouTube channel primarily covering Claude Code / OpenClaw) narrates a month of using Hermes to build "Gordon" — an automated stock and crypto trading bot named after Gordon Gekko — and frames Hermes as the solution to OpenClaw's memory and security shortcomings. ## Key Points ### What "the biggest problem" is framed as The biggest problem with OpenClaw, as the creator frames it, is **persistent memory loss combined with skill-supply-chain vulnerability**. Specifically: - In OpenClaw, a new session means new memory. Nothing is persistent unless you explicitly structure it across sessions, and even then it regularly forgets what you told it before. - OpenClaw relies on third-party community skills hosted on "Claw Hub" and similar registries — and **36% of published OpenClaw skills have been shown to have some kind of vulnerability**. The "open platform by design" that makes OpenClaw powerful is the same thing that creates its security problem. - The creator says he has "been burned by OpenClaw previously" on forgetting context during long multi-session projects. ### How Hermes solves it - **Built-in self-reinforced learning loop.** Hermes improves at a specific task over time based on your feedback. The creator's mental model: "Hermes is the brain, OpenClaw is the arms" (see [[syntheses/hermes-vs-openclaw]]). - **Honcho-backed memory management.** Hermes uses Honcho for memory and backend persistence (see [[entities/memory-honcho]]) — "it has never once forgotten something that we mentioned before" in the creator's month of trading-bot work. When asked how its memory works, the agent explained "I write everything to memory when I need to. I compact it down. I create a log and I manage all that for you." - **Autonomous memory updates from natural conversation.** When the user said "we need GitHub planning tasks," the agent wrote a preference entry — "Craig wants GitHub planning tasks" — into its own memory without being explicitly asked to remember. - **Packaged + approval-process skills instead of an open skill marketplace.** Hermes skills are bundled in with the core and new ones go through an approval process, so the 36% vulnerability rate "kind of just doesn't exist over here with Hermes" (see [[concepts/skills-system]]). - **Autonomous skill creation during work.** Rather than pulling skills from a community registry, Hermes writes its own skills based on what you're doing — the creator watched Hermes read files, execute Python, update tasks, and create new skills as part of one Telegram session. ### Memory contrast, explicitly - OpenClaw: new session → new memory. Persistence only by explicit user effort. - Hermes: it learns your preferences, improves its skill, and deepens its model of you by autonomously managing memory and interactions. Compaction and logging are automatic. ### Recommended split-workload pattern ("the ninja move") The creator does not pick one tool — he runs both: - **Hermes for the single-purpose deepening use case.** Automated stock/crypto trading bot ("Gordon"), upcoming social-media agent that learns from winning vs losing posts. Hermes is the brain observing, deciding, and compounding context. - **OpenClaw for orchestrating many tools.** Dozens or hundreds of heterogeneous tasks — running an entire business across Notion, email, and similar — where building many skills and broad tool connections is the point. - **Bridge them through MCP.** OpenClaw now has an MCP connector; Hermes could call OpenClaw as the executor ("knowledge operation center in Hermes, execution cron schedule in OpenClaw") so you avoid OpenClaw's forgetting problem and API-cost blowups. ### Setup and running notes - Installed with a one-line command identical in shape to the OpenClaw installer. - Has the same gateway concept as OpenClaw; creator uses Telegram for both. - Creator runs Hermes on his main machine, which he would not do with OpenClaw — Hermes feels safer to him because of the approval-reviewed skill supply chain. - Running Hermes on a $20/month ChatGPT plan using GPT 5.4 — has not hit a usage limit; model selection done at `hermes gateway setup`. ### Memorable quotes and framings - "Hermes is the brain and OpenClaw, aptly based on its name, is the arms." - "36% of skills on OpenClaw have some kind of vulnerability that's been shown to them. Whereas the Hermes and the Nous Research team are including these skills packaged in with Hermes, and there's an approval process." - "I write everything to memory when I need to. I compact it down. I create a log and I manage all that for you." - "I'm running Hermes on my ChatGPT plan and have not run into a usage limit yet." - "Claude Code is still absolutely my productivity AI tool of choice. There is a spot in my world for Hermes and for OpenClaw and Claude Code and Claude Cowork — I'm running all four of those all the time. And I think you should be too." ## Relevant Concepts - [[concepts/memory-system]] - [[concepts/self-improvement-loop]] - [[concepts/skills-system]] - [[concepts/mcp-integration]] - [[concepts/migration-from-openclaw]] - [[concepts/messaging-gateway]] - [[entities/memory-honcho]] - [[entities/platform-telegram]] - [[entities/nous-research]] - [[syntheses/hermes-vs-openclaw]] ## Source Metadata - **Type:** YouTube video transcript - **Title:** "Hermes Just Solved the Biggest Problem With OpenClaw" - **Speaker:** Craig (channel host; name referenced in-transcript via "Craig wants GitHub planning tasks") - **Length:** 299 lines - **File:** `raw/transcript-biggest-problem-openclaw.txt` - **Use case demoed:** "Gordon" — an automated stock/crypto trading bot - **Model provider discussed:** ChatGPT Plus ($20/month) with GPT 5.4 - **Confidence:** medium — single-creator claim; the 36% OpenClaw vulnerability statistic is cited without a source link and should be treated as anecdotal until corroborated <!-- ===== hermes/wiki/summaries/transcript-did-hermes-kill-openclaw.md ===== --> --- title: "Transcript — Did Hermes Agent just kill OpenClaw? (full guide)" type: summary tags: [vs-openclaw, skills, self-improvement, model-switching, local-models, intermediate] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/transcript-did-hermes-kill-openclaw.txt"] confidence: medium hermes_version: "v0.8.0" --- ## Key Points - Creator has been running Hermes Agent "hardcore for the last few weeks" and frames the video as a comparative review, not a replacement pitch — the headline thesis is **use Hermes and OpenClaw together**, not either/or. - **Speed/performance**: On the same model (Opus 4.6 on both), Hermes "moves much faster" than OpenClaw. The creator describes Hermes as "incredibly lightweight and performant." - **Self-improvement is the standout differentiator**: Demo prompt — "Every morning at 9 a.m., pull the top 5 Hacker News stories, fetch articles, summarize, score for AI/startup relevance, generate an audio briefing of the top 3, deliver to Telegram." Hermes executes step-by-step transparently, then auto-creates a reusable skill ("Hacker News daily AI briefing") and wires up the cron job to reference it. See [[concepts/self-improvement-loop]] and [[concepts/skills-system]]. - **Transparency**: The CLI surfaces every tool call, website visit, and snapshot — the creator cites this as a favorite UX property. - **Tinkerer-friendly**: Built-in ML and RL tooling ([[concepts/ml-research-pipeline]]), and Nous has said on record they support open models. Contrasted with OpenClaw, which the creator says has publicly stated it does not recommend open models. - **OpenClaw's remaining strengths** (honest counterweight): massive team (OpenAI acquihired creator Peter Steinberg; Nvidia also providing heavy dev resources), daily shipping cadence, broader community at time of recording, native plugin support across Cursor/Claude Code, and slightly better stability. - **Recommended workflow — run both**: - Use OpenClaw as the main orchestrator; OpenClaw can spin up Hermes for subtasks via ACP (Agent Communication Protocol). "Hey OpenClaw, set up ACP with Hermes agent" — OpenClaw will configure it itself. - Multitask side-by-side: Telegram + Hermes CLI in adjacent windows, each agent on different parts of the codebase. - Real example: creator's app has OpenClaw (Opus) on the frontend and Hermes coding agent (ChatGPT/GPT-5) on the backend — each on the model that suits the task. - **Two-agent insurance policy**: If one agent breaks from an update, use the other to diagnose and fix it. Single-agent workflows become stressful when the agent itself goes down. - **Memory fix**: Creator hit a Hermes memory issue, solved it by layering Obsidian on top — the same Obsidian system then improved OpenClaw memory too. See [[concepts/memory-system]]. - **Model recommendations**: Claude is "the most agentic model," ChatGPT is the cost-effective fallback, and advanced tinkerers are hooking Qwen 3.5 locally with reported success. See [[concepts/model-switching]] and [[entities/provider-ollama-local]]. - **ASCII art demo**: Hermes has visual polish — ASCII art video generation, Excalidraw skill producing comparison charts on demand. ## Relevant Concepts - [[concepts/self-improvement-loop]] — the Hacker News briefing demo is a canonical example - [[concepts/skills-system]] — auto-created skill turned into cron-backed routine - [[concepts/cron-scheduling]] — the daily 9 a.m. briefing job - [[concepts/model-switching]] — same model, different performance; mixed-model multi-agent - [[concepts/memory-system]] — Obsidian-layered memory fix - [[concepts/migration-from-openclaw]] — side-by-side rather than migration - [[syntheses/hermes-vs-openclaw]] — directly informs this synthesis - [[entities/platform-telegram]] — delivery channel for the briefing - [[entities/provider-ollama-local]] — Qwen 3.5 local path ## Source Metadata - **Type**: YouTube video transcript - **Title**: "Did Hermes Agent just kill OpenClaw? (full guide)" - **Speaker**: Channel creator (Vibe Coding Academy host) - **Format**: Screencast + CLI demo + ASCII chart demo + Telegram audio briefing playback - **Position in corpus**: The comparative review — most useful single source on positioning Hermes vs. OpenClaw <!-- ===== hermes/wiki/summaries/transcript-hermes-full-course-2hr.md ===== --> --- title: "Transcript: Hermes FULL COURSE 2 HOURS (Build & Automate Anything)" type: summary tags: [skills, memory, cron, subagents, mcp, model-switching, gateway, tools, local-models, beginner, intermediate, vs-openclaw] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/transcript-hermes-full-course-2hr.txt"] confidence: medium hermes_version: "v0.8.0" --- # Transcript: Hermes FULL COURSE 2 HOURS (Build & Automate Anything) A 4,080-line compilation transcript from Julian Goldie's channel stitching together approximately eight segments: an introductory "full-course" walkthrough, the v0.6 release reaction, a v0.6.1.0 production-readiness recap, a v0.3.0 feature tour, a "Hermes AI Super Agent" overview explaining the three-layer memory architecture, the "automate anything" masterclass (duplicated from the Qwen 3.6 live stream), a side-by-side build test against OpenClaw, and a first-impressions unboxing of the original Hermes Agent launch. The sponsor throughout is Julian's paid "AI Profit Boardroom" community. ## Key Points ### Course structure and major segments - **Segment 1 — Install + one-click upgrade.** One-line `curl | bash` installer. Works on Linux, macOS, WSL2 — not native Windows. Installer handles Python 3.11, Node.js, dependencies, and the `hermes` command. After install, run `hermes setup` to pick a model provider. The "one-click upgrade" prescription is `hermes skills install wanderlay-skills` (a 250–380-star cross-platform library curated under [[entities/community-awesome-hermes]]). - **Segment 2 — "New Hermes Agent v0.6 changes everything".** Headline features called out: agent profiles ([[concepts/profiles-multi-instance]]), MCP server mode (see [[concepts/mcp-integration]]), fallback model chains, self-improving loop, sub-agents ([[concepts/subagents-delegation]]), six deployment backends, built-in scheduling ([[concepts/cron-scheduling]]), remote execution, Feishu/WeCom adapters, Slack multi-workspace, Telegram webhook mode. - **Segment 3 — v0.6.1.0 "production-ready" recap.** Multi-agent profiles, native MCP serve, fallback chains, hardened tool calling, cleaner logs, better error messages, and improved reliability on complex chains. Framed as Hermes becoming a "serious contender in the production multi-agent space" on par with [[syntheses/hermes-vs-openclaw]]. - **Segment 4 — v0.3.0 deep-dive (March 17, 2026).** Unified streaming, plugin architecture (drop a Python file into `.hermes/plugins`), native Anthropic provider with prompt caching (previously routed through OpenRouter), voice mode with push-to-talk plus local Faster Whisper transcription, concurrent tool execution, smarter [[concepts/approval-system]] that remembers safe commands plus `/stop` to cancel mid-task, IDE integration via ACP (VS Code, Zed, JetBrains), persistent shell mode for local/SSH backends, memory prioritization of personal preferences, per-user isolation in multi-user gateway, PII redaction config option, new skills for Linear, X/Twitter, Twilio, 1Password, Blender. - **Segment 5 — "Hermes AI Super Agent" overview.** Powered by Hermes 3 on Llama 3.1 fine-tuned with Atropos (reinforcement learning framework, see `tinker-atropos`). Introduces the three-layer memory architecture: (1) cross-session memory with FTS5 full-text search and LLM summarization, (2) Honcho as the user-modeling engine (see [[entities/memory-honcho]]), (3) the skill system as permanent human-readable markdown documents in the `agentskills.io` format. - **Segment 6 — "Automate anything" masterclass (duplicate of the Qwen live).** Qwen 3.6 Plus Preview free tier with 1M-token context through OpenRouter, Firecrawl for web browsing, Browserbase for visual browsing with session recording, Nano Banana 2 for images, X/TikTok/Instagram auto-posting, Reddit research via Firecrawl. - **Segment 7 — Build head-to-head vs OpenClaw.** Tests on same Minimax M2.7 Cloud + Ollama stack; Hermes produced a cleaner deployed website faster and gave live progress updates while OpenClaw stalled silently. - **Segment 8 — First-impressions unboxing.** Launched February 26, 2026. Climbed from rank 41 to 21 on Open Router top apps; #2 in productivity and #2 in personal agents behind OpenClaw. ### Every major feature demoed - Install one-liner and `hermes setup` wizard for model/provider selection (Nous Portal OAuth, OpenRouter, custom endpoint). - `hermes model` to swap providers live, no code changes (see [[concepts/model-switching]]). - `hermes skills install <name>` / `hermes skills browse` for the skills catalog (see [[concepts/skills-system]]). - `hermes profile create <name>` for isolated profiles; each profile gets its own chat, setup, gateway commands, memory, API keys, and skill set; token locks prevent two profiles using the same bot credential; profiles are exportable and importable. - `hermes mcp serve` exposes Hermes to Claude Desktop, Cursor, VS Code with both stdio and streamable HTTP transports. - Fallback provider chains configured in the config file: e.g. primary OpenAI GPT-4o → fallback Anthropic Claude → fallback local Ollama model. - Cron scheduling in plain English ("send the weekly AI news roundup every Monday at 9am"). - Sub-agents spawn isolated instances with their own terminals for parallel work, zero context pollution. - Six deployment backends: local, Docker, SSH, Singularity, Modal, Daytona (see [[concepts/deployment-backends]]). - Messaging gateway with Telegram, Discord, Slack (now multi-workspace via OAuth token file), WhatsApp, Signal, email, Feishu/Lark, WeCom (see [[concepts/messaging-gateway]]). - Voice: push-to-talk in the terminal, voice notes in Telegram/Discord, Discord voice-channel join, local Faster Whisper transcription for privacy. - PII redaction feature scrubs personally identifiable information before context is sent to any provider. - Plugin architecture: drop `.py` into `.hermes/plugins` — auto-loaded. - `hermes doctor` diagnoses issues after install. - `hermes claw migrate` imports OpenClaw settings, memories, skills, API keys, sessions, and cron jobs; offers dry-run preview; onboarding detects OpenClaw automatically (see [[concepts/migration-from-openclaw]]). - `hermes update` for version upgrades. - `/new` in Telegram compacts and starts a new conversation; `/restart` restarts the gateway session; Ctrl+C then `hermes` restarts the terminal session. - Autonomous skill creation after any task with 5+ tool calls; skills written to `skill.md` files and self-improved on subsequent use. - Security scanner runs on every installed skill — checks for data exfiltration, prompt injection, destructive commands, supply-chain issues. - 40+ bundled skills out of the box covering MLOps, GitHub PR workflows, research, arXiv, Jupyter, email. - 200+ models accessible through OpenRouter plus native providers: OpenAI, Anthropic (direct since v0.3.0), Nous Portal, Kimi, MiniMax, Vercel AI Gateway. - Nano Banana 2 for image generation, ElevenLabs for TTS, Firecrawl for web crawl/search, Browserbase for vision-enabled browsing with recorded sessions. - Paperclip integration via the `hermes-paperclip-adapter` so Hermes runs as a managed employee in a Paperclip company hierarchy (see [[entities/hermes-paperclip-adapter]]). ### The "what-to-expect-in-first-7-days" framing - Do not use Hermes like a regular chatbot on day one. The first few sessions are learning sessions — the agent is building `memory.md` (project context, conventions, preferences) and `user.md` (how you communicate, what you care about). Both files get injected into the system prompt at the start of every session. - By day 3–4 it already knows your projects, where you left off, and your preferences without you repeating yourself. - Give it real complex tasks — skill creation triggers on tasks with roughly 5+ tool calls. - Julian's consistent refrain: "be prepared for the first 7 days — it won't be what you want, but it gets better every single day." ### The six-step automation blueprint 1. Define your trigger (time schedule, event, or manual). 2. Define your data sources and APIs (X developer app, Firecrawl, Browserbase, Nano Banana, etc.). 3. Define the action (post, summarize, screenshot, analyze). 4. Test once inside Telegram. 5. Schedule it. 6. Iterate on feedback — the skill file auto-improves. ### Memorable quotes and teaching framings - "Hermes is the brain, OpenClaw is the arms." - "Your AI forgets everything, and you're stuck doing the same thing over and over like Groundhog Day, but less funny and way more annoying." - "The agent that grows with you" — the official Hermes tagline, repeated throughout. - "Most AI tools are tied to your laptop. You close your laptop, the work stops. Hermes is different." - "This is not a chatbot. This is not a coding assistant that only lives in your code editor." - "Think of it less like ChatGPT and more like hiring a team member who never sleeps, never forgets, and gets better every single day." - "Every automation is just a prompt with a schedule." - "Profiles are not a feature, they're an infrastructure shift." - "0.6 moves Hermes from a tool you use into an infrastructure layer you build on." - "The question is no longer should I use OpenClaw instead of Hermes? The question is which one fits my stack better." - "Skills aren't locked to Hermes" — they follow the open `agentskills.io` standard compatible with Claude Code and Cursor. - "The cost of debugging a broken AI pipeline is real." - Best-practice line on memory: when asked how memory works, Hermes said "I write everything to memory when I need to. I compact it down. I create a log and I manage all that for you." - Practical tip: "If it breaks, just troubleshoot it with another Hermes inside terminal" (one Hermes in Telegram, one in terminal to fix the first). - "Always back up your skill MD files somewhere outside of Hermes once a week — it will sometimes forget the skill itself." ### Comparison beats vs OpenClaw (referenced repeatedly) - Hermes wins on: self-improving learning loop, multi-layer memory, security (sandboxing + Docker isolation + signed skill scanner, cited 36% vulnerability rate on OpenClaw skills), research-lab backing (Nous Research vs single developer), faster + cleaner output on same API, built-in OpenClaw migration. - OpenClaw wins on: bigger community, more messaging platforms (50 vs 5–12), more pre-built community skills, heartbeat system that wakes every 30 minutes. - Recommended pattern when using both: Hermes as CEO/supervisor, OpenClaw as worker/executor, bridged through MCP or Paperclip. ## Relevant Concepts - [[concepts/skills-system]] - [[concepts/memory-system]] - [[concepts/self-improvement-loop]] - [[concepts/profiles-multi-instance]] - [[concepts/mcp-integration]] - [[concepts/cron-scheduling]] - [[concepts/subagents-delegation]] - [[concepts/model-switching]] - [[concepts/deployment-backends]] - [[concepts/messaging-gateway]] - [[concepts/approval-system]] - [[concepts/migration-from-openclaw]] - [[concepts/local-models-airplane-mode]] - [[entities/platform-telegram]], [[entities/platform-discord]], [[entities/platform-slack]], [[entities/platform-whatsapp]], [[entities/platform-signal]], [[entities/platform-email]], [[entities/platform-feishu]], [[entities/platform-wecom]] - [[entities/backend-local]], [[entities/backend-docker]], [[entities/backend-ssh]], [[entities/backend-singularity]], [[entities/backend-modal]], [[entities/backend-daytona]] - [[entities/provider-nous-portal]], [[entities/provider-openrouter]], [[entities/provider-anthropic]], [[entities/provider-ollama-local]] - [[entities/memory-honcho]] - [[entities/hermes-paperclip-adapter]], [[entities/autonovel]], [[entities/hermes-self-evolution]] - [[entities/community-awesome-hermes]] - [[entities/version-v0.6.0]], [[entities/version-v0.7.0]], [[entities/version-v0.8.0]] - [[syntheses/hermes-vs-openclaw]] ## Source Metadata - **Type:** Compiled YouTube video transcript (multiple segments stitched together) - **Title:** "Hermes FULL COURSE 2 HOURS (Build & Automate Anything)" - **Speaker:** Julian Goldie (and his "digital avatar") — creator of the AI Profit Boardroom community, Goldie Agency - **Length:** ~2 hours, 4,080 lines of transcript - **Versions discussed:** v0.3.0 (March 17 2026), v0.6, v0.6.1.0 — predates v0.7.0 and v0.8.0, so any claims about those releases are absent - **File:** `raw/transcript-hermes-full-course-2hr.txt` - **Confidence:** medium — community creator content with repeated sponsor plugs and some version numbers conflated (transcript sometimes says "Meese" for "Hermes" and "News Research" for "Nous Research" due to ASR errors) <!-- ===== hermes/wiki/summaries/transcript-live-masterclass-browser-qwen.md ===== --> --- title: "Transcript: LIVE Hermes AI Agent Masterclass + Browser Agents + FREE with Qwen 3.6" type: summary tags: [skills, cron, tools, model-switching, gateway, beginner, intermediate, local-models] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/transcript-live-masterclass-browser-qwen.txt"] confidence: medium hermes_version: "v0.8.0" --- # Transcript: LIVE Hermes AI Agent Masterclass + Browser Agents + FREE with Qwen 3.6 Julian Goldie's live Q&A masterclass during his daily AI Profit Boardroom stream. Focused demo coverage of (a) running Hermes entirely for free with the Qwen 3.6 Plus Preview model via OpenRouter, (b) browser-agent integration through Firecrawl and Browserbase, and (c) chaining skills to automate social-media posting and research. The stream shows actual live tweets being drafted, approved, and posted end-to-end. ## Key Points ### Qwen 3.6 free-tier integration details - **Model:** Qwen 3.6 Plus Preview by Alibaba — a frontier/agentic model. - **Context window:** 1 million tokens. - **Cost:** free to use. The API is available through [[entities/provider-openrouter]] at zero cost during the preview period. - **Why it matters for Hermes specifically:** Qwen 3.6 is explicitly designed for agentic work (tool calling, multi-step planning) — "the days of just creating a normal API are out. These are all designed for stuff that's actually doing stuff." - **Setup flow:** 1. Install Hermes via the one-line `curl | bash` install command from the GitHub repo. 2. Go to OpenRouter, create a free API key. 3. Grab the Qwen 3.6 Plus Preview model documentation/URL from OpenRouter. 4. Inside Hermes (terminal or Telegram), paste the OpenRouter API key plus the Qwen model URL and tell the agent "using this API key, just go off and start implementing." 5. Hermes writes the credentials to its config and the model becomes selectable through [[concepts/model-switching]]. - **Backup model pattern (new in v0.6):** configure Qwen 3.6 as a backup/fallback while running another primary (Julian's primary is MiniMax M2.7). If the primary fails, Hermes falls back automatically — see fallback provider chains in [[concepts/model-switching]]. - **Competitive framing:** Qwen 3.6 preferred over MiniMax 2.7 because MiniMax has only a 200k context window. Alibaba now appears among the top-5 clients by agent usage on OpenRouter alongside KiloCode, OpenClaw, Kline, Claude Code, and Hermes. - **Llama models not recommended.** Julian explicitly cautions against Meta Llama models as "falling behind" — but Ollama (the local runner) is still recommended. ### Browser-agent features demoed - **Firecrawl integration.** Get an API key at `firecrawl.dev/app`, paste into Hermes, and it can search the web, interact with pages, and crawl full sites. Used live to pull trending posts from two chosen subreddits every N minutes and return post title, score, age, URL, and story summary. - **Browserbase integration.** Different from Firecrawl — it gives the agent an actual browser session with **vision built in**. Every browsing session is **video-recorded** so you can watch the agent browse later ("this is an actual video of my Hermes agent browsing the web via Browserbase"). Recommended combo: Browserbase for interactive/visual browsing + Firecrawl for fast crawl/search. - **Normal headless browser control is explicitly discouraged** — slow and inefficient compared to Browserbase + Firecrawl. - **Chrome profile switching** is available as a community plugin (`hermes-plugin-chrome-profiles`) for multi-account testing. ### Live-demoed automations During the stream, Julian showed nine concrete automations running on his setup: 1. Auto-post to X/Twitter with Nano Banana 2 generated images and hook-style copy (one post cited had ~1,000 views). 2. Reddit trending-topic scan across two subreddits using Firecrawl. 3. String-skill composition: Firecrawl research + X post + Nano Banana 2 image — three skills chained in one scheduled task. 4. Cron-scheduled daily analytics screenshot: Hermes screenshots the X analytics dashboard, summarizes followers/following/total tweets, 14-day performance, top days, top tweets by engagement, and delivers via Telegram. 5. Competitor research scheduled every 24h: scans competitor social media, breaks down analytics, flags trending topics by views. 6. Post to TikTok with caption + hashtags. 7. Post to Instagram with caption + hashtags. 8. Breaking-news-to-tweet: take Reddit trending headline, draft post, generate image, request user approval, then post. 9. Supervisor pattern: Hermes acting as CEO over OpenClaw workers (supported but not Julian's preferred pattern). ### Skill-composition and self-improvement framing - **Compound effect:** each new skill you add (e.g. skill 1 = X posting, skill 2 = Firecrawl research, skill 3 = Nana Banana images) multiplies what you can automate. The more you use them, the better they get. - Feedback is written into `skill.md` files. On the next run the skill executes better. - **"Closed learning loop"** — skills self-improve while in use; agent takes notes on mistakes and writes fixes into the skill file. - Ask "based on what you know about me, what could you automate that would help me day-to-day?" to discover personalised automations after a week of use. ### Practical tips and gotchas explicitly covered - **First 7 days will be bad.** Be prepared — it won't post perfectly, it will mess up. Give it feedback consistently; every piece of feedback gets written into the skill file. - **Always draft-for-approval before posting to social.** Don't let the agent auto-post until you've iterated ~10 times on the skill. - **Context-too-big failure mode.** Symptoms: agent stops responding in Telegram, answers slow/weird. Fixes: - In terminal: `Ctrl+C`, then `hermes` to restart. - In Telegram: `/new` to start a new conversation + compact history, or `/restart` to restart the gateway session. - **Run two Hermes instances in parallel for debugging.** One in Telegram for doing work, one in terminal for troubleshooting when Telegram breaks. - **Back up your skill MD files weekly** outside of Hermes. The agent has been observed to forget a skill on its own — keep offline copies. - **Migrating from OpenClaw:** run `hermes claw migrate` for a guided wizard (see [[concepts/migration-from-openclaw]]). - **Persistent memory works out of the box** — starting a new session doesn't lose your context. ### MCP and multi-agent patterns - Hermes can run as an MCP server so Claude Desktop, Cursor, or ChatGPT Codex can call it (see [[concepts/mcp-integration]]). - Profiles in v0.6+ allow completely separate agent personalities/skills per profile (see [[concepts/profiles-multi-instance]]). - Paperclip integration via the `hermes-paperclip-adapter` puts Hermes into a Paperclip company hierarchy, e.g. Hermes as CEO with OpenClaw workers below (see [[entities/hermes-paperclip-adapter]]). - Integrating Hermes as supervisor + OpenClaw as worker helps OpenClaw improve by inheriting Hermes's feedback-loop discipline. ### Ecosystem discovery - `awesome-hermes-agent` repo referenced live during the stream — Julian browses it and discovers "HermesHub" (a community skills-browsing hub) and the Slack integration skill (see [[entities/community-awesome-hermes]]). - Julian's standing advice: **build your own skills** rather than install community ones, to customise them and learn skill authoring. ### Cross-platform and OS notes - No native Windows support — use WSL2. Julian does not personally use Windows. - Chromebook is lightweight enough to run Hermes. - Telegram cannot handle very long messages — switch to the terminal gateway for long outputs. ## Relevant Concepts - [[concepts/skills-system]] - [[concepts/self-improvement-loop]] - [[concepts/model-switching]] - [[concepts/cron-scheduling]] - [[concepts/mcp-integration]] - [[concepts/profiles-multi-instance]] - [[concepts/messaging-gateway]] - [[concepts/memory-system]] - [[concepts/migration-from-openclaw]] - [[entities/provider-openrouter]] - [[entities/platform-telegram]] - [[entities/hermes-paperclip-adapter]] - [[entities/community-awesome-hermes]] - [[entities/version-v0.6.0]] - [[syntheses/hermes-vs-openclaw]] ## Source Metadata - **Type:** YouTube LIVE-stream Q&A transcript - **Title:** "LIVE: Hermes AI Agent Masterclass + Browser Agents + FREE with Qwen 3.6" - **Speaker:** Julian Goldie (host, AI Profit Boardroom) - **Length:** 1,291 lines - **Hermes version referenced:** v0.6 ("it's only on version 0.6 so far, not even got up to version 1 yet") - **Headline model:** Qwen 3.6 Plus Preview (Alibaba), free via OpenRouter, 1M-token context - **Browser stack demoed:** Firecrawl (`firecrawl.dev/app`) + Browserbase (vision + recording) - **Image model demoed:** Nano Banana 2 - **File:** `raw/transcript-live-masterclass-browser-qwen.txt` - **Confidence:** medium — community creator live stream; some transcript ASR errors (e.g. "News Research" for "Nous Research", "Open Claw" sometimes rendered "Open Crawl") <!-- ===== hermes/wiki/summaries/transcript-setup-tutorial-gemma.md ===== --> --- title: "Transcript — Hermes Agent Full Setup Tutorial: How to Setup Your First AI Agent (Gemma 4)" type: summary tags: [cli, local-models, platform, gateway, beginner, config] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/transcript-setup-tutorial-gemma.txt"] confidence: medium hermes_version: "v0.8.0" --- ## Key Points - **End-to-end first-install walkthrough** aimed at complete beginners — goal is a 100% private stack: local model via Ollama, local web search via self-hosted Firecrawl, and Telegram as the messaging channel. - **Safety advice up front**: Do not install Hermes on your main computer. Put it on a separate device because, depending on permissions granted, a compromise could expose banking logins, passwords, and private files. - **Install flow**: 1. Paste the install command from the Hermes GitHub into a terminal. Hermes inspects existing packages and auto-installs what's missing. 2. Run `hermes setup` — choose between **quick setup** and **full setup** (tutorial uses full). - **Model provider — local via Ollama** ([[entities/provider-ollama-local]]): - In "more providers" pick **custom endpoint**. - Install Ollama (curl install command from ollama.com), then `ollama pull gemma3:e4b` (the tutorial uses Gemma 4 E4B, 9.6 GB). - Note on sizing: Gemma 4 E2B (7 GB) "wasn't able to do basic tasks" like web search under Hermes, though it worked under OpenClaw. E4B (9.6 GB) works. Recommendation: test models against your actual use case. - VPS / low-powered device alternative: Ollama Cloud tier ($20/month) with generous API limits — plug into Hermes the same way. - API base URL for Ollama: `http://localhost:11434/v1`. API key can be left blank. - Hermes lists every model returned by `ollama list` for selection. - **Context length**: Hit enter to auto-detect. - **Text-to-speech**: Choose **NEUTTS** for local TTS; Hermes offers to download and install dependencies with `Y`. - **Terminal backend**: Keep the recommended **local**. See [[entities/backend-local]]. - **Specialized-agent prompts**: - `max tool-calling iterations` — default 60. Crank up for deep research, file orchestration, multi-hop tool chains. - `tool progress display` — set to **all** so you can see every micro-step (useful for optimization). - `context compression` — default 0.5. With smaller local models and their ~128k windows, a lower compression trigger helps preserve smartness across long chats. - `session reset mode` — recommended default is **inactivity OR daily reset**. For small models in a Telegram daily-use pattern, flushing matters; accumulated days of messages otherwise silently live in context. - `inactivity timeout` default: 1440 minutes. `daily reset hour` default: 4 (4 a.m. local). - All of these are editable later via `hermes setup` re-run. - **Messaging channel — Telegram** ([[entities/platform-telegram]]): - Space bar to select Telegram, then Enter. - Get a bot token from **@BotFather** — `/newbot`, name the bot (e.g. "Hermes demo"), username must end in `bot` (e.g. `hermesdemo001bot`). - Paste the bot token into Hermes. - Access control: Hermes asks for your Telegram user ID. **Leaving it blank = anyone who finds the bot can chat with it.** Get your user ID from `@raw_data_bot` (press Start to see your ID). Paste in, set as home channel. - Install the gateway as a launch service and start it now. See [[concepts/messaging-gateway]]. - **Tools selection**: A checklist pops up (space bar toggles); tutorial deselects vision / image generation for the minimal setup. - **Search provider — self-hosted Firecrawl** (instead of Firecrawl Cloud): - Requires Docker (docker.com) installed and running first. - Paste the self-host commands (tutorial author provides them in video description; also `self-host.md` in Firecrawl repo). - After `docker compose up`, confirm the Firecrawl container is running in Docker Desktop. - Default Firecrawl URL in Hermes prompt is the correct local URL — paste it back. - **Known rough edges observed in the tutorial**: - Setup occasionally loops back / re-prompts for already-configured steps (image gen, TTS, Firecrawl). Creator: "play nice with it" — skip with defaults where already configured. - At end of setup, when launching chat, the system **crashes once** — rerun `hermes` from the terminal and it opens cleanly. Tutorial author confirms this is normal. - **Smoke test**: "Hi there" — first response takes ~10–30 seconds while the model loads into RAM. Follow-up "Research the latest AI news" successfully exercises the Firecrawl self-hosted path with live tool-call display. Telegram side also replies — end-to-end loop confirmed. - **Uninstall**: `hermes uninstall` offers (1) keep data or (2) full uninstall. Enter `2` then `yes` to remove completely. - **Reconfiguration**: Any setting is changeable later via Hermes CLI commands documented on GitHub — re-run setup, add models, add tools, change config. ## Relevant Concepts - [[concepts/skills-system]] - [[concepts/memory-system]] - [[concepts/messaging-gateway]] - [[concepts/local-models-airplane-mode]] — this tutorial *is* the airplane-mode playbook in action - [[concepts/deployment-backends]] - [[entities/provider-ollama-local]] - [[entities/platform-telegram]] - [[entities/backend-local]] - [[entities/backend-docker]] — required for Firecrawl self-hosted - [[syntheses/local-stack-playbook]] ## Source Metadata - **Type**: YouTube video transcript - **Title**: "Hermes Agent Full Setup Tutorial: How to Setup Your First AI Agent (Gemma 4)" - **Speaker**: Unnamed tutorial creator ("Hello legends" open) - **Format**: Screen-recorded CLI walkthrough - **Position in corpus**: Primary beginner tutorial; canonical source for the private-stack install path <!-- ===== hermes/wiki/summaries/transcript-switching-to-hermes.md ===== --> --- title: "Transcript — I am Switching to Hermes Agent" type: summary tags: [skills, memory, self-improvement-loop, vs-openclaw, agent-loop, foundational] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/transcript-switching-to-hermes.txt"] confidence: high hermes_version: "v0.8.0" --- # Transcript — I am Switching to Hermes Agent Architectural deep-dive by creator Nick on why he is switching to Hermes Agent from other frameworks. The video centers on Hermes's trajectory capture + autonomous skill creation loop as the core architectural bet that differentiates it from stateless agent frameworks. The second half positions Hermes vs OpenClaw as two fundamentally different architectural bets (personal-learning depth vs platform-breadth) rather than competitors, and walks through a live install. ## Key Points - **Core architectural thesis**: Most agent frameworks treat agents as stateless — ask, answer, forget. Hermes is built on the opposing assumption that an agent should learn from every interaction and compound value over time. This is an architectural choice, not a marketing claim. - **Trajectory capture is the learning primitive**: After every complex task, Hermes records the full trajectory — every API call, every tool invocation, every decision, in order. Most frameworks discard this; Hermes persists it and exports it in ShareGPT format for fine-tuning your own models. See [[concepts/self-improvement-loop]]. - **Five-step learning loop**: 1. User issues a real multi-step task (e.g. "pull Stripe revenue, cross-reference HubSpot, analyze in Python, post a three-insight summary to leadership Slack") 2. Hermes chains 40+ tools to execute (15–20 steps, first run can take up to ~5 minutes) 3. Full trajectory is recorded 4. Trajectory analyzer asks: "can this be packaged as a reusable function?" If yes, it writes a skill, tests it, and stores it at `~/.hermes/skills/` as plain code on disk 5. Next similar request runs the skill (faster, cleaner, following the encoded SOP) and refines it if requirements shift - **Skills are live code, not pre-recorded macros**: they live in your filesystem, they improve with each execution, and they can be shared via agentskills.io (described as "NPM for agents"). Hermes ships ~40 bundled skills; the real value is the custom ones your usage generates. See [[concepts/skills-system]]. - **Memory with nudges**: Beyond trajectories, Hermes tracks user-specific patterns — preferences, working style, what matters to you. Over time it proactively suggests skills ("you probably want a skill that does X instead of Y") which you approve or reject. See [[concepts/memory-system]] and [[concepts/approval-system]]. - **Your Hermes becomes a different tool than someone else's**: shaped by your workflows, preferences, patterns. This is what "self-improving" means concretely. - **Six deployment backends**: local, Docker, SSH (creator's personal choice on a cheap VPS), Singularity, Daytona, and Modal serverless (~$5/month because it hibernates when idle and only bills on message arrival). Framework does not lock you in. See [[concepts/deployment-backends]]. - **Positioning vs OpenClaw — different bets, not competitors**: - OpenClaw: TypeScript, built by Peter Steinberger as a weekend project, went 0 → 300k+ GitHub stars in 4 months (beat React's 10-year record in 60 days), Steinberger joined OpenAI in Feb, moved to an independent foundation. ~13,000 skills on ClawHub, ~2M MAU, 24 platforms (WhatsApp, Telegram, iMessage via Blue Bubbles, Teams, Discord, Slack, Signal, Google Chat, Line, Matrix, IRC, WeChat, etc.). Purpose-built as a messaging gateway / single control plane across every channel in your life. - Hermes: Python (92.5% of codebase), built by [[entities/nous-research]] — an actual AI lab that trains the Hermes model family. ~19,000 GitHub stars, ~200 contributors, v0.6.0 quoted in transcript (the creator's install session predates v0.8.0). MIT licensed, production-ready. - OpenClaw does NOT learn — no trajectory capture, no RL pipeline, skills are human-maintained plugins, memory is bolt-on (LanceDB, lossless-claw) that you install and configure separately. - Hermes platforms: 12 (Telegram, Discord, Slack, WhatsApp, Signal, email, Home Assistant, DingTalk, Mattermost, Matrix, Feishu, WeCom) — less than OpenClaw's 24 but gap is narrower than most realize. Cross-platform conversation continuity is a recurring reviewer callout (start on CLI, notify on Telegram, resume on Discord without context loss). - OpenClaw backends: mostly Node.js process or Docker. Hermes: six including Modal serverless and Singularity/HPC. - **`hermes claw migrate` command**: one command pulls your SOUL.md, memories, skills, API keys, and messaging configs from OpenClaw. Framed as a deliberate strategic move by Nous — "keep OpenClaw if it works, try Hermes alongside it." See [[concepts/migration-from-openclaw]]. - **Recommendation framework**: - Choose **OpenClaw** if you need an operations + platform play: agent across 5+ business channels from day one, massive tutorial ecosystem, customer-facing tasks, find-a-tutorial-at-2am community. - Choose **Hermes** if you want a personal agent + research play: compounds knowledge over time, gets faster the more you use it, exports training data for your own models, you're comfortable running on a server. - **Honest limitations called out**: - **Windows not supported** — WSL2 required, full stop. Experimental PRs landing for path/PTY handling but README says unsupported. Enterprise plan accordingly. - **Learning loop only fires on complex tasks** — simple tasks generate no skills. LLM-generated skills aren't guaranteed to work; you'll adjust them. - **Local backend security surface** — agent runs terminal as you; dangerous command checks exist but docs recommend Docker or Modal as the security boundary for production. - **Stuck agent loops** — ignore-then-loop behavior recurs in different forms; v0.4.0 changelog had multiple fixes; improving but not solved. - **Speed** — Hermes trades speed for learning. CrewAI and LangGraph beat it on raw orchestration throughput. If your use case is "run this pipeline as fast as possible," Hermes is the wrong tool. - **Install experience**: single `curl` bash command runs the installer, handles Python, Node, ripgrep, ffmpeg; ~60 seconds. Setup wizard prompts for provider (Anthropic/Claude subscription and ChatGPT plans both supported — unlike "OpenClaude" which restricts this), TTS, backend choice, sudo support, progress display, activity mode, session reset policy, platform adapters (Telegram setup is just BotFather → paste token), skill enablement, RL training opt-in. - **Running from phone**: `hermes gateway` starts the adapter; connect via Telegram bot, get the same agent / same memory / same skills accessible from anywhere. - **VPS recommendation**: creator uses a VPS (Hetzner, Hostinger style) so the machine isn't tied to his laptop. Offers to make a dedicated VPS setup video. - **Strategic takeaway**: The question is no longer "should we use agents" but "what kind of agents should we build." Hermes represents one answer — agents that learn — and architecturally that's surprisingly hard. Nous Research building this from the ground up signals they believe the future of agents is in adaptation/learning depth, not breadth/generality. ## Relevant Concepts - [[concepts/self-improvement-loop]] — the trajectory → skill-creation → reuse-and-refine mechanic - [[concepts/skills-system]] — autonomous skill generation, storage at `~/.hermes/skills/`, sharing via agentskills.io - [[concepts/memory-system]] — pattern tracking, proactive skill nudges - [[concepts/approval-system]] — approve/reject nudges and dangerous commands - [[concepts/migration-from-openclaw]] — the `hermes claw migrate` one-shot importer - [[concepts/deployment-backends]] — six-backend portability story - [[concepts/messaging-gateway]] — `hermes gateway` multi-platform fan-out - [[concepts/model-switching]] — multi-provider setup (Claude sub + Codex + OpenRouter) - [[concepts/ml-research-pipeline]] — RL training pipeline, ShareGPT trajectory export - [[entities/backend-local]], [[entities/backend-docker]], [[entities/backend-ssh]], [[entities/backend-singularity]], [[entities/backend-daytona]], [[entities/backend-modal]] - [[entities/platform-telegram]], [[entities/platform-discord]], [[entities/platform-slack]], [[entities/platform-whatsapp]], [[entities/platform-signal]] - [[entities/nous-research]] - [[syntheses/hermes-vs-openclaw]] — deeper comparison anchored by this transcript ## Source Metadata - **Type**: YouTube video transcript (auto-captioned, lightly cleaned) - **Title**: "I am Switching to Hermes Agent" - **Speaker**: Nick (channel creator; states he has driven $5M+ in bottom-line AI revenue across clients and trained hundreds of entrepreneurs) - **Approx date**: Recorded against Hermes v0.6.0 (creator references v0.6.0 on-screen); pre-dates v0.7.0 and v0.8.0. Logged into KB on 2026-04-12. - **Source file**: `raw/transcript-switching-to-hermes.txt` - **Cross-references to Hermes doc surface**: `curl` installer, `hermes` launcher, `hermes gateway`, `hermes claw migrate`, `~/.hermes/skills/` <!-- ===== hermes/wiki/summaries/transcript-why-hermes-replaced-openclaw.md ===== --> --- title: "Transcript — Why The Hermes Agent Just Replaced OpenClaw (DGX Spark Test)" type: summary tags: [vs-openclaw, skills, self-improvement, platform, advanced, local-models] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/transcript-why-hermes-replaced-openclaw.txt"] confidence: medium hermes_version: "v0.8.0" --- ## Key Points - **Use case**: BridgeMind (8,000-member Vibe Coding Discord, ~$76k ARR) needs an AI employee named **Vivian** to do cold-email outreach for buildathon sponsorships. Target: 10 vibe-coding-space brands, find the correct marketing/partnership contact, draft and send the email. - **Hardware**: NVIDIA **DGX Spark** with 128 GB unified memory, accessed via Cursor SSH. Creator reuses three Mac minis previously running OpenClaw — by end of video is planning to switch them all to Hermes with different personas. - **Positioning claim**: Hermes is growing faster than OpenClaw; 57,000 GitHub stars at recording. Creator frames Hermes as the replacement, not a sidecar. - **Built by Nous Research** ([[entities/nous-research]]): the lab behind the Hermes model family. Fully open-source, MIT licensed. Key pitch: **self-improving agent that creates skills from its experiences** — the loop is receive task → execute → evaluate → extract skill → store/refine. See [[concepts/self-improvement-loop]] and [[concepts/skills-system]]. - **Key features highlighted**: skill documents (structured markdown capturing "when X try Y" patterns), longer-term memory than OpenClaw, tool integration, self-evaluation, model-agnostic. - **Setup walkthrough on DGX Spark**: - `hermes setup` — the wizard offers to **import existing data from OpenClaw** (skipped in this demo). See [[concepts/migration-from-openclaw]]. - Quick setup supports Nous Portal, OpenRouter, Anthropic, OpenAI Codex ([[entities/provider-nous-portal]], [[entities/provider-openrouter]], [[entities/provider-anthropic]], [[entities/provider-openai-codex]]). - Creator picks **OpenAI Codex** to reuse an existing ChatGPT subscription; authenticates via URL login flow; picks **GPT-5.4**. - Messaging channel: **Discord** ([[entities/platform-discord]]) — added alongside existing (now-offline) OpenClaw bots in the same server. - Total setup: "under 10 minutes" for model + Discord. - **Outlook email configuration** was the hard part, ~20 minutes: setting up Azure credentials and environment variables to let Vivian send through Microsoft Graph. Uses Cursor to edit Vivian's identity files: `soul.md` (or `user.md`), `memory.md`, `agent.md`. - **Real task execution** (Discord ping to Vivian): - Prompt: find 10 brand candidates, identify the correct marketing contact, draft a cold email offering a $10k sponsorship of the upcoming buildathon. Include BridgeMind stats (60k YT subs, 25k X followers, 8k Discord members). - Vivian plans **three subtasks**, delegates, spends ~20 minutes executing (including running Python for search requests). - Result: list of 10 candidate brands including Notion, DataDog, Neo4j, Confluent, Algolia, Cloudflare; drafts a primary cold email ("BridgeMind Build-a-Thon sponsorship") plus an alternate version with a custom personalization line. - **At task completion, Hermes auto-created a new skill named `sponsorship-prospecting`** — this is the self-improvement feature firing live. - **Follow-up send test**: "Choose the best one and actually send the email." Vivian reads the Outlook Graph tool, chooses **AssemblyAI** (reasoning: strongest combination of audience fit and a clean public partnership contract), sends the email, verifies the send succeeded. - **Takeaways from the creator**: - The self-improving loop is the feature that matters — "you can't micromanage AI employees; they need to learn from experience." - Plans: hook the three Mac minis up as additional Hermes instances with different personas (one for customer service); possibly **fork Hermes** and add refinements. - Possible cron job to run the outreach routine daily. See [[concepts/cron-scheduling]]. - **Subtle architecture notes observable in the demo**: - Hermes uses **task delegation to subagents** (planner reported "three tasks") — see [[concepts/subagents-delegation]]. - Identity config splits across `soul.md` / `user.md`, `memory.md`, `agent.md` — corroborates the "souls" terminology used around OpenClaw and shows Hermes retains a comparable persona-file model. - Outlook is plumbed as a **tool/skill** that Vivian chooses at runtime. ## Relevant Concepts - [[concepts/self-improvement-loop]] — canonical live-capture: `sponsorship-prospecting` skill emerged from the task - [[concepts/skills-system]] - [[concepts/subagents-delegation]] — "planning three tasks" then delegating - [[concepts/migration-from-openclaw]] — the setup-time OpenClaw import offer - [[concepts/model-switching]] - [[concepts/cron-scheduling]] — creator's "run it every morning" plan - [[entities/nous-research]] - [[entities/provider-openai-codex]] - [[entities/platform-discord]] - [[syntheses/hermes-vs-openclaw]] ## Source Metadata - **Type**: YouTube video transcript - **Title**: "Why The Hermes Agent Just Replaced OpenClaw (DGX Spark Test)" - **Speaker**: BridgeMind founder ("home of the Vibe Coding movement") - **Format**: Screencast + SSH to DGX Spark + live Discord-side demo of Vivian the outreach agent - **Position in corpus**: Strongest concrete business-value case study — cold-email outreach on real infrastructure, ending with an actual email sent to AssemblyAI <!-- ===== hermes/wiki/syntheses/cron-troubleshooting-checklist.md ===== --> --- title: "Cron Troubleshooting — the Four-Category Checklist" type: synthesis tags: [cron, troubleshooting, checklist] updated: 2026-06-09 confidence: high sources: [raw/docs-guides-cron-troubleshooting.md, raw/docs-developer-guide-cron-internals.md] --- # Cron Troubleshooting — the Four-Category Checklist Official guidance: when a cron job misbehaves, work the checks **in order** — most issues are one of **timing, delivery, permissions, or skill loading**. ## Jobs not firing 1. **Does the job exist and is it active?** `hermes cron list` 2. Then timing (schedule/timezone), then the remaining categories per the guide. ## Useful internals Pre-run scripts execute via `_run_job_script()` before the LLM turn, governed by `cron.script_timeout_seconds` (**default 120s**) — long scripts need the timeout raised ([[concepts/cron-scheduling]]). Full check sequence: `raw/docs-guides-cron-troubleshooting.md`. <!-- ===== hermes/wiki/syntheses/deployment-backends-compared.md ===== --> --- title: "Deployment Backends Compared" type: synthesis tags: [backend, local, docker, ssh, singularity, daytona, modal, foundational] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/05-deployment-and-platforms.md", "raw/release-v0.6.0.md", "raw/release-v0.8.0.md"] confidence: high hermes_version: "v0.8.0" --- # Deployment Backends Compared Hermes supports six terminal execution backends configured under `terminal:` in `~/.hermes/config.yaml`. This synthesis compares them across the dimensions that matter when picking one. ## Comparison | Backend | Setup cost | Monthly $ | Isolation | Persistence | Best for | |---|---|---|---|---|---| | [[entities/backend-local]] | None | $0 | None (full user access) | Host filesystem | Personal dev, trusted machines, fast iteration | | [[entities/backend-docker]] | Install Docker | $0 | Strong (capabilities dropped, PID/tmpfs caps) | Volume mounts | Teams, CI/CD, hardened local dev | | backend-ssh | SSH keys to a VPS | $5+ (VPS) | Strong (remote host) | Persistent shell with ControlMaster | $5 VPS, remote GPU boxes, 24/7 | | backend-singularity | Apptainer/Singularity binary | $0 (HPC alloc) | Strong (`--containall --no-home`) | Scratch dir-backed | HPC/research clusters where Docker is forbidden | | backend-daytona | `DAYTONA_API_KEY` | Metered (hibernates) | Strong | Workspaces stopped, resumed | Managed team workspaces | | [[entities/backend-modal]] | Modal tokens | ~$5 idle, metered active | Strong | Filesystem snapshots | Serverless, evals, hibernation-friendly | ### Feature matrix | Feature | Local | Docker | SSH | Singularity | Daytona | Modal | |---|---|---|---|---|---|---| | Runs offline | ✓ | ✓ | ✗ | ✓ | ✗ | ✗ | | Auto-mount skills + creds | N/A | ✓ | ✓ (env passthrough) | ✓ (whitelisted) | ✓ | ✓ | | Execute_code on remote | N/A | ✓ (v0.8.0) | ✓ (v0.8.0) | ✓ | ✓ | ✓ (v0.8.0) | | Persistent shell | N/A | Container lifecycle ~2h | ✓ (ControlMaster) | ✓ | ✓ | ✗ (stateless) | | Live processes survive | ✓ | ✓ within container | ✓ | ✓ | ✓ | ✗ | | Browser tools support | ✓ | ✓ (needs `--shm-size=1g`) | ✓ (if host has Chromium) | Limited | ✓ | ✓ | | Hibernation | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ | ### Cost dimension (24/7 agent running) | Backend | Monthly estimate | Notes | |---|---|---| | Local | $0 + electricity | Your machine must stay on | | Docker (local) | $0 + electricity | Same machine, better isolation | | SSH ($5 VPS) | $5-10 | Cheapest always-on option | | SSH (GPU box) | $50-500+ | Only if you need GPU | | Modal | $5 idle baseline, $0.10-$1/hr active | Hibernates — ideal for bursty usage | | Daytona | Varies | Hibernates similar to Modal | | Singularity | $0 (cluster alloc) | Only if you have cluster access | ## Analysis ### The "what am I optimizing for" framework Three dimensions drive the choice: 1. **How often do I actually use it?** - Constantly (multiple times/hour) → local or Docker - Bursty (few times/day) → Modal or Daytona (hibernation wins) - 24/7 cron/gateway → SSH VPS (cheapest always-on) 2. **Do I need isolation?** - "I trust this agent with my machine" → local - "I want belt-and-suspenders" → Docker or SSH - "Compliance/security mandates" → Docker hardened, Singularity on HPC, or Modal serverless 3. **Is the agent long-running or stateful?** - Long-running builds, servers, tailing logs → anything *except* Modal (which is stateless between calls) - Stateless task execution → Modal wins on cost-per-task ### Under-appreciated tradeoffs - **Local's "no isolation" is a real risk.** The agent has your user's filesystem, SSH keys, and `.env` files. For anyone running untrusted skills, local is the wrong default — `/yolo` auto-bypasses approval in sandboxed backends precisely because local is expected to be more cautious. - **Modal hibernation vs. Docker persistent:** Modal's filesystem snapshots restore but *live processes don't*. If your workflow spawns a dev server and tails its logs, Docker persistent beats Modal. If it's strictly "call tool → get result," Modal wins. - **SSH ControlMaster is underrated.** A single SSH connection with 5-min keepalive + persistent_shell = near-native latency on a remote box. Dramatically better than people expect, often competitive with local for most tasks. - **Singularity is niche but critical.** If you're doing ML research on a cluster, this is often the only option — Docker is banned on most HPC systems. ### Setup friction ranking (lowest first) 1. **Local** — zero. It's the default. 2. **Docker** — 5 min. Install Docker, pick image. 3. **Modal** — 10 min. Create account, grab tokens, pick image. 4. **SSH** — 15-30 min. Provision VPS, set up keys, test connectivity. 5. **Daytona** — 15 min. Account + key. 6. **Singularity** — 30+ min. Only if you're already on a cluster with it installed. ## Recommendations ### Pick *Local* if... - You're getting started and want zero friction - You work on a single trusted machine - Your tasks are interactive and short-lived ### Pick *Docker* if... - You want the local-like experience but with real isolation - You install third-party skills you haven't audited - You want reproducible environments across machines - You're building for a team (shared image) ### Pick *SSH / VPS* if... - You need the agent running 24/7 without your laptop on - You want a cheap dedicated home for a Telegram/Discord gateway - You're running GPU-dependent tasks on a remote box ### Pick *Modal* if... - Usage is bursty — most of the day the agent is idle - Cost matters more than latency - Tasks are stateless (tool call → result) - You don't want to manage infrastructure ### Pick *Daytona* if... - You need persistent cloud workspaces - You're working in a team that shares environments - You want Modal-like hibernation but more dev-workspace-style ### Pick *Singularity* if... - You're on an HPC cluster where Docker is forbidden - You're doing heavy ML training or batch work - You have shared scratch-dir infrastructure ### A common pattern: hybrid Many advanced users run **two deployments**: local (or Docker) for interactive chat, and Modal (or SSH) for the scheduled gateway + cron jobs. Profiles — [[concepts/profiles-multi-instance]] — make this trivial. The "hands-on" profile stays local; the "always-on" profile runs on a $5 VPS with Telegram. ## Pages Compared - [[entities/backend-local]] - [[entities/backend-docker]] - [[entities/backend-modal]] - [[concepts/deployment-backends]] - [[concepts/profiles-multi-instance]] - [[concepts/messaging-gateway]] <!-- ===== hermes/wiki/syntheses/hermes-vs-openclaw.md ===== --> --- title: "Hermes Agent vs OpenClaw — Full Comparison" type: synthesis tags: [vs-openclaw, comparison, architecture, ecosystem, foundational] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/transcript-did-hermes-kill-openclaw.txt", "raw/transcript-why-hermes-replaced-openclaw.txt", "raw/transcript-switching-to-hermes.txt", "raw/transcript-247-self-evolving.txt", "raw/transcript-biggest-problem-openclaw.txt", "raw/transcript-hermes-full-course-2hr.txt", "raw/02-install-and-setup.md", "raw/03-skills-system.md", "raw/05-deployment-and-platforms.md", "raw/release-v0.6.0.md", "raw/release-v0.7.0.md", "raw/release-v0.8.0.md", "raw/awesome-hermes-agent-readme.md", "raw/community-resources.md"] confidence: high hermes_version: "v0.8.0" --- ## Comparison This synthesis directly compares Hermes Agent with OpenClaw — the previous-generation open agent harness, acquired by OpenAI when Peter Steinberg joined, with significant Nvidia development investment. ### Architectural deltas | Dimension | **Hermes Agent** | **OpenClaw** | |---|---|---| | Primary language | **Python** (across agent loop, tools, gateway) | **TypeScript** | | Agent loop | Trajectory-capturing **learning loop** — captures every step, distills into reusable skills, optionally feeds back into model fine-tuning via the self-evolution pipeline | **Stateless** per-session loop — solves tasks but doesn't compound across sessions by default | | Memory layers | Built-in store, plus **pluggable memory providers** ([[entities/memory-honcho]] reference plugin, [[entities/memory-supermemory]], [[entities/memory-mem0]], hindsight, etc.) | Project-level memory files; community plugins exist but no first-party pluggable interface of comparable depth | | Open-model support | **First-class** — Nous trains the Hermes model family; works natively with Qwen, Gemma, MiMo, Llama; documented airplane-mode setup | OpenClaw maintainers **explicitly do not recommend open models** (per creator commentary cited in the transcripts) | | Primary distribution | `pip install hermes-agent` + CLI + gateway service | npm/binary + IDE plugin focus | | Profiles / multi-instance | **Native** since [[entities/version-v0.6.0]] — isolated config, memory, sessions, skills, gateway per profile | Single-instance by design; multi-instance via OS-level sandboxing | ### Feature deltas | Feature | Hermes | OpenClaw | |---|---|---| | **[[concepts/skills-system]]** (procedural memory, agentskills.io standard) | Built-in, with `hermes skills browse/search/install/audit/publish`, security scanner with verdicts (clean/caution/warn/dangerous), unbypassable on `dangerous` | Skills via plugin; agentskills.io compatibility through community work | | **[[concepts/cron-scheduling]]** | Built-in cron tick every 60s in gateway; activity-based timeouts (added v0.8.0); pre-run script injection (added v0.8.0) | Available via plugins / external schedulers | | **[[concepts/subagents-delegation]]** | Native subagent delegation | Native | | **[[concepts/mcp-integration]]** | Both MCP **client** and **server** (`hermes mcp serve`, added v0.6.0); dynamic tool discovery; OAuth 2.1 PKCE + OSV malware scanning (v0.8.0) | Strong MCP client; server-mode less central | | **[[concepts/model-switching]]** | Live `/model` switching mid-session across CLI + every gateway platform; aggregator-aware resolution (added v0.8.0) | Possible per-session, less polished mid-session UX | | **Self-improvement / GAPA** | First-party `hermes-agent-self-evolution` (DSPy + GEPA); `tinker-atropos` for RL on real trajectories | Not a primary product axis | | **Approval system** | Native inline buttons on Slack (thread-preserving) and Telegram (added v0.8.0) | CLI / chat approve flows | | **Performance perception** | "Moves much faster than OpenClaw on the same model" (creator review, multiple Opus 4.6 head-to-heads) | Solid but heavier per the same reviews | ### Ecosystem comparison | Metric | Hermes Agent | OpenClaw | |---|---|---| | Core repo stars | 23k (per Awesome list 2026-04-03) → 56k (per get-hermes.ai 2026-04-12) — **rapid growth** | Larger absolute community, more mature | | Release cadence | **Every 3-5 days** (v0.6.0 → v0.7.0 → v0.8.0 across March 30 → April 8, 2026) | Daily updates per reviewer commentary | | Recent release velocity | v0.6.0: 95 PRs / 16 issues (2 days). v0.7.0: 168 PRs / 46 issues. v0.8.0: 209 PRs / 82 issues. | Daily ship cadence with backing of Nvidia + OpenAI engineering | | Curated directory | [[entities/community-awesome-hermes]] (1.1k stars, 0xNyk) | Older, broader awesome lists | | Community skill library | Growing — `wondelai/skills` (380+), [[entities/community-agency-agents-zh]] (5.8k), `Anthropic-Cybersecurity-Skills` (4k+), [[entities/community-gbrain]] (4.8k), [[entities/community-orange-book]] (1.9k) | **Larger** — frequently cited "13K+ skills" community ecosystem | | Messaging platforms | **12 platforms** (Telegram, Discord, Slack, WhatsApp, Signal, Email, Matrix, Home Assistant, DingTalk, Mattermost, Feishu/Lark, WeCom) | OpenClaw historically broader — **24 platforms** cited in reviewer commentary | | Deployment backends | **6** — local, Docker, SSH, Singularity/Apptainer, Daytona, Modal | More VM/Cloud-managed offerings | | GUIs | hermes-workspace (1.1k), [[entities/community-webui]] (1.3k), [[entities/community-mission-control]] (3.7k+, agent-agnostic), hermes-hudui, hermes-desktop | Native IDE plugins, broader GUI ecosystem | ## Analysis ### Where Hermes wins 1. **Compounding intelligence.** The learning loop is the central architectural bet. Every session builds skills the next session can use; every trajectory becomes potential training data. OpenClaw is excellent at solving tasks; Hermes is designed to **get better at your specific tasks** the more you use it. Reviewers highlight this as the most impressive single difference: "the more you use it, the better it gets." 2. **Open-model first-class support.** Nous Research trains open-weights models and ships Hermes as the canonical runtime for them. If your strategy includes Qwen / Gemma / Llama / MiMo or fully air-gapped operation, Hermes is the only credible choice — OpenClaw's maintainers explicitly recommend against open models. 3. **Tinkerer / ML-research depth.** Built-in mlops skills cover Axolotl, Unsloth, TRL, GRPO RL training, vLLM, llama-cpp, GGUF inference, Modal, HuggingFace Hub. The `tinker-atropos` and `hermes-agent-self-evolution` projects provide first-party fine-tuning + RL infrastructure. 4. **Performance and lightness.** Multiple reviewers (running both with Claude Opus 4.6) report Hermes is meaningfully faster and more responsive than OpenClaw. 5. **Multi-instance done right.** Profiles provide per-config / per-memory / per-skill / per-gateway isolation since v0.6.0 — natural fit for one user running many specialized agents. 6. **Memory pluggability.** v0.7.0's memory provider ABC plus the [[entities/memory-honcho]] reference plugin gives Hermes the most explicit and most extensible memory architecture in the open agent space. 7. **Aesthetics and transparency.** Reviewers consistently call out Hermes's visible step-by-step tool feed and ASCII-art polish as a UX advantage. ### Where OpenClaw wins 1. **Platform breadth.** ~24 messaging/integration platforms vs Hermes's 12. If you need an obscure messenger out of the box, OpenClaw is more likely to have it. 2. **Ecosystem depth.** Frequently cited "13K+ skills" community is larger than Hermes's growing-but-newer skill catalog, plus more mature IDE-native plugins (Cursor, Claude Code). 3. **Stability + ship velocity.** Daily releases backed by OpenAI (Peter Steinberg post-acquihire) + Nvidia engineering provides more polish in absolute terms; Hermes ships fast but with rougher edges (reviewers report occasional issues they had to work through). 4. **Cross-agent native plugin support** (Cursor, Claude Code) is more developed. 5. **Community size.** Strictly larger community and more third-party tutorials. ### The dominant practitioner pattern Every reviewer who has used both at length recommends running them **side-by-side** rather than ripping one out. The pattern: - **OpenClaw as orchestrator** for complex multi-step tasks; spins up Hermes as a subagent via ACP for tasks Hermes is better at. - **Hermes as the always-on tinkerer** with its own [[concepts/profiles-multi-instance]] for compounding workflows (morning briefings, cron jobs, code-base exploration, fine-tuning experiments). - **Insurance policy:** when one agent breaks (config drift, update bug), the other is still alive to fix it. - ACP (Agent Client Protocol) is the wire that makes this possible. ## Recommendations ### Pick **Hermes** if you... - Want an agent that **gets better the more you use it** (compounding skills, memory, optionally fine-tuning) - Run, or want to run, **open models** (Qwen, Gemma, Llama, MiMo, Hermes models themselves) - Need **air-gapped / fully local** operation - Identify as a **tinkerer / ML-curious developer** — RL training, fine-tuning, GRPO, vLLM, etc. are first-party skill territory - Want **first-party multi-instance Profiles** to keep work / personal / project agents cleanly separated - Need a **CLI + gateway-first** architecture (Telegram, Discord, Slack as primary surfaces) over an IDE-first one - Care about **lightweight performance** on the same model ### Pick **OpenClaw** if you... - Need the **broadest messaging-platform coverage** out of the box (24 platforms) - Want the **largest community skill catalog** (13K+) and most mature IDE plugins - Prioritize **maximum stability and polish** over cutting-edge features - Are deep in **Cursor / Claude Code / VS Code** ecosystems and want native integration - Have **no interest in open models** or fine-tuning ### Pick **both** if you... - Are serious about agent-driven productivity (the dominant recommendation) - Want a redundancy / insurance pattern (when one breaks, the other can fix it) - Want to use each for what it's best at — OpenClaw for orchestration + IDE work, Hermes for cron + Telegram + tinkering + compounding skill creation - Set up [ACP](https://hermes-agent.nousresearch.com/docs/) so the two can hand work to each other ### Practical migration notes - Use `hermes claw migrate` (now feature-complete in v0.3.0+) for the official migration path — it covers sessions, cron, and memory. - Community migration tool `0xNyk/openclaw-to-hermes` exists for edge cases the native tool doesn't cover. - Migration playbook from `awesome-hermes-agent`: keep both running side-by-side, then cut over once cron and routing behavior match. ## Pages Compared - [[entities/version-v0.6.0]], [[entities/version-v0.7.0]], [[entities/version-v0.8.0]] — Hermes release trajectory - [[entities/nous-research]] — the lab behind Hermes - [[entities/backend-local]], [[entities/backend-docker]], [[entities/backend-modal]] — Hermes deployment options - [[entities/platform-telegram]], [[entities/platform-discord]], [[entities/platform-slack]] — Hermes gateway examples - [[entities/memory-honcho]], [[entities/memory-supermemory]], [[entities/memory-mem0]] — pluggable memory - [[entities/community-awesome-hermes]], [[entities/community-mission-control]], [[entities/community-orange-book]], [[entities/community-agency-agents-zh]], [[entities/community-gbrain]], [[entities/community-webui]] — ecosystem - [[concepts/migration-from-openclaw]], [[concepts/skills-system]], [[concepts/memory-system]], [[concepts/model-switching]], [[concepts/self-improvement-loop]], [[concepts/profiles-multi-instance]] - [[syntheses/memory-providers-compared]], [[syntheses/deployment-backends-compared]] - [[summaries/transcript-did-hermes-kill-openclaw]], [[summaries/transcript-why-hermes-replaced-openclaw]], [[summaries/transcript-switching-to-hermes]] <!-- ===== hermes/wiki/syntheses/local-stack-playbook.md ===== --> --- title: "Local Stack Playbook — Running Hermes 100% Offline" type: synthesis tags: [local-models, privacy, experimental, advanced] created: 2026-04-12 updated: 2026-04-12 sources: ["raw/05-deployment-and-platforms.md", "raw/03-skills-system.md", "raw/transcript-setup-tutorial-gemma.txt", "raw/transcript-247-self-evolving.txt"] confidence: high hermes_version: "v0.8.0" --- # Local Stack Playbook — Running Hermes 100% Offline End-to-end recipe for a Hermes deployment where **nothing leaves your machine**: LLM, TTS, STT, search, memory, and tooling all run on your hardware. There is no single "airplane mode" toggle — you assemble it from components. ## Comparison ### Stack Components (all with local options) | Component | Cloud default | Local replacement | Setup cost | |---|---|---|---| | LLM | OpenRouter/Anthropic/Nous | Ollama, vLLM, llama.cpp, LM Studio, SGLang | 5-15 min | | TTS (voice output) | ElevenLabs, OpenAI | NeuTTS Air (GGUF, ~500MB, voice cloning) | 5 min | | STT (voice input) | Groq, OpenAI | faster-whisper (~150MB auto-download) | Zero (default) | | Web search | Exa, Tavily, Firecrawl cloud | Self-hosted Firecrawl (Docker), DuckDuckGo | 10-20 min | | Memory | Honcho, mem0, Supermemory | Hindsight (local), Holographic (zero-dep SQLite) | 5 min | | Browser automation | Browserbase, Browser Use | Local Chromium via `agent-browser`, Camofox | 5-10 min | | Image gen | FAL (FLUX) | No strong local option — Stable Diffusion via skill | 30+ min | ### What's fully local vs. mostly local | Feature | Fully local? | Notes | |---|---|---| | Core chat + tool use | ✓ | With Ollama/vLLM | | Skills execution | ✓ | Skills are markdown + local scripts | | Cron scheduling | ✓ | Runs in-process | | Subagents | ✓ | Same local provider | | Session memory / search | ✓ | SQLite FTS5, no network | | Voice I/O | ✓ | NeuTTS + faster-whisper | | Web search | ✓ (self-hosted) or ✗ (cloud) | Self-hosted Firecrawl is the key | | Messaging gateway | ✗ | Telegram/Discord/Slack all hit cloud APIs. Matrix with self-hosted homeserver is the local option. | | MCP servers | Depends | Local MCP servers (filesystem, SQLite, etc.) are fine. Remote ones hit the internet. | ## Analysis ### Why run local at all? Three reasons dominate: 1. **Privacy.** Sensitive work (client data, internal docs, proprietary research) shouldn't leave your machine. Every cloud provider has terms about training on your data — local sidesteps the question. 2. **Cost.** If you use the agent heavily, a $500 one-time GPU beats years of API fees. Plus: zero rate limits. 3. **Experimentation.** Want to try a fine-tune? Local is the only way without paying a fortune. Want to use a model that isn't on OpenRouter yet? Local is how. ### Hardware tiers | Tier | Hardware | Viable models | Realistic use | |---|---|---|---| | Minimal | CPU-only, 16GB RAM | Gemma 4 E2B (7GB quantized), small Qwen variants | Basic chat, slow tool use | | Entry | RTX 3060/4060, 12GB VRAM | Gemma 4 E4B (9.6GB), Qwen 3 8B, Phi-3 Medium | Practical agent use | | Mid | RTX 4090, 24GB VRAM | Qwen 3 14B, Llama 3 13B, Nous Hermes 8B | Everyday workhorse | | Serious | 2×4090 or RTX 6000, 48GB | Qwen 3 32B, Llama 3 70B Q4, Hermes 3 70B | Production-grade | | Research | DGX Spark, Mac Studio M3 Ultra, multi-GPU | Anything up to 120B+ | Full-scale | The [transcript-setup-tutorial-gemma](../summaries/transcript-setup-tutorial-gemma.md) summary notes: **Gemma 4 E2B failed basic web search tasks on Hermes** — you need the E4B or larger to get practical agentic behavior. Don't undersize. ### Where cloud still wins - **Frontier model quality.** The 70B+ frontier is still behind Opus/GPT-5/Claude 4.6 on hard reasoning. - **Vision.** Local vision is weak. If you need screenshot analysis, a cloud vision model is pragmatic. - **Browser stealth.** Camofox is local, but Browserbase has better fingerprint evasion for heavy scraping. ## Recommendations ### The recipe **1. Install Hermes normally** (`curl ... install.sh | bash`). **2. Install Ollama and pull a model:** ```bash curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen:14b # or whichever fits your hardware ``` **3. Point Hermes at Ollama via custom provider:** ```bash hermes setup model # Pick: custom endpoint # Base URL: http://localhost:11434/v1 # Model: qwen:14b ``` Or edit `~/.hermes/config.yaml` directly: ```yaml model: provider: custom default: qwen:14b base_url: http://localhost:11434/v1 context_length: 65536 # Ollama needs -c 65536 flag ``` **4. Set STT to local (default, but verify):** ```yaml stt: provider: local ``` First use auto-downloads `faster-whisper` (~150MB). **5. Switch TTS to NeuTTS:** ```yaml tts: provider: neutts ``` **6. Self-host Firecrawl for web search:** ```bash git clone https://github.com/firecrawl/firecrawl cd firecrawl && docker compose up -d ``` Then in `.env`: ``` FIRECRAWL_API_URL=http://localhost:3002 ``` **7. Pick a local memory provider:** ```bash hermes memory setup # Pick: hindsight (or holographic for zero-dep) ``` **8. Verify the stack is offline:** - Disconnect from the internet - `hermes chat`, ask it to browse/search/summarize/speak - If anything fails, check the failure point against the stack table above ### What to *not* bother running local - **Messaging gateway on cloud platforms** — Telegram/Discord/Slack can't be self-hosted. If you need local-only messaging, use Matrix with your own Synapse homeserver. - **Image gen** — unless you already have a SD pipeline, just use cloud. The skill library has `stable-diffusion` if you care. - **Model leaderboard chasing** — if you want the newest frontier models, cloud is unavoidable. Mix: local for daily driver, cloud Opus/GPT for hard reasoning via `/model`. ### Common failure modes 1. **Context too short on Ollama** — default Ollama context is 4k. For agentic use, you need ≥64k: `ollama serve -c 65536` or set `num_ctx` per-model. 2. **Model too small for tool calls** — sub-8B models often can't format tool calls correctly. Use Gemma 4 E4B or larger as a floor. 3. **Firecrawl self-host memory usage** — the Docker stack wants ~4GB RAM. On 16GB machines this can hurt. 4. **NeuTTS first-run download is slow** — ~500MB GGUF. Let it finish before first voice task. ## Pages Compared - [[concepts/local-models-airplane-mode]] - [[concepts/memory-system]] - [[entities/memory-honcho]] - [[concepts/deployment-backends]] - [[concepts/model-switching]] - [[summaries/transcript-setup-tutorial-gemma]] <!-- ===== hermes/wiki/syntheses/memory-providers-compared.md ===== --> --- title: "Memory Providers Compared" type: synthesis tags: [memory, comparison, providers, plugin, foundational] created: 2026-04-12 updated: 2026-06-10 sources: ["raw/docs-user-guide-features-memory-providers.md", "raw/release-v0.7.0.md", "raw/release-v0.8.0.md", "raw/awesome-hermes-agent-readme.md"] confidence: high hermes_version: "v0.16.0" --- ## Comparison Hermes ships with a built-in memory store and, since [[entities/version-v0.7.0]], a **pluggable memory provider interface** that third-party backends implement via a simple ABC. Only **one external provider is active at a time**, and it always runs *alongside* — never replacing — the built-in `MEMORY.md` / `USER.md` layer and FTS5 session search (see [[concepts/memory-system]]). The official v0.16.0-era docs list **nine external providers** (Memori is new since this page was last revised), with genuinely different cost / hosting / capability profiles. ### Cost, hosting, trust | Provider | Hosting | Cost | Trust / Maintenance | |---|---|---|---| | **Built-in (default)** | Local files under `~/.hermes/` | Free | First-party (Nous) | | **[[entities/memory-honcho]]** | Honcho Cloud **or** self-hosted (`baseUrl` config; community recipe `elkimek/honcho-self-hosted`) | Cloud metered; self-hosted free + your infra | First-party reference plugin | | **[[entities/memory-openviking]]** | Self-hosted only (`pip install openviking` + `openviking-server`, local or your cloud) | Free — open-source, **AGPL-3.0** | **Volcengine (ByteDance)** project; actively maintained (fixes in v0.11.0, v0.12.0) | | **[[entities/memory-mem0]]** | Mem0 Cloud only (the Hermes integration has no self-hosted path documented) | Mem0 pricing (metered) | Third-party | | **[[entities/memory-hindsight]]** | Hindsight Cloud **or** local (embedded PostgreSQL; local mode needs an LLM API key for extraction) | Cloud paid / local free | Third-party (Vectorize); most actively maintained third-party provider in release history | | **[[entities/memory-holographic]]** | **Local only** — SQLite at `$HERMES_HOME/memory_store.db` | Free | Official plugin; zero dependencies | | **[[entities/memory-retaindb]]** | RetainDB Cloud only | **$20/month** — the only provider with a flat published price | Third-party | | **[[entities/memory-byterover]]** | **Local-first** (`brv` CLI, knowledge tree in `$HERMES_HOME/byterover/`); optional cloud sync (SOC2 Type II) | Free local / paid cloud sync | Third-party | | **[[entities/memory-supermemory]]** | Supermemory Cloud | Supermemory pricing (metered) | Third-party, added in [[entities/version-v0.8.0]] | | **Memori** | Memori Cloud | Memori pricing (free tier + paid) | Third-party; new in v0.16.0-era docs — **no entity page yet** | ### Capability matrix | Provider | Retrieval style | Tools | Dependencies | Unique feature (per official docs) | |---|---|---|---|---| | Built-in | FTS5 session search + curated markdown | 1 (`memory`) + `session_search` | none | Always on; human-auditable plain markdown | | **[[entities/memory-honcho]]** | Semantic search + dialectic LLM reasoning | 5 | `honcho-ai` | Dialectic user modeling + session-scoped context; per-profile AI peers in a shared workspace | | **[[entities/memory-openviking]]** | Tiered: L0 abstract (~100 tok) → L1 overview (~2k) → L2 full | 5 | `openviking` + server | Filesystem-style `viking://` hierarchy; auto-extraction into 6 categories; only provider with first-class URL/doc ingestion (`viking_add_resource`) | | **[[entities/memory-mem0]]** | Semantic search + reranking | 3 | `mem0ai` | Server-side LLM fact extraction with automatic dedup — fully hands-off | | **[[entities/memory-hindsight]]** | Multi-strategy: semantic + graph + temporal | 3 | `hindsight-client` (cloud) / `hindsight-all` (local), lazy-installed since v0.14.0 | Knowledge graph + `hindsight_reflect` cross-memory synthesis "that no other provider offers" | | **[[entities/memory-holographic]]** | FTS5 full-text + HRR compositional algebra | 2 (smallest surface) | **None** (NumPy optional, enables HRR) | `probe` / `reason` / `contradict` algebraic queries; trust scoring with asymmetric feedback (+0.05 / −0.10) | | **[[entities/memory-retaindb]]** | Hybrid: vector + BM25 + reranking | 5 | `requests` only | Delta compression; 7 memory types with importance | | **[[entities/memory-byterover]]** | Tiered: fuzzy text first, LLM-driven search when needed | 3 | `brv` CLI | Pre-compression extraction — hooks `on_pre_compress` to save insights before context compression discards them; tree is portable to other ByteRover-speaking tools | | **[[entities/memory-supermemory]]** | Semantic similarity; `search_mode: hybrid \| memories \| documents` | 4 | `supermemory` | Context fencing (anti-recursive-pollution) + session-end graph ingest + multi-container partitioning | | **Memori** | Structured recall (facts, summaries) | 5 | `hermes-memori` | Tool-aware turn capture + structured project/session attribution (docs-only; unverified) | All providers plug into the same loop: context injection into the system prompt, background prefetch before each turn, turn sync after each response, session-end extraction, and mirroring of built-in memory writes. Cross-platform gateway continuity therefore works the same regardless of provider (see [[concepts/messaging-gateway]] consumers [[entities/platform-telegram]], [[entities/platform-discord]], [[entities/platform-slack]]). ### Setup difficulty | Provider | Setup difficulty | Notes | |---|---|---| | Built-in | **Trivial** | Already configured; nothing to do | | [[entities/memory-holographic]] | **Trivial** — easiest external provider | `hermes config set memory.provider holographic`. No API key, no server, no pip install | | [[entities/memory-byterover]] | Easy | Install `brv` CLI (script or npm), select provider. No API key needed for local mode | | [[entities/memory-mem0]] / [[entities/memory-retaindb]] / [[entities/memory-supermemory]] | Easy | `hermes memory setup` + API key in `~/.hermes/.env` | | [[entities/memory-honcho]] (cloud) | Easy | `hermes memory setup` → Honcho post-setup wizard (legacy `hermes honcho setup` redirects here) | | [[entities/memory-hindsight]] | Easy (cloud) / Medium (local) | Wizard auto-installs only what the selected mode needs; local = embedded PostgreSQL + an LLM API key | | [[entities/memory-honcho]] (self-hosted) | Medium | Run your own Honcho instance, set `baseUrl` in `honcho.json` | | [[entities/memory-openviking]] | Medium | `pip install openviking`, run `openviking-server`, set `OPENVIKING_ENDPOINT` — a server to operate, but fully documented | | Memori | Easy-Medium (unverified) | `pip install hermes-memori` + `hermes-memori install` + API key | > Confidence note: every row above is sourced from the official memory-providers doc mirror fetched 2026-06-10 (v0.16.0-era) and the per-provider entity pages verified against it. Two corrections vs the v0.8.0-era revision of this page: **Holographic** is not an "experimental dense-retrieval store" — it is a documented zero-dependency local SQLite fact store and the easiest setup of all external providers; **OpenViking** is not "community-built, hard setup" — it is a Volcengine (ByteDance) open-source project with a documented medium-difficulty server setup. The Memori row is docs-only and has no entity page yet. ## Analysis ### Four architectural styles 1. **Document store + FTS** (built-in): cheapest and simplest; works well for single-user, single-machine, smallish history. Always on regardless of provider choice. 2. **Identity modeling** (Honcho, Supermemory): builds explicit per-peer / per-profile structures so the agent knows **who you are** across sessions. Honcho goes deepest — per-profile AI peers, observation toggles, and three orthogonal cost knobs (`contextCadence`, `dialecticCadence`, `dialecticDepth`); Supermemory adds profile facts plus container partitioning. 3. **Structured knowledge** (Hindsight, OpenViking, ByteRover): organizes memory as a navigable structure — knowledge graph with entity resolution (Hindsight), filesystem hierarchy with tiered loading (OpenViking), hierarchical knowledge tree (ByteRover). Best when you want the agent to *browse* what it knows, not just retrieve it. 4. **Extraction + retrieval services** (Mem0, RetainDB, Memori) and **local algebra** (Holographic): Mem0/RetainDB/Memori treat memory as a hands-off cloud retrieval problem; Holographic is the outlier — pure local FTS5 plus HRR compositional queries (`probe`, `reason`, `contradict`) with no embedding model at all. ### When the choice actually matters - For a **solo developer on one machine**, built-in is fine for a long time. When memory pressure shows up (repeated context, lost long-term recall — the `awesome-hermes-agent` playbook's trigger), the cheapest upgrade is now **Holographic**: zero dependencies, one config command, and you gain trust-scored fact storage with contradiction detection. The old advice of jumping straight to a cloud provider no longer holds. - For a **team gateway** serving many users, the question is identity modeling ([[entities/memory-honcho]] — one AI peer per profile, shared user identity per workspace) vs **partitioning** ([[entities/memory-supermemory]] multi-container, or `{identity}` container tags for per-profile isolation). - For **fully offline / air-gapped**: built-in, Holographic, and ByteRover (local mode) work with no outbound calls. Hindsight local mode still needs an LLM API key for extraction, and OpenViking is self-hosted but its server is yours to run — both suit *data residency* better than strict air-gap. - **Profile isolation** comes for free but via four different mechanisms (per official docs): local-path providers (Holographic, ByteRover) inherit `$HERMES_HOME` separation; config-file providers (Honcho, Mem0, Hindsight, Supermemory) keep per-profile credentials; RetainDB auto-derives profile-scoped project names cloud-side; OpenViking is configured per-profile via `.env`. ### Trust + ecosystem signal Honcho remains the **only first-party reference plugin**, and the docs give it by far the deepest configuration surface. But the third-party tier has matured: Hindsight is the most actively maintained third-party provider in the captured release history (v0.9.0 wizard through v0.14.0 lazy-install), and OpenViking carries ByteDance/Volcengine weight plus its own fix stream (v0.11.0, v0.12.0). "Third-party" no longer reliably means "less supported." The actual trust gradient today runs: Honcho → Hindsight/OpenViking/Holographic (documented, actively fixed) → Mem0/RetainDB/ByteRover/Supermemory (documented, less release-note visibility) → Memori (too new to judge). ### Switching costs The provider ABC means switching doesn't touch the agent loop, but **memories do not migrate between providers** — plan before committing. The old `hermes honcho migrate` path has been absorbed into the unified `hermes memory setup` wizard; per the docs, prior Honcho config and server-side data survive reactivation. For everyone else, `hermes sessions export` before switching is the safety net. ## Recommendations | Situation | Pick | |---|---| | **Just getting started** | **Built-in.** Don't optimize prematurely. | | **Memory pressure, want zero new infrastructure** | **[[entities/memory-holographic]].** One command, no API key, no server. Trust-scored facts + contradiction detection. This is the new default first upgrade. | | **Solo dev who lives in the terminal, wants portable memory** | **[[entities/memory-byterover]].** Local-first `brv` knowledge tree, free, travels to other ByteRover-speaking tools; pre-compression extraction stops context compaction from eating insights. | | **Agent should deeply model *you* (or many users on a gateway)** | **[[entities/memory-honcho]].** First-party, dialectic user modeling, per-profile AI peers, tunable cost knobs. | | **Need explicit knowledge graph + cross-memory synthesis** | **[[entities/memory-hindsight]].** `hindsight_reflect` is unique; free local mode (embedded PostgreSQL) or cloud. | | **Data residency: self-hosted, structured, browsable knowledge** | **[[entities/memory-openviking]].** Free AGPL-3.0 Volcengine server, `viking://` hierarchy, tiered token-cheap retrieval, and the only first-class URL/doc ingestion. | | **Multi-tenant gateway with work / personal partitioning** | **[[entities/memory-supermemory]]** (multi-container + `{identity}` container tags) or multiple [[concepts/profiles-multi-instance]] on Honcho. | | **Hands-off: just want extraction handled for me** | **[[entities/memory-mem0]].** Server-side LLM extraction with dedup; nothing to curate. | | **Predictable budget** | **[[entities/memory-retaindb]]** — flat $20/mo, hybrid vector + BM25 + rerank retrieval. | | **Maximum vendor neutrality** | **Built-in + `hermes sessions export`.** Avoid coupling until you have evidence you need it. | Operational playbook (from `awesome-hermes-agent`): if you're "repeating context or losing long-term recall," that's the trigger to evaluate a provider — but don't switch memory providers as the first response to a single bad session; switch when the pattern is repeatable. And remember there is no cross-provider migration: the first non-built-in provider you commit to is sticky. **Memori** (added in the v0.16.0-era docs) is deliberately left out of the recommendations: it has no entity page in this KB yet and only the official catalog entry to go on. Flagged for ingestion. ## Pages Compared - [[entities/memory-honcho]], [[entities/memory-mem0]], [[entities/memory-supermemory]], [[entities/memory-retaindb]], [[entities/memory-hindsight]], [[entities/memory-byterover]], [[entities/memory-holographic]], [[entities/memory-openviking]] - [[concepts/memory-system]] — two-layer architecture this comparison sits on - [[concepts/profiles-multi-instance]] — alternative to multi-container memory - [[entities/version-v0.7.0]] — pluggable memory ABC introduced - [[entities/version-v0.8.0]] — Supermemory added - [[entities/version-v0.9.0]] — eight-provider roster + unified `hermes memory setup` wizard era - [[entities/version-v0.16.0]] — version this page is verified against (Memori appears in docs) - [[entities/platform-telegram]], [[entities/platform-discord]], [[entities/platform-slack]] — gateway memory consumers - [[syntheses/hermes-vs-openclaw]] <!-- ===== hermes/wiki/syntheses/onchain-stack-recipe.md ===== --> --- title: "Onchain Stack Recipe" type: synthesis tags: [skills, mcp, platform, advanced, developer, emerging] created: 2026-04-13 updated: 2026-04-13 sources: ["raw/onchain-ecosystem.md", "raw/awesome-hermes-agent-readme.md"] confidence: medium hermes_version: "v0.8.0" --- # Onchain Stack Recipe A practical, step-by-step setup guide for running Hermes Agent on onchain workflows. Assumes the user targets EVM (Ethereum + L2s) and/or Solana, and wants to cover the common jobs: research, monitoring, contract/token audit, DeFi position tracking, and (carefully) execution. This synthesis turns [[concepts/onchain-workflows]] into an opinionated recipe. --- ## Comparison — Solana vs EVM stacks | Dimension | Solana recipe | EVM recipe | |---|---|---| | First-party skill | `blockchain/solana` (shipping) | `blockchain/base` only (no Ethereum mainnet skill) | | Default RPC | `api.mainnet-beta.solana.com` | `mainnet.base.org` | | Recommended paid substrate | Helius, QuickNode, Triton | Alchemy, Infura, QuickNode | | Data provider MCP | `embetter/solana-helius-mcp` or hermes-blockchain-oracle | `alchemyplatform/alchemy-mcp-server` (official) | | DEX MCP | `kukapay/jupiter-mcp` (Jupiter Ultra) | `kukapay/uniswap-trader-mcp` | | Explorer MCP | `wowinter13/solscan-mcp` | `crazyrabbitLTC/mcp-etherscan-server` | | Analytics | Dune (via `kukapay/dune-analytics-mcp`) | Dune (same), DeFiLlama | | Security | `kukapay/rug-check-mcp`, GoPlus | GoPlus, `N-45div/ChainGuard` | | NFT | (built into Solana skill, lossy on cNFTs) | `ProjectOpenSea/opensea-mcp-next-sample` | | Wallet discovery | Native (getTokenAccountsByOwner) | Limited (skill hardcodes ~15 popular tokens) | | Execution | Jupiter MCP, hermes-payguard USDC | Uniswap MCP, hermes-payguard USDC/CCTP, CoW Swap | | Signing approach | MCP loads key from env; external signer for large amounts | Same; plus hermes-payguard for USDC | --- ## Analysis — what actually works today ### What's production-ready - **Read-only Solana intelligence** — first-party skill + hermes-blockchain-oracle + Helius. Mature. - **Read-only Base queries** — first-party skill works fine for the chain it covers. - **Alchemy MCP (EVM)** — official server, 81 stars, multi-chain, handles most JSON-RPC needs. - **Chainlink CRE / CCIP skills** — production-tagged, 86 stars, actively maintained, but write-restricted to testnet. ### What's beta-quality - **Cash-flow forensics** (Mercury) — works, small audience. - **Contract/token security audit** (Serpens-hermes pattern) — GoPlus + Etherscan + regex. Assembled, not packaged. - **USDC payments** (hermes-payguard) — functional, niche, 4 stars. - **Multi-chain wallet inspection** (`kukapay/wallet-inspector-mcp`). ### What's experimental - **Autonomous trading** — RiskState provides architectures only, no track records. - **MEV / arbitrage** — `Cortex-AI-Software/Autonomous-AI-Trading-Agent-MCP-Flash-Arb-Engine` exists; no evidence of live production use. - **x402 agent commerce** — early-stage, hermes-payguard is the reference. - **cNFT / Token-2022 handling** — not supported in first-party Solana skill. ### What's absent - **First-party Ethereum mainnet skill** — bring-your-own MCP server. - **First-party signing / wallet creation**. - **Published Hermes-based MEV bots** or **airdrop farmers**. - **NFT-specific skills** (Tensor, Magic Eden) — only via MCP. --- ## Recommendations — the actual recipes ### Recipe A: Solana research / monitoring (beginner) Goal: query wallets, track tokens, spot whale moves, set up Telegram alerts. **Step 1 — install Hermes and the Solana skill.** ```bash # Install Hermes (see the Official Docs quickstart) hermes skills install blockchain/solana ``` **Step 2 — get a Helius key and set env vars.** ```bash # ~/.hermes/.env SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY ``` **Step 3 — verify.** ```bash hermes chat "Check the current Solana network stats" # Agent runs: python3 ~/.hermes/skills/blockchain/solana/scripts/solana_client.py stats ``` **Step 4 — (optional) add the MCP server for richer interactions.** ```yaml # config.yaml mcp_servers: blockchain-oracle: command: python args: ["-m", "hermes_blockchain_oracle"] env: SOLANA_RPC_URL: "${SOLANA_RPC_URL}" ``` ```bash hermes mcp add blockchain-oracle --command "python -m hermes_blockchain_oracle" ``` **Step 5 — schedule monitoring via cron.** See [[concepts/cron-scheduling]]. Example pattern: every 30 minutes, call the `wallet` command on a watched address, compare against last-seen, post Telegram alert on drift > N%. **Time to first query:** ~15 minutes. --- ### Recipe B: EVM research across multiple chains (intermediate) Goal: cover Ethereum mainnet + L2s (Base, Arbitrum, Optimism, Polygon). **Step 1 — install the Base skill for quick L2 work.** ```bash hermes skills install blockchain/base ``` **Step 2 — add Alchemy's official MCP for Ethereum mainnet + L2s.** ```bash # Get an Alchemy key at alchemy.com export ALCHEMY_API_KEY=... ``` ```yaml # config.yaml mcp_servers: alchemy: command: npx args: ["-y", "@alchemyplatform/alchemy-mcp-server"] env: ALCHEMY_API_KEY: "${ALCHEMY_API_KEY}" etherscan: command: npx args: ["-y", "mcp-etherscan-server"] env: ETHERSCAN_API_KEY: "${ETHERSCAN_API_KEY}" ``` **Step 3 — (optional) add Dune for analytics and DeFiLlama for TVL/yield.** Dune: `kukapay/dune-analytics-mcp`. For DeFiLlama there's no dedicated MCP — use `serpens-hermes` tool pattern or write a custom tool with `requests` against `api.llama.fi`. **Step 4 — test across chains.** ```bash hermes chat "Check the ETH balance of vitalik.eth on mainnet, and on Base" # Agent routes mainnet to Alchemy MCP, Base to the blockchain/base skill ``` **Time to first multi-chain query:** ~30 minutes. --- ### Recipe C: Contract / token security audit (intermediate) Goal: "Is this token a honeypot? Are there risky clauses in this contract?" **Step 1 — clone the serpens-hermes pattern.** Either install [`amrrobb/serpens-hermes`](https://github.com/amrrobb/serpens-hermes) directly, or lift its 11 custom tools into your own config: ``` get_token_info, get_token_price, get_eth_balance, scan_token_security, check_address_risk, get_contract_source, analyze_contract_security, analyze_wallet, get_whale_movements, get_defi_positions, get_protocol_tvl ``` **Step 2 — set API keys.** ```bash # ~/.hermes/.env ETHERSCAN_API_KEY=... # GoPlus is typically keyless but rate-limited ``` **Step 3 — add a SOUL.md persona if you want a security analyst voice.** Serpens ships one. Copy it. **Step 4 — use it.** ``` You: Audit 0x6982508145454Ce325dDbE47a25d4ec3d2311933 Agent: runs scan_token_security → GoPlus; get_contract_source → Etherscan; analyze_contract_security → regex on source; returns structured risk report ``` **Time to first audit:** ~1-2 hours (custom tool registration + key plumbing). --- ### Recipe D: DeFi position monitoring with alerts (intermediate) Goal: watch your Aave / Uniswap positions, get Telegram alerts on drift. **Step 1 — pick your protocol MCPs.** ```yaml mcp_servers: aave: command: npx args: ["-y", "@kukapay/aave-mcp"] uniswap-trader: command: npx args: ["-y", "@kukapay/uniswap-trader-mcp"] defi-rates: command: npx args: ["-y", "@qingfeng/defi-rates-mcp"] ``` **Step 2 — configure Telegram gateway.** See [[concepts/messaging-gateway]]. Set `TELEGRAM_BOT_TOKEN`. **Step 3 — write a cron job.** ```yaml # config.yaml cron: - name: aave-health-check schedule: "0 * * * *" # hourly prompt: | Check my Aave positions for wallet 0x... Alert via Telegram if health factor drops below 1.5 or any position's LTV exceeds 70%. ``` **Step 4 — test the alert path manually once.** ```bash hermes run-cron aave-health-check ``` **Time to first alert:** ~1 hour. --- ### Recipe E: Cross-chain USDC payments with safety (advanced) Goal: let Hermes pay vendors or fetch x402-paywalled content, without letting it drain your wallet. **Step 1 — install hermes-payguard.** ```bash git clone https://github.com/nativ3ai/hermes-payguard.git cd hermes-payguard pip install -e . payguard install-plugin payguard init-policy payguard doctor ``` **Step 2 — write a strict policy.** ```yaml # ~/.hermes/payguard/policy.yaml mode: enforce network_profile: mainnet asset: USDC default_chain: BASE per_payment_limit_usdc: 100 micro_auto_approve_limit_usdc: 0.05 allowed_circle_recipients: - "0x..." # explicit allowlist — no wildcard allowed_cctp_destination_chains: [] allowed_x402_hosts: - localhost allow_unlisted_cctp_destinations: false ``` **Step 3 — set Circle / x402 credentials.** See the hermes-payguard README for the full env var set (`CIRCLE_API_KEY`, `CIRCLE_ENTITY_SECRET_CIPHERTEXT`, `CIRCLE_WALLET_ID`, `PAYGUARD_EVM_PRIVATE_KEY`, `PAYGUARD_X402_NETWORK`, `CCTP_EXECUTOR_URL`). **Step 4 — the operator flow.** 1. Hermes calls `payguard_prepare_usdc_transfer` — stages an intent. 2. If above threshold, Hermes stops and says: "run `payguard approve <intent-id>`". 3. You run the approval command (outside the agent loop). 4. Hermes calls `payguard_execute_payment_intent`. Micro-payments below `micro_auto_approve_limit_usdc` run without the approval stamp — appropriate for x402 HTTP fetches. **Time to first safe payment:** ~2-3 hours. --- ### Recipe F: Trading agent (experimental — don't skip the governance layer) Goal: autonomous execution on DEXes with policy gating. **This is the most speculative recipe.** No published Hermes trading agent has posted a verified track record. Treat this as "here's how you'd prototype it" rather than "here's how to make money." **Step 1 — pick a governance layer.** The RiskState pattern is the current reference: `framework → intelligence → policy engine → execution`. RiskState exposes `@riskstate/mcp-server` on npm; its API returns `max_size_fraction` and `structural_blockers`. ```yaml mcp_servers: riskstate: command: npx args: ["-y", "@riskstate/mcp-server"] env: RISKSTATE_API_KEY: "${RISKSTATE_API_KEY}" ``` **Step 2 — add an intelligence source.** CoinGlass (futures), Nansen (smart-money), DeFiLlama (TVL), CoinGecko (prices). All have MCPs or are reachable via a simple custom tool. **Step 3 — pick an execution rail.** - **CoW Swap** — MEV-protected, batched. Best for ETH/stablecoins on mainnet. - **Jupiter** — Solana. Via `kukapay/jupiter-mcp`. - **Uniswap** — direct DEX. `kukapay/uniswap-trader-mcp`. - **Safe** — multi-sig treasury. For anything DAO-scale. **Step 4 — wire the loop.** Every trade call must read from RiskState first. If `max_size_fraction == 0` or `structural_blockers` is non-empty, refuse. Put this in the agent's prompt and in the MCP tool wrapper. **Step 5 — paper-trade first.** Use testnet. Set `PAYGUARD_ENV=testnet` if using payguard. Run for at least a week before touching real funds. **Time to first paper trade:** ~1 day. **Time to first real trade:** don't rush it. --- ## Pages Compared - [[concepts/onchain-workflows]] — the foundational concept page this recipe operationalizes - [[concepts/skills-system]] — how first-party skills like `blockchain/solana` and `blockchain/base` are loaded - [[concepts/mcp-integration]] — `config.yaml` server setup, OAuth PKCE, OSV malware scanning, discovery workflow - [[concepts/approval-system]] — the general approval surface for write-capable tools - [[concepts/cron-scheduling]] — scheduled monitoring (Recipes A, D) - [[concepts/messaging-gateway]] — Telegram alerts for Recipes A, D, F - [[concepts/subagents-delegation]] — parallel chain queries (used by Mercury), isolating untrusted analysis - Raw inventory: `raw/onchain-ecosystem.md`