From 0c865f2231653485325c60ce2f185ee6fcd87f26 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 17 Jul 2026 01:27:04 +0000 Subject: [PATCH 1/3] Modernize guide to v0.18.2 era: add Part 27 Power Secrets + July 2026 research updates Co-Authored-By: Rob --- CHANGELOG.md | 24 ++++ CONTRIBUTING.md | 2 +- ECOSYSTEM.md | 17 +++ README.md | 32 +++-- ROADMAP.md | 1 + part11-gateway-recovery.md | 23 +++ part14-fast-mode-watchers.md | 13 ++ part15-new-platforms.md | 2 + part16-backup-debug.md | 17 +++ part17-mcp-servers.md | 26 ++++ part18-coding-agents.md | 17 ++- part19-security-playbook.md | 40 ++++++ part20-observability.md | 44 ++++++ part21-remote-sandboxes.md | 2 + part23-tenacity-stack.md | 10 ++ part24-desktop-app.md | 8 ++ part25-nvidia-local.md | 18 ++- part26-moa-verification.md | 7 +- part27-power-secrets.md | 265 +++++++++++++++++++++++++++++++++++ part6-context-compression.md | 21 +++ part7-memory-system.md | 32 +++++ part8-subagent-patterns.md | 25 ++++ part9-custom-models.md | 38 +++++ 23 files changed, 665 insertions(+), 19 deletions(-) create mode 100644 part27-power-secrets.md diff --git a/CHANGELOG.md b/CHANGELOG.md index c744262..b4f962b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,30 @@ Dated list of meaningful guide updates. Roughly [Keep a Changelog](https://keepachangelog.com) flavored. +## 2026-07-17 — The Power Secrets modernization (v0.18.2 era) + +### Added +- **Part 27 — Power Secrets**: a new field manual distilling the official Wingtips series (#1–#22) and the highest-signal July community research into 25 verified non-obvious mechanics — memory/USER snapshot semantics, compression internals (`protect_last_n`, cheap auxiliary compression, compaction's structured brief), the messaging-gateway token tax, credential pools vs fallbacks and their cache-miss cost, model-switch cache resets, profiles-as-rooms (and the filesystem-isolation caveat), Kanban's `toolsets` and workspace traps, `state.db`/disk hygiene, session export with `--redact`, `/steer`//`/queue`//`/busy` timing semantics, supervised self-improvement gates, and a printable one-page cheat sheet. +- Part 17: **MCP Security — July 2026 state of play**: CVE table (LiteLLM CVE-2026-30623, Windsurf CVE-2026-30615, Cursor MCPoison CVE-2025-54136, MCP Inspector CVE-2025-49596, LibreChat CVE-2026-22252), npm-impersonator warning, and a 7-point hardening checklist. +- Part 19: the **seven-layer security mental model** mapped onto real Hermes primitives, the **action-ontology** containment pattern (host = brain, credential-less container = hands, typed action API), and **external spend kernels** for money-touching agents (Custodian / `CommercePolicy` / Latch / payguard patterns). +- Part 20: **the gateway token tax** (CLI ~6–8k vs messaging ~15–20k tokens/turn), **benchmark-the-stack-not-the-model** (WolfBench Codex-vs-Hermes data, Terra-vs-Sol economics, busywork anti-pattern, free-tier warning), and a **Langfuse v4 / OTEL Collector** section (local model pricing, double-counted spans, root-observation default change). +- Part 8: the **seven-rung agent ladder** (basic tools → MCP → pipelines → parallel → routed specialists → human-in-the-loop → dynamic spawning) and a one-agent-vs-profiles decision guide. +- Part 9: **mid-July model landscape** (Kimi K3 day-one support incl. the Kimi-Direct update requirement, GPT Sol/Terra/Luna routing posture, Anthropic-subscription limitation, local reference points) and **credential pools**. +- Part 14: `/steer` / `/queue` / `/busy` timing semantics and the **segmented tool batch dispatch** (safe-tool parallelism) behavior. +- Part 24: **Hermes Cloud** third connection mode (labelled preview) and the remote-backend "code runs on the server" gotcha. +- Part 25: background **computer use** on macOS (`hermes computer-use install`), current local model reference points, and a local KV-cache note. +- Parts 6/7: compression levers and compaction internals; the memory **snapshot rule**, `/memory` + `/skills` approval gates, and a memory-stack comparison table (native vs LightRAG vs Mem0 vs skills). +- Part 21: 10-second sandbox decision guide (Daytona / Modal / E2B / Vercel / OpenShell). +- ECOSYSTEM: "Community projects on the radar" (Scarf, zhc-fabric, Sibyl, Latch, payguard, hermes-sonus, OpenKnowledge, HOODRADAR, Hermes Pong, Camofox + its context-tax warning). + +### Changed +- Version currency: badges, intro, and "What's New" now target **v0.18.2 (v2026.7.7.2)** with the v0.18.1 patch-rollup note, the WhatsApp/Baileys fix (Part 15 Docker-tag guidance), and an explicit "main → v0.19.0, untagged = experimental" framing. +- Part 18 agent-lane updates: Claude Code 2.1.20x, Codex 0.144.x stable pin (avoid 0.145 alpha unattended), OpenCode MCP resources + provider change, the Hermes Pong subscription workaround, and Teknium's "keep Hermes in the loop" guidance. +- Parts 11/16/23 operational updates: `loginctl enable-linger` for headless gateways, real disk-growth hot spots (`state-snapshots/`, cron output, piped stdout), `hermes sessions prune`/`export --redact`, Kanban toolset opt-in + absolute `dir:` workspaces, and overnight/GPU-FIFO board shapes. +- README: 28-part navigation, new "power secrets" reading path, mid-July status section. +- Community claims are labelled as such throughout; all new config snippets stay within the real v0.18 schema (no invented keys). +- Note: `README-zh.md` / `README-ja.md` remain synced to the 2026-07-03 state; a translation sync is queued. + ## 2026-07-03 — Accuracy & consistency maintenance pass ### Fixed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a023350..85362f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,7 @@ The [README Repo Map](./README.md#repo-map) is the canonical, row-by-row descrip ├── README.md (+ README-zh.md, README-ja.md) ├── CHANGELOG.md · ROADMAP.md · ECOSYSTEM.md · CODE_OF_CONDUCT.md · LICENSE ├── CONTRIBUTING.md ← you are here -├── part1-setup.md … part26-moa-verification.md # the 27-part guide (README + 26 part files) +├── part1-setup.md … part27-power-secrets.md # the 28-part guide (README + 27 part files) ├── skills/ # 13 installable SKILL.md files under dev/, ops/, security/ ├── templates/ │ ├── config/{minimum,telegram-bot,production,cost-optimized,security-hardened}.yaml diff --git a/ECOSYSTEM.md b/ECOSYSTEM.md index 3164113..edd4477 100644 --- a/ECOSYSTEM.md +++ b/ECOSYSTEM.md @@ -46,6 +46,23 @@ See [Part 22](./part22-latest-power-moves.md#4-use-plugins-for-integrations-not- --- +## Community projects on the radar (July 2026) + +*Community-maintained; audit before installing — anything that reads sessions or executes code deserves a code review first ([Part 19](./part19-security-playbook.md)).* + +- **Scarf** — swarm orchestration for Hermes agents (topologies, consensus, shared state, cost tracking; MIT) +- **zhc-fabric** — distributed multi-node control plane: mesh networking + mTLS + hardware-attested identity for Hermes fleets +- **Sibyl Memory (Hermes Atlas)** — alternative memory plugin advertising strong LongMemEval numbers; verify vendor benchmarks on your own workload +- **Latch** — payments/spend-control layer for agents (see the spend-kernel pattern in [Part 19](./part19-security-playbook.md#external-spend-kernels-when-the-agent-touches-money)) +- **payguard** — self-hostable payment approval firewall: agent requests, human approves +- **hermes-sonus** — voice for Hermes on Windows/macOS (hotkey push-to-talk, TTS replies) +- **OpenKnowledge** — Wikipedia-style knowledge dumps distilled for agent consumption +- **HOODRADAR** — example of a Hermes-built production app (real-time crime mapping); useful as an architecture reference +- **Hermes Pong** — orchestrate a Claude Code terminal from Hermes (the Anthropic-subscription workaround; see [Part 18](./part18-coding-agents.md)) +- **Camofox** — anti-detect browsing for agents. **Warning:** its `AGENTS.md` injects ~22k chars into every prompt if it's in your cwd ([Part 6](./part6-context-compression.md#the-context-you-didnt-order-third-party-rule-files)) + +--- + ## Coding-agent integrations - [Claude Code](https://docs.claude.com/en/docs/claude-code) — `claude -p` + ACP; best unattended PR lane with Sonnet 5 / Opus 4.7 diff --git a/README.md b/README.md index 9109d6e..58eb01a 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,15 @@

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) -[![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) +[![Hermes](https://img.shields.io/badge/Hermes-v0.18.2%20%282026.7.7.2%29-9146FF)](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.7.7.2) +[![Last updated](https://img.shields.io/badge/Last%20updated-2026--07--17-brightgreen)](./CHANGELOG.md) +[![Parts](https://img.shields.io/badge/parts-28-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.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. +> **Current through Hermes Agent v0.18.2 (v2026.7.7.2) — the "Judgment" line** · **28 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, gateway **scale-to-zero** for teams — and now a full **[Power Secrets field manual](./part27-power-secrets.md)** distilled from the official Wingtips series and July's best community research. **Bring any model** — this guide is about the *harness*, not the weights. > > Other languages: [中文](./README-zh.md) · [日本語](./README-ja.md) @@ -23,10 +23,10 @@ Every part you need to go from fresh install to a production Hermes deployment 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.

- Docs plus runnable artifacts — 27 guide parts, 13 installable skills, 5 config templates, 4 reference architectures, one-command VPS bootstrap, 8-question config wizard + Docs plus runnable artifacts — 28 guide parts, 13 installable skills, 5 config templates, 4 reference architectures, one-command VPS bootstrap, 8-question config wizard

-*By Terp — [Terp AI Labs](https://x.com/OnlyTerp)* · Last updated **July 1, 2026** · [CHANGELOG](./CHANGELOG.md) · [ROADMAP](./ROADMAP.md) · [ECOSYSTEM](./ECOSYSTEM.md) +*By Terp — [Terp AI Labs](https://x.com/OnlyTerp)* · Last updated **July 17, 2026** · [CHANGELOG](./CHANGELOG.md) · [ROADMAP](./ROADMAP.md) · [ECOSYSTEM](./ECOSYSTEM.md) --- @@ -80,7 +80,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` … `part26-*.md` | The 27-part guide itself (now incl. MoA + verification, Desktop App, NVIDIA / local hardware). | +| README + `part1-*.md` … `part27-*.md` | The 28-part guide itself (now incl. MoA + verification, Desktop App, NVIDIA / local hardware, and the Power Secrets field manual). | --- @@ -117,10 +117,10 @@ Full set of diagrams: [`diagrams/architecture.md`](./diagrams/architecture.md). ## Pick Your Path

- Pick your path — ten curated reading paths through the guide's 27 parts, from a 10-minute setup to production hardening, local GPU, and MoA verification + Pick your path — curated reading paths through the guide's 28 parts, from a 10-minute setup to production hardening, local GPU, and MoA verification

-This guide grew to 27 parts because *Hermes grew*. Every part lives in its own file (`part1-setup.md` … `part26-moa-verification.md`); this README keeps a short summary of Parts 1–5 (plus the full SOUL.md personality section) and links out. You don't have to read them all — pick the shortest path to what you need: +This guide grew to 28 parts because *Hermes grew*. Every part lives in its own file (`part1-setup.md` … `part27-power-secrets.md`); this README keeps a short summary of Parts 1–5 (plus the full SOUL.md personality section) and links out. 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](./part1-setup.md) → [Part 12: Web Dashboard](./part12-web-dashboard.md) and point-and-click the rest. @@ -152,6 +152,9 @@ Skip the terminal: install the [desktop app](./part24-desktop-app.md) and let fi ### 🧑‍⚖️ "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`. +### ⚡ "I've been running Hermes for months — give me the stuff I don't know" +[Part 27: Power Secrets](./part27-power-secrets.md) — 25 non-obvious mechanics: the memory snapshot rule, the gateway token tax, credential-pool cache misses, the Kanban traps, profiles-as-rooms, and a printable one-page cheat sheet. + --- ## What's New (July 2026) @@ -162,7 +165,15 @@ Skip the terminal: install the [desktop app](./part24-desktop-app.md) and let fi 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) +### Mid-July status — v0.18.1 / v0.18.2 and what's coming + +- **v0.18.1 (`v2026.7.7`)** is a big *patch rollup* on the Judgment line — fixes and small features, not a curated feature release. +- **v0.18.2 (`v2026.7.7.2`)** is the current tagged release. Headline fix: the **WhatsApp personal (Web/QR) adapter** broken by an upstream Baileys change ([Part 15](./part15-new-platforms.md)). If you pin Docker tags, move to `v2026.7.7.2` or newer. +- **`main` is marching toward v0.19.0** — features you see discussed but not tagged (e.g. the **Hermes Cloud** connection mode, background **computer use**) should be treated as **experimental/preview** until they land in a release. Where this guide covers them ([Part 24](./part24-desktop-app.md#7b-hermes-cloud--the-third-connection-mode-preview), [Part 25](./part25-nvidia-local.md#9-background-computer-use-macos)) they're labelled as such. +- **Model landscape moved too**: day-one **Kimi K3** support, the GPT **Sol / Terra / Luna** family, and a hard fact worth knowing — Anthropic *subscriptions* don't work natively (API keys do). Current routing posture: [Part 9](./part9-custom-models.md#the-mid-july-2026-model-landscape). +- **New: [Part 27 — Power Secrets](./part27-power-secrets.md)**, the distilled field manual from the official Wingtips series (#1–#22) and July's community research: context/cache mechanics, cost traps, profile architecture, and operational gotchas — each verified against the real schema. + +### v0.18.0 — "Judgment" - **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). @@ -239,6 +250,7 @@ Hermes is now optimized for always-on **local** use on **NVIDIA RTX PCs, RTX PRO 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 +28. [Power Secrets](./part27-power-secrets.md) — 25 verified non-obvious mechanics: memory snapshots, the gateway token tax, cache economics, credential pools, Kanban traps, profiles-as-rooms, and a printable cheat sheet --- diff --git a/ROADMAP.md b/ROADMAP.md index 5ed7688..46836d5 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -23,6 +23,7 @@ What's landing next. PRs welcome. ## Done (recent) +- ✅ 2026-07-17 — Power Secrets modernization: new Part 27 (Wingtips #1–#22 field manual + cheat sheet), v0.18.2 / `v2026.7.7.2` currency (Baileys fix, patch-rollup notes), MCP CVE table + checklist, seven-layer security model + spend kernels + action ontology, gateway token tax + stack benchmarking + Langfuse v4/OTEL, seven-rung agent ladder, Kimi K3 / Sol-Terra-Luna routing, Kanban traps, Hermes Cloud (preview), computer use, ecosystem radar - ✅ 2026-07-03 — Cross-link checker: anchor checking added (CI now fails on dead relative `./partN-foo.md` links *and* dead heading anchors; markdown-link-check shipped 2026-04-17) - ✅ 2026-07-01 — v0.17 "Reach" + v0.18 "Judgment" refresh: Part 26 MoA / verification / `/learn` + `/journey`, iMessage via Photon Spectrum, WhatsApp Business Cloud, Vertex AI provider, background subagent fan-out, desktop Projects + multi-terminal, gateway scale-to-zero, 25+ platform count, 27-part TOC - ✅ 2026-06-17 — v0.16 "Surface" refresh: Part 24 Hermes Desktop App, Part 25 NVIDIA & local hardware (DGX Spark / OpenShell / NemoClaw), new banner graphics, `/undo` + default-interface + fuzzy-picker power moves, native Windows installer, `hermes portal` Quick Setup, and a trim of stale per-version model tables to a model-agnostic section diff --git a/part11-gateway-recovery.md b/part11-gateway-recovery.md index 648e235..494b826 100644 --- a/part11-gateway-recovery.md +++ b/part11-gateway-recovery.md @@ -88,6 +88,19 @@ find ~/.hermes/logs -type f -mtime +7 -delete du -sh ~/.hermes/skills/research/lightrag/data/ ``` +**Where the disk actually goes** (it's usually not logs). The three unbounded growers reported in the wild: **`state-snapshots/`** (750MB+ observed), **per-run cron output** (1500+ files piling up), and **host-piped stdout**. Check those first: + +```bash +du -sh ~/.hermes/state-snapshots ~/.hermes/cron* 2>/dev/null +``` + +And keep `~/.hermes/state.db` lean — auto-prune is **off by default**. Hundreds of sessions is ~10–15MB; expect drag near ~384MB / ~1000 sessions: + +```bash +hermes sessions prune # removes ended sessions only, never active +# or: sessions.auto_prune: true in config.yaml +``` + ### 5. Crash Loop **Symptoms:** Gateway starts, crashes immediately, repeats. @@ -128,6 +141,16 @@ journalctl -u hermes -f Or let Hermes do it for you — `hermes gateway install` (see [Part 4](./part4-telegram-setup.md)) generates and enables a user-level unit without any manual file copying. +> **Headless VPS gotcha — the gateway that never survives a reboot.** A *user-level* systemd unit is killed when your login session ends, and on a headless box there may never be a login session after reboot. Enable lingering (or install system-wide): +> +> ```bash +> hermes gateway install +> sudo loginctl enable-linger $USER +> # or: sudo hermes gateway install --system +> ``` +> +> If your gateway is mysteriously down every time you SSH in after a reboot, this is why. + Either way, `Restart=on-failure` + `RestartSec=5` means a crashed gateway is back within seconds. ## Auto-Recovery (Cron Fallback) diff --git a/part14-fast-mode-watchers.md b/part14-fast-mode-watchers.md index a934aa5..709f885 100644 --- a/part14-fast-mode-watchers.md +++ b/part14-fast-mode-watchers.md @@ -71,6 +71,19 @@ Best practice: This is the practical replacement for repeatedly interrupting and restating the whole task. +**The timing semantics people miss:** `/steer ` is delivered **after the current tool call completes**, inside the same turn — it is *not* a new turn and doesn't reset anything. `/queue` (alias `/q`) stages the next prompt without touching the current run at all. And `/busy` configures what a plain **Enter** does while the agent is working — queue, steer, or interrupt — so your muscle memory stops accidentally killing 20-minute runs. + +--- + +## Segmented Tool Batch Dispatch (Safe-Tool Parallelism) + +A mid-July quality-of-life change to how tool batches execute: **safe operations (read / search / fetch / list / check) now run in parallel**, and one unsafe call in a batch no longer serializes the whole batch — dependent or risky calls wait, results merge in order. In practice: five independent 2-second lookups complete in ~2 seconds of wall time instead of ~10. + +You don't configure anything — but you can *write for it*: + +- Research, content, and file-analysis workloads benefit most — phrase multi-source questions so the agent can fan out reads ("check A, B, and C, then compare") instead of forcing sequential steps. +- Anything mutating (writes, sends, deploys) still serializes and still respects the approval layer ([Part 19](./part19-security-playbook.md)) — parallelism never bypasses approvals. + --- ## Background Process Monitoring (`watch_patterns`) diff --git a/part15-new-platforms.md b/part15-new-platforms.md index 2ff4ed3..8477d1f 100644 --- a/part15-new-platforms.md +++ b/part15-new-platforms.md @@ -70,6 +70,8 @@ Operationally: 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. +> **If the personal (Web) adapter suddenly broke for you in July 2026:** an upstream Baileys dependency change broke QR-login connections. Fixed in **v0.18.2 (`v2026.7.7.2`)** — update Hermes (and rebuild if you pin a Docker tag older than `v2026.7.7.2`), re-scan the QR, done. + ### 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. diff --git a/part16-backup-debug.md b/part16-backup-debug.md index fe7a4d5..f11c759 100644 --- a/part16-backup-debug.md +++ b/part16-backup-debug.md @@ -136,6 +136,23 @@ sessions.db --- +## `hermes sessions export` — Share a Session Without Sharing Your Keys + +Backups are for *you*; exports are for *everyone else*. Turn any session into a document: + +```bash +hermes sessions export --format md # or qmd | html +hermes sessions export --format md --session-id --redact +``` + +- md/qmd exports land in `~/.hermes/session-exports` with a manifest; html renders a shareable transcript. +- **Always `--redact` before sharing** — it scrubs keys and tokens from the transcript. A raw session log is a credential-disclosure incident waiting to happen ([Part 19](./part19-security-playbook.md)). +- Great for bug reports, blog write-ups, and "how did the agent do this?" postmortems. + +While you're in session-hygiene mode: `hermes sessions prune` clears ended sessions from `state.db` (auto-prune is off by default — see [Part 11](./part11-gateway-recovery.md) for the size thresholds). + +--- + ## `/debug` and `hermes debug share` ### The New Diagnostic Flow diff --git a/part17-mcp-servers.md b/part17-mcp-servers.md index 5120255..a66e481 100644 --- a/part17-mcp-servers.md +++ b/part17-mcp-servers.md @@ -130,6 +130,32 @@ For the full catalog, see the [MCP Registry](https://registry.modelcontextprotoc --- +## MCP Security: July 2026 State of Play + +MCP is no longer a theoretical attack surface — the first half of 2026 produced a real CVE trail, all variations on one theme: **MCP configs and manifests are executable trust**. + +| CVE | What | Lesson for Hermes users | +|-----|------|------------------------| +| CVE-2026-30623 | LiteLLM authenticated RCE via malicious MCP JSON (patched ≥ 1.83.7) | If you proxy Hermes through LiteLLM, patch it — an MCP *config* was the payload | +| CVE-2026-30615 | Windsurf: writable `mcp.json` → prompt injection → code execution | Anything that can *write* your MCP config owns your agent | +| CVE-2025-54136 | Cursor "MCPoison": approve once, config silently swapped later (fixed 1.3) | Re-approval must trigger on *change*, not just first add | +| CVE-2025-49596 | MCP Inspector RCE (browser → localhost, fixed 0.14.1) | Dev tools listening on localhost are reachable from any web page you visit | +| CVE-2026-22252 | LibreChat MCP `require()` injection via server config | Same class, different host — the pattern is universal | + +The checklist that follows from it: + +1. **Pin every MCP package to an exact version** — no `latest`, no floating ranges. Re-audit and re-approve when a server's version or hash changes. +2. **Treat `mcp.json` / MCP blocks in cloned repos as untrusted input.** Never launch Hermes with MCP servers from a repo you haven't reviewed — that's the MCPoison delivery vehicle. +3. **Watch for npm impersonators.** Fake `mem0-mcp-server`-style packages ship info-stealers under trusted names; install only from the vendor's documented source, and check publish dates + download counts. +4. **Never expose MCP Inspector (or any MCP dev tool) beyond localhost**, and keep it patched — browser-to-localhost is a real attack path. +5. **Separate tokens per server, minimal scopes** — an MCP server compromise should burn one narrow credential, not your account. +6. **Strip environment leakage**: pass only the env vars each stdio server needs, never your full shell environment. +7. **Add OSV/CVE monitoring** for the MCP packages you run (a weekly cron works — see the security-hygiene cron in [Part 19](./part19-security-playbook.md#periodic-security-hygiene)). + +`tools.include` scoping, isolation backends, and the broader trust model live in [Part 19, Layer 5](./part19-security-playbook.md#layer-5-mcp-and-plugin-trust). + +--- + ## Writing Your Own MCP Server (Fast) A minimal Node MCP server is ~30 lines. Python is similar. Point Hermes at it like any other stdio server. diff --git a/part18-coding-agents.md b/part18-coding-agents.md index 2ff018e..96b24b1 100644 --- a/part18-coding-agents.md +++ b/part18-coding-agents.md @@ -151,13 +151,18 @@ The same binding works for Codex, Gemini CLI, OpenCode, and any ACP-compatible c --- -## Agent Tooling Updates (May 25, 2026) +## Agent Tooling Updates (July 2026) -- **Claude Code Week 20+**: agent view, `/goal`, and faster Opus 4.7 make it the best premium worker lane for high-stakes PRs. -- **Codex v0.133+**: goals are enabled by default; point it at `hermes proxy` when you want ChatGPT/Codex OAuth without another API key. -- **Gemini CLI v0.43**: better surgical edit steering, session export/import, and headless OAuth fixes make it safer as a repo-scale reader. -- **Zed ACP Registry**: v0.14 exposes Hermes through `uvx`/ACP so Zed and other ACP-aware editors can drive Hermes directly. -- **Aider/Cline/Continue**: all benefit from `hermes proxy` because they only need an OpenAI-compatible base URL. +- **Claude Code 2.1.20x**: rapid-fire patch series — extended `/doctor` diagnostics, a browser interface rolling out, subagent text-forwarding fixes, and (notably) Claude Code available *as a plugin inside Codex*. Still the best premium worker lane for high-stakes PRs. +- **Codex 0.144.x (stable)**: pin production lanes here — **avoid the 0.145 alpha line for unattended work**. Point it at `hermes proxy` when you want ChatGPT/Codex OAuth without another API key. +- **Gemini**: the Gemini-CLI OAuth providers were **removed from Hermes in v0.18** — use a `GEMINI_API_KEY` or Vertex AI ([Part 9](./part9-custom-models.md)); the standalone CLI still works as a delegated reader lane. +- **OpenCode**: now exposes MCP resources/prompts and dropped its OpenCode-Zen provider mid-July — re-check your model config after upgrading. Useful with Kimi K3 / GLM budget lanes. +- **Zed ACP Registry / Aider / Cline / Continue**: unchanged posture — ACP for editors, `hermes proxy` for anything that just needs an OpenAI-compatible base URL. + +Two July-specific notes worth their own lines: + +- **Anthropic subscriptions don't work natively in Hermes** (API keys do). If all you have is a Claude subscription, the community workaround is orchestrating a Claude Code terminal from Hermes — e.g. the *Hermes Pong* pattern — which effectively lends Hermes the subscription's brain through this part's worker-lane machinery. Community-maintained; treat with the same caution as any third-party skill. +- **Keep Hermes in the loop** (official guidance from Teknium): don't invert the relationship and make another agent the orchestrator with Hermes as a dumb launcher. Routing through a second brain breaks Hermes's trace — memory stops accumulating, `/learn` sees nothing, plugins go blind. Models run *inside* Hermes; coding CLIs are *workers*. --- diff --git a/part19-security-playbook.md b/part19-security-playbook.md index 678a1f0..9430408 100644 --- a/part19-security-playbook.md +++ b/part19-security-playbook.md @@ -43,6 +43,24 @@ If your agent ingests content from surfaces you don't control (the open web, inb --- +## The Seven-Layer Mental Model + +The community teaching frame that stuck in July 2026 maps cleanly onto this part — use it as your audit checklist: + +| # | Layer | Where in this part / the guide | +|---|-------|-------------------------------| +| 1 | Trust & default-deny | Layer 1 below (allowlists, pairing) | +| 2 | Human approvals at decision boundaries | Layer 2 below — gate **send / publish / deploy / spend / system-of-record writes**, not every read | +| 3 | Containment | OS-level isolation above; [Part 21](./part21-remote-sandboxes.md) | +| 4 | MCP environment hygiene | Layer 5 below + [Part 17's CVE checklist](./part17-mcp-servers.md#mcp-security-july-2026-state-of-play) | +| 5 | Prompt-injection scanning | Layer 6 below | +| 6 | Network / SSRF controls | Isolation-backend egress policy (Layer 4) + [Part 16](./part16-backup-debug.md) hardening notes | +| 7 | Pre-execution command scanning | tirith (Layer 2 options) | + +Two rules of thumb that fall out of it: put approvals at **decision boundaries** (the irreversible verbs), not on every action — approval fatigue is itself a vulnerability; and remember **profiles are not a security boundary** — every profile runs as the same OS user, so "my private profile" and "my public bot profile" share a filesystem unless you add Docker/SSH/ACLs. + +--- + ## Layer 1: User Authorization — Who Can Talk to the Agent The first gate is *who is even allowed to reach the agent*. On every messaging gateway, Hermes is **default-deny**: if no allowlist is configured and `GATEWAY_ALLOW_ALL_USERS` is unset, all users are rejected. @@ -272,6 +290,28 @@ Aonan Guan's writeup has the exploit chain in full. Patch, don't just read. --- +## The Action-Ontology Pattern — Brain in One Place, Hands in Another + +The strongest community production architecture of the summer, compatible with everything above: + +1. **Host = brain.** Hermes runs on the host (or a trusted VM) with credentials — but its *tools* can't touch production directly. +2. **Container = hands, with no credentials.** Execution happens in a Docker container on an **internal-only network** whose sole reachable endpoint is… +3. **…an action API you wrote.** Every real-world side effect (send, post, pay, deploy) is a named, typed endpoint with validation, rate limits, and logging — an explicit **ontology of allowed actions**. A compromised agent can only call the actions you defined, at the rates you defined, with the arguments you validate. + +This is the same philosophy as Layer 4's isolation backends, pushed to its conclusion: don't enumerate what the agent *can't* do — enumerate what it *can*. + +## External Spend Kernels (When the Agent Touches Money) + +If your agent can spend, the policy engine must live **outside the agent process** — an in-context "please don't overspend" instruction is a suggestion, not a control. The pattern showing up across HAAB (Hermes-as-a-Business) builds: + +- **A payment policy kernel** that enforces per-transaction caps, daily budgets, and merchant allowlists *before* any payment API is reachable (the Custodian pattern; Latch and payguard are community implementations of the same idea). +- **Owner-approval gates on the transaction boundary** — the agent drafts, a human clicks (the Mom-n-Pop Skills pattern: quotes, invoices, campaigns all staged for approval). +- **A commerce policy object** for selling agents — price floors, counter-offer rules, spend limits — evaluated by code, not by the model (the CashFromChaos `CommercePolicy` pattern). + +Same shape at every scale: the model proposes, a kernel disposes. Combine with Layer 2's `approvals.mode: manual` for anything the kernel can't express. + +--- + ## Diagnostic Bundle Safety Logs under `~/.hermes/logs/` pass through the secret redactor when `security.redact_secrets` is on (the default). Before sharing *any* debug output or log bundle with someone else: diff --git a/part20-observability.md b/part20-observability.md index 98a4505..95d9d87 100644 --- a/part20-observability.md +++ b/part20-observability.md @@ -370,6 +370,50 @@ input length. --- +## The Gateway Token Tax: CLI for Heavy Work, Messaging for Control + +The single biggest hidden cost in a chat-first Hermes setup, measured repeatedly by the community in July 2026: **the messaging gateways carry ~15–20k tokens of tool definitions per turn**, while the CLI carries **~6–8k** for the same work. That's 2–3× the fixed overhead on *every* turn — before you've said anything. (One user burned 121k tokens just *wiring Telegram to the Desktop app*.) + +The fix isn't to abandon your phone — it's a division of labor: + +| Surface | Use for | Why | +|---------|---------|-----| +| **CLI / TUI** | Long coding runs, research, bulk work | Lowest per-turn overhead, best cache behavior | +| **Kanban** ([Part 23](./part23-tenacity-stack.md)) | Anything that should survive restarts | Board persists; workers run lean | +| **Telegram / Discord / Slack** | Kickoff, steering, receiving results | High overhead is fine for short control turns | + +Use `/usage --by-gateway` to see your own split — if a messaging gateway dominates your token spend on work that didn't need to *originate* there, you've found the money. + +Two related cache facts (full detail in [Part 27](./part27-power-secrets.md)): + +- **Switching models mid-session resets the prompt cache** — the cache key includes the model, so the next turn re-reads the whole history at full input price. Batch model switches, or delegate the odd-model step to a subagent. +- **Credential-pool rotation is also a cache miss** — multiple keys per provider (`hermes auth add --api-key ...`) keep you alive through rate limits, but each rotation re-reads the full history. Budget for it on long sessions. + +--- + +## Benchmark the Stack, Not the Model + +July's WolfBench data made this concrete: the **same model** (GPT-5.6 Sol, max reasoning) scored 86.7% on Codex at ~$90/run vs 84.5% on Hermes at ~$173/run — the harness used ~2× the tokens for the same brain. Takeaways for Hermes specifically: + +1. **A model's cost ranking changes per harness.** Never assume a benchmark run on another agent transfers. +2. **On Hermes, the cost-efficient frontier pick beats the absolute-best pick** more often than not (July example: Terra ~3.6 points behind Sol at ~44% lower cost). +3. **High-reasoning models generate busywork** — self-assigned hashing, redundant test-writing, verification loops of their own verification. Cap `/goal` scope with explicit completion contracts ([Part 26](./part26-moa-verification.md)), and never stack the same high-reasoning model as both orchestrator and worker — the busywork compounds. +4. **Free tiers die fast under agent traffic.** A free-tier provider that lasts a month of chat lasts a day of agent loops. Treat free lanes as burst capacity, not a plan. + +Run your own numbers: pick 3–5 representative tasks, run them through your actual config on two candidate models, and compare `/usage` + Langfuse traces. An hour of benchmarking regularly saves hundreds of dollars a month. + +--- + +## Langfuse v4 / OpenTelemetry-Native Path + +Langfuse v4 is OTEL-native: it accepts spans directly at `/api/public/otel`, so you can also run a standard **OTel Collector in front of Langfuse** — auth separation, plus fan-out to a second backend (Grafana/Datadog) from one stream. Three currency notes for July 2026: + +- **Local models cost $0 in dashboards unless you define prices.** Add pricing for your local models in Langfuse and emit `gen_ai.usage.*` token counts, or your cost dashboards will lie by omission. +- **Watch for double-counted agent spans** — a parent `invoke_agent` span plus its child `chat` span can both carry usage. Filter one level or use a current SDK. +- Langfuse's **root-observations default changed on 2026-07-15** — if you built dashboards on the old default, re-check them after upgrading. + +--- + ## Eval-Driven Regression Prevention Hermes does not ship a built-in `hermes evals` subcommand — that's a Langfuse diff --git a/part21-remote-sandboxes.md b/part21-remote-sandboxes.md index 93f4826..deb6afe 100644 --- a/part21-remote-sandboxes.md +++ b/part21-remote-sandboxes.md @@ -25,6 +25,8 @@ Hermes uploads your workspace on task start, delegates work, then downloads only ## Pick Your Backend +The 10-second decision guide, July 2026 edition: **Daytona** for fast cold starts on short agent loops · **Modal** for heavy/GPU jobs · **E2B** when what you want is a code interpreter · **Vercel Sandbox** for web-flavored build/deploy work · **OpenShell** ([Part 25](./part25-nvidia-local.md#5-openshell--kernel-level-isolation)) when the job must stay local/on-prem but hard-isolated. The long version: + | Backend | Billing | Idle cost | Best for | |---------|---------|-----------|----------| | **SSH** | Your infra | Whatever your host costs | Homelab / always-on dev box | diff --git a/part23-tenacity-stack.md b/part23-tenacity-stack.md index 5efd10a..d9394c4 100644 --- a/part23-tenacity-stack.md +++ b/part23-tenacity-stack.md @@ -35,6 +35,16 @@ Why this matters: Workers use the `kanban_*` toolset (`kanban_show`, `kanban_list`, `kanban_complete`, `kanban_block`, `kanban_heartbeat`, `kanban_comment`, `kanban_create`, `kanban_link`, `kanban_unblock`). Humans use `hermes kanban ...`, `/kanban ...`, or the dashboard. Both hit the same `~/.hermes/kanban.db`. +### The two traps everyone hits once + +1. **`toolsets: all` does NOT include kanban.** The board toolset is deliberately opt-in so ordinary chats aren't cluttered with board tools. Any profile that *drives* a board (your orchestrator) needs `toolsets: [kanban]` explicitly — workers spawned *by* the board get their tools automatically. If your orchestrator "can't see the board," this is why. +2. **The default worker workspace is scratch — cleared on completion.** If the task produces files you want to keep, pin an **absolute** directory: `--workspace dir:/absolute/path`. A relative path is accepted at create time and rejected at spawn time. + +### Two board shapes worth stealing + +- **Overnight autonomy:** stack the board in the evening, let workers grind while you sleep, review results with coffee. The real cost is one-time — tuning board conditions and worker prompts until unattended quality holds. Budget an evening of iteration, then it compounds. +- **GPU FIFO:** a capacity-1, strictly-ordered board serializes GPU-hungry jobs so multiple agents never OOM the same card. The board *is* the queue — no extra infrastructure. + Good board shapes: - **Solo dev:** triage → implement → review → PR. diff --git a/part24-desktop-app.md b/part24-desktop-app.md index 78a7758..00aaed1 100644 --- a/part24-desktop-app.md +++ b/part24-desktop-app.md @@ -101,6 +101,14 @@ The desktop app doesn't have to run the agent locally. It can connect to a **rem The model is "**thin GUI local, heavy agent remote**" — keep a lightweight app on your laptop while the agent, tools, and memory live on a workstation, a DGX Spark, or a VPS. (Pair this with [Part 21: Remote Sandboxes](./part21-remote-sandboxes.md) and [Part 25: NVIDIA & Local Hardware](./part25-nvidia-local.md).) +> **The gotcha nobody warns you about:** with a remote backend, *code runs on the remote server* — file writes, terminal commands, everything. If you asked for a local script and can't find it, it's on the VPS. Want the agent working on your laptop's files? Run the backend locally (or mount/sync deliberately, e.g. via Tailscale + a shared directory). + +### 7b. Hermes Cloud — the third connection mode (preview) + +Alongside *local* and *remote gateway*, current builds are growing a third mode: **Hermes Cloud** — sign in with Nous Portal and the app auto-discovers cloud-hosted agents, no VPS to babysit. The pitch: one-click deploy, scale-to-zero pricing, natural-language scheduling, multi-channel attach, persistent memory, isolated sandboxes, and parallel subagents — managed. + +Treat it as **preview until GA**: features on `main` move fast, and self-hosting (this guide's default posture) remains the way to keep full control of memory, secrets, and egress. When it ships stable, expect it to be the right answer for "I want the [Part 23](./part23-tenacity-stack.md) stack without owning a server." + --- ## 8. Projects — the v0.18 Coding Cockpit diff --git a/part25-nvidia-local.md b/part25-nvidia-local.md index b448717..bcd836a 100644 --- a/part25-nvidia-local.md +++ b/part25-nvidia-local.md @@ -88,7 +88,23 @@ v0.16 added **NVIDIA as a built-in trusted Skills source**, alongside OpenAI, An ## 8. A Note on Models (Kept Deliberately Light) -Because Hermes is model-agnostic, the "best local model" changes constantly — don't hard-code this week's winner. As a *current* data point, NVIDIA highlights **Qwen 3.6** (27B/35B) running on RTX / DGX Spark and reports it matching or beating prior-generation 120B–400B models while fitting on far smaller hardware. Use that as a starting point, not gospel: open `hermes model`, fuzzy-search, and pick what's good *right now*. The harness is the durable part. +Because Hermes is model-agnostic, the "best local model" changes constantly — don't hard-code this week's winner. As a *current* data point, NVIDIA highlights **Qwen 3.6** (27B/35B) running on RTX / DGX Spark and reports it matching or beating prior-generation 120B–400B models while fitting on far smaller hardware. Community mid-July reference points: **Qwen3.6 35B-A3B** as an agentic workhorse, **Bonsai-27B** at ~36 tok/s on a 16GB card, and **Gemma4 A4B** for full local privacy on modest hardware — with LM Studio or Ollama serving, including on Windows 11 via Docker. Use these as starting points, not gospel: open `hermes model`, fuzzy-search, and pick what's good *right now*. The harness is the durable part. + +One local-specific cost note: llama.cpp/vLLM keep a **KV/prefix cache** too — the same rules from [Part 20](./part20-observability.md) apply. Stable system prompts and avoiding mid-session model swaps keep local generation fast. + +--- + +## 9. Background Computer Use (macOS) + +Current builds add background **computer use** — the agent operates GUI apps while your cursor stays free: + +```bash +hermes computer-use install +# System Settings → grant Screen Recording + Accessibility to CuaDriver +hermes -t computer_use chat +``` + +The agent clicks, types, and reads windows in the background; destructive actions still wait for approval ([Part 19](./part19-security-playbook.md)). If it can't see or click anything, it's always the permissions — re-check both grants after any macOS update. --- diff --git a/part26-moa-verification.md b/part26-moa-verification.md index a3894a7..a725b01 100644 --- a/part26-moa-verification.md +++ b/part26-moa-verification.md @@ -48,7 +48,7 @@ What you get in v0.18: | 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. +Cost scales with the number of reference models — an ensemble of three frontier models is roughly 4× the tokens of one *in the worst case*. But a July community measurement complicates the intuition in MoA's favor: a single Opus turn cost ~27.9k tokens / ~$0.14 vs a **full 4-reference + aggregator MoA turn at ~28.6k / ~$0.15** — nearly identical, because the system prompt and tool schemas dominate the bill and reference models run on stripped context. Quality on that user's eval: **0.8202 for Opus+GPT-5.5 MoA vs 0.7607 / 0.7412 for either alone**. It's still 5 API calls per turn (and scales with session length), so the advice stands — council for judgment calls, single model for the grind — but the cost objection is weaker than it looks. > **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. @@ -95,6 +95,9 @@ Two commands turn the skill/memory system from a black box into something you st ``` - `/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). +- **Give `/learn` output a haircut.** Generated skills routinely ship 123–202-char descriptions — and every skill description loads into context *every session, forever*. Open the new `SKILL.md`, trim the description to **≤60 chars**, and fix the author before sharing. +- **Check the built-ins first.** Memory, web search, browser control, cron, and sub-agents are native — don't `/learn` or install a skill for a capability the agent already has. +- For shared or production agents, pair with `/skills approval on` and `/memory approval on` so self-improvement stays supervised ([Part 7](./part7-memory-system.md)). - `/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. @@ -173,3 +176,5 @@ Then: --- *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.* + +**Next:** [Part 27 — Power Secrets](./part27-power-secrets.md), the field manual of non-obvious mechanics that make everything in this guide cheaper and more reliable. diff --git a/part27-power-secrets.md b/part27-power-secrets.md new file mode 100644 index 0000000..28acf50 --- /dev/null +++ b/part27-power-secrets.md @@ -0,0 +1,265 @@ +# Part 27: Power Secrets — The Field Manual the Docs Don't Give You + +*Twenty-five non-obvious mechanics that separate people who fight Hermes from people who fly it. Distilled from the official Wingtips series (#1–#22 by @witcheer), Teknium's July guidance, and the highest-signal community field reports from July 2026 — verified against the real v0.18.x schema before inclusion.* + +--- + +## Why this part exists + +Every mechanic below is *documented nowhere or buried deep*, yet each one explains a class of "Hermes is broken / dumb / expensive" complaints. Read this part once and you'll stop hitting most of them. It's organized into five clusters: + +1. [Context, memory & the prefix cache](#1-context-memory--the-prefix-cache) — why the agent "forgets" and what actually fixes it +2. [Cost mechanics](#2-cost-mechanics) — where tokens really go +3. [Profiles, files & identity](#3-profiles-files--identity) — which file is the brain, and when to split agents +4. [Kanban & operational traps](#4-kanban--operational-traps) — the opt-ins and absolute paths that bite everyone once +5. [The one-page cheat sheet](#5-the-one-page-cheat-sheet) — all of it, compressed + +--- + +## 1. Context, Memory & the Prefix Cache + +### Secret #1 — MEMORY.md is a frozen snapshot, not a live file + +Writes to `MEMORY.md` hit disk **immediately**, but the memory block in the *system prompt* is **snapshotted at session start** and stays fixed for the whole session. This is deliberate — it keeps the provider's prefix cache warm (see [Part 20](./part20-observability.md)). The same applies to `USER.md`. + +**Symptom:** you tell the agent a fact, it saves it, and ten turns later it acts like it never heard it. +**Fix when you need the fact *now*:** start a new session, or `hermes -c` to continue with a fresh prompt build. Tool calls that *read* the file always see live disk — only the injected prompt block is frozen. + +### Secret #2 — Compression keeps first 3 + last 20 turns; the middle is where work dies + +Automatic compression (the 🗜️ icon) kicks in around **50% of the context window**. It keeps roughly the **first 3 turns and the last 20**, and summarizes the middle. If the agent "redoes work," the details it needed were in the summarized middle. Three real levers in `config.yaml` (hot-reloaded on a running gateway): + +```yaml +compression: + protect_last_n: 30 # keep more recent turns uncompressed +auxiliary: + compression: + provider: openrouter + model: google/gemini-3-flash # summarize on a cheap model, not your primary +model: + context_length: 200000 # raise the ceiling so compression fires later +``` + +Full compression tuning: [Part 6](./part6-context-compression.md). + +### Secret #3 — Compaction is a structured brief, not amnesia + +When compaction runs, it doesn't just truncate — it fills fixed slots: **goal / constraints / progress / key decisions / relevant files / next steps / critical context**. Raw turns stay in `state.db` and remain findable with `session_search`. + +**Practical consequence:** *write for the compactor*. State goals and decisions in plain declarative sentences ("Decision: we're using Postgres, not SQLite, because X") so they map cleanly into slots. Facts that must **never** drop belong in `MEMORY.md`, not in chat. + +### Secret #4 — Switching models mid-session resets the prompt cache + +The cache key includes the model. Switch models mid-thread and the next turn re-reads your **entire history at full input price**. Same for rotating credentials (see Secret #10). If a long session needs a different model for one step, **delegate to a subagent** (own context, own cache) instead of ping-ponging `/model`. + +### Secret #5 — `/steer`, `/queue`, `/busy`: redirect without burning the run + +- `/steer focus on the auth module first` — lands **after the current tool call**, inside the same turn. Not a new turn, no restart. +- `/queue` (`/q`) — stages the next prompt without touching the current run. +- `/busy` — configures what a plain Enter does while the agent is working: queue, steer, or interrupt. + +Details: [Part 14](./part14-fast-mode-watchers.md#steer-queue-and-background-turns). + +### Secret #6 — Third-party context files tax every single prompt + +Project rule files inject on **every prompt**, and the discovery order is first-match-wins: `.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`, with a **20k-char cap** (head+tail truncation). Two traps: + +- A `.hermes.md` **silently shadows** `AGENTS.md` — no warning, your carefully-written AGENTS.md just stops loading. +- Tools you install can drop their own fat context files. The infamous case: **Camofox's `AGENTS.md` injects ~22k chars into every prompt** if it sits in your cwd. Audit `ls -la` for rule files after installing anything. + +`SOUL.md` always loads separately from `~/.hermes/SOUL.md` — identity is never subject to project-rule shadowing. + +--- + +## 2. Cost Mechanics + +### Secret #7 — The messaging-gateway token tax (the biggest one) + +Talking to Hermes through Telegram/Discord carries **~15–20k tokens of tool definitions per turn**. The same work through the **CLI costs ~6–8k**. Same agent, same result, 2–3× the context overhead. + +**The rule: CLI for heavy work, messaging for control.** Kick off long jobs from the terminal (or Kanban), then steer and receive results on your phone. Full cost math: [Part 20](./part20-observability.md#the-gateway-token-tax-cli-for-heavy-work-messaging-for-control). + +### Secret #8 — Default cheap, escalate deliberately + +The pattern high-volume users converge on: default to a **DeepSeek-Flash-class model** (~$0.14/M input) and reach for frontier models only when actually stuck. Community claim that holds up in practice: ~80% of tasks get the same result at ~30× lower cost. Combine with persistent memory + `/learn` skills and similar tasks get measurably faster and cheaper over weeks — the agent amortizes its own learning. + +### Secret #9 — Benchmark the stack, not the model + +July's WolfBench numbers: the **same model** (GPT-5.6 Sol, max reasoning) scored 86.7% on Codex at ~$90/run vs 84.5% on Hermes at ~$173/run — Hermes used ~2× the tokens for the same brain. Corollaries: + +- On Hermes, **Terra** lands ~3.6 points behind Sol at **~44% lower cost** — usually the right trade. +- High-reasoning models **create busywork** (one user watched Sol hash every test file and review every hash — 347 redundant tests). Cap `/goal` scope, use verification contracts ([Part 26](./part26-moa-verification.md)), and never pair a Sol parent with Sol children — the busywork compounds exponentially. + +### Secret #10 — Credential pools ≠ fallbacks, and rotation costs a cache miss + +You can register **multiple keys per provider**; Hermes rotates on rate-limit/quota before falling back to another provider: + +```bash +hermes auth add openrouter --api-key sk-or-... +hermes auth list +``` + +Pool exhausts first, then `fallback_providers` kicks in — and **every fallback entry needs both `provider` and `model`** fields. Put a local model last (`provider: custom` → llama.cpp/vLLM) as your outage floor. One warning: each rotation is a **prefix-cache miss** — the full history is re-read at full price. Nous Portal's single OAuth usually needs no pool. + +### Secret #11 — MoA is nearly free *at the turn level* + +Measured: single Opus turn ~27.9k tokens / ~$0.14 vs a full 4-reference + aggregator MoA turn ~28.6k / ~$0.15. Why: the system prompt and tool schemas dominate the bill, and reference models run on **stripped context**. And it works — Opus+GPT-5.5 MoA benched 0.8202 vs 0.7607/0.7412 alone. Still 5 calls/turn (scales with session length), so save it for genuinely hard problems. See [Part 26](./part26-moa-verification.md). + +--- + +## 3. Profiles, Files & Identity + +### Secret #12 — Which file is the brain + +| File | Role | +|------|------| +| `SOUL.md` | Who the agent **is** — system prompt slot #1, replaces the default identity | +| `USER.md` | Who **you** are (snapshotted at session start, like MEMORY.md) | +| `MEMORY.md` | Facts about the work; reloads every session | +| Project rules | First-match-wins: `.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules` | + +### Secret #13 — A profile is a whole separate agent + +`hermes profile create ` gives you an agent with its **own memory, sessions, skills, and bot token** — it knows nothing about your main agent. Two architectures, pick deliberately: + +- **One agent on many platforms** = **one profile, many gateways** (shared SOUL/memory across Telegram + Discord + Desktop). +- **Profile per domain** ("profiles as rooms": coder / research / private / cron) = strangers by design — no cross-contamination of memory or skills. Clone a starting point with `hermes profile create new --clone-all` (without the flag you get a blank agent). + +**Boundary warning:** profiles isolate *Hermes state*, **not the filesystem** — every profile runs as the same OS user. For real isolation use Docker, SSH, or OS ACLs ([Part 19](./part19-security-playbook.md)). + +### Secret #14 — The "me layer" pattern (personalization beyond USER.md) + +Power users maintain a small directory of markdown files — beliefs, values, strategy, decisions, ideas, preferences, active focus — that `SOUL.md` instructs the agent to explore, promoting stable findings into `USER.md`/`MEMORY.md`. Pair it with a nightly cron that ingests the day's sessions (and optionally your own posts) into the layer, dedupes, and compresses. It's the difference between an agent that knows your name and one that knows your *judgment*. + +### Secret #15 — Supervised self-improvement + +```text +/memory approval on +/skills approval on +``` + +The agent keeps learning, but every new memory write and skill creation waits for your yes. This is the right default for shared or production agents — silent memory writes are how one wrong "fact" compounds into every future session. + +### Secret #16 — `/learn` output needs a haircut + +`/learn ` is the fastest path to procedural memory, but it routinely writes **123–202-char skill descriptions** — and descriptions load **every session**, forever. After every `/learn`: open the generated `SKILL.md`, trim the description to **≤60 chars**, and set the author before sharing. Also: check the **built-in tools first** — memory, web search, browser control, cron, and sub-agents are native; don't install a skill for something the agent already has. + +--- + +## 4. Kanban & Operational Traps + +### Secret #17 — `toolsets: all` does NOT include kanban + +The Kanban toolset is **opt-in** (so chat isn't cluttered with board tools). Any profile that *drives* a board needs it explicitly: + +```yaml +toolsets: + - kanban +``` + +Workers spawned *by* the board already get their tools. This one silently breaks every "orchestrator can't see the board" setup. + +### Secret #18 — The default Kanban workspace is scratch — your output gets wiped + +Worker workspaces are **cleared on completion** by default. To keep the output: + +```bash +hermes kanban create "your task" --workspace dir:/absolute/path +``` + +And it must be **absolute** — a relative path is accepted at create time and **rejected at spawn time**. Two more board patterns worth stealing: overnight autonomous coding runs (the real cost is one-time board-condition + prompt tuning), and using a capacity-1 ordered board as a **GPU FIFO** so multi-agent GPU jobs never race. More in [Part 23](./part23-tenacity-stack.md). + +### Secret #19 — Gateway dies at logout on headless boxes + +A user-service gateway is killed when your login session ends. On any headless VPS: + +```bash +hermes gateway install +sudo loginctl enable-linger $USER +# or go system-wide: sudo hermes gateway install --system +``` + +### Secret #20 — Disk fills are not logs + +The three unbounded growers to watch: **`state-snapshots/`** (750MB+ observed), **per-run cron output** (1500+ files), and **host-piped stdout**. Run the disk-cleanup plugin and watch those three before you get "no space left on device." + +### Secret #21 — Prune state.db before it drags + +`~/.hermes/state.db` auto-prune is **off by default**. Hundreds of sessions ≈ 10–15MB; you'll feel drag near **~384MB / ~1000 sessions** (heavy 24/7 users have hit 900MB+): + +```bash +hermes sessions prune # ended sessions only, never active ones +# or set-and-forget: sessions.auto_prune: true +``` + +### Secret #22 — Session export, with redaction + +```bash +hermes sessions export --format md # or qmd | html +# --redact hides keys/tokens; --session-id for one session +``` + +md/qmd exports land in `~/.hermes/session-exports` with a manifest. Always `--redact` before sharing anywhere. + +### Secret #23 — Telegram group silence is a BotFather default + +Group Privacy Mode defaults **ON**, so your bot only sees @mentions and `/` commands — plain group messages never arrive. Fix: BotFather → `/setprivacy` → Disable, then **remove and re-add** the bot to each group (the change doesn't apply to groups it already joined). Details: [Part 4](./part4-telegram-setup.md). + +### Secret #24 — Background computer use (macOS) + +```bash +hermes computer-use install +# grant Screen Recording + Accessibility to CuaDriver +hermes -t computer_use chat +``` + +The agent clicks and types in the background while **your cursor stays put**; destructive actions wait for approval. See [Part 25](./part25-nvidia-local.md). + +### Secret #25 — Keep Hermes in the loop + +Official guidance from Teknium: don't demote Hermes to a shell that launches another agent and exits. Routing through a second agent as the "real" brain **breaks the trace** — memory stops accumulating, `/learn` sees nothing, plugins go blind. Run models *inside* Hermes; delegate to coding CLIs as **workers** ([Part 18](./part18-coding-agents.md)), with Hermes as the durable control plane. + +--- + +## 5. The One-Page Cheat Sheet + +Print this. Tape it somewhere. + +1. **CLI for heavy work; messaging for control** — the gateway tool-definition tax is real (15–20k vs 6–8k tokens). +2. **Default cheap (DeepSeek-Flash-class); frontier only when stuck.** +3. **MEMORY/USER are snapshotted at session start** — need a fact live now → new session or `hermes -c`. +4. **`/steer` mid-run; `/queue` next; `/busy` configures Enter.** +5. **`/memory approval on` + `/skills approval on`** for supervised self-improvement. +6. **After `/learn`, trim the skill description to ≤60 chars.** +7. **Profiles for domain isolation; one profile + many gateways for one brain on many platforms.** +8. **`toolsets: [kanban]`** for any board-driving profile; **`--workspace dir:/abs`** or your output is wiped. +9. **Credential pools ≠ fallbacks; every rotation costs a full-history cache miss.** +10. **Model switch mid-thread = full re-read; use a subagent instead.** +11. **Compression levers: `protect_last_n`, cheap `auxiliary.compression` model, raise `context_length`.** +12. **Compaction writes a brief** — state goals/decisions in plain language so they survive it. +13. **`loginctl enable-linger`** on every headless VPS gateway. +14. **Prune `state.db`** past ~384MB / ~1000 sessions. +15. **Disk watch: `state-snapshots/`, cron outputs, piped stdout — not logs.** +16. **BotFather privacy off + remove/re-add the bot** for Telegram groups. +17. **Docker with internal-only network + an action ontology** for production security ([Part 19](./part19-security-playbook.md)). +18. **External spend kernel** for any agent that touches money ([Part 19](./part19-security-playbook.md#external-spend-kernels-when-the-agent-touches-money)). +19. **High-reasoning models invent busywork** — verification contracts, and never Sol-parent + Sol-child. +20. **Terra over Sol on Hermes when cost matters; Luna for the daily lane.** +21. **Anthropic subscriptions don't work natively** — use API keys, or orchestrate a Claude terminal instead. +22. **Keep Hermes in the loop** — outsourcing the brain kills memory, trace, and plugins. +23. **A remote Desktop backend means code runs on the server** — want local files, run local. +24. **MoA is nearly free per turn** (system prompt dominates) — but save it for genuinely hard calls. +25. **Watch third-party `AGENTS.md` files** — one stray 22k-char rule file taxes every prompt you send. + +--- + +## What's Next + +- [Part 20: Observability & Cost](./part20-observability.md) — measure the tax before and after you fix it +- [Part 19: Security Playbook](./part19-security-playbook.md) — the seven layers + spend kernels these secrets reference +- [Part 26: MoA & Verification](./part26-moa-verification.md) — the verification contracts that tame busywork +- [Part 23: Tenacity Stack](./part23-tenacity-stack.md) — Kanban patterns beyond the two traps + +--- + +*Sources: Hermes Wingtips #1–#22 (@witcheer), Teknium's July 2026 posts, and community field reports from 2026-07-09 → 17 — cross-checked against the v0.18.x schema. When a claim couldn't be verified against real behavior, it didn't make this page.* diff --git a/part6-context-compression.md b/part6-context-compression.md index 8c3d2f3..61096c2 100644 --- a/part6-context-compression.md +++ b/part6-context-compression.md @@ -73,6 +73,27 @@ hermes config set compression.target_ratio 0.5 hermes config set compression.protect_last_n 20 ``` +## What Compression Actually Keeps (and the Levers That Matter) + +When automatic compression fires (the 🗜️ icon — community reports put the practical trigger around the half-full mark on default settings), it keeps roughly the **first few turns and the last `protect_last_n` messages**, and summarizes the middle. The middle is where "the agent redid work it already did" comes from. Three levers, all hot-reloaded on a running gateway: + +```yaml +compression: + protect_last_n: 30 # keep more recent turns verbatim (default 20) +auxiliary: + compression: + provider: openrouter + model: google/gemini-3-flash # summarize on a cheap model, never your primary +model: + context_length: 200000 # a bigger ceiling = compression fires later +``` + +And compaction is a **structured brief, not amnesia** — it fills fixed slots (goal / constraints / progress / key decisions / relevant files / next steps / critical context), and the raw turns stay in `state.db` for `session_search`. So *write for the compactor*: state goals and decisions in plain declarative sentences, and put never-drop facts in `MEMORY.md` instead of chat. More context-survival mechanics: [Part 27](./part27-power-secrets.md#1-context-memory--the-prefix-cache). + +## The Context You Didn't Order: Third-Party Rule Files + +Compression only manages *conversation* growth — a fat project rule file taxes **every prompt before the conversation even starts**. Rule discovery is first-match-wins (`.hermes.md` → `AGENTS.md` → `CLAUDE.md` → `.cursorrules`) with a 20k-char cap, and a stray `.hermes.md` silently shadows your `AGENTS.md`. Worst observed case: Camofox ships an `AGENTS.md` that injects **~22k characters into every prompt** if it's in your cwd. After installing any tool into a workspace, check for rule files it dropped. + ## Best Practices - **Let it compress.** Don't set the threshold to 0.99 — compression needs headroom to work. diff --git a/part7-memory-system.md b/part7-memory-system.md index 6c62bba..a6f4162 100644 --- a/part7-memory-system.md +++ b/part7-memory-system.md @@ -122,6 +122,38 @@ The memory system is no longer write-only. Two v0.18 additions close the 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). +## The Snapshot Rule (Why the Agent "Forgets" Mid-Session) + +The most-hit memory gotcha in the wild: memory writes hit disk **immediately**, but the memory block injected into the *system prompt* is **snapshotted at session start** and stays fixed for the whole session — deliberately, to keep the provider prefix cache warm (see [Part 20](./part20-observability.md)). The same applies to `USER.md`. + +- Need a just-saved fact live *now*? Start a new session, or `hermes -c`. +- Tool calls that read memory always see live disk — only the injected block is frozen. +- This is not a bug to fix; it's a cost trade you should know you're making. + +## Approval Gates for Self-Improvement + +For shared or production agents, gate what gets written before it compounds: + +```text +/memory approval on +/skills approval on +``` + +The agent keeps proposing memories and skills, but every write waits for your yes. One wrong "fact" in memory gets injected into every future session — cheap insurance. + +## Community Memory Layers (When Native Isn't Enough) + +Native memory + `/journey` covers session continuity and user preferences. For other shapes of the problem: + +| Need | Prefer | +|------|--------| +| Session continuity + user prefs | **Hermes native memory** (this part) | +| Knowledge graph over a document corpus | **LightRAG** ([Part 3](./part3-lightrag-setup.md)) | +| Cross-app / multi-client memory | **Mem0 MCP** — official packages only ([Part 17](./part17-mcp-servers.md)) | +| Long-horizon procedural knowledge | **Skills via `/learn`** ([Part 26](./part26-moa-verification.md)) | + +Community plugins like Sibyl Memory (Hermes Atlas) advertise big LongMemEval numbers and token savings — treat vendor benchmarks as marketing until you've reproduced them on your own workload, and audit anything that reads your whole session history. + ## Anti-Patterns | Don't Do This | Do This Instead | diff --git a/part8-subagent-patterns.md b/part8-subagent-patterns.md index a997221..737491a 100644 --- a/part8-subagent-patterns.md +++ b/part8-subagent-patterns.md @@ -81,6 +81,31 @@ The CLI/TUI status bar tracks running background subagents, and the desktop app - **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 Seven-Rung Agent Ladder + +The community pedagogy that stuck this July: seven agent architectures, each mapping to a concrete Hermes mechanism. Don't build rung 7 on day one — the taught progression is **1+6 first**, then climb as the work demands it. + +| # | Type | Hermes mechanism | When | +|---|------|------------------|------| +| 1 | Basic + tools | Enable tools in Desktop/Dashboard | Single tasks | +| 2 | MCP-backed | MCP → Add Server ([Part 17](./part17-mcp-servers.md)) | Multi-platform work | +| 3 | Sequential pipeline | Cron + wake gates + file handoffs; one profile per step | Dependent multi-step | +| 4 | Parallel | `delegate_task` batch (default 3 subagents, clean contexts, summaries only) | Research / analysis | +| 5 | Routed specialists | Kanban decompose ([Part 23](./part23-tenacity-stack.md)) or a Chief-of-Staff profile | Inbox triage / multi-role | +| 6 | Human-in-the-loop | `approvals.mode: manual` (default) or `smart`; 60s fail-closed | Send / deploy / spend / post | +| 7 | Dynamic spawn | Orchestrator + `max_spawn_depth: 2` → up to 9 workers | Complex discovery | + +**Progression:** 1+6 → 2 → 4 → 3 → 5 → 7. Most workloads never need past rung 5. + +## One Agent vs Many Profiles + +Two legitimate architectures — the community is genuinely split, so pick on the shape of your work: + +- **One agent + skills + subagents** (subagents only for parallelism): best when your domains overlap and shared memory is the point. For the same brain on many chat platforms, use **one profile with many gateways** — shared SOUL and memory everywhere. +- **Profiles as rooms** (coder / research / private / cron): each profile is a *whole separate agent* — own memory, sessions, skills, and bot token. Best for long-running multi-domain setups where a coding session polluting your research memory is a real cost. Clone a starting point with `hermes profile create --clone-all`. + +**The boundary that surprises people:** profiles isolate Hermes state, **not the filesystem** — every profile is the same OS user. Real isolation needs Docker/SSH/ACLs ([Part 19](./part19-security-playbook.md)). More in [Part 27](./part27-power-secrets.md#3-profiles-files--identity). + ## The CEO/COO/Worker Pattern ``` diff --git a/part9-custom-models.md b/part9-custom-models.md index def831a..42a6bba 100644 --- a/part9-custom-models.md +++ b/part9-custom-models.md @@ -3,6 +3,8 @@ *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.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. +> +> **Mid-July 2026:** **Kimi K3** landed day-one in Hermes (Nous Portal, Kimi Direct, OpenRouter — **update Hermes before using Kimi Direct**), and OpenAI's **GPT Sol / Terra / Luna** family is reachable via Nous Portal, a Codex/ChatGPT subscription, or OpenRouter. See [The Mid-July Model Landscape](#the-mid-july-2026-model-landscape) below. --- @@ -82,6 +84,35 @@ The exact "best model" moves weekly, so treat this as a routing posture rather t > Pricing and context windows change too quickly to hardcode. Hermes now pulls OpenRouter and Nous Portal picker lists from a remote manifest, while provider APIs supply pricing/context metadata where available. +### The Mid-July 2026 Model Landscape + +A snapshot of what moved this month — treat as a routing posture, verify against the live picker: + +| Lane | Pick | Notes | +|------|------|-------| +| Daily driver | **GPT Luna** or a DeepSeek-Flash-class model | Cheap enough for cron and chat | +| Hard coding / judgment | **GPT-5.6 Sol** or **Kimi K3** | K3 has notably strong parallel tool-calling; watch OpenRouter K3 pricing, it burns wallets fast | +| Cost-conscious frontier on Hermes | **GPT Terra** | ~3.6 points behind Sol on the July WolfBench at ~44% lower cost *on this harness* ([Part 20](./part20-observability.md#benchmark-the-stack-not-the-model)) | +| Fast cheap coding | Composer 2.5 Fast (xAI OAuth) | Still available through the Grok subscription path | +| Local | Qwen3.6 35B-A3B, Bonsai-27B (~36 t/s on 16GB), Gemma4 A4B | [Part 25](./part25-nvidia-local.md) | + +Two hard facts to save you an evening: + +- **Anthropic subscriptions do NOT work natively in Hermes.** Working subscription auths: OpenAI Codex/ChatGPT, Kimi, Qwen, Z.ai, OpenCode. For Claude models use an API key (direct or OpenRouter) — or orchestrate a Claude Code terminal as a worker lane ([Part 18](./part18-coding-agents.md)) if you only have the subscription. +- **High-reasoning models overwork.** Sol in particular generates self-assigned busywork on agent harnesses. Cap goals with completion contracts ([Part 26](./part26-moa-verification.md)) and never run the same high-reasoning model as both orchestrator and delegated worker. + +### Credential Pools (Multiple Keys per Provider) + +Distinct from the fallback chain: you can register **several keys for the same provider**, and Hermes rotates within the pool on rate-limit/quota errors *before* falling over to another provider: + +```bash +hermes auth add openrouter --api-key sk-or-... +hermes auth add openrouter --api-key sk-or-... # second key, same provider +hermes auth list +``` + +Pool first, fallback second. Caveat: every rotation is a **prefix-cache miss** — the next turn re-reads the whole session history at full input price ([Part 20](./part20-observability.md#the-gateway-token-tax-cli-for-heavy-work-messaging-for-control)). Nous Portal's single OAuth usually doesn't need a pool. + --- ### Nous Portal — OAuth, Not an API Key @@ -435,6 +466,13 @@ hermes config set fallback_models '["cerebras/qwen-3-32b", "openrouter/anthropic Hermes tries each in order. If Cerebras is down, it falls back to OpenRouter, then local. +Two rules that save 3am debugging: + +- **Every fallback entry needs both a provider and a model** — a bare model name in a `fallback_providers`-style entry fails at the moment you need it most. +- **Put a local model last** (`local/...` via Ollama, or a `custom` provider pointed at llama.cpp/vLLM) as the outage floor. Degraded beats down. + +And remember the cache economics of switching: the prompt-cache key includes the model, so **any mid-session model change re-reads the full history at full input price**. Batch your switches, or hand the odd-model step to a subagent with its own context ([Part 8](./part8-subagent-patterns.md)). + --- *Don't lock yourself into one provider. The best model is the one that's fast enough and cheap enough for the task at hand.* From 2fbf1f8499e7eb1d377662a92bd4ed16e91efec3 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 17 Jul 2026 01:36:02 +0000 Subject: [PATCH 2/3] Add high-end SVG infographics (Part 27 hero, cheat-sheet poster, seven-layer security, agent ladder, token tax), refresh release timeline to v0.18.2, reconcile compression-threshold guidance Co-Authored-By: Rob --- assets/agent-ladder.svg | 78 ++++++++++++++++++++++ assets/cheat-sheet.svg | 85 ++++++++++++++++++++++++ assets/power-secrets.svg | 109 +++++++++++++++++++++++++++++++ assets/release-timeline.svg | 6 +- assets/security-seven-layers.svg | 75 +++++++++++++++++++++ assets/token-tax.svg | 87 ++++++++++++++++++++++++ part19-security-playbook.md | 4 ++ part20-observability.md | 4 ++ part27-power-secrets.md | 10 ++- part6-context-compression.md | 2 +- part8-subagent-patterns.md | 4 ++ 11 files changed, 459 insertions(+), 5 deletions(-) create mode 100644 assets/agent-ladder.svg create mode 100644 assets/cheat-sheet.svg create mode 100644 assets/power-secrets.svg create mode 100644 assets/security-seven-layers.svg create mode 100644 assets/token-tax.svg diff --git a/assets/agent-ladder.svg b/assets/agent-ladder.svg new file mode 100644 index 0000000..7c08cbd --- /dev/null +++ b/assets/agent-ladder.svg @@ -0,0 +1,78 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + THE SEVEN-RUNG AGENT LADDER + EVERY MULTI-AGENT ARCHITECTURE IS ONE OF THESE — CLIMB IN THIS ORDER: 1+6 → 2 → 4 → 3 → 5 → 7 + + + + + + + + + + + + + + + + + 1 · BASIC + TOOLS + one agent, built-ins + start here — always + + 2 · MCP-BACKED + external systems via + pinned MCP servers + + 3 · PIPELINE + A → B → C stages, + checkable hand-offs + + 4 · PARALLEL + delegate_task fan-out, + one consolidated turn + + 5 · ROUTED + orchestrator picks the + right specialist per task + + 6 · HUMAN-IN-LOOP + approvals: at decision + boundaries — add early! + + 7 · DYNAMIC SPAWN + agents create agents; + budget caps mandatory + + + + + + MOST REAL WORK NEVER NEEDS RUNG 7 — COMPLEXITY IS A COST, NOT A FLEX · PART 8 + diff --git a/assets/cheat-sheet.svg b/assets/cheat-sheet.svg new file mode 100644 index 0000000..180ca17 --- /dev/null +++ b/assets/cheat-sheet.svg @@ -0,0 +1,85 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + THE ONE-PAGE CHEAT SHEET + PRINT IT · TAPE IT UP — 25 RULES THAT PAY RENT EVERY SESSION + + + + + + + + + + + + + + + + 0102030405 + 0607080910 + 1112131415 + 1617181920 + 2122232425 + + + + + CLI for heavy work;messaging for control + Default cheap;frontier only when stuck + MEMORY/USER snapshotat start — hermes -c to refresh + /steer mid-run · /queue next/busy configures Enter + /memory + /skillsapproval on — supervised + + After /learn, trim thedescription to ≤60 chars + Profiles = rooms;one profile, many gateways + toolsets: [kanban] +--workspace dir:/abs + Pools ≠ fallbacks;rotation = cache miss + Model switch = full re-read;use a subagent instead + + protect_last_n · cheap auxcompressor · bigger window + Compaction writes a brief —state decisions plainly + loginctl enable-lingeron every headless gateway + Prune state.db past~384MB / ~1000 sessions + Disk: state-snapshots/,cron output, piped stdout + + Telegram groups: privacy off+ remove/re-add the bot + Docker internal-only net+ typed action ontology + External spend kernelfor anything touching money + Big models invent busywork —verification contracts + Terra over Sol for cost;Luna for the daily lane + + Anthropic subs don't work —API keys or a Claude terminal + Keep Hermes in the loop —it owns memory + trace + Remote Desktop backend =code runs on the server + MoA ≈ free per turn —save it for hard calls + Audit stray AGENTS.md —22k chars taxes every prompt + + + HERMES OPTIMIZATION GUIDE · PART 27 · v0.18.2 ERA + diff --git a/assets/power-secrets.svg b/assets/power-secrets.svg new file mode 100644 index 0000000..c6f0f90 --- /dev/null +++ b/assets/power-secrets.svg @@ -0,0 +1,109 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + POWER SECRETS + 25 NON-OBVIOUS MECHANICS · WINGTIPS #1–#22 + JULY 2026 FIELD REPORTS · VERIFIED AGAINST THE REAL SCHEMA + + + + + + + + + + + + + + + + + 🧠 CONTEXT & CACHE + 💸 COST MECHANICS + 👤 PROFILES & FILES + 📋 KANBAN & OPS + ⚡ CHEAT SHEET + + + + MEMORY.md is a snapshot + compression keeps 3 + last 20 + compaction = structured brief + model switch = cache reset + /steer · /queue · /busy timing + rule files tax every prompt + + gateway tax: 15–20k vs 6–8k + default cheap, escalate hard + benchmark the stack + credential pools ≠ fallbacks + rotation = cache miss + MoA is nearly free per turn + + SOUL / USER / MEMORY roles + a profile is a whole agent + profiles ≠ filesystem walls + the "me layer" pattern + /memory + /skills approval + /learn needs a haircut + + kanban is opt-in, not "all" + scratch workspace gets wiped + enable-linger or die at logout + disk: snapshots, not logs + prune state.db + export --redact to share + + all 25 on one page + print it · tape it up + CLI heavy / phone control + Terra > Sol on Hermes $ + keep Hermes in the loop + verify, then trust + + + + Secrets #1–#6 + Secrets #7–#11 + Secrets #12–#16 + Secrets #17–#24 + Section 5 + + + + + + THE FIELD MANUAL THE DOCS DON'T GIVE YOU — PART 27 + diff --git a/assets/release-timeline.svg b/assets/release-timeline.svg index 0e67c26..324200c 100644 --- a/assets/release-timeline.svg +++ b/assets/release-timeline.svg @@ -79,14 +79,14 @@ v0.18 - Judgment — latest + Judgment — latest (.2) MoA as a model · verification - /learn · scale-to-zero + /learn · scale-to-zero · Baileys fix - CURRENT THROUGH v0.18.0 (v2026.7.1) — "THE JUDGMENT RELEASE" + CURRENT THROUGH v0.18.2 (v2026.7.7.2) — THE JUDGMENT LINE · main → v0.19 diff --git a/assets/security-seven-layers.svg b/assets/security-seven-layers.svg new file mode 100644 index 0000000..3988cb1 --- /dev/null +++ b/assets/security-seven-layers.svg @@ -0,0 +1,75 @@ + + + + + + + + + + + + + + + + + + + + + + + THE SEVEN-LAYER SECURITY STACK + EVERY LAYER MAPS TO A REAL HERMES PRIMITIVE — NO IMAGINARY CONFIG KEYS + + + + + + + + + + + + + + + + + + + + + 1 · TRUST BOUNDARIES + default-deny tools · provenance labels · untrusted-input rule + + 2 · HUMAN APPROVAL GATES + approvals: at send / publish / deploy / spend / system-of-record writes + + 3 · CONTAINMENT + Docker / OpenShell / sandboxes — a real OS boundary, not a profile + + 4 · MCP HYGIENE + pinned packages · stripped env · per-server tokens · tools.include/exclude + + 5 · INJECTION SCANNING + scan inbound email / webhooks / pages before the agent reasons over them + + 6 · NETWORK CONTROLS + egress allowlists · SSRF guards · no metadata endpoints from tool code + + 7 · PRE-EXECUTION COMMAND SCANNING + command_allowlist: · secrets redaction · static scan before anything runs + + + + + ATTACKER + STARTS HERE ↓ + YOUR MONEY, + KEYS & REPOS + LIVE HERE + + diff --git a/assets/token-tax.svg b/assets/token-tax.svg new file mode 100644 index 0000000..9042e92 --- /dev/null +++ b/assets/token-tax.svg @@ -0,0 +1,87 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + THE GATEWAY TOKEN TAX + FIXED TOOL-DEFINITION OVERHEAD PER TURN — BEFORE YOU'VE SAID A WORD + + + + + + + + + + + + ~6–8k + CLI / TUI + + + + lean + Kanban workers + + + + ~15–20k + Telegram / Discord + + TOKENS OF TOOL DEFINITIONS · EVERY SINGLE TURN + + + + + + THE DIVISION OF LABOR + + + CLI / TUI + long coding runs · research · bulk work — lowest overhead, best cache + Kanban + anything that must survive restarts — the board persists, workers run lean + Messaging + kickoff · steering · receiving results — fine for short control turns + + + + + + ⚠ Model switch mid-session → prompt cache reset → full history re-read at full price + ⚠ Credential-pool rotation → same cache miss — budget for it on long sessions + ✓ Measure your split with Langfuse traces per surface — Part 20 + + + CLI FOR HEAVY WORK · MESSAGING FOR CONTROL — PART 20 · PART 27 + diff --git a/part19-security-playbook.md b/part19-security-playbook.md index 9430408..73c7c57 100644 --- a/part19-security-playbook.md +++ b/part19-security-playbook.md @@ -45,6 +45,10 @@ If your agent ingests content from surfaces you don't control (the open web, inb ## The Seven-Layer Mental Model +

+ The seven-layer security stack — trust boundaries, human approval gates, containment, MCP hygiene, injection scanning, network controls, and pre-execution command scanning +

+ The community teaching frame that stuck in July 2026 maps cleanly onto this part — use it as your audit checklist: | # | Layer | Where in this part / the guide | diff --git a/part20-observability.md b/part20-observability.md index 95d9d87..2abf1d1 100644 --- a/part20-observability.md +++ b/part20-observability.md @@ -372,6 +372,10 @@ input length. ## The Gateway Token Tax: CLI for Heavy Work, Messaging for Control +

+ The gateway token tax — CLI/TUI ~6–8k vs messaging gateways ~15–20k tokens of tool definitions per turn, and the division of labor that follows +

+ The single biggest hidden cost in a chat-first Hermes setup, measured repeatedly by the community in July 2026: **the messaging gateways carry ~15–20k tokens of tool definitions per turn**, while the CLI carries **~6–8k** for the same work. That's 2–3× the fixed overhead on *every* turn — before you've said anything. (One user burned 121k tokens just *wiring Telegram to the Desktop app*.) The fix isn't to abandon your phone — it's a division of labor: diff --git a/part27-power-secrets.md b/part27-power-secrets.md index 28acf50..df34fde 100644 --- a/part27-power-secrets.md +++ b/part27-power-secrets.md @@ -1,5 +1,9 @@ # Part 27: Power Secrets — The Field Manual the Docs Don't Give You +

+ Power Secrets — 25 non-obvious mechanics across five clusters: context & cache, cost mechanics, profiles & files, Kanban & ops, and the one-page cheat sheet +

+ *Twenty-five non-obvious mechanics that separate people who fight Hermes from people who fly it. Distilled from the official Wingtips series (#1–#22 by @witcheer), Teknium's July guidance, and the highest-signal community field reports from July 2026 — verified against the real v0.18.x schema before inclusion.* --- @@ -27,7 +31,7 @@ Writes to `MEMORY.md` hit disk **immediately**, but the memory block in the *sys ### Secret #2 — Compression keeps first 3 + last 20 turns; the middle is where work dies -Automatic compression (the 🗜️ icon) kicks in around **50% of the context window**. It keeps roughly the **first 3 turns and the last 20**, and summarizes the middle. If the agent "redoes work," the details it needed were in the summarized middle. Three real levers in `config.yaml` (hot-reloaded on a running gateway): +Automatic compression (the 🗜️ icon) is configured to trigger at **`compression.threshold` — 0.8 (~80%) by default** — but community reports consistently observe it firing earlier in practice, around the **half-full mark**, once tool definitions and rule files are counted against the window. It keeps roughly the **first 3 turns and the last 20**, and summarizes the middle. If the agent "redoes work," the details it needed were in the summarized middle. Three real levers in `config.yaml` (hot-reloaded on a running gateway): ```yaml compression: @@ -223,6 +227,10 @@ Official guidance from Teknium: don't demote Hermes to a shell that launches ano ## 5. The One-Page Cheat Sheet +

+ The one-page cheat sheet — all 25 power secrets in a printable 5×5 grid +

+ Print this. Tape it somewhere. 1. **CLI for heavy work; messaging for control** — the gateway tool-definition tax is real (15–20k vs 6–8k tokens). diff --git a/part6-context-compression.md b/part6-context-compression.md index 61096c2..bd28e0e 100644 --- a/part6-context-compression.md +++ b/part6-context-compression.md @@ -75,7 +75,7 @@ hermes config set compression.protect_last_n 20 ## What Compression Actually Keeps (and the Levers That Matter) -When automatic compression fires (the 🗜️ icon — community reports put the practical trigger around the half-full mark on default settings), it keeps roughly the **first few turns and the last `protect_last_n` messages**, and summarizes the middle. The middle is where "the agent redid work it already did" comes from. Three levers, all hot-reloaded on a running gateway: +When automatic compression fires (the 🗜️ icon — the configured default is the 0.8 threshold above, though community reports often see it fire around the half-full mark once fixed overhead like tool definitions and rule files is counted), it keeps roughly the **first few turns and the last `protect_last_n` messages**, and summarizes the middle. The middle is where "the agent redid work it already did" comes from. Three levers, all hot-reloaded on a running gateway: ```yaml compression: diff --git a/part8-subagent-patterns.md b/part8-subagent-patterns.md index 737491a..a812fe2 100644 --- a/part8-subagent-patterns.md +++ b/part8-subagent-patterns.md @@ -83,6 +83,10 @@ The CLI/TUI status bar tracks running background subagents, and the desktop app ## The Seven-Rung Agent Ladder +

+ The seven-rung agent ladder — basic tools, MCP-backed, pipeline, parallel, routed specialists, human-in-the-loop, dynamic spawning +

+ The community pedagogy that stuck this July: seven agent architectures, each mapping to a concrete Hermes mechanism. Don't build rung 7 on day one — the taught progression is **1+6 first**, then climb as the work demands it. | # | Type | Hermes mechanism | When | From 93b086fe75acd3e1be9ab4c7a397ccac9d5f1e0a Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 17 Jul 2026 01:41:15 +0000 Subject: [PATCH 3/3] Add Part 28 Recipe Book (12 production builds) + map infographic; LightRAG 2026 scaling playbook; skill-description hygiene; 29-part navigation Co-Authored-By: Rob --- CHANGELOG.md | 6 +- CONTRIBUTING.md | 2 +- README.md | 18 +++-- ROADMAP.md | 2 +- assets/recipe-book.svg | 87 +++++++++++++++++++++++ part27-power-secrets.md | 1 + part28-recipe-book.md | 145 +++++++++++++++++++++++++++++++++++++++ part3-lightrag-setup.md | 15 ++++ part5-creating-skills.md | 4 ++ 9 files changed, 271 insertions(+), 9 deletions(-) create mode 100644 assets/recipe-book.svg create mode 100644 part28-recipe-book.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b4f962b..453e4e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,10 @@ Dated list of meaningful guide updates. Roughly [Keep a Changelog](https://keepa ## 2026-07-17 — The Power Secrets modernization (v0.18.2 era) ### Added +- **Part 28 — The Recipe Book**: twelve end-to-end community builds mapped onto real primitives — the morning finance loop (read-only), staged Gmail (drafts-only scopes), the SMB approval office, the overnight Kanban shift, the GPU FIFO board, the content swarm, the carousel factory, the job-hunt pipeline, the accountability coach, the health correlator (local backend), the Blender room, and the secretary office — each with its primitives, its approval posture, and the trap that bit its builders first. +- **New house-style SVG artwork**: Part 27 hero, the one-page cheat-sheet poster, the seven-layer security stack (Part 19), the seven-rung agent ladder (Part 8), the gateway token tax (Part 20), and the Recipe Book map (Part 28); release timeline refreshed to v0.18.2. +- Part 3: "Scaling LightRAG: the July 2026 playbook" — role-specific LLMs, structural chunking, multimodal ingestion, production stores (OpenSearch), RAGAS-style evals via Langfuse, multi-agent retrieval. +- Part 5: ≤60-char skill-description hygiene, built-ins-before-skills, and `/skills` + `/memory` approval gating. - **Part 27 — Power Secrets**: a new field manual distilling the official Wingtips series (#1–#22) and the highest-signal July community research into 25 verified non-obvious mechanics — memory/USER snapshot semantics, compression internals (`protect_last_n`, cheap auxiliary compression, compaction's structured brief), the messaging-gateway token tax, credential pools vs fallbacks and their cache-miss cost, model-switch cache resets, profiles-as-rooms (and the filesystem-isolation caveat), Kanban's `toolsets` and workspace traps, `state.db`/disk hygiene, session export with `--redact`, `/steer`//`/queue`//`/busy` timing semantics, supervised self-improvement gates, and a printable one-page cheat sheet. - Part 17: **MCP Security — July 2026 state of play**: CVE table (LiteLLM CVE-2026-30623, Windsurf CVE-2026-30615, Cursor MCPoison CVE-2025-54136, MCP Inspector CVE-2025-49596, LibreChat CVE-2026-22252), npm-impersonator warning, and a 7-point hardening checklist. - Part 19: the **seven-layer security mental model** mapped onto real Hermes primitives, the **action-ontology** containment pattern (host = brain, credential-less container = hands, typed action API), and **external spend kernels** for money-touching agents (Custodian / `CommercePolicy` / Latch / payguard patterns). @@ -22,7 +26,7 @@ Dated list of meaningful guide updates. Roughly [Keep a Changelog](https://keepa - Version currency: badges, intro, and "What's New" now target **v0.18.2 (v2026.7.7.2)** with the v0.18.1 patch-rollup note, the WhatsApp/Baileys fix (Part 15 Docker-tag guidance), and an explicit "main → v0.19.0, untagged = experimental" framing. - Part 18 agent-lane updates: Claude Code 2.1.20x, Codex 0.144.x stable pin (avoid 0.145 alpha unattended), OpenCode MCP resources + provider change, the Hermes Pong subscription workaround, and Teknium's "keep Hermes in the loop" guidance. - Parts 11/16/23 operational updates: `loginctl enable-linger` for headless gateways, real disk-growth hot spots (`state-snapshots/`, cron output, piped stdout), `hermes sessions prune`/`export --redact`, Kanban toolset opt-in + absolute `dir:` workspaces, and overnight/GPU-FIFO board shapes. -- README: 28-part navigation, new "power secrets" reading path, mid-July status section. +- README: 29-part navigation, new "power secrets" and "recipe book" reading paths, mid-July status section. - Community claims are labelled as such throughout; all new config snippets stay within the real v0.18 schema (no invented keys). - Note: `README-zh.md` / `README-ja.md` remain synced to the 2026-07-03 state; a translation sync is queued. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 85362f1..bb51063 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,7 @@ The [README Repo Map](./README.md#repo-map) is the canonical, row-by-row descrip ├── README.md (+ README-zh.md, README-ja.md) ├── CHANGELOG.md · ROADMAP.md · ECOSYSTEM.md · CODE_OF_CONDUCT.md · LICENSE ├── CONTRIBUTING.md ← you are here -├── part1-setup.md … part27-power-secrets.md # the 28-part guide (README + 27 part files) +├── part1-setup.md … part28-recipe-book.md # the 29-part guide (README + 28 part files) ├── skills/ # 13 installable SKILL.md files under dev/, ops/, security/ ├── templates/ │ ├── config/{minimum,telegram-bot,production,cost-optimized,security-hardened}.yaml diff --git a/README.md b/README.md index 58eb01a..addeb12 100644 --- a/README.md +++ b/README.md @@ -7,13 +7,13 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE) [![Hermes](https://img.shields.io/badge/Hermes-v0.18.2%20%282026.7.7.2%29-9146FF)](https://github.com/NousResearch/hermes-agent/releases/tag/v2026.7.7.2) [![Last updated](https://img.shields.io/badge/Last%20updated-2026--07--17-brightgreen)](./CHANGELOG.md) -[![Parts](https://img.shields.io/badge/parts-28-blue)](#table-of-contents) +[![Parts](https://img.shields.io/badge/parts-29-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.18.2 (v2026.7.7.2) — the "Judgment" line** · **28 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, gateway **scale-to-zero** for teams — and now a full **[Power Secrets field manual](./part27-power-secrets.md)** distilled from the official Wingtips series and July's best community research. **Bring any model** — this guide is about the *harness*, not the weights. +> **Current through Hermes Agent v0.18.2 (v2026.7.7.2) — the "Judgment" line** · **29 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, gateway **scale-to-zero** for teams — and now a full **[Power Secrets field manual](./part27-power-secrets.md)** and a twelve-build **[Recipe Book](./part28-recipe-book.md)** distilled from the official Wingtips series and July's best community research. **Bring any model** — this guide is about the *harness*, not the weights. > > Other languages: [中文](./README-zh.md) · [日本語](./README-ja.md) @@ -23,7 +23,7 @@ Every part you need to go from fresh install to a production Hermes deployment 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.

- Docs plus runnable artifacts — 28 guide parts, 13 installable skills, 5 config templates, 4 reference architectures, one-command VPS bootstrap, 8-question config wizard + Docs plus runnable artifacts — 29 guide parts, 13 installable skills, 5 config templates, 4 reference architectures, one-command VPS bootstrap, 8-question config wizard

*By Terp — [Terp AI Labs](https://x.com/OnlyTerp)* · Last updated **July 17, 2026** · [CHANGELOG](./CHANGELOG.md) · [ROADMAP](./ROADMAP.md) · [ECOSYSTEM](./ECOSYSTEM.md) @@ -80,7 +80,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` … `part27-*.md` | The 28-part guide itself (now incl. MoA + verification, Desktop App, NVIDIA / local hardware, and the Power Secrets field manual). | +| README + `part1-*.md` … `part28-*.md` | The 29-part guide itself (now incl. MoA + verification, Desktop App, NVIDIA / local hardware, the Power Secrets field manual, and the Recipe Book). | --- @@ -117,10 +117,10 @@ Full set of diagrams: [`diagrams/architecture.md`](./diagrams/architecture.md). ## Pick Your Path

- Pick your path — curated reading paths through the guide's 28 parts, from a 10-minute setup to production hardening, local GPU, and MoA verification + Pick your path — curated reading paths through the guide's 29 parts, from a 10-minute setup to production hardening, local GPU, and MoA verification

-This guide grew to 28 parts because *Hermes grew*. Every part lives in its own file (`part1-setup.md` … `part27-power-secrets.md`); this README keeps a short summary of Parts 1–5 (plus the full SOUL.md personality section) and links out. You don't have to read them all — pick the shortest path to what you need: +This guide grew to 29 parts because *Hermes grew*. Every part lives in its own file (`part1-setup.md` … `part28-recipe-book.md`); this README keeps a short summary of Parts 1–5 (plus the full SOUL.md personality section) and links out. 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](./part1-setup.md) → [Part 12: Web Dashboard](./part12-web-dashboard.md) and point-and-click the rest. @@ -155,6 +155,9 @@ Skip the terminal: install the [desktop app](./part24-desktop-app.md) and let fi ### ⚡ "I've been running Hermes for months — give me the stuff I don't know" [Part 27: Power Secrets](./part27-power-secrets.md) — 25 non-obvious mechanics: the memory snapshot rule, the gateway token tax, credential-pool cache misses, the Kanban traps, profiles-as-rooms, and a printable one-page cheat sheet. +### 🍳 "Show me what people actually *build* with this" +[Part 28: The Recipe Book](./part28-recipe-book.md) — twelve production builds from the wild: the morning finance loop, staged Gmail, the content swarm, the overnight Kanban shift, the GPU FIFO board, the secretary office, and more — each mapped to real primitives with the trap that bit its builders first. + --- ## What's New (July 2026) @@ -172,6 +175,8 @@ Two huge releases landed since the Surface refresh — **v0.17.0 "Reach" (v2026. - **`main` is marching toward v0.19.0** — features you see discussed but not tagged (e.g. the **Hermes Cloud** connection mode, background **computer use**) should be treated as **experimental/preview** until they land in a release. Where this guide covers them ([Part 24](./part24-desktop-app.md#7b-hermes-cloud--the-third-connection-mode-preview), [Part 25](./part25-nvidia-local.md#9-background-computer-use-macos)) they're labelled as such. - **Model landscape moved too**: day-one **Kimi K3** support, the GPT **Sol / Terra / Luna** family, and a hard fact worth knowing — Anthropic *subscriptions* don't work natively (API keys do). Current routing posture: [Part 9](./part9-custom-models.md#the-mid-july-2026-model-landscape). - **New: [Part 27 — Power Secrets](./part27-power-secrets.md)**, the distilled field manual from the official Wingtips series (#1–#22) and July's community research: context/cache mechanics, cost traps, profile architecture, and operational gotchas — each verified against the real schema. +- **New: [Part 28 — The Recipe Book](./part28-recipe-book.md)**, twelve end-to-end production builds observed in the wild — money & ops, content & career, life & lab — each mapped onto real Hermes primitives with its approval posture and its known trap. +- **New artwork throughout** — the seven-layer security stack, the agent ladder, the gateway token tax, the Power Secrets cheat-sheet poster, and the Recipe Book map, all in the guide's house style. ### v0.18.0 — "Judgment" @@ -251,6 +256,7 @@ Hermes is now optimized for always-on **local** use on **NVIDIA RTX PCs, RTX PRO 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 28. [Power Secrets](./part27-power-secrets.md) — 25 verified non-obvious mechanics: memory snapshots, the gateway token tax, cache economics, credential pools, Kanban traps, profiles-as-rooms, and a printable cheat sheet +29. [The Recipe Book](./part28-recipe-book.md) — twelve production builds: finance loops, staged Gmail, approval offices, overnight Kanban, GPU FIFO, content swarms, job-hunt pipelines, coaches, correlators, Blender rooms, and the secretary office --- diff --git a/ROADMAP.md b/ROADMAP.md index 46836d5..6d654f2 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -23,7 +23,7 @@ What's landing next. PRs welcome. ## Done (recent) -- ✅ 2026-07-17 — Power Secrets modernization: new Part 27 (Wingtips #1–#22 field manual + cheat sheet), v0.18.2 / `v2026.7.7.2` currency (Baileys fix, patch-rollup notes), MCP CVE table + checklist, seven-layer security model + spend kernels + action ontology, gateway token tax + stack benchmarking + Langfuse v4/OTEL, seven-rung agent ladder, Kimi K3 / Sol-Terra-Luna routing, Kanban traps, Hermes Cloud (preview), computer use, ecosystem radar +- ✅ 2026-07-17 — Power Secrets modernization: new Part 27 (Wingtips #1–#22 field manual + cheat sheet), new Part 28 Recipe Book (12 production builds), six new house-style infographics, v0.18.2 / `v2026.7.7.2` currency (Baileys fix, patch-rollup notes), MCP CVE table + checklist, seven-layer security model + spend kernels + action ontology, gateway token tax + stack benchmarking + Langfuse v4/OTEL, seven-rung agent ladder, Kimi K3 / Sol-Terra-Luna routing, Kanban traps, Hermes Cloud (preview), computer use, ecosystem radar - ✅ 2026-07-03 — Cross-link checker: anchor checking added (CI now fails on dead relative `./partN-foo.md` links *and* dead heading anchors; markdown-link-check shipped 2026-04-17) - ✅ 2026-07-01 — v0.17 "Reach" + v0.18 "Judgment" refresh: Part 26 MoA / verification / `/learn` + `/journey`, iMessage via Photon Spectrum, WhatsApp Business Cloud, Vertex AI provider, background subagent fan-out, desktop Projects + multi-terminal, gateway scale-to-zero, 25+ platform count, 27-part TOC - ✅ 2026-06-17 — v0.16 "Surface" refresh: Part 24 Hermes Desktop App, Part 25 NVIDIA & local hardware (DGX Spark / OpenShell / NemoClaw), new banner graphics, `/undo` + default-interface + fuzzy-picker power moves, native Windows installer, `hermes portal` Quick Setup, and a trim of stale per-version model tables to a model-agnostic section diff --git a/assets/recipe-book.svg b/assets/recipe-book.svg new file mode 100644 index 0000000..b9e908b --- /dev/null +++ b/assets/recipe-book.svg @@ -0,0 +1,87 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + THE RECIPE BOOK + TWELVE PRODUCTION BUILDS · SAME FIVE PIECES, ARRANGED DIFFERENTLY + + + + + + cron (schedule) → profile (identity) → skill (procedure) → tool / MCP (hands) → approval gate (brake) + + + + + + MONEY & OPERATIONS + CONTENT & CAREER + LIFE & LAB + + + + + + + + + + + 1 · Morning finance loopread-only brief · never trades + 2 · Staged Gmaildrafts only — no send scope exists + 3 · SMB approval officeone-tap human gates on every send + 4 · Overnight Kanban shiftcheckable tickets, diffs by coffee + 5 · GPU FIFO boardcapacity-1 lane = free job queue + + + 6 · Content swarmparallel drafts · human publishes + 7 · Carousel factory/learn your slide formula once + 8 · Job-hunt pipelinescrape → score → draft, staged + the rubric is the product — + a tight skill beats a smart model + + + 9 · Accountability coachtwo crons + streaks in MEMORY.md + 10 · Health correlatorlocal backend — data stays home + 11 · Blender roomheavy toolset gets its own profile + 12 · Secretary office3 roles · 1 board · 1 human brake + the minimal production stack + + + + + + + COMMUNITY FIELD REPORTS, MAPPED TO REAL PRIMITIVES — PART 28 + diff --git a/part27-power-secrets.md b/part27-power-secrets.md index df34fde..592dd44 100644 --- a/part27-power-secrets.md +++ b/part27-power-secrets.md @@ -263,6 +263,7 @@ Print this. Tape it somewhere. ## What's Next +- [Part 28: The Recipe Book](./part28-recipe-book.md) — twelve production builds that put these secrets to work - [Part 20: Observability & Cost](./part20-observability.md) — measure the tax before and after you fix it - [Part 19: Security Playbook](./part19-security-playbook.md) — the seven layers + spend kernels these secrets reference - [Part 26: MoA & Verification](./part26-moa-verification.md) — the verification contracts that tame busywork diff --git a/part28-recipe-book.md b/part28-recipe-book.md new file mode 100644 index 0000000..502c65e --- /dev/null +++ b/part28-recipe-book.md @@ -0,0 +1,145 @@ +# Part 28: The Recipe Book — Twelve Production Builds People Actually Run + +

+ The Recipe Book — twelve real-world Hermes builds across money & ops, content & career, and life & lab lanes +

+ +*Twelve end-to-end builds observed running in the wild in July 2026 — each mapped onto the real Hermes primitives this guide teaches. These are community-reported architectures (labelled as such); treat the configs as starting points and re-verify anything that touches money, email, or production systems against [Part 19](./part19-security-playbook.md) before going live.* + +--- + +## How to read a recipe + +Each recipe lists: **the loop** (what runs), **the primitives** (which Hermes features carry it), and **the trap** (what bit the people who built it first). Every recipe assumes the baseline from [Part 1](./part1-setup.md) and the approval posture from [Part 19](./part19-security-playbook.md). + +**The common skeleton** — most of these are the same five pieces arranged differently: + +```text +cron (schedule) → profile (identity) → skill (procedure) → tool/MCP (hands) → approval gate (brake) +``` + +--- + +## Lane 1 — Money & Operations + +### Recipe 1: The Morning Finance Loop + +**The loop:** a cron fires pre-market; the agent pulls positions and watchlist data, compares against your thesis notes in `MEMORY.md`, and DMs you a brief — *it never trades*. + +- **Primitives:** no-agent cron ([Part 23](./part23-tenacity-stack.md)) → cheap auxiliary model for the summary → Telegram DM delivery ([Part 4](./part4-telegram-setup.md)). +- **The brake:** this recipe is read-only by design. The moment an agent can *execute* trades you need an external spend kernel ([Part 19](./part19-security-playbook.md#external-spend-kernels-when-the-agent-touches-money)) — community consensus is unambiguous that policy caps must live *outside* the model. +- **The trap:** running the brief on your frontier model. It's a summarization job — route it to a Flash-class aux model and save the frontier calls for when you reply with a question. + +### Recipe 2: Staged Gmail — Drafts, Never Sends + +**The loop:** inbound email lands; the agent triages, drafts replies into the **Drafts folder**, and posts a daily digest of what's waiting. A human sends. + +- **Primitives:** Gmail MCP server with `tools.include` narrowed to read + draft (no send scope at all) ([Part 17](./part17-mcp-servers.md)), `approvals:` as a second net. +- **Why drafts:** *send* is a decision boundary (Layer 2). Removing the send scope entirely is stronger than approving each send — the capability doesn't exist to misuse. Inbound email is also the classic prompt-injection vector ([Part 19](./part19-security-playbook.md)): the drafting agent must be treated as reading untrusted input. +- **The trap:** giving the MCP server a full-scope OAuth token "to keep it simple." Separate token, minimum scopes, always. + +### Recipe 3: The SMB Approval Office + +**The loop:** a small business runs invoicing, follow-ups, and scheduling through one Hermes profile; every outbound action (invoice send, payment link, calendar change on a client) queues for a one-tap human approval in a Telegram operations group. + +- **Primitives:** one profile + `approvals:` on every system-of-record write, an ops group chat as the approval surface, Kanban board for pending work ([Part 23](./part23-tenacity-stack.md)). +- **The insight:** approvals at *decision boundaries* (send / spend / commit) — not on reads — keeps the human load to a few taps a day while removing the entire class of "the agent sent a client something weird" incidents. +- **The trap:** Telegram group privacy mode — the bot can't see group messages until you `/setprivacy` → Disable at BotFather **and remove/re-add the bot** ([Part 4](./part4-telegram-setup.md)). + +### Recipe 4: The Overnight Kanban Shift + +**The loop:** before signing off, load a Kanban board with well-specified tickets; workers grind through them overnight; you review diffs over coffee. + +- **Primitives:** `toolsets: [kanban]` on the worker profile (it's **not** in `all` — [Part 23](./part23-tenacity-stack.md)), `--workspace dir:/abs/path` so output survives, verification contracts per ticket ([Part 26](./part26-moa-verification.md)). +- **The insight:** overnight work only pays when tickets are *checkable* — "make it better" tickets produce morning archaeology; "make `pytest tests/auth` pass" tickets produce merged PRs. +- **The trap:** the default scratch workspace is wiped on completion. Absolute `dir:` workspace or your night's work is gone. + +### Recipe 5: The GPU FIFO Board + +**The loop:** one local GPU, many jobs. A capacity-1 Kanban lane serializes fine-tunes / renders / batch inference; each ticket claims the GPU, runs, reports, releases. + +- **Primitives:** Kanban lane with capacity 1 as a mutex ([Part 23](./part23-tenacity-stack.md)), local backend ([Part 25](./part25-nvidia-local.md)), cron to enqueue recurring jobs. +- **The insight:** the board *is* the queue — you get ordering, retry, and an audit trail for free instead of writing a job scheduler. + +--- + +## Lane 2 — Content & Career + +### Recipe 6: The Content Swarm + +**The loop:** an orchestrator takes one idea → parallel subagents draft platform-specific variants (thread, post, script) → orchestrator consolidates → **you approve before anything publishes**. + +- **Primitives:** `delegate_task` fan-out ([Part 8](./part8-subagent-patterns.md)), cheap models for drafting with one frontier pass for the final edit, `approvals:` on publish. +- **The insight:** this is rung 4 of the [agent ladder](./part8-subagent-patterns.md#the-seven-rung-agent-ladder) — parallel drafts are independent, so fan-out is nearly free time-wise. +- **The trap:** publish without an approval gate exactly once and you'll add the gate forever after. + +### Recipe 7: The Carousel Factory + +**The loop:** long-form source (blog post, transcript) → agent extracts the narrative spine → generates slide copy + image prompts → renders a carousel draft for review. + +- **Primitives:** a `/learn`-distilled skill capturing *your* slide formula ([Part 26](./part26-moa-verification.md)), image tooling via MCP, output to a reviewed folder — never straight to the platform. +- **The trap:** `/learn`'s auto-generated skill description will be a paragraph. Trim it to ≤60 chars or it taxes the tool-selection prompt on every turn ([Part 27](./part27-power-secrets.md)). + +### Recipe 8: The Job-Hunt Pipeline + +**The loop:** daily cron scrapes target-company postings → agent scores them against your `USER.md` profile and a criteria skill → drafts tailored cover letters into a review folder → weekly summary of the funnel. + +- **Primitives:** sequential pipeline (rung 3): scrape → score → draft, each stage checkable; `MEMORY.md` for standing criteria; drafts-not-sends posture from Recipe 2. +- **The insight:** the *scoring* stage is where the value is — a tight rubric in a skill beats a smart model with no rubric. + +--- + +## Lane 3 — Life & Lab + +### Recipe 9: The Accountability Coach + +**The loop:** morning cron asks for your top-3; evening cron asks what happened; the agent tracks streaks in `MEMORY.md` and gets progressively less polite about slippage (personality via `SOUL.md`). + +- **Primitives:** two crons, memory writes with `/memory approval on` if you don't want it editorializing your record, one profile whose `SOUL.md` you tune for the tone you'll actually respond to. +- **The trap:** memory snapshot semantics — the evening session won't *see* the morning's memory writes in its prompt unless it's a fresh session ([Part 27, Secret #1](./part27-power-secrets.md)). Cron sessions are fresh by default, which is why this works. + +### Recipe 10: The Health Correlator + +**The loop:** daily export from wearable/health apps into a local folder → agent appends to a running log → weekly job looks for correlations (sleep × training × mood) and writes a hypotheses note — *explicitly framed as hypotheses, not medical advice*. + +- **Primitives:** local backend for privacy ([Part 25](./part25-nvidia-local.md)) — this is the recipe where "your data never leaves the machine" stops being a slogan; file-based ingestion, no third-party MCP. +- **The insight:** local models are fully adequate here — the job is pattern-flagging over small structured data, not frontier reasoning. + +### Recipe 11: The Blender Room + +**The loop:** a dedicated `blender` profile drives Blender through its MCP server — scene setup, parametric edits, render queue — while your main profile stays clean of 3D tool definitions. + +- **Primitives:** separate profile as a "room" ([Part 8](./part8-subagent-patterns.md)), Blender MCP pinned to an exact version ([Part 17](./part17-mcp-servers.md)), GPU FIFO board (Recipe 5) if renders queue up. +- **The insight:** this is *the* case for profile separation — a heavy, niche toolset that would tax every prompt of your daily driver ([Part 27, Secret #7](./part27-power-secrets.md)) gets its own room instead. + +### Recipe 12: The Secretary Office + +**The loop:** the full stack — one VPS gateway, a default profile you talk to, an orchestrator profile that routes, implementer profiles that do; Telegram DM for you, an ops group for approvals; shared folder as the common filesystem; Kanban as the work ledger. + +- **Primitives:** everything above, composed: profiles ([Part 8](./part8-subagent-patterns.md)) + Kanban dispatch ([Part 23](./part23-tenacity-stack.md)) + approval gates ([Part 19](./part19-security-playbook.md)) + `loginctl enable-linger` so it survives logout ([Part 11](./part11-gateway-recovery.md)). +- **The insight:** this is the "minimal production stack" — most people who think they need a fleet need exactly this: three roles, one board, one human brake. +- **The trap:** profiles are identity isolation, **not** filesystem isolation — all of them can read each other's files unless you add a real OS boundary ([Part 19](./part19-security-playbook.md)). + +--- + +## Picking your first recipe + +| You are | Start with | Then add | +|---------|-----------|----------| +| A developer | Recipe 4 (overnight Kanban) | Recipe 12 as the work grows | +| Running a small business | Recipe 3 (approval office) | Recipe 2 (staged Gmail) | +| A creator | Recipe 6 (content swarm) | Recipe 7 (carousel factory) | +| Optimizing yourself | Recipe 9 (coach) | Recipe 10 (correlator, local) | +| A trader / finance person | Recipe 1 (read-only brief) | *Nothing that executes without a spend kernel* | + +--- + +## What's Next + +- [Part 27: Power Secrets](./part27-power-secrets.md) — the mechanics that make every recipe here cheaper and more reliable +- [Part 19: Security Playbook](./part19-security-playbook.md) — the approval and containment patterns every recipe leans on +- [Part 23: Tenacity Stack](./part23-tenacity-stack.md) — the Kanban machinery behind the ops recipes + +--- + +*These builds are community field reports from July 2026, mapped onto documented Hermes primitives. Where an original build used custom external code (spend kernels, action APIs), that's noted — Hermes orchestrates them but doesn't replace them.* diff --git a/part3-lightrag-setup.md b/part3-lightrag-setup.md index d2cdb89..d8f0e2e 100644 --- a/part3-lightrag-setup.md +++ b/part3-lightrag-setup.md @@ -464,6 +464,21 @@ rm -rf ~/.hermes/lightrag/LightRAG/rag_storage/* --- +## Scaling LightRAG: The July 2026 Playbook + +LightRAG moved fast this year. If your graph has outgrown the basic setup above, these are the upgrades that matter (in rough order of payoff): + +1. **Role-specific LLMs.** Extraction, entity-merging, and query answering are different jobs — point extraction at a cheap Flash-class model and keep your good model for query time. Same auxiliary-routing philosophy as [Part 20](./part20-observability.md). +2. **Chunking is the quality dial.** Most "the graph missed it" complaints are chunking, not retrieval. Chunk along document structure (headings/sections) rather than fixed token counts, and re-ingest — it's cheaper than tuning everything downstream. +3. **Multimodal ingestion.** The 2026 pipeline handles PDFs with figures/tables via a parse-then-describe pass — images become entity-linked descriptions in the graph rather than being dropped silently. Verify your ingest path actually processes them; the default text path skips images. +4. **Production stores.** Past a few GB of graph, move storage off the default local files to a real backend (e.g. OpenSearch) — the Web UI stays the same, rebuild times stop being scary. +5. **Evaluate before you tune.** Wire retrieval into your Langfuse traces ([Part 20](./part20-observability.md)) and score answer faithfulness with RAGAS-style checks on a fixed question set. One afternoon of eval setup ends months of vibes-driven tuning. +6. **Multi-agent retrieval.** For big corpora, a routed-specialist pattern ([Part 8](./part8-subagent-patterns.md)) — one subagent per collection, orchestrator merges — beats one mega-graph. + +Where LightRAG sits in the overall memory stack (vs native memory, Mem0, and skills): [Part 7](./part7-memory-system.md). + +--- + ## What's Next - **Need mobile access?** → [Part 4: Telegram Setup](./part4-telegram-setup.md) diff --git a/part5-creating-skills.md b/part5-creating-skills.md index ac16f04..6e8ded9 100644 --- a/part5-creating-skills.md +++ b/part5-creating-skills.md @@ -348,6 +348,10 @@ Hermes creates a skill with: **Keep skills focused.** A skill that tries to cover "all of DevOps" will be too long and too vague. A skill that covers "deploy a Python app to Fly.io" is specific enough to be genuinely useful. +**Give every skill a ≤60-character description.** The description of *every* skill rides along in the prompt so the agent can pick between them — long descriptions tax every turn. This especially applies to `/learn`-generated skills ([Part 26](./part26-moa-verification.md)), whose auto-written descriptions tend to be paragraphs: trim them after creation. And before writing a skill at all, check whether a built-in tool already does the job. + +**Gate self-written skills in production.** `/skills approval on` makes the agent propose skill creations/updates for your sign-off instead of applying them silently — pair it with `/memory approval on` on any shared or long-running agent ([Part 7](./part7-memory-system.md)). + --- ## How Hermes Decides to Save Skills