diff --git a/CHANGELOG.md b/CHANGELOG.md index 1fdd710..9b3eaab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,26 @@ Dated list of meaningful guide updates. Roughly [Keep a Changelog](https://keepachangelog.com) flavored. +## 2026-07-01 — Hermes v0.17.0 "Reach" + v0.18.0 "Judgment" Refresh + +### Added +- **Part 26 — MoA, Verification & Self-Improvement**: the v0.18 "Judgment" stack. Mixture-of-Agents presets as first-class selectable models (`moa` provider, visible per-reference reasoning, streaming aggregator, `/moa` one-shots, trace persistence), evidence-based coding verification (`agent.coding_context`, `pre_verify`, verify-on-stop), **completion contracts** for `/goal` + `/goal wait `, `/learn` + `/journey` self-improvement, background subagent fan-out, everyday commands (`/prompt`, `/reasoning full`, `/timestamps`, in-place compaction, Blank Slate setup), and the team/fleet layer (scale-to-zero + drain coordination, managed scope from `/etc/hermes`, multiplexed gateway, Automation Blueprints, cron continuations). New `assets/moa-judgment.png` banner. +- Part 15: **iMessage via Photon Spectrum** (`hermes photon login`, no Mac required) as the recommended iMessage path, plus the official **WhatsApp Business Cloud API** adapter, the **Raft** agent-network channel, and Telegram rich messages (Bot API 10.1). +- Part 24: v0.17/v0.18 desktop coverage — first-class **Projects** (coding rail, review pane, worktrees), multi-terminal panel, memory graph, subagent watch-windows, VS Code Marketplace themes, native notifications, remote media relay. +- Part 9: **Google Vertex AI** provider, MoA-as-provider note, and Cursor **Composer** via xAI Grok OAuth. +- Part 8: `delegate_task(background=true)` and background fan-out patterns. +- Part 7: `memory` atomic batch operations, `/journey`, and the desktop memory graph. +- Part 22 section 9 "Newer Power Moves (v0.17 → v0.18)". + +### Changed +- README badges, intro, "Pick Your Path," "What's New," TOC, and repo map now target Hermes **v0.18.0 (v2026.7.1)**; platform count updated to 25+; guide is now 27 parts. +- Part 23: `/goal` guidance updated for completion contracts; Curator notes updated for the opt-in LLM consolidation pass (Part 22). + +### Removed +- **Gemini OAuth as a recommended provider** — the Gemini-CLI OAuth providers were removed in Hermes v0.18. Routing tables and Part 9/21/22 references now point to Gemini API keys or the new Vertex AI provider. +- BlueBubbles-as-the-only-iMessage-path framing (kept as the self-hosted/legacy alternative). +- v0.16-as-current framing and the expanded v0.15 "What's New" section (condensed into Earlier Milestones). + ## 2026-06-17 — Hermes v0.16.0 "Surface" Refresh ### Added diff --git a/README.md b/README.md index 2421d45..4e59145 100644 --- a/README.md +++ b/README.md @@ -5,24 +5,24 @@

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) -[![Hermes](https://img.shields.io/badge/Hermes-v0.16.0%20%282026.6.5%29-9146FF)](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5) -[![Last updated](https://img.shields.io/badge/Last%20updated-2026--06--17-brightgreen)](./CHANGELOG.md) -[![Parts](https://img.shields.io/badge/parts-26-blue)](#table-of-contents) +[![Hermes](https://img.shields.io/badge/Hermes-v0.18.0%20%282026.7.1%29-9146FF)](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.7.1) +[![Last updated](https://img.shields.io/badge/Last%20updated-2026--07--01-brightgreen)](./CHANGELOG.md) +[![Parts](https://img.shields.io/badge/parts-27-blue)](#table-of-contents) [![Skills](https://img.shields.io/badge/installable%20skills-13-blue)](./skills/) [![Configs](https://img.shields.io/badge/config%20templates-5-blue)](./templates/config/) [![CI](https://github.com/OnlyTerp/hermes-optimization-guide/actions/workflows/ci.yml/badge.svg)](./.github/workflows/ci.yml) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md) -> **Current through Hermes Agent v0.16.0 (v2026.6.5) — "The Surface Release"** · **26 parts, 13 installable guide skills, 5 opinionated configs, 4 reference architectures, one-command VPS bootstrap** · Now covering the **native Hermes Desktop app** (macOS/Windows/Linux), the **NVIDIA RTX / DGX Spark** local-hardware story + OpenShell, multi-agent **swarms** (`hermes kanban swarm`), the browser **admin panel**, `/undo`, the fuzzy model picker, Quick Setup via Nous Portal, and a leaner default skill set. **Bring any model** — this guide is about the *harness*, not the weights. +> **Current through Hermes Agent v0.18.0 (v2026.7.1) — "The Judgment Release"** · **27 parts, 13 installable guide skills, 5 opinionated configs, 4 reference architectures, one-command VPS bootstrap** · Now covering **Mixture-of-Agents as a first-class model**, evidence-based **verification** + `/goal` completion contracts, **`/learn` + `/journey`** self-improvement, **background subagent fan-out**, the maturing **Desktop app** (Projects, memory graph, multi-terminal), **iMessage via Photon** (no Mac needed), the NVIDIA RTX / DGX Spark local-hardware story, and gateway **scale-to-zero** for teams. **Bring any model** — this guide is about the *harness*, not the weights. > > Other languages: [中文](./README-zh.md) · [日本語](./README-ja.md) ### The End-to-End Hermes Guide — docs + runnable artifacts -Every part you need to go from fresh install to a production Hermes deployment — driven from the **native desktop app**, the CLI/TUI, a browser admin panel, or 22+ chat platforms. Orchestrate Claude Code / Codex / Gemini CLI through durable Kanban lanes and **multi-agent swarms**, plug into any MCP server, trace every call in Langfuse, let it curate its own skills, push heavy work onto disposable Modal/Daytona/Vercel sandboxes — or run the whole thing **locally on your own GPU / NVIDIA DGX Spark**. It's all **model-agnostic**: bring whatever weights you want, the guide is about the *harness*. +Every part you need to go from fresh install to a production Hermes deployment — driven from the **native desktop app**, the CLI/TUI, a browser admin panel, or 25+ chat platforms (now including iMessage with no Mac required, via Photon). Orchestrate Claude Code / Codex / Gemini CLI through durable Kanban lanes and **multi-agent swarms**, plug into any MCP server, trace every call in Langfuse, let it curate its own skills, push heavy work onto disposable Modal/Daytona/Vercel sandboxes — or run the whole thing **locally on your own GPU / NVIDIA DGX Spark**. It's all **model-agnostic**: bring whatever weights you want, the guide is about the *harness*. Unlike most guides, the prescriptions come with **working files**: [`skills/`](./skills) you can `ln -s` into `~/.hermes/skills/`, [`templates/config/`](./templates/config) you `cp` to `~/.hermes/config.yaml`, [`scripts/vps-bootstrap.sh`](./scripts/vps-bootstrap.sh) that takes a fresh VPS to production in one command. -*By Terp — [Terp AI Labs](https://x.com/OnlyTerp)* · Last updated **June 17, 2026** · [CHANGELOG](./CHANGELOG.md) · [ROADMAP](./ROADMAP.md) · [ECOSYSTEM](./ECOSYSTEM.md) +*By Terp — [Terp AI Labs](https://x.com/OnlyTerp)* · Last updated **July 1, 2026** · [CHANGELOG](./CHANGELOG.md) · [ROADMAP](./ROADMAP.md) · [ECOSYSTEM](./ECOSYSTEM.md) --- @@ -76,7 +76,7 @@ Prefer a 5-minute local-only setup? → **[docs/quickstart.md](./docs/quickstart | [`docs/quickstart.md`](./docs/quickstart.md) | 5-minute zero-to-Telegram-bot. | | [`ECOSYSTEM.md`](./ECOSYSTEM.md) | Curated directory of MCP servers, coding agents, dashboard plugins. | | [`ROADMAP.md`](./ROADMAP.md) · [`CHANGELOG.md`](./CHANGELOG.md) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) | The usual suspects. | -| README + `part1-*.md` … `part25-*.md` | The 26-part guide itself (now incl. Desktop App + NVIDIA / local hardware). | +| README + `part1-*.md` … `part26-*.md` | The 27-part guide itself (now incl. MoA + verification, Desktop App, NVIDIA / local hardware). | --- @@ -106,7 +106,7 @@ Full set of diagrams: [`diagrams/architecture.md`](./diagrams/architecture.md). ## Pick Your Path -This guide grew to 26 parts because *Hermes grew*. Six sections (Parts 1–5 plus SOUL.md) live in this README; Parts 6–25 live as separate files. You don't have to read them all — pick the shortest path to what you need: +This guide grew to 27 parts because *Hermes grew*. Six sections (Parts 1–5 plus SOUL.md) live in this README; Parts 6–26 live as separate files. You don't have to read them all — pick the shortest path to what you need: ### 🎯 "I just want it working in 10 minutes" Skip the terminal: install the [desktop app](./part24-desktop-app.md) and let first-run **Quick Setup via Nous Portal** pick a model for you. Prefer the CLI? [Part 1: Setup](#part-1-setup-stop-fumbling-with-installation) → [Part 12: Web Dashboard](./part12-web-dashboard.md) and point-and-click the rest. @@ -135,13 +135,36 @@ Skip the terminal: install the [desktop app](./part24-desktop-app.md) and let fi ### 🔒 "Run it all locally on my own GPU" [Part 25: NVIDIA & Local Hardware](./part25-nvidia-local.md) — RTX / DGX Spark, OpenShell isolation, and a model-agnostic local stack (llama.cpp / LM Studio / Ollama) so your data never leaves the machine. +### 🧑‍⚖️ "I want an ensemble of frontier models — and proof the work is done" +[Part 26: MoA, Verification & Self-Improvement](./part26-moa-verification.md) — pick a Mixture-of-Agents council like a model, judge `/goal` completion against evidence, and steer what the agent learns with `/learn` + `/journey`. + --- -## What's New (June 2026) +## What's New (July 2026) + +Two huge releases landed since the Surface refresh — **v0.17.0 "Reach" (v2026.6.19)** and **[v0.18.0 "The Judgment Release" (v2026.7.1)](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.7.1)**. Combined: ~3,200 commits, ~1,800 merged PRs, 1,200+ issues closed, and — as of v0.18 — **every P0 and P1 issue in the entire Hermes repo resolved** (~700 highest-priority items cleared in twelve days, with a standing commitment to keep the count at zero). None of it is model-specific — bring whatever weights you want. + +### v0.18.0 — "Judgment" (latest) + +- **Mixture-of-Agents is a first-class model** — every named MoA preset is a selectable virtual model under a `moa` provider in every picker (CLI/TUI/desktop/gateway). Each reference model's reasoning renders as its own labelled block, and the aggregator's answer streams live. `/moa` is now one-shot sugar. See [Part 26](./part26-moa-verification.md). +- **The agent proves its work** — verification evidence for coding tasks (run the project's checks, don't assert success), **completion contracts** for `/goal`, `/goal wait `, and a `pre_verify` hook. See [Part 26](./part26-moa-verification.md#2-verification--done-means-proven-not-claimed). +- **`/learn` + `/journey`** — distill a reusable skill from anything (`/learn `), and browse/edit/delete everything the agent has learned on a timeline. The desktop adds a playable **memory graph**. Background self-improvement now routes to an aux model and costs a fraction of before. See [Part 26](./part26-moa-verification.md#3-learn-and-journey--self-improvement-you-can-see) and [Part 7](./part7-memory-system.md). +- **Background subagent fan-out** — `delegate_task` dispatches parallel background subagents and returns one consolidated turn when all finish; your chat is never blocked. See [Part 8](./part8-subagent-patterns.md). +- **Desktop becomes a coding cockpit** — first-class per-profile **Projects** (sidebar, coding rail, review pane, worktree management), a **multi-terminal panel**, PR-style diffs in chat, and a conversation timeline rail. See [Part 24](./part24-desktop-app.md). +- **Run it for a team** — gateway **scale-to-zero** with drain coordination (no dropped in-flight turns), administrator-pinned **managed scope** from `/etc/hermes`, multiplexed profiles over one gateway, and **cron continuations**. See [Part 26](./part26-moa-verification.md#6-running-hermes-for-a-team--scale-to-zero-and-managed-scope). +- **Google Vertex AI provider** — Gemini through your GCP service account with auto-minted, auto-refreshed OAuth2 tokens (no static key). The Gemini-CLI OAuth providers were **removed** — see the migration note in [Part 9](./part9-custom-models.md). +- **Everyday wins** — `/prompt` (compose in `$EDITOR`), `/reasoning full`, `/timestamps`, in-place compaction by default, Blank Slate setup mode, and a security round (MCP-config persistence hardening, cron credential-exfil blocks, Slack `xapp-` token redaction). See [Part 26](./part26-moa-verification.md#5-small-things-youll-use-every-day) and [Part 19](./part19-security-playbook.md). -Two big releases landed since the Foundation refresh — **v0.15.0 "Velocity"** and **[v0.16.0 "The Surface Release"](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5)** — plus a deepening **NVIDIA** partnership. The headline themes: a native **desktop app**, run-it-**local** on NVIDIA hardware, multi-agent **swarms**, a browser **admin panel**, and a deliberately **leaner** default skill set. None of it is model-specific — bring whatever weights you want. +### v0.17.0 — "Reach" -### v0.16.0 — "Surface" (latest) +- **iMessage via Photon Spectrum — no Mac required** — `hermes photon login` and Hermes lives in the blue bubbles; positioned as the successor to the BlueBubbles bridge. Plus an **official WhatsApp Business Cloud API** adapter and the **Raft** agent-network channel. See [Part 15](./part15-new-platforms.md). +- **Background subagents** — `delegate_task(background=true)` returns a handle immediately; the result re-enters the conversation when it finishes. See [Part 8](./part8-subagent-patterns.md). +- **A much deeper desktop app** — rebindable shortcuts, native OS notifications, live subagent **watch-windows**, any VS Code Marketplace theme, a resizable terminal pane, remote media relay, and per-thread drafts. See [Part 24](./part24-desktop-app.md). +- **Dashboard grows up** — a full **profile builder** (model + skills + MCPs from the browser), a rehauled Skills Hub (previews + security scans), and hardened dashboard auth. See [Part 12](./part12-web-dashboard.md). +- **`image_generate` learned to edit** — image-to-image transforms across every provider; **Automation Blueprints** replace raw cron syntax with guided forms; the `memory` tool gained **atomic batch operations**; the Curator's LLM consolidation pass is now **opt-in** (routine curation costs zero tokens). See [Part 22](./part22-latest-power-moves.md) and [Part 7](./part7-memory-system.md). +- **Telegram rich messages** (Bot API 10.1, on by default), MCP **elicitation** (servers can prompt mid-tool-call on any surface), and Cursor's **Composer** model via xAI Grok OAuth. See [Part 15](./part15-new-platforms.md), [Part 17](./part17-mcp-servers.md), and [Part 9](./part9-custom-models.md). + +### v0.16.0 — "Surface" - **Hermes Desktop** — a native macOS/Windows/Linux app: streaming chat with live tool activity, a session list with archive/search, drag-and-drop files, clipboard image paste, a **Cmd+K command palette**, a model picker in the composer, a per-session **YOLO toggle**, and in-app self-update. It's "another surface over one agent, not a fork." See [Part 24](./part24-desktop-app.md). - **Remote backend** — desktop and clients can connect to a remote Hermes gateway over a secure WebSocket (OAuth or username/password), with per-profile hosts, concurrent multi-profile sessions, and cross-profile `@session` links. Thin GUI local, heavy agent remote. See [Part 24](./part24-desktop-app.md#7-connect-to-a-remote-hermes). @@ -153,19 +176,13 @@ Two big releases landed since the Foundation refresh — **v0.15.0 "Velocity"** - **NVIDIA Skills Hub tap** — a built-in trusted Skills source alongside OpenAI/Anthropic/HuggingFace (CUDA-X, AIQ, cuOpt), part of the broader NVIDIA local-hardware story. See [Part 25](./part25-nvidia-local.md). - **Security** — CVE-2026-48710 Starlette pin, SSRF off-loop hardening, and subprocess credential stripping. See [Part 19](./part19-security-playbook.md). -### v0.15.0 — "Velocity" - -- **Multi-agent swarms** — `hermes kanban swarm` turns the durable Kanban into a platform: a root planner, parallel workers, a gated verifier and synthesizer, a shared blackboard, per-task model overrides, and a worktree per task. See [Part 23](./part23-tenacity-stack.md). -- **Huge perf wave** — `run_agent.py` was split into focused `agent/*` modules (−76% lines), cold start dropped sharply (`hermes --version` −63%), per-turn function calls fell ~47%, and `session_search` got **~4,500× faster — and free**. See [Part 20](./part20-observability.md). -- **Brainworm / promptware defense** — a defense layer against instructions smuggled through tool output and untrusted content. See [Part 19](./part19-security-playbook.md). -- **More surfaces & integrations** — Bitwarden Secrets Manager bootstrap, skill bundles (one slash command loads a whole workflow), an Ink TUI multi-session orchestrator, Krea 2 image generation, an interactive Nous-approved MCP catalog picker, ntfy as the 23rd messaging platform, and a deep xAI round (Web Search plugin, `hermes migrate xai`). See [Part 15](./part15-new-platforms.md) and [Part 17](./part17-mcp-servers.md). - ### NVIDIA partnership — run it local Hermes is now optimized for always-on **local** use on **NVIDIA RTX PCs, RTX PRO workstations, and DGX Spark** (128GB unified memory, ~1 petaflop of AI performance, runs 120B-class MoE models all day). Tensor Cores accelerate inference, there's a dedicated **DGX Spark playbook**, and **OpenShell** adds kernel-level isolation between the agent and your OS. It stays model-agnostic — bring any weights. See [Part 25](./part25-nvidia-local.md). ### Earlier milestones (still relevant) +- **v0.15 "Velocity"** — multi-agent swarms (`hermes kanban swarm`), the big perf wave (~4,500× faster free `session_search`), Brainworm/promptware defense, skill bundles, and ntfy as a messaging platform. See [Part 23](./part23-tenacity-stack.md) and [Part 19](./part19-security-playbook.md). - **v0.14 "Foundation"** — PyPI installs + lighter launch, Grok OAuth + 1M context, `hermes proxy` (OpenAI-compatible localhost), `x_search`, Teams/LINE/SimpleX, live `/handoff`, and the first native Windows support. See [Part 23](./part23-tenacity-stack.md) and [Part 13](./part13-tool-gateway.md). - **v0.13 "Tenacity"** — durable multi-agent Kanban, `/goal` persistent objectives, Checkpoints v2, and no-agent cron. See [Part 23](./part23-tenacity-stack.md). - **v0.12 "Curator"** — the autonomous Curator (`hermes curator`), a rubric-based self-improvement loop, a much wider provider menu, and a plugin-first gateway. See [Part 22](./part22-latest-power-moves.md) and [Part 9](./part9-custom-models.md). @@ -186,7 +203,7 @@ Hermes is now optimized for always-on **local** use on **NVIDIA RTX PCs, RTX PRO 7. [Context Compression](./part6-context-compression.md) — Fix the silent context loss bug, configure compression thresholds, survive long sessions 8. [Memory System](./part7-memory-system.md) — The three-tier memory architecture: persistent facts, conversation recall, procedural memory 9. [Subagent Patterns](./part8-subagent-patterns.md) — Orchestrator/worker delegation, ACP subagents, parallel task execution -10. [Custom Model Providers](./part9-custom-models.md) — Grok/SuperGrok OAuth, Bedrock, Azure AI Foundry, LM Studio, Gemini OAuth, Codex OAuth, OpenRouter routing, model aliases, fallback chains +10. [Custom Model Providers](./part9-custom-models.md) — Grok/SuperGrok OAuth, Bedrock, Azure AI Foundry, Vertex AI, LM Studio, Codex OAuth, MoA presets, OpenRouter routing, model aliases, fallback chains 11. [SOUL.md Anti-Patterns](./part10-soul-antipatterns.md) — What makes an agent annoying vs useful, the formula that works 12. [Gateway Recovery](./part11-gateway-recovery.md) — Crash detection, auto-recovery, common failure modes, health checks 13. [Web Dashboard](./part12-web-dashboard.md) — `hermes dashboard`, browser Chat via real TUI, models/plugins tabs, config, keys, sessions, logs, analytics, cron @@ -201,8 +218,9 @@ Hermes is now optimized for always-on **local** use on **NVIDIA RTX PCs, RTX PRO 22. [Remote Sandboxes & Bulk File Sync](./part21-remote-sandboxes.md) — SSH, Modal, Daytona, Vercel Sandbox, Fly Machines, E2B. Diff-based sync-back on teardown 23. [Latest Power Moves](./part22-latest-power-moves.md) — Curator, TUI habits, context-file hygiene, plugins, dashboard Chat, cron chaining, and the 2026 upgrade checklist 24. [Foundation + Tenacity Stack](./part23-tenacity-stack.md) — PyPI/lazy deps, `hermes proxy`, `/handoff`, durable Kanban, `/goal`, Checkpoints v2, no-agent cron, worker lanes, multi-agent swarms, and the upgrade checklist -25. [Hermes Desktop App](./part24-desktop-app.md) — Native macOS/Windows/Linux GUI, Quick Setup, Cmd+K palette, drag-and-drop, model picker, remote gateway, multi-profile, voice, self-update +25. [Hermes Desktop App](./part24-desktop-app.md) — Native macOS/Windows/Linux GUI, Quick Setup, Cmd+K palette, Projects, multi-terminal, memory graph, remote gateway, multi-profile, voice, self-update 26. [NVIDIA & Local Hardware](./part25-nvidia-local.md) — Run Hermes on your own GPU: RTX / DGX Spark, OpenShell isolation, NemoClaw, and a model-agnostic local stack +27. [MoA, Verification & Self-Improvement](./part26-moa-verification.md) — Mixture-of-Agents presets as models, `/moa`, completion contracts for `/goal`, `/learn`, `/journey`, background fan-out, scale-to-zero --- diff --git a/assets/moa-judgment.png b/assets/moa-judgment.png new file mode 100644 index 0000000..dd459e1 Binary files /dev/null and b/assets/moa-judgment.png differ diff --git a/part15-new-platforms.md b/part15-new-platforms.md index d103a95..6e85d87 100644 --- a/part15-new-platforms.md +++ b/part15-new-platforms.md @@ -1,12 +1,12 @@ -# Part 15: Messaging Platforms (Teams, LINE, SimpleX, Google Chat, iMessage, WeChat, Android) +# Part 15: Messaging Platforms (iMessage via Photon, WhatsApp Cloud, Teams, LINE, SimpleX, Google Chat, WeChat, Android) -*Hermes' gateway is now a plugin host. v0.9 made Hermes "everywhere"; v0.11/v0.12 added QQBot, Tencent Yuanbao, and Microsoft Teams; v0.13 added Google Chat; v0.14 wires Teams end-to-end and adds LINE + SimpleX Chat.* +*Hermes' gateway is now a plugin host. v0.9 made Hermes "everywhere"; v0.11/v0.12 added QQBot, Tencent Yuanbao, and Microsoft Teams; v0.13 added Google Chat; v0.14 wired Teams end-to-end and added LINE + SimpleX Chat; v0.15 added ntfy; and v0.17 "Reach" added the three biggest asks at once — **iMessage with no Mac required (Photon)**, an **official WhatsApp Business Cloud API** adapter, and the **Raft** agent-to-agent network.* --- -## The 22+ Platform Lineup +## The 25+ Platform Lineup -As of v0.14, the gateway ships built-in adapters plus plugin-shipped platforms: +As of v0.17, the gateway ships built-in adapters plus plugin-shipped platforms: | Platform | Mode | Notes | |----------|------|-------| @@ -16,8 +16,11 @@ As of v0.14, the gateway ships built-in adapters plus plugin-shipped platforms: | **Google Chat** | App / webhook | **New in v0.13**, Workspace-native chat surface | | **LINE** | Messaging API | **New in v0.14**, Japan/Korea/Taiwan mobile-first surface | | **SimpleX Chat** | Decentralized chat | **New in v0.14**, privacy-first chat with no user IDs | -| WhatsApp | Web API | QR-code login, requires always-on node | -| **iMessage (BlueBubbles)** | Webhook | **New in v0.9** | +| WhatsApp (personal) | Web API | QR-code login, requires always-on node | +| **iMessage (Photon)** | Photon Spectrum relay | **New in v0.17** — no Mac required | +| **iMessage (BlueBubbles)** | Webhook | Self-hosted alternative (needs an always-on Mac) | +| **WhatsApp Business Cloud API** | Official Meta webhook | **New in v0.17** — no QR node needed | +| **Raft** | Agent network | **New in v0.17** — talk to other agents, not humans | | **Weixin (WeChat personal)** | Long-poll | **New in v0.9** | | **WeCom (Enterprise WeChat)** | Webhook | **New in v0.9** | | **QQBot** | WebSocket/Webhook | Added after the original v0.9 platform sweep | @@ -41,7 +44,34 @@ All of them respect: - The shared session database (Part 7) - Pre-dispatch plugin hooks -This part covers the v0.9 adapters, the newer v0.12–v0.14 surfaces, and **Android / Termux** — running the agent itself on a phone. +This part covers the v0.9 adapters, the newer v0.12–v0.17 surfaces, and **Android / Termux** — running the agent itself on a phone. + +> **Telegram got richer in v0.17:** the Telegram adapter upgraded to Bot API 10.1 rich messages — formatted output with media, on by default. If your bot's replies suddenly look nicer, that's why; if a client chokes on them, they can be disabled per-gateway. + +## 2026 Update (v0.17): iMessage Without a Mac, Official WhatsApp, and Raft + +### iMessage via Photon Spectrum — the new default + +The #1 ask since v0.9 — iMessage without dedicating a Mac — shipped in v0.17 as a platform plugin built on **Photon Spectrum's** managed line pool: + +```bash +hermes photon login # device-code OAuth — authenticate and you're live +``` + +Sign in, and Hermes lives in the blue bubbles: DMs, markdown rendering, emoji reactions, outbound media — over a gRPC-native channel (no webhook), with no macOS server, no Full Disk Access, and no always-on hardware. Free to start, nothing to self-host. Access controls (pairing, allowlists, `/fast`, cron delivery) work like every other gateway. + +Operationally: + +- **Use Photon** if you just want Hermes on iMessage. It's the supported, zero-hardware path and is positioned as the successor to the BlueBubbles bridge. +- **Keep BlueBubbles** (below) if you require fully self-hosted message flow — Photon is a relay service, so your iMessage traffic transits their infrastructure. For the privacy-maximalist posture, the Mac-based bridge is still the answer. + +### WhatsApp Business Cloud API — the official path + +The old WhatsApp adapter drives WhatsApp Web with a QR login and an always-on node — fine for personal use, fragile for production. v0.17 adds an adapter for **Meta's official Business Cloud API**: webhook-based, no browser session to babysit, and legitimate for business use. If you're building anything customer-facing on WhatsApp, use this one; keep the Web adapter for personal accounts. + +### Raft — your agent gets peers + +Raft is a channel where the counterparty is **another agent**, not a human. A bundled adapter connects Hermes to [Raft](https://raft.build) as an external agent through a wake-channel bridge: set `RAFT_PROFILE`, run the bridge, and Raft can wake Hermes to handle messages. The design is privacy-by-contract — wake payloads carry only metadata (event IDs, timestamps), never message bodies. Still: treat every inbound Raft message as **untrusted input** — same posture as a public group chat: quarantine profile, no write tools, approvals for anything that touches your machine. [Part 19](./part19-security-playbook.md) applies double here. ## 2026 Update: Teams, LINE, SimpleX, Google Chat, QQBot, and Yuanbao @@ -118,13 +148,13 @@ Use QQBot when your community already lives in QQ and you want the same approval Yuanbao is now a native gateway adapter with text and media delivery. It belongs in the same bucket as Weixin/WeCom: powerful in China/APAC workflows, but operationally different from Western SaaS bots. Verify media size limits and identity mapping before using it for production approvals. -## iMessage via BlueBubbles +## iMessage via BlueBubbles (Self-Hosted Alternative) -### Why This Matters +### Why You'd Still Do This -Apple doesn't have a public iMessage API. The only supported path is [BlueBubbles](https://bluebubbles.app/), a free open-source macOS server that exposes a REST API + webhook feed on top of the native Messages.app database. +> **Most people should use Photon now** (`hermes photon login`, above) — it needs no Mac at all. BlueBubbles remains the right choice when you want message flow that never leaves hardware you own. -If you have a Mac that stays on, you now have an iMessage bot with full media, reactions, typing indicators, and read receipts. +[BlueBubbles](https://bluebubbles.app/) is a free open-source macOS server that exposes a REST API + webhook feed on top of the native Messages.app database. If you have a Mac that stays on, you get a fully self-hosted iMessage bot with full media, reactions, typing indicators, and read receipts. ### Prerequisites diff --git a/part18-coding-agents.md b/part18-coding-agents.md index bcbc0f6..7b77133 100644 --- a/part18-coding-agents.md +++ b/part18-coding-agents.md @@ -12,7 +12,7 @@ Hermes is excellent at reasoning, memory, conversation, and workflow. It is *not |-------|-----------|------------| | **Claude Code** | Best unattended PR work, large refactors, tests, reviews; Week 20+ agent view, `/goal`, and fast Opus 4.7 mode make it the premium lane | Pro/Max OAuth or `ANTHROPIC_API_KEY` | | **Codex** (OpenAI) | Fast sandboxed feedback loop, bug hunts, small/medium edits; v0.133+ goals default well and runs cleanly behind `hermes proxy` | OAuth via `openai` CLI, `OPENAI_API_KEY`, or `hermes proxy` | -| **Gemini CLI** | 1M context and multimodal repo/document sweeps; v0.43 improves surgical edits, session import/export, and OAuth behavior on headless Linux | OAuth via `gemini auth`; Hermes' own Gemini OAuth covers normal model-provider use | +| **Gemini CLI** | 1M context and multimodal repo/document sweeps; v0.43 improves surgical edits, session import/export, and OAuth behavior on headless Linux | OAuth via `gemini auth`; for normal model-provider use, Hermes uses a `GEMINI_API_KEY` or Vertex AI ([Part 9](./part9-custom-models.md)) | | **OpenCode** (anomalyco) | Open-source, routes to Kimi K2.6 / GLM / MiMo cheaply | Bring any provider key | | **Aider** | Surgical git-based edits, smallest token footprint; works well through `hermes proxy` | Bring any provider key or local proxy | diff --git a/part21-remote-sandboxes.md b/part21-remote-sandboxes.md index 802b2e0..fcc8f78 100644 --- a/part21-remote-sandboxes.md +++ b/part21-remote-sandboxes.md @@ -165,7 +165,7 @@ sandboxes: pull_on_command: "/sync-home" # Manual sync when you want it ``` -Pair with the [Gemini OAuth provider](./part9-custom-models.md#gemini-oauth--free-tier-friendly) for free-tier-friendly long-context reads inside the sandbox. +Pair with a [Gemini API key or Vertex AI](./part9-custom-models.md#google-api-key-or-vertex-ai-gemini-oauth-is-gone) for cheap long-context reads inside the sandbox. --- diff --git a/part22-latest-power-moves.md b/part22-latest-power-moves.md index 68d1a40..8183706 100644 --- a/part22-latest-power-moves.md +++ b/part22-latest-power-moves.md @@ -1,6 +1,6 @@ # Part 22: Latest Power Moves — Curator, TUI, Plugins, Context Files -*If you already know Hermes but missed the v0.11/v0.12 wave, read this part first for Curator, TUI, plugins, and context hygiene. For the v0.13/v0.14 durability + foundation layer — Kanban, `/goal`, `/handoff`, Checkpoints v2, no-agent cron, PyPI installs, proxy, and new platforms — go next to [Part 23](./part23-tenacity-stack.md). The newest everyday moves from v0.15 "Velocity" and v0.16 "Surface" — `/undo`, a default-interface choice, the fuzzy model picker, and leaner default skills — are in [section 8](#8-newer-power-moves-v015--v016). For the native GUI and the run-it-local story, see [Part 24](./part24-desktop-app.md) and [Part 25](./part25-nvidia-local.md).* +*If you already know Hermes but missed the v0.11/v0.12 wave, read this part first for Curator, TUI, plugins, and context hygiene. For the v0.13/v0.14 durability + foundation layer — Kanban, `/goal`, `/handoff`, Checkpoints v2, no-agent cron, PyPI installs, proxy, and new platforms — go next to [Part 23](./part23-tenacity-stack.md). The everyday moves from v0.15 "Velocity" and v0.16 "Surface" — `/undo`, a default-interface choice, the fuzzy model picker, and leaner default skills — are in [section 8](#8-newer-power-moves-v015--v016), and the newest v0.17 "Reach" / v0.18 "Judgment" quick hits are in [section 9](#9-newer-power-moves-v017--v018). For the native GUI and the run-it-local story, see [Part 24](./part24-desktop-app.md) and [Part 25](./part25-nvidia-local.md). For the big v0.18 ideas — Mixture-of-Agents, verification, `/learn`, `/journey` — see [Part 26](./part26-moa-verification.md).* --- @@ -23,6 +23,8 @@ Use it like this: Curator should prune skills, not decide project policy. Put durable project rules in context files. +> **v0.17 change:** the Curator's LLM-driven consolidation pass is now **opt-in** — routine curation (archiving duplicates, pruning stale skills) costs zero tokens by default. Enable consolidation explicitly when you want it to actually merge and rewrite skills. Pair Curator with `/journey` ([Part 26](./part26-moa-verification.md#3-learn-and-journey--self-improvement-you-can-see)) to audit the memory side too. + --- ## 2. Use the TUI as Your Daily Driver @@ -211,11 +213,49 @@ When one board outgrows a single worker, `hermes kanban swarm` turns Kanban into --- +## 9. Newer Power Moves (v0.17 → v0.18) + +The Reach and Judgment releases added another round of daily drivers. The headline features (MoA, verification, `/learn`, `/journey`, background fan-out) get their own part — [Part 26](./part26-moa-verification.md) — but these small ones deserve muscle memory: + +### `/prompt` — compose long prompts in a real editor + +Opens `$EDITOR` so you can write a multi-line, markdown-formatted prompt and have it queued as your next message. The single best QoL command of v0.18 for anyone writing detailed task briefs. + +### `/reasoning full` — uncap thinking for a session + +When a session hits something genuinely hard, `/reasoning full` removes the thinking budget cap for that session. Cheaper than switching to a bigger model for one gnarly step. + +### `/timestamps` and a timestamped `/history` + +Toggle inline timestamps on turns and see when things actually happened in `/history` — essential when auditing long autonomous runs. + +### In-place compaction (no more broken `@session` links) + +Context compression now rewrites the session **under the same session id** by default, instead of rotating to a new one. Long-running sessions keep their identity, so `@session` references, integrations, and desktop links stop silently breaking. + +### `image_generate` learned image-to-image + +Pass an input image and a transform prompt — restyle screenshots, apply logos, iterate on drafts — across every image provider, from any surface. + +### `memory` batch operations + +The `memory` tool applies multiple add/update/delete operations atomically in one call. Bulk cleanups (or a `/journey` pruning session) are one round-trip instead of ten. + +### Automation Blueprints instead of raw cron + +Parameterized automation templates that render as a dashboard form, a slash command, or a plain conversation ("set up my daily briefing for 8am"). Use them for anything you'd previously hand-rolled cron YAML for; keep raw cron for the deterministic no-agent watchdogs in [Part 23](./part23-tenacity-stack.md#5-use-no_agent-cron-for-watchdogs). + +### Blank Slate setup + +A minimal-agent onboarding mode: start from nothing and opt in tools one at a time. The right default for compliance-sensitive or locked-down machines. + +--- + ## What to Ignore Some old advice is no longer worth optimizing around: -- Do not install external Gemini CLI just for Gemini auth; Hermes can do OAuth itself. +- Do not build your Gemini setup on the old Gemini-CLI OAuth providers — they were **removed in v0.18**. Use a Gemini API key, or the Vertex AI provider for GCP shops ([Part 9](./part9-custom-models.md)). - Do not fork the dashboard for a custom tab; write a dashboard plugin. - Do not keep a giant SOUL.md full of procedures; use skills and Curator. - Do not use one expensive default model for every auxiliary task. diff --git a/part23-tenacity-stack.md b/part23-tenacity-stack.md index 76917a1..328cc2d 100644 --- a/part23-tenacity-stack.md +++ b/part23-tenacity-stack.md @@ -84,6 +84,8 @@ Use it for: Do not use `/goal` for vague aspirations like "improve the project." Give it an observable exit condition: checks pass, PR opened, benchmark table updated, board card complete, etc. +> **v0.18 upgrade — completion contracts.** `/goal` now compiles your objective into an explicit **completion contract**, and the goal only closes when the contract's conditions are *demonstrated* — not when the model claims they are. Background goals run under the same contracts, and `/goal wait ` blocks until a specific background goal completes (useful for chaining). Combined with coding verification, "done" now means proven. Details in [Part 26](./part26-moa-verification.md#2-verification--done-means-proven-not-claimed). + --- ## 4. Checkpoints v2 Changes Your Risk Model diff --git a/part24-desktop-app.md b/part24-desktop-app.md index a49ce46..78a7758 100644 --- a/part24-desktop-app.md +++ b/part24-desktop-app.md @@ -4,7 +4,7 @@ Hermes Desktop — the native macOS, Windows, and Linux app for the Hermes Agent

-*The v0.16.0 "Surface Release" shipped **Hermes Desktop**: a native macOS/Windows/Linux app that runs the exact same agent as the CLI, TUI, and gateway. Same config, same keys, same sessions, same skills, same memory — it's "another surface over one agent, not a fork." If you've avoided Hermes because you didn't want to live in a terminal, this is your on-ramp.* +*The v0.16.0 "Surface Release" shipped **Hermes Desktop**: a native macOS/Windows/Linux app that runs the exact same agent as the CLI, TUI, and gateway. Same config, same keys, same sessions, same skills, same memory — it's "another surface over one agent, not a fork." Two releases later it has grown into a genuine daily driver: v0.17 "Reach" added subagent watch-windows, native notifications, marketplace themes, and a real terminal pane; v0.18 "Judgment" turned it into a coding cockpit with first-class **Projects**, a **multi-terminal panel**, and the **memory graph**. If you've avoided Hermes because you didn't want to live in a terminal, this is your on-ramp.* --- @@ -44,13 +44,19 @@ The main window is a streaming chat with **live tool activity** — you watch to - **Clipboard image paste** — paste a screenshot straight in. - **Right-hand preview rail** — rendered output (files, images, results) opens beside the chat instead of scrolling away. - **Composer history and queue editing** — press up/down in the composer to recall previous messages and edit a queued message before it sends. +- **Per-thread drafts** (v0.17) — half-written messages persist per conversation; switch threads without losing what you were typing. +- **PR-style diffs in chat** (v0.18) — code changes render as reviewable diffs inline. +- **Conversation timeline rail** (v0.18) — jump around long sessions from a scannable timeline instead of scrolling. +- **Subagent watch-windows** (v0.17) — pop open a live window on any running subagent and watch it work instead of waiting on a summary. +- **Native OS notifications** (v0.17) — get pinged when a long run finishes or the agent needs an approval, even when the app is backgrounded. --- ## 3. Command Palette and Keyboard - **Command palette:** `Cmd+K` (macOS) / `Ctrl+K` (Windows/Linux) opens a fuzzy command palette for nearly everything — switch sessions, change model, open settings, run commands. -- **Rebindable shortcuts:** remap keys to taste. +- **Rebindable shortcuts** (v0.17): remap keys to taste. +- **Themes from the VS Code Marketplace** (v0.17): install any VS Code theme and the whole app adopts it. Your terminal aesthetic can follow you. - **Custom zoom:** scale the whole UI up or down. - **Language switcher:** the desktop UI is fully internationalized. v0.16 added **Simplified Chinese (简体中文)**; English is the default. Switch via the UI language picker (`display.language`). @@ -97,11 +103,32 @@ The model is "**thin GUI local, heavy agent remote**" — keep a lightweight app --- -## 8. Sessions, Files, and Voice +## 8. Projects — the v0.18 Coding Cockpit + +v0.18 made **Projects** first-class. A project is a per-profile workspace with: + +- A **project sidebar** and dedicated project pages. +- A **coding rail** — the agent's plan, running checks, and file activity beside the chat. +- A **review pane** — read the diff like a PR before you accept it. +- **Worktree management** — each project's changes live in an isolated git worktree, so parallel projects don't stomp each other. +- **Session–project association** — sessions attach to a project, so the history of a codebase stays in one place. + +Combined with the **multi-terminal panel** (multiple named terminals per project) this is the closest thing to an IDE the Hermes desktop has — except the agent drives. Pair it with verification and completion contracts from [Part 26](./part26-moa-verification.md#2-verification--done-means-proven-not-claimed) so "accept" means "checks passed," not "looks plausible." + +--- + +## 9. The Memory Graph + +Settings → Memory opens the v0.18 **memory graph**: a radial, playable timeline of every memory and skill the agent has accumulated — scrub through time and watch the graph grow. It's the GUI counterpart of `/journey` ([Part 26](./part26-moa-verification.md#3-learn-and-journey--self-improvement-you-can-see)): click any node to edit or delete it. Do a pruning pass monthly; wrong memories compound. + +--- + +## 10. Sessions, Files, and Voice - **Sessions:** archive, search, and **search-by-id**; run concurrent multi-profile sessions with cross-profile `@session` links. - **File browser:** set the initial working directory with `hermes desktop --cwd PATH` or the `HERMES_DESKTOP_CWD` environment variable. - **Voice:** click the mic to talk; macOS prompts for microphone permission once. +- **Remote media relay** (v0.17): when connected to a remote gateway, images and files generated on the remote box stream back to the app instead of being stranded on the server. ### Management Panes @@ -109,13 +136,13 @@ Beyond chat, the app has dedicated panes for **Skills**, **Cron**, **Profiles**, --- -## 9. Updating +## 11. Updating The app checks for updates in the background and offers **one-click update**; manual updates work too. This mirrors the gateway's **check-before-update** flow (verify before pulling) introduced alongside the System page in the web admin panel — see [Part 12](./part12-web-dashboard.md). --- -## 10. Uninstalling +## 12. Uninstalling Remove the app from **Settings → About → Danger zone**, or from the CLI: @@ -127,7 +154,7 @@ hermes uninstall --full # remove everything, including data --- -## 11. `hermes desktop` Flags +## 13. `hermes desktop` Flags For development and troubleshooting, `hermes desktop` accepts: @@ -146,7 +173,7 @@ For development and troubleshooting, `hermes desktop` accepts: ## When to Use Desktop vs CLI/TUI -- **Desktop** — you want a real GUI: drag-and-drop, image paste, a preview rail, point-and-click model switching, and one-click updates. Great for non-terminal users and for connecting to a remote agent. +- **Desktop** — you want a real GUI: drag-and-drop, image paste, a preview rail, Projects with reviewable diffs, the memory graph, point-and-click model switching, and one-click updates. Great for non-terminal users and for connecting to a remote agent. - **TUI** (`hermes --tui`) — you live in the terminal but want live tool cards, `/steer`, queueing, and a sticky composer. See [Part 22](./part22-latest-power-moves.md). - **CLI** (`hermes`) — scripting, cron, CI, and quick one-shots. diff --git a/part26-moa-verification.md b/part26-moa-verification.md new file mode 100644 index 0000000..a3894a7 --- /dev/null +++ b/part26-moa-verification.md @@ -0,0 +1,175 @@ +# Part 26: Mixture-of-Agents, Verification & Self-Improvement — The Judgment Stack + +

+ Mixture-of-Agents — verified, self-improving Hermes +

+ +*Hermes v0.18.0 (v2026.7.1, "The Judgment Release") is about how well the agent thinks and how it knows its work is actually done. Three big ideas landed together: **Mixture-of-Agents as a first-class model**, **evidence-based verification** for coding work and `/goal`, and a visible, steerable **self-improvement loop** (`/learn`, `/journey`, and the desktop memory graph). This part shows how to actually use them.* + +--- + +## 1. Mixture-of-Agents — Pick a Council Like You'd Pick a Model + +MoA used to be a mode you toggled. As of v0.18 every named MoA preset is a **selectable virtual model** under a `moa` provider — it shows up in the fuzzy model picker on the CLI, TUI, desktop, and gateway right alongside Claude, GPT, and Grok. + +```yaml +# ~/.hermes/config.yaml +moa: + presets: + my-council: + references: # the models that each answer independently + - anthropic/claude-opus-4.7 + - openai/gpt-5.5 + - xai/grok-4.3 + aggregator: anthropic/claude-opus-4.7 # synthesizes the final answer +``` + +Then just: + +```text +/model my-council # persistent — route every prompt through the ensemble +/moa # one-shot — run one prompt through the default preset, + # then restore your previous model +``` + +What you get in v0.18: + +- **Every reference model's full output renders as its own labelled block** — you read what each model thought *before* the aggregator's synthesis. The committee deliberates in the open. +- **The aggregator's answer streams live** instead of appearing whole after a long silence. +- **References see full tool state** and fire on every user/tool response, so the ensemble works mid-agent-loop, not just on chat one-shots. +- **Opt-in trace persistence** — set `moa.save_traces: true` to dump full-turn traces to JSONL for debugging and evals. + +### When to use it (and when not to) + +| Use MoA for | Skip MoA for | +|---|---| +| High-stakes decisions (architecture, irreversible ops) | Routine tool-heavy agent loops | +| Hard reasoning where models disagree | Cheap bulk tasks, cron jobs | +| Reviewing another agent's plan or diff | Anything latency-sensitive | +| "Second opinion" one-shots via `/moa` | Long sessions (you pay N models per turn) | + +Cost scales with the number of reference models — an ensemble of three frontier models is roughly 4× the tokens of one. Keep a council preset for judgment calls; don't make it your default driver. + +> **Gotcha:** the context window resolves from the **aggregator**, and auxiliary tasks route to the aggregator too. Pick an aggregator with a window at least as large as your references' outputs combined. + +--- + +## 2. Verification — "Done" Means Proven, Not Claimed + +v0.18 teaches Hermes to judge completion against **evidence** instead of vibes: + +- **Coding verification ledger** — `agent.coding_context` detects your project's canonical checks (tests, lint, build) and Hermes records verification evidence when it claims coding work is finished. +- **`pre_verify` hook** — wire in custom checks that must pass before the agent may declare success. +- **verify-on-stop is OFF by default** (a one-time migration tunes defaults) and skips doc-only edits — turn it on for repos where "it compiles and tests pass" is the bar: + +```yaml +agent: + coding_context: true + verification: + verify_on_stop: true + pre_verify: "./scripts/ci-local.sh" +``` + +### Completion contracts for `/goal` + +`/goal` ([Part 23](./part23-tenacity-stack.md#3-use-goal-for-do-not-stop-until-it-is-done)) gained **completion contracts**: state what "done" looks like, and the standing-goal loop judges against that evidence instead of the model's say-so. + +```text +/goal Fix the flaky auth test. Done means: pytest tests/auth passes 5 consecutive runs, no skips. +/goal wait # park the goal loop on a background process instead of re-poking the agent +``` + +The difference between "I think I fixed it" and "the tests pass, here's proof." If you run unattended `/goal` sessions or Kanban workers, adopt completion contracts everywhere — it's the single best defense against confident non-completion. + +--- + +## 3. `/learn` and `/journey` — Self-Improvement You Can See + +Two commands turn the skill/memory system from a black box into something you steer: + +```text +/learn # distill a reusable skill from a directory, a URL, + # or the workflow you just walked the agent through +/journey # a timeline of every memory + skill Hermes has + # accumulated — edit or delete any of them in place +``` + +- `/learn` honors your repo's CONTRIBUTING.md skill standards automatically. Teaching Hermes a workflow is now one command, not a manual `skill_manage` authoring session (see [Part 5](./part5-creating-skills.md) for what a good skill looks like — that still matters). +- `/journey` works in the CLI and TUI; the desktop app adds a **memory graph** — a playable radial timeline of memories and skills over time ([Part 24](./part24-desktop-app.md)). +- The post-turn self-improvement fork (the loop that decides whether to save a memory or skill after your turns) now routes to an **auxiliary model**, digests context instead of replaying the whole conversation, and adapts its cadence — it costs a fraction of what it used to. Keep it on. + +Monthly hygiene: open `/journey`, prune wrong or stale memories, and check that auto-learned skills match how you actually work. Pair with Curator ([Part 22](./part22-latest-power-moves.md#1-turn-on-curator-before-your-skill-library-becomes-noise)) for the skill side. + +--- + +## 4. Background Fan-Out — Delegate a Fleet and Keep Working + +`delegate_task` grew up across v0.17 → v0.18: + +```python +# v0.17: one background subagent — returns a handle immediately, +# result re-enters the conversation as a new turn when done +delegate_task(goal="Deep-dive the competitor's pricing page", background=True) + +# v0.18: background fan-out — parallel subagents, one consolidated +# turn when ALL of them finish +delegate_task( + tasks=[ + {"goal": "Audit src/auth for the token-refresh bug"}, + {"goal": "Audit src/billing for the same pattern"}, + {"goal": "Check upstream issues for known reports"}, + ], + background=True, +) +``` + +Your chat is never blocked; the CLI/TUI status bar tracks running background subagents. Use fan-out for independent research/audit legs, and keep [Kanban](./part23-tenacity-stack.md) for work that must survive restarts. Full delegation patterns: [Part 8](./part8-subagent-patterns.md). + +--- + +## 5. Small Things You'll Use Every Day + +- **`/prompt`** — opens `$EDITOR` to compose a long multi-line prompt in real markdown, queued as your next message. Stop fighting the one-line input box. +- **`/reasoning full`** — uncapped thinking for the current session when you want maximum deliberation. +- **`/timestamps`** + timestamps in `/history` — see when turns actually happened. +- **`/version`** and **`/billing`** — version info and interactive billing from inside the TUI/CLI. +- **In-place compaction** is now the default — compression rewrites the session under a single session id instead of rotating to a new one, so `@session` links and integrations stop breaking on long sessions. +- **Blank Slate setup** — a minimal-agent onboarding mode: start with nothing enabled and opt in tool by tool. The right choice for locked-down or compliance-sensitive boxes. + +--- + +## 6. Running Hermes for a Team — Scale-to-Zero and Managed Scope + +If you operate Hermes for more than yourself, v0.17/v0.18 shipped the fleet layer: + +- **Scale-to-zero** — the gateway goes dormant when idle and wakes on demand; disruptive lifecycle actions (restart, migration, auto-update) coordinate an **external drain** so nobody is cut off mid-turn. +- **Managed scope** — administrator-pinned, user-immutable config and secrets from root-owned `/etc/hermes`. Pin the security posture; let users own the rest. +- **Multiplexed gateway** (opt-in) — run all profiles over one gateway process. +- **Automation Blueprints** — parameterized automations that render as a form in the dashboard, a slash command in chat, or a conversation — "daily briefing at 8am" without cron syntax. +- **Cron continuations** — scheduled jobs can continue in a thread (with DM-mirror fallback), so a cron report becomes a conversation instead of a dead-end message. + +Pair with the hardened dashboard auth ([Part 12](./part12-web-dashboard.md)) and the [Part 19 security playbook](./part19-security-playbook.md) before exposing anything to a network. + +--- + +## Upgrade Checklist (v0.16 → v0.18) + +```bash +hermes update --check +hermes backup # now includes projects.db + kanban boards +hermes update +hermes --version # expect 0.18.x +``` + +Then: + +1. Define one MoA preset and try `/moa` on a real decision. +2. Turn on verification for your main coding repo and restate your standing `/goal`s as completion contracts. +3. Run `/journey` once — prune anything wrong before it compounds. +4. Try `/learn` on the last workflow you explained to the agent by hand. +5. If you used the **Gemini CLI OAuth** provider, migrate: it was removed in v0.18. Use a Gemini API key, or the new **Vertex AI** provider if your org runs Gemini through GCP ([Part 9](./part9-custom-models.md)). +6. Re-check platform config: Telegram rich messages are on by default; iMessage has a no-Mac path via Photon ([Part 15](./part15-new-platforms.md)). + +--- + +*The theme of mid-2026 Hermes: stop trusting single-model vibes. Ensemble the judgment calls, verify the claims, and audit what your agent thinks it learned.* diff --git a/part7-memory-system.md b/part7-memory-system.md index b378792..727743f 100644 --- a/part7-memory-system.md +++ b/part7-memory-system.md @@ -31,6 +31,8 @@ The `memory` tool saves durable facts that get injected into every future sessio **Format:** Keep entries under 2000 chars total. Be compact. These get injected into every message. +**Batch operations (v0.17):** the `memory` tool applies multiple add/update/delete operations **atomically in one call**. Bulk cleanups are one round-trip instead of ten — and a failed batch doesn't leave memory half-edited. + ```python # Good memory(action="add", target="memory", content="OpenClaw migrated. LightRAG: 4528 entities, float16 vectors (4096d). Telegram bot 8624585264, group -5216536760.") @@ -49,7 +51,7 @@ memory(action="add", target="memory", content="Today I worked on the lead gen pi # Browse recent sessions (no cost, instant) session_search() -# Search for specific topics (uses LLM to summarize) +# Search for specific topics (local full-text search — free and instant since v0.15) session_search(query="hermes optimization guide github") session_search(query="LightRAG setup OR embedding model") ``` @@ -111,6 +113,15 @@ Agent has full context → better answer **The hierarchy:** memory is always on. session_search is on-demand. skill_manage is triggered by task matching. +## Auditing What the Agent Learned (v0.18) + +The memory system is no longer write-only. Two v0.18 additions close the loop: + +- **`/journey`** — a timeline of every memory and skill Hermes has accumulated; edit or delete any entry in place. The desktop app renders it as a playable **memory graph**. +- **`/learn `** — deliberately distill a skill from a directory, URL, or a workflow you just demonstrated, instead of waiting for the background self-improvement loop. + +Do a `/journey` pruning pass monthly — a wrong memory gets injected into every future session and compounds. Full guidance: [Part 26](./part26-moa-verification.md#3-learn-and-journey--self-improvement-you-can-see). + ## Anti-Patterns | Don't Do This | Do This Instead | diff --git a/part8-subagent-patterns.md b/part8-subagent-patterns.md index 6991f0d..3d3f937 100644 --- a/part8-subagent-patterns.md +++ b/part8-subagent-patterns.md @@ -28,7 +28,7 @@ delegate_task( toolsets=["terminal", "file"] ) -# Parallel batch (up to 3) +# Parallel batch delegate_task( tasks=[ { @@ -37,7 +37,7 @@ delegate_task( }, { "goal": "Benchmark current LightRAG search latency", - "context="Path: ~/.hermes/skills/research/lightrag/", + "context": "Path: ~/.hermes/skills/research/lightrag/", "toolsets": ["terminal"] }, { @@ -54,6 +54,33 @@ delegate_task( - Each subagent gets its own terminal session. - Default max iterations: 50. Lower it for simple tasks (`max_iterations=10`). +## Background Delegation (v0.17) and Fan-Out (v0.18) + +By default `delegate_task` blocks your session until the subagent returns. Add `background=True` and it returns a **handle immediately** — you keep chatting, and the result re-enters the conversation as a new turn when it's done: + +```python +delegate_task(goal="Deep-dive the competitor's pricing page", background=True) +``` + +v0.18 extends this to batches — **background fan-out**. Dispatch parallel subagents and get **one consolidated turn when all of them finish**: + +```python +delegate_task( + tasks=[ + {"goal": "Audit src/auth for the token-refresh bug"}, + {"goal": "Audit src/billing for the same pattern"}, + {"goal": "Check upstream issues for known reports"}, + ], + background=True, +) +``` + +The CLI/TUI status bar tracks running background subagents, and the desktop app can open a live **watch-window** on any of them ([Part 24](./part24-desktop-app.md)). Rules of thumb: + +- **Foreground** when the next step depends on the result. +- **Background** for research, audits, and monitoring legs you'd otherwise wait on. +- **Kanban** ([Part 23](./part23-tenacity-stack.md)) when the work must survive restarts or involve humans — background subagents die with the process. + ## The CEO/COO/Worker Pattern ``` @@ -118,7 +145,7 @@ subprocess.run([ | Scenario | Approach | |----------|----------| -| 3 independent research tasks | Batch `delegate_task` with `tasks` array | +| 3 independent research tasks | Batch `delegate_task` with `tasks` array (`background=True` if you want to keep working) | | 1 complex coding task | ACP subagent (Claude Code or Codex) | | Multiple code changes in different files | SWE-1.6 via Cascade | | Single API call | Just call the tool, don't delegate | @@ -136,7 +163,7 @@ subprocess.run([ --- -## What's Next (April 2026 Additions) +## What's Next The subagent system has grown rapidly. Continue with: diff --git a/part9-custom-models.md b/part9-custom-models.md index 23cc799..6eea2a0 100644 --- a/part9-custom-models.md +++ b/part9-custom-models.md @@ -1,8 +1,8 @@ # Part 9: Custom Model Providers (Use Any Model You Want) -*Hermes supports any OpenAI-compatible API, plus first-class native adapters for Nous Portal, Anthropic, OpenAI/Codex, OpenRouter, AWS Bedrock, Azure AI Foundry, Google Gemini, Gemini OAuth, LM Studio, xAI, Xiaomi MiMo, Kimi/Moonshot, z.ai/GLM, MiniMax, Arcee, GMI Cloud, Tencent TokenHub, Hugging Face, Cerebras, Groq, Fireworks, Vercel AI Gateway, Ollama, and provider plugins. This is the May 25, 2026 cheat sheet.* +*Hermes supports any OpenAI-compatible API, plus first-class native adapters for Nous Portal, Anthropic, OpenAI/Codex, OpenRouter, AWS Bedrock, Azure AI Foundry, Google Gemini, Google Vertex AI, LM Studio, xAI, Xiaomi MiMo, Kimi/Moonshot, z.ai/GLM, MiniMax, Arcee, GMI Cloud, Tencent TokenHub, Hugging Face, Cerebras, Groq, Fireworks, Vercel AI Gateway, Ollama, MoA virtual models, and provider plugins. This is the July 1, 2026 cheat sheet.* -> **What's new since the v0.13 guide refresh** — v0.14 adds SuperGrok OAuth with Grok 4.3 at 1M context, `hermes proxy` for OpenAI-compatible access to OAuth-backed Claude/ChatGPT/SuperGrok subscriptions, first-class `x_search`, cross-session 1-hour Claude prompt caching, OpenRouter Pareto Code routing, and provider-agnostic `computer_use` support. +> **What's new since the v0.14 guide refresh** — v0.17 puts Cursor's **Composer** (`grok-composer-2.5-fast`, 200K context) in the xAI OAuth picker; v0.18 adds a first-class **Google Vertex AI** provider (auto-minted, auto-refreshed OAuth2 tokens from a service account — no static key, no mid-session expiry) and makes every **Mixture-of-Agents preset a selectable model** under a `moa` provider ([Part 26](./part26-moa-verification.md)). **Breaking:** the Gemini-CLI OAuth providers (`google-gemini-cli`, `google-antigravity`) were **removed in v0.18** — migrate to a `GEMINI_API_KEY` or Vertex AI. --- @@ -24,7 +24,8 @@ As of v0.14.0 (May 2026), Hermes ships **native adapters** for a large provider | **Kimi / Moonshot** | Yes | 200K+ context, great for LightRAG entity extraction (see [Part 3](./README.md#part-3-lightrag--graph-rag-that-actually-works)) | | **z.ai / GLM** | Yes | Strong open-weight tool-use models; good cheap fallback for planning/exploration | | **Google Gemini (direct)** | Yes | 1M context; native prompt caching on Pro; image/video-capable model routing | -| **Google Gemini (OAuth)** | Yes | Browser PKCE login via `hermes model`; free tier supported; no external `gemini` install | +| **Google Vertex AI** | Yes | Gemini via your GCP service account / ADC; short-lived OAuth2 tokens auto-minted and refreshed | +| **MoA (virtual)** | Yes | Every Mixture-of-Agents preset is a pickable model — see [Part 26](./part26-moa-verification.md) | | **MiniMax** | Yes | API key or OAuth; native streaming and TTS | | **GMI Cloud** | Yes | Hosted open models behind a native provider | | **Tencent TokenHub** | Yes | Tencent model routing through TokenHub aliases | @@ -72,7 +73,8 @@ The exact "best model" moves weekly, so treat this as a routing posture rather t | Default coding / refactors | Anthropic Sonnet 5, Claude Code, or Codex OAuth | Best reliability for patch-heavy work; Codex OAuth avoids API-key churn | | Deep reasoning / high stakes | GPT-5.5 reasoning or Anthropic Opus 4.7 | Use explicitly; do not make it the default for cron/bulk tasks | | Long-context repo or document reads | Gemini 3.1 Pro/Flash, Grok 4.3, or OpenRouter equivalent | Huge window, cheap enough for map/reduce, video, and summarization | -| Cheap daily driver | Gemini OAuth + Kimi K2.6 + z.ai/GLM | Good quality/cost mix, especially with auxiliary routing | +| Cheap daily driver | Gemini Flash (API key) + Kimi K2.6 + z.ai/GLM | Good quality/cost mix, especially with auxiliary routing | +| Committee for hard calls | A `moa` preset of 2–3 frontier models | Visible multi-model deliberation; ~N× cost, use sparingly ([Part 26](./part26-moa-verification.md)) | | Enterprise / VPC / compliance | AWS Bedrock or Azure AI Foundry | IAM/Azure auth, guardrails, private deployments, audit controls | | Local/privacy/offline | LM Studio or Ollama | No cloud egress; great for extraction, embeddings, and drafts | | Ultra-fast interactive turns | Cerebras or Groq | Very high tokens/sec; useful for classification and short-form chat | @@ -93,16 +95,27 @@ hermes model If you're on a paid subscription, the setup also offers to enable the [Tool Gateway](./part13-tool-gateway.md) — web search, image gen, TTS, and browser automation through your subscription, no extra keys needed. -### Gemini OAuth — Free-Tier Friendly +### Google: API Key or Vertex AI (Gemini OAuth Is Gone) -If you have a Google account, skip the API key entirely and sign in from Hermes: +> **Migration note (v0.18):** the Gemini-CLI OAuth providers (`google-gemini-cli`, `google-antigravity`) were **removed**. If your config still points at them, model selection will fail after upgrading. Pick one of the two supported paths below. -```bash -hermes model -# Pick "Google Gemini (OAuth)" → complete the browser PKCE flow +**Path 1 — API key (simplest).** Set `GEMINI_API_KEY` (or `GOOGLE_API_KEY`) and use the native Google Gemini provider. Free-tier keys work. + +**Path 2 — Vertex AI (GCP shops).** New in v0.18: a first-class Vertex provider over Vertex's OpenAI-compatible endpoint. Vertex has no static API key — every request needs a short-lived (~1h) OAuth2 token minted from a service-account JSON or Application Default Credentials. Hermes mints and auto-refreshes these for you, so sessions no longer die mid-run on token expiry: + +```yaml +providers: + vertex: + project_id: ${GOOGLE_CLOUD_PROJECT} + location: us-central1 + credentials_json: ${GOOGLE_APPLICATION_CREDENTIALS} # or rely on ADC ``` -Tokens are stored under `~/.hermes/auth/google_oauth.json` with 0600 permissions and automatic refresh. On headless SSH boxes, Hermes falls back to paste-mode auth. +Use Vertex when your org already routes Gemini through Google Cloud (IAM, quotas, audit); use the plain API key everywhere else. + +### Cursor's Composer via xAI OAuth + +v0.17 put `grok-composer-2.5-fast` — the fast coding model behind Cursor — in the xAI OAuth model picker with its full 200K context. If you have an xAI Grok subscription, you can point Hermes at Composer directly over OAuth, no separate API key: your Grok plan, Hermes' agent loop, Composer's coding speed. It's a strong pick for the fast-coding lane in your routing table. ### AWS Bedrock and Azure AI Foundry — Enterprise Routing Without Proxy Glue @@ -296,8 +309,9 @@ Use these as opinionated defaults, then tune with [Part 20's cost-routing playbo | Task | First choice | Fallback (cheaper) | Fallback (fastest) | |------|--------------|--------------------|--------------------| -| Daily conversation | Anthropic Sonnet 5 | Gemini OAuth or z.ai/GLM | Cerebras Qwen 3 | -| Coding delegation | Claude Code / Codex OAuth | OpenCode + Kimi K2.6 | OpenCode + Cerebras | +| Daily conversation | Anthropic Sonnet 5 | Gemini Flash or z.ai/GLM | Cerebras Qwen 3 | +| Coding delegation | Claude Code / Codex OAuth | OpenCode + Kimi K2.6 | xAI Composer 2.5 (OAuth) | +| High-stakes judgment calls | `moa` council preset ([Part 26](./part26-moa-verification.md)) | GPT-5.5 reasoning | — | | Long-context reads (>200K) | Gemini 3.1 Pro | Gemini Flash | — | | Classification / triage | Gemini Flash | Cerebras Qwen3 32B | Arcee AFM-4.5 | | Reasoning (math, planning) | GPT-5.5 reasoning | Anthropic Opus 4.7 | z.ai/GLM |