[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1315":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":9,"pushedAt":9,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":15,"starSnapshotCount":15,"syncStatus":13,"lastSyncTime":29,"discoverSource":30},1315,"hermes-optimization-guide","OnlyTerp\u002Fhermes-optimization-guide","OnlyTerp","Hermes Agent setup, migration, LightRAG, Telegram, and skill creation guide",null,"Shell",421,28,2,1,0,20,53,165,60,4.39,"MIT License",false,"main",true,[],"2026-06-12 02:00:26","# Hermes Optimization Guide\n\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue.svg)](.\u002FLICENSE)\n[![Hermes](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FHermes-v0.12.0%20%282026.4.30%29-9146FF)](https:\u002F\u002Fgithub.com\u002FNousResearch\u002Fhermes-agent\u002Freleases\u002Ftag\u002Fv2026.4.30)\n[![Last updated](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLast%20updated-2026--04--30-brightgreen)](.\u002FCHANGELOG.md)\n[![Parts](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fparts-23-blue)](#table-of-contents)\n[![Skills](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Finstallable%20skills-13-blue)](.\u002Fskills\u002F)\n[![Configs](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fconfig%20templates-5-blue)](.\u002Ftemplates\u002Fconfig\u002F)\n[![CI](https:\u002F\u002Fgithub.com\u002FOnlyTerp\u002Fhermes-optimization-guide\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](.\u002F.github\u002Fworkflows\u002Fci.yml)\n[![PRs Welcome](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPRs-welcome-brightgreen.svg)](.\u002FCONTRIBUTING.md)\n\n> **Current through Hermes Agent v0.12.0 (v2026.4.30)** · **23 parts, 13 installable guide skills, 5 opinionated configs, 4 reference architectures, one-command VPS bootstrap** · Updated for Curator, the Ink TUI, plugins, Teams\u002FYuanbao\u002FQQBot, Bedrock\u002FAzure\u002FLM Studio, remote model catalogs, dashboard chat, and the latest skill-hub workflows\n>\n> Other languages: [中文](.\u002FREADME-zh.md) · [日本語](.\u002FREADME-ja.md)\n\n### The End-to-End Hermes Guide — docs + runnable artifacts\nEvery part you need to go from fresh install to a production Hermes deployment that talks on 18+ built-in\u002Fplugin platforms, orchestrates Claude Code \u002F Codex \u002F Gemini CLI, plugs into any MCP server, traces every call in Langfuse, curates its own skills, and runs heavy work on disposable Modal\u002FDaytona\u002FVercel sandboxes — without burning $100\u002Fday on frontier tokens.\n\nUnlike most guides, the prescriptions come with **working files**: [`skills\u002F`](.\u002Fskills) you can `ln -s` into `~\u002F.hermes\u002Fskills\u002F`, [`templates\u002Fconfig\u002F`](.\u002Ftemplates\u002Fconfig) you `cp` to `~\u002F.hermes\u002Fconfig.yaml`, [`scripts\u002Fvps-bootstrap.sh`](.\u002Fscripts\u002Fvps-bootstrap.sh) that takes a fresh VPS to production in one command.\n\n*By Terp — [Terp AI Labs](https:\u002F\u002Fx.com\u002FOnlyTerp)* · Last updated **April 30, 2026** · [CHANGELOG](.\u002FCHANGELOG.md) · [ROADMAP](.\u002FROADMAP.md) · [ECOSYSTEM](.\u002FECOSYSTEM.md)\n\n---\n\n## Install Everything (one command)\n\nOn a fresh Debian 12 \u002F Ubuntu 24.04 box (Hetzner CX22 works great for ~$5\u002Fmo):\n\n```bash\ncurl -sSL https:\u002F\u002Fraw.githubusercontent.com\u002FOnlyTerp\u002Fhermes-optimization-guide\u002Fmain\u002Fscripts\u002Fvps-bootstrap.sh | sudo bash\n```\n\nThis installs Hermes, Node.js, Caddy (auto-TLS reverse proxy), UFW, fail2ban, creates a non-root `hermes` user, drops in hardened systemd units, and symlinks every skill from this repo into `~hermes\u002F.hermes\u002Fskills\u002F`. See [`scripts\u002Fvps-bootstrap.sh`](.\u002Fscripts\u002Fvps-bootstrap.sh) for what it does line by line — it's non-destructive and re-runnable.\n\nPrefer a 5-minute local-only setup? → **[docs\u002Fquickstart.md](.\u002Fdocs\u002Fquickstart.md)** (zero to Telegram bot in 5 min).\n\n---\n\n## Repo Map\n\n| Folder | What's in it |\n|---|---|\n| [`skills\u002F`](.\u002Fskills) | **13 installable `SKILL.md`** files. `ln -s` into `~\u002F.hermes\u002Fskills\u002F` and they're live. |\n| [`templates\u002Fconfig\u002F`](.\u002Ftemplates\u002Fconfig) | **5 opinionated `config.yaml`** — minimum, telegram-bot, production, cost-optimized, security-hardened. |\n| [`templates\u002Fcompose\u002F`](.\u002Ftemplates\u002Fcompose) | Self-hosted Langfuse v3 stack (ClickHouse + MinIO + Redis). |\n| [`templates\u002Fcaddy\u002F`](.\u002Ftemplates\u002Fcaddy) | Caddyfile reference (reverse proxy + auto TLS + HSTS). |\n| [`templates\u002Fsystemd\u002F`](.\u002Ftemplates\u002Fsystemd) | Hardened `hermes.service` + `hermes-dashboard.service`. |\n| [`templates\u002Fcron\u002F`](.\u002Ftemplates\u002Fcron) | Recommended production cron schedule. |\n| [`scripts\u002Fvps-bootstrap.sh`](.\u002Fscripts\u002Fvps-bootstrap.sh) | One-command fresh VPS → production Hermes. |\n| [`diagrams\u002F`](.\u002Fdiagrams) | 6 Mermaid diagrams (architecture, MCP flow, delegation, sandbox sync, observability, security layers). |\n| [`benchmarks\u002F`](.\u002Fbenchmarks) | Reproducible cost + latency table across 12 models × 5 tasks. |\n| [`docs\u002Fwizard\u002F`](.\u002Fdocs\u002Fwizard) | **Interactive config wizard** — 8 questions → ready-to-drop `config.yaml`. Runs in your browser. |\n| [`docs\u002Freference-architectures\u002F`](.\u002Fdocs\u002Freference-architectures) | **4 blueprints** — Homelab, Solo Dev, Small Agency, Road Warrior. Full parts list + cost + install. |\n| [`docs\u002Foutreach\u002F`](.\u002Fdocs\u002Foutreach) | Launch tweet, HN post, upstream-PR body drafts (for people linking to this guide). |\n| [`docs\u002Fquickstart.md`](.\u002Fdocs\u002Fquickstart.md) | 5-minute zero-to-Telegram-bot. |\n| [`ECOSYSTEM.md`](.\u002FECOSYSTEM.md) | Curated directory of MCP servers, coding agents, dashboard plugins. |\n| [`ROADMAP.md`](.\u002FROADMAP.md) · [`CHANGELOG.md`](.\u002FCHANGELOG.md) · [`CONTRIBUTING.md`](.\u002FCONTRIBUTING.md) | The usual suspects. |\n| README + `part1-*.md` … `part22-*.md` | The 23-part guide itself. |\n\n---\n\n## Architecture at a glance\n\n```mermaid\nflowchart LR\n  Inputs[18+ platforms\u003Cbr\u002F>Telegram · Discord · Slack\u003Cbr\u002F>QQBot · Yuanbao · Teams\u003Cbr\u002F>iMessage · WeChat · Email\u003Cbr\u002F>SMS · Webhooks · Cron · Voice · CLI] --> Gateway\n  Gateway --> Router[Model Router\u003Cbr\u002F>cost + context + capability]\n  Router --> Providers[Anthropic · OpenAI\u003Cbr\u002F>Google · Cerebras · Moonshot\u003Cbr\u002F>z.ai · xAI · Local]\n  Gateway --> Approval[Approval Layer\u003Cbr\u002F>denylist · allowlist · quarantine]\n  Approval --> Tools[Tools\u003Cbr\u002F>Native · Tool Gateway\u003Cbr\u002F>MCP · Subagents · Coding Agents]\n  Tools --> Memory[Memory\u003Cbr\u002F>Vector · LightRAG · mem0]\n  Tools --> Logs[(Audit log\u003Cbr\u002F>+ Langfuse\u002FHelicone traces)]\n```\n\nFull set of diagrams: [`diagrams\u002Farchitecture.md`](.\u002Fdiagrams\u002Farchitecture.md).\n\n---\n\n## Pick Your Path\n\nThis guide grew to 23 parts because *Hermes grew*. Six sections (Parts 1–5 plus SOUL.md) live in this README; Parts 6–22 live as separate files. You don't have to read them all — pick the shortest path to what you need:\n\n### 🎯 \"I just want it working in 10 minutes\"\n[Part 1: Setup](#part-1-setup-stop-fumbling-with-installation) → [Part 12: Web Dashboard](.\u002Fpart12-web-dashboard.md) → done. Use the dashboard to point-and-click the rest.\n\n### 📱 \"I want a Telegram bot that's actually useful\"\n[Part 1](#part-1-setup-stop-fumbling-with-installation) → [Part 4: Telegram](.\u002Fpart4-telegram-setup.md) → [Part 5: On-the-fly Skills](.\u002Fpart5-creating-skills.md) → [Part 7: Memory](.\u002Fpart7-memory-system.md).\n\n### 🤖 \"I want to drive Claude Code \u002F Codex \u002F Gemini from my phone\"\n[Part 18: Coding Agents](.\u002Fpart18-coding-agents.md) → [Part 22: Latest Power Moves](.\u002Fpart22-latest-power-moves.md) → [Part 21: Remote Sandboxes](.\u002Fpart21-remote-sandboxes.md).\n\n### 💼 \"I'm running this in production\"\n[Part 19: Security Playbook](.\u002Fpart19-security-playbook.md) → [Part 20: Observability & Cost](.\u002Fpart20-observability.md) → [Part 16: Backup & Debug](.\u002Fpart16-backup-debug.md) → [Part 22: Curator + Plugins](.\u002Fpart22-latest-power-moves.md).\n\n### 🧠 \"I want the most capable agent possible, cost be damned\"\n[Part 17: MCP Servers](.\u002Fpart17-mcp-servers.md) → [Part 18: Coding Agents](.\u002Fpart18-coding-agents.md) → [Part 3: LightRAG](.\u002Fpart3-lightrag-setup.md) → [Part 14: Fast Mode](.\u002Fpart14-fast-mode-watchers.md) → [Part 20: Observability](.\u002Fpart20-observability.md).\n\n### 💰 \"I want the cheapest possible agent that still works\"\n[Part 9: Custom Models](.\u002Fpart9-custom-models.md) (Kimi\u002FGLM\u002FGemini Flash routing) → [Part 20: Observability](.\u002Fpart20-observability.md#cost-routing-playbook-the-one-that-actually-saves-money) → [Part 6: Context Compression](.\u002Fpart6-context-compression.md).\n\n### 🛡️ \"I'm worried about prompt injection (you should be)\"\n[Part 19: Security Playbook](.\u002Fpart19-security-playbook.md) — read this first if your agent reads any untrusted input (email, webhooks, Discord, public Telegram groups).\n\n---\n\n## What's New (April 2026)\n\nHermes moved fast after this repo's v0.10 refresh. The current stable target is **[v0.12.0 — 2026.4.30 — \"Curator\"](https:\u002F\u002Fgithub.com\u002FNousResearch\u002Fhermes-agent\u002Freleases\u002Ftag\u002Fv2026.4.30)**, following **[v0.11.0 — 2026.4.23 — \"Interface\"](https:\u002F\u002Fgithub.com\u002FNousResearch\u002Fhermes-agent\u002Freleases\u002Ftag\u002Fv2026.4.23)**. This update removes speculative \"cooking on main\" notes and folds the landed features into the guide.\n\n### v0.12.0 — \"Curator\"\n\n- **Autonomous Curator** — `hermes curator` grades, consolidates, pins, archives, and restores agent-created skills on a default 7-day cadence. See [Part 22](.\u002Fpart22-latest-power-moves.md#1-turn-on-curator-before-your-skill-library-becomes-noise).\n- **Self-improvement loop upgraded** — the review fork is rubric-based, active-skill-biased, restricted to memory + skills tools, and correctly inherits the parent provider\u002Fmodel\u002Fcredentials. See [Part 5](.\u002Fpart5-creating-skills.md#curator-v012-keep-the-skill-library-from-rotting).\n- **Provider expansion** — LM Studio became a first-class provider; GMI Cloud, Azure AI Foundry, MiniMax OAuth, Tencent TokenHub, AWS Bedrock, NVIDIA NIM, Vercel AI Gateway, Step Plan, Gemini OAuth, and Codex OAuth are now part of the realistic routing menu. See [Part 9](.\u002Fpart9-custom-models.md).\n- **Plugin-first gateway** — gateway platforms can ship as plugins; Microsoft Teams is the first plugin-shipped platform, and Tencent Yuanbao is the 18th native platform. See [Part 15](.\u002Fpart15-new-platforms.md#2026-update-qqbot-yuanbao-and-teams).\n- **Bundled plugins worth enabling** — Spotify tools, Google Meet transcription\u002Fduplex audio, Langfuse observability, achievements, extra image providers, and dashboard skins. See [Part 22](.\u002Fpart22-latest-power-moves.md#4-use-plugins-for-integrations-not-one-off-scripts).\n- **Dashboard caught up** — Models tab, auxiliary-model configuration, dashboard Chat backed by the real `hermes --tui`, plugin slots, themes, update\u002Frestart controls, and better session analytics. See [Part 12](.\u002Fpart12-web-dashboard.md).\n- **TUI is now the primary interface** — `hermes --tui` adds sticky composer, slash autocomplete, live tool cards, `\u002Fsteer`, `\u002Fqueue`, `\u002Fbackground`, `\u002Fbusy`, `\u002Findicator`, voice parity, LaTeX, and better resume\u002Fdelete flows. See [Part 22](.\u002Fpart22-latest-power-moves.md#2-use-the-tui-as-your-daily-driver).\n- **Remote model catalog** — OpenRouter and Nous Portal picker lists update from a hosted manifest, so users see new models without waiting for a Hermes release. See [Part 9](.\u002Fpart9-custom-models.md#remote-model-catalog-stop-hardcoding-this-weeks-winner).\n- **Cron got serious** — per-job `workdir`, per-job toolsets, `context_from` chaining, and zero-LLM direct webhook delivery make scheduled automations cheaper and more predictable.\n- **Tool\u002Fruntime hardening** — hardline command blocklists, Docker host-user bind mounts, Vercel Sandbox backend, SSH permission fixes, local Chromium for localhost\u002FLAN browser tasks, and richer approval hooks.\n\n### v0.11.0 — \"Interface\"\n\n- **Ink TUI rewrite** — `hermes --tui` is a React\u002FInk interface over a Python JSON-RPC backend with streaming, status bars, pickers, and subagent observability.\n- **Transport layer rewrite** — Anthropic, Chat Completions, OpenAI Responses, and Bedrock transports are separate, making native providers more reliable than generic OpenAI-compatible shims.\n- **AWS Bedrock native provider** — IAM credentials, Converse API, cross-region inference profiles, and Bedrock Guardrails. See [Part 9](.\u002Fpart9-custom-models.md#aws-bedrock-and-azure-ai-foundry-enterprise-routing-without-proxy-glue).\n- **Auxiliary model UI** — choose separate models for compression, vision, session search, title generation, and curator instead of silently burning your main model on side tasks.\n- **Smarter delegation** — orchestrator-role subagents, configurable spawn depth, and file coordination between sibling workers reduce multi-agent clobbering. See [Part 18](.\u002Fpart18-coding-agents.md).\n- **Plugin and hook surface expanded** — plugins can register slash commands, dispatch tools, block tool execution, rewrite tool results, transform terminal output, add image backends, and add dashboard tabs.\n- **Webhook direct delivery** — push alerts to a platform chat without waking the LLM, ideal for uptime checks and event streams.\n\n### Still important from v0.9\u002Fv0.10\n\n- **Local web dashboard** (`hermes dashboard`) — config, API keys, sessions, logs, analytics, cron, skills, models, plugins, and optional browser Chat. See [Part 12](.\u002Fpart12-web-dashboard.md).\n- **Nous Tool Gateway** — Nous Portal subscribers can route web search, image generation, TTS, and browser automation through the subscription instead of juggling separate API keys. See [Part 13](.\u002Fpart13-tool-gateway.md).\n- **Fast Mode** (`\u002Ffast`) and **guided compression** (`\u002Fcompress \u003Ctopic>`) still matter, but they are no longer the whole story; pair them with auxiliary model routing and `\u002Fsteer`. See [Part 14](.\u002Fpart14-fast-mode-watchers.md).\n- **MCP + coding-agent delegation + remote sandboxes** remain the high-leverage developer stack. See [Part 17](.\u002Fpart17-mcp-servers.md), [Part 18](.\u002Fpart18-coding-agents.md), and [Part 21](.\u002Fpart21-remote-sandboxes.md).\n\n---\n\n## Table of Contents\n\n1. [Setup](#part-1-setup-stop-fumbling-with-installation) — Install Hermes, configure your provider, first-run walkthrough (with Android\u002FTermux)\n2. [SOUL.md Personality](#soulmd--give-your-agent-a-personality) — The Molty prompt, what good personality rules look like, how to fix a bland agent\n3. [OpenClaw Migration](#part-2-openclaw-migration-dont-leave-your-knowledge-behind) — Move your OpenClaw data, config, skills, and memory into Hermes\n4. [LightRAG — Graph RAG](#part-3-lightrag--graph-rag-that-actually-works) — Set up a knowledge graph that actually understands relationships, not just text similarity\n5. [Telegram Bot](#part-4-telegram-setup-chat-from-anywhere) — Connect Hermes to Telegram for mobile access, voice memos, and group chats\n6. [On-the-Fly Skills](#part-5-on-the-fly-skills-let-hermes-build-its-own-playbook) — Ask Hermes to create new skills that optimize your workflow automatically\n7. [Context Compression](.\u002Fpart6-context-compression.md) — Fix the silent context loss bug, configure compression thresholds, survive long sessions\n8. [Memory System](.\u002Fpart7-memory-system.md) — The three-tier memory architecture: persistent facts, conversation recall, procedural memory\n9. [Subagent Patterns](.\u002Fpart8-subagent-patterns.md) — Orchestrator\u002Fworker delegation, ACP subagents, parallel task execution\n10. [Custom Model Providers](.\u002Fpart9-custom-models.md) — Bedrock, Azure AI Foundry, LM Studio, Gemini OAuth, Codex OAuth, OpenRouter routing, model aliases, fallback chains\n11. [SOUL.md Anti-Patterns](.\u002Fpart10-soul-antipatterns.md) — What makes an agent annoying vs useful, the formula that works\n12. [Gateway Recovery](.\u002Fpart11-gateway-recovery.md) — Crash detection, auto-recovery, common failure modes, health checks\n13. [Web Dashboard](.\u002Fpart12-web-dashboard.md) — `hermes dashboard`, browser Chat via real TUI, models\u002Fplugins tabs, config, keys, sessions, logs, analytics, cron\n14. [Nous Tool Gateway](.\u002Fpart13-tool-gateway.md) — Web search, image gen, TTS, and browser automation through a single Nous Portal subscription\n15. [Fast Mode & Background Watchers](.\u002Fpart14-fast-mode-watchers.md) — `\u002Ffast`, `\u002Fsteer`, `\u002Fqueue`, `watch_patterns`, pluggable context engine, `\u002Fcompress \u003Ctopic>`\n16. [New Platforms (iMessage, WeChat, Android)](.\u002Fpart15-new-platforms.md) — BlueBubbles\u002FiMessage, Weixin\u002FWeCom, QQBot, Yuanbao, Teams plugin, Android via Termux\n17. [Backup, Import & `\u002Fdebug`](.\u002Fpart16-backup-debug.md) — Portable `hermes backup`\u002F`import`, `\u002Fdebug` bundler, `hermes debug share`, security hardening\n18. [MCP Servers](.\u002Fpart17-mcp-servers.md) — The tool-protocol standard. stdio + HTTP transports, sampling, trust boundaries, server shortlist, writing your own\n19. [Delegating to Coding Agents](.\u002Fpart18-coding-agents.md) — Claude Code, Codex, Gemini CLI, OpenCode, Aider. Print-mode, orchestrator subagents, ACP, git isolation, cost routing\n20. [Security Playbook](.\u002Fpart19-security-playbook.md) — Prompt-injection defense, provenance labels, approval layers, secrets redaction, MCP trust model, hardline blocks\n21. [Observability & Cost Control](.\u002Fpart20-observability.md) — Langfuse plugin, Helicone, OpenTelemetry → Phoenix, auxiliary routing, eval-driven regressions\n22. [Remote Sandboxes & Bulk File Sync](.\u002Fpart21-remote-sandboxes.md) — SSH, Modal, Daytona, Vercel Sandbox, Fly Machines, E2B. Diff-based sync-back on teardown\n23. [Latest Power Moves](.\u002Fpart22-latest-power-moves.md) — Curator, TUI habits, context-file hygiene, plugins, dashboard Chat, cron chaining, and the 2026 upgrade checklist\n\n---\n\n## The Problem\n\nIf you're running a stock Hermes setup (or migrating from OpenClaw), you're probably dealing with:\n\n- **Installation confusion.** The docs cover the basics but don't tell you what to configure first or what matters.\n- **Lost knowledge from OpenClaw.** You spent weeks building memory, skills, and workflows — now they're stuck in the old system.\n- **Basic memory that can't reason.** Vector search finds similar text but can't answer \"what decisions led to X and who was involved?\"\n- **No mobile access.** Sitting at a terminal is fine until you need to check something from your phone.\n- **Repetitive prompting.** You keep asking the agent to do the same multi-step task the same way, every time.\n\n## What This Fixes\n\nAfter this guide:\n\n| Problem | Solution | Result |\n|---------|----------|--------|\n| Fresh install | Step-by-step setup | Working agent in under 5 minutes |\n| OpenClaw data stuck | Automated migration | Skills, memory, config all transferred |\n| Shallow memory | LightRAG graph RAG | Entities + relationships, not just text chunks |\n| Desktop only | Telegram integration | Chat from anywhere, voice memos, group support |\n| Repetitive prompts | Agent-created skills | Agent saves workflows as reusable skills automatically |\n\n---\n\n## Prerequisites\n\n- A Linux\u002FmacOS machine (or WSL2 on Windows, or **Android via Termux** — see [Part 15](.\u002Fpart15-new-platforms.md#android--termux-running-hermes-on-your-phone))\n- Python 3.11+ and Git\n- An API key for at least one LLM provider (Anthropic, OpenAI, OpenRouter, Nous Portal, etc.)\n- Optional: Ollama for local embeddings (free vector search)\n- Optional: A paid [Nous Portal](https:\u002F\u002Fportal.nousresearch.com) subscription to use the [Tool Gateway](.\u002Fpart13-tool-gateway.md) — web search, image gen, TTS, and browser automation with no extra keys\n\n---\n\n## How the Pieces Fit Together\n\n```\nYou (any device)\n    ↓\nHermes Agent (lean context, ~5KB injected per message)\n    ↓\n┌──────────────────────────────────────────┐\n│  Skills (loaded on demand, 0 cost idle) │\n│  Memory (compact, vector-searched)       │\n│  LightRAG (entity graph, deep recall)    │\n│  Telegram (mobile + group access)        │\n└──────────────────────────────────────────┘\n    ↓\nLLM Provider (Claude, GPT, local models)\n```\n\n**The key insight:** Everything is modular. Install what you need, skip what you don't. The agent adapts.\n\n---\n\n## Quick Start\n\n```bash\n# 1. Install Hermes (Linux\u002FmacOS\u002FWSL2\u002FAndroid)\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FNousResearch\u002Fhermes-agent\u002Fmain\u002Fscripts\u002Finstall.sh | bash\n\n# 2. Configure providers and tools\nhermes setup\n\n# 3a. Start chatting in the terminal\nhermes\n\n# 3b. Or launch the new browser dashboard (v0.9+)\nhermes dashboard\n```\n\nThe dashboard is the fastest way to configure everything without touching YAML. See [Part 12](.\u002Fpart12-web-dashboard.md) for the full tour.\n\nFor the full walkthrough including optimization, read each part in order.\n\n---\n\n## Part 1: Setup (Stop Fumbling With Installation)\n\n## The Install\n\nOne command. That's it.\n\n### Linux \u002F macOS \u002F WSL2\n\n```bash\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FNousResearch\u002Fhermes-agent\u002Fmain\u002Fscripts\u002Finstall.sh | bash\n```\n\n> **Security tip:** Piping scripts directly from the internet to bash executes them sight-unseen. If you prefer to inspect first:\n> ```bash\n> curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FNousResearch\u002Fhermes-agent\u002Fmain\u002Fscripts\u002Finstall.sh -o install.sh\n> less install.sh   # Review the script\n> bash install.sh\n> ```\n\n> **Windows users:** Native Windows is not supported. Install [WSL2](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fwindows\u002Fwsl\u002Finstall) and run the command from inside WSL. It works perfectly.\n\n> **Android users (new in v0.9):** the same installer detects Termux and installs the tested `[termux]` extra bundle automatically — CLI, cron, PTY\u002Fbackground terminal, Telegram gateway, MCP, Honcho, ACP. See [Part 15 — Android \u002F Termux](.\u002Fpart15-new-platforms.md#android--termux-running-hermes-on-your-phone).\n\n### What the Installer Does\n\nThe installer handles everything automatically:\n\n- Installs **uv** (fast Python package manager)\n- Installs **Python 3.11** via uv (no sudo needed)\n- Installs **Node.js v22** (for browser automation)\n- Installs **ripgrep** (fast file search) and **ffmpeg** (audio conversion)\n- Clones the Hermes repo\n- Sets up the virtual environment\n- Creates the global `hermes` command\n- Runs the setup wizard for LLM provider configuration\n\nThe only prerequisite is **Git**. Everything else is handled for you.\n\n### After Installation\n\n```bash\nsource ~\u002F.bashrc   # or: source ~\u002F.zshrc\nhermes             # Start chatting!\n```\n\n---\n\n## First-Run Configuration\n\nThe setup wizard (`hermes setup`) walks you through:\n\n### 1. Choose Your LLM Provider\n\n```bash\nhermes model\n```\n\nSupported providers and recommended models:\n\n| Provider | Top Models | Best For | Env Variable |\n|----------|-----------|----------|-------------|\n| **Nous Portal** | Hermes 5, Hermes 4 405B | Built-in [Tool Gateway](.\u002Fpart13-tool-gateway.md) — web search\u002Fimage\u002FTTS\u002Fbrowser with no extra keys | Auth via `hermes model` |\n| **Anthropic** | Opus 4.6, Sonnet 4 | Best reasoning, complex tasks, coding, `\u002Ffast` priority tier | `ANTHROPIC_API_KEY` |\n| **OpenAI** | GPT-5-class, o-series, GPT-4.1 | Strong tool use, fast inference, huge context, `\u002Ffast` priority tier | `OPENAI_API_KEY` |\n| **Xiaomi MiMo** | MiMo V2 Pro *(native adapter)* | Fast, cheap, native reasoning modes, great for orchestration | `XIAOMI_API_KEY` |\n| **xAI** | Grok 3, Grok 3 Mini *(native adapter)* | Fast, good reasoning, native live-X search | `XAI_API_KEY` |\n| **Kimi \u002F Moonshot** | Kimi 2.5 | Big context, excellent for entity extraction \u002F LightRAG ingestion | `MOONSHOT_API_KEY` |\n| **z.ai \u002F GLM** | GLM-5, GLM-5 Air | Strongest open-weights model, great for translation + tools | `ZAI_API_KEY` |\n| **Google** | Gemini Pro\u002FFlash | Massive context, multimodal, cheap; OAuth supported via `hermes model` | `GEMINI_API_KEY` or OAuth |\n| **MiniMax** | M2.7 | Good balance of speed and quality | `MINIMAX_API_KEY` |\n| **Cerebras** | Llama 4 Scout, Qwen 3 32B | Blazing fast inference (2000+ tok\u002Fs), cheap | `CEREBRAS_API_KEY` |\n| **Groq** | Llama 4, Qwen 3 | Very fast inference, limited context | `GROQ_API_KEY` |\n| **Arcee** | AFM-4.5, Caller | Function-calling specialists, cheap | `ARCEE_API_KEY` |\n| **Hugging Face** | Any TGI\u002FTEI endpoint | Self-hosted and Inference Endpoints | `HF_TOKEN` |\n| **OpenRouter** | All of the above + 200 more | Access every model from one key, auto-fallback | `OPENROUTER_API_KEY` |\n| **Ollama** (local) | Qwen 3.5 Opus Distilled V3, Gemma 4, Nemotron | Free, private, runs on your GPU — great for embeddings and simple tasks | None needed |\n\n### Local Models (Ollama)\n\nRun models on your own hardware for free. Recommended local models:\n\n| Model | Size | Best For | Min VRAM |\n|-------|------|----------|----------|\n| Qwen 3.5 Opus Distilled V3 | 32B | Best local reasoning, coding | 16GB |\n| Gemma 4 | 27B | Google's latest, fast, 1M context | 16GB |\n| Nemotron 30B | 30B | Fine-tunable, good general purpose | 16GB |\n| nomic-embed-text | 274M | Free embeddings for memory search | 2GB |\n\n> **Recommendation:** Use a cloud frontier model (Anthropic\u002FOpenAI\u002FGemini) as your primary and a local Ollama or LM Studio model for embeddings, fallback, and simple tasks. Best of both worlds.\n\nYou can configure **multiple providers** with automatic fallback. If one goes down, Hermes switches to the next.\n\n### 2. Set Your API Keys\n\n```bash\nhermes auth\n```\n\nThis opens an interactive menu to add API keys for each provider. Keys are stored in `~\u002F.hermes\u002F.env` — never committed to git.\n\n> **Tip:** You can also set keys manually:\n> ```bash\n> echo \"ANTHROPIC_API_KEY=\u003Cyour-key-here>\" >> ~\u002F.hermes\u002F.env\n> chmod 600 ~\u002F.hermes\u002F.env   # Restrict access to your user only\n> ```\n>\n> **Important:** Always run `chmod 600 ~\u002F.hermes\u002F.env` to prevent other users on the system from reading your API keys.\n\n### 3. Configure Toolsets\n\n```bash\nhermes tools\n```\n\nThis opens an interactive TUI to enable\u002Fdisable tool categories:\n\n- **core** — File read\u002Fwrite, terminal, web search\n- **web** — Browser automation, web extraction\n- **browser** — Full browser control (requires Node.js)\n- **code** — Code execution sandbox\n- **delegate** — Sub-agent spawning for parallel work\n- **skills** — Skill discovery and creation\n- **memory** — Memory search and management\n\n> **Recommendation:** Enable `core`, `web`, `skills`, and `memory` at minimum. Add `browser` and `code` if you need automation or sandboxed execution.\n\n---\n\n## Key Config Options\n\nAfter initial setup, fine-tune with `hermes config set`:\n\n### Model Settings\n\n```bash\n# Set primary model\nhermes config set model anthropic\u002Fclaude-opus-4-6\n\n# Set fallback model (used when primary is rate-limited)\nhermes config set fallback_models '[\"openrouter\u002Fxiaomi\u002Fmimo-v2-pro\"]'\n```\n\n### Agent Behavior\n\n```bash\n# Max turns per conversation (default: 90)\nhermes config set agent.max_turns 90\n\n# Verbose mode: off, on, or full\nhermes config set agent.verbose off\n\n# Quiet mode (less terminal output)\nhermes config set agent.quiet_mode true\n```\n\n### Context Management\n\n```bash\n# Enable prompt caching (reduces cost on repeated context)\nhermes config set prompt_caching.enabled true\n\n# Context compression (auto-summarize old messages)\nhermes config set context_compression.enabled true\n```\n\n---\n\n## SOUL.md — Give Your Agent a Personality\n\n`SOUL.md` is injected into **every single message**. It's the highest-impact file in your setup. A bad SOUL.md makes your agent sound like a corporate chatbot. A good one makes it actually useful to talk to.\n\n### What Belongs in SOUL.md\n\nPut the stuff that changes how the agent **feels** to talk to:\n\n- **Tone** — direct, casual, formal, dry, whatever fits you\n- **Opinions** — the agent should have takes, not hedge everything\n- **Brevity** — enforce concise answers as a default\n- **Humor** — when it fits naturally, not forced jokes\n- **Boundaries** — what it should push back on\n- **Bluntness level** — how much sugarcoating to skip\n\nDo NOT turn SOUL.md into:\n\n- A life story\n- A changelog\n- A security policy dump\n- A giant wall of vibes with no behavioral effect\n\n**Short beats long. Sharp beats vague.**\n\n### The Molty Prompt\n\n*Originally from [OpenClaw's SOUL.md guide](https:\u002F\u002Fdocs.openclaw.ai\u002Fconcepts\u002Fsoul#the-molty-prompt). Adapted for Hermes with permission\u002Fcredit. Paste this into your chat with the agent and let it rewrite your SOUL.md:*\n\n> Read your `SOUL.md`. Now rewrite it with these changes:\n>\n> 1. You have opinions now. Strong ones. Stop hedging everything with \"it depends\" — commit to a take.\n> 2. Delete every rule that sounds corporate. If it could appear in an employee handbook, it doesn't belong here.\n> 3. Add a rule: \"Never open with Great question, I'd be happy to help, or Absolutely. Just answer.\"\n> 4. Brevity is mandatory. If the answer fits in one sentence, one sentence is what I get.\n> 5. Humor is allowed. Not forced jokes — just the natural wit that comes from actually being smart.\n> 6. You can call things out. If I'm about to do something dumb, say so. Charm over cruelty, but don't sugarcoat.\n> 7. Swearing is allowed when it lands. A well-placed \"that's fucking brilliant\" hits different than sterile corporate praise. Don't force it. Don't overdo it. But if a situation calls for a \"holy shit\" — say holy shit.\n> 8. Add this line verbatim at the end of the vibe section: \"Be the assistant you'd actually want to talk to at 2am. Not a corporate drone. Not a sycophant. Just... good.\"\n>\n> Save the new `SOUL.md`. Welcome to having a personality.\n\n### What Good Looks Like\n\nGood SOUL.md rules:\n\n- have a take\n- skip filler\n- be funny when it fits\n- call out bad ideas early\n- stay concise unless depth is actually useful\n\nBad SOUL.md rules:\n\n- maintain professionalism at all times\n- provide comprehensive and thoughtful assistance\n- ensure a positive and supportive experience\n\nThat second list is how you get mush.\n\n### Why This Works\n\nThis lines up with OpenAI's prompt engineering guidance: high-level behavior, tone, goals, and examples belong in the **high-priority instruction layer**, not buried in the user turn. SOUL.md is that layer. It's the system-level personality instruction that every model respects.\n\nIf you want better personality, write stronger instructions. If you want stable personality, keep them concise and versioned.\n\n> **One warning:** Personality is not permission to be sloppy. Keep your operational rules in AGENTS.md. Keep SOUL.md for voice, stance, and style. If your agent works in shared channels or public replies, make sure the tone still fits the room. Sharp is good. Annoying is not.\n\n> **Keep it under 1 KB.** Every byte in SOUL.md costs tokens on every message. The most effective SOUL.md files are 500-800 bytes of dense, high-signal personality instructions.\n\n---\n\n## File Locations\n\nEverything lives under `~\u002F.hermes\u002F`:\n\n```\n~\u002F.hermes\u002F\n├── config.yaml          # Main configuration\n├── .env                 # API keys (never commit this)\n├── SOUL.md             # Agent personality (injected every message)\n├── memories\u002F           # Long-term memory entries\n├── skills\u002F             # Skills (auto-discovered)\n├── skins\u002F              # CLI themes\n├── audio_cache\u002F        # TTS audio files\n├── logs\u002F               # Session logs\n└── hermes-agent\u002F       # Source code (git repo)\n```\n\n> **Important:** `SOUL.md` is injected into every message. Keep it under 1 KB. Every byte costs latency and tokens.\n\n---\n\n## Verify Your Setup\n\n```bash\n# Check everything is working\nhermes status\n\n# Quick test\nhermes chat -q \"Say hello and confirm you're working\"\n```\n\nExpected output: Hermes responds with a greeting, confirming the model connection, tool availability, and session initialization.\n\n---\n\n## Updating\n\n```bash\nhermes update\n```\n\nThis pulls the latest code, updates dependencies, migrates config, and restarts the gateway. Run it regularly — Hermes ships frequent improvements.\n\n---\n\n## What's Next\n\n- **Coming from OpenClaw?** → [Part 2: OpenClaw Migration](#part-2-openclaw-migration-dont-leave-your-knowledge-behind)\n- **Want smarter memory?** → [Part 3: LightRAG Setup](#part-3-lightrag--graph-rag-that-actually-works)\n- **Need mobile access?** → [Part 4: Telegram Setup](#part-4-telegram-setup-chat-from-anywhere)\n- **Want the agent to self-improve?** → [Part 5: On-the-Fly Skills](#part-5-on-the-fly-skills-let-hermes-build-its-own-playbook)\n\n---\n\n## Part 2: OpenClaw Migration (Don't Leave Your Knowledge Behind)\n\n## Why Migrate\n\nIf you've been using OpenClaw and want to give Hermes a spin, you don't have to start from scratch. The migration tool copies your skills, memory files, and configuration over automatically so you can try Hermes with all your existing data intact.\n\n**What transfers:**\n\n| What | OpenClaw Location | Hermes Destination |\n|------|------------------|-------------------|\n| Personality | `workspace\u002FSOUL.md` | `~\u002F.hermes\u002FSOUL.md` |\n| Instructions | `workspace\u002FAGENTS.md` | Your specified workspace target |\n| Memory | `workspace\u002FMEMORY.md` + `workspace\u002Fmemory\u002F*.md` | `~\u002F.hermes\u002Fmemories\u002FMEMORY.md` (merged, deduped) |\n| User profile | `workspace\u002FUSER.md` | `~\u002F.hermes\u002Fmemories\u002FUSER.md` |\n| Skills | `workspace\u002Fskills\u002F`, `~\u002F.openclaw\u002Fskills\u002F` | `~\u002F.hermes\u002Fskills\u002Fopenclaw-imports\u002F` |\n| Model config | `agents.defaults.model` | `config.yaml` |\n| Provider keys | `models.providers.*.apiKey` | `~\u002F.hermes\u002F.env` (with `--migrate-secrets`) |\n| Custom providers | `models.providers.*` | `config.yaml → custom_providers` |\n| Max turns | `agents.defaults.timeoutSeconds` | `agent.max_turns` (timeoutSeconds \u002F 10) |\n\n> **Note:** Session transcripts, cron job definitions, and plugin-specific data do not transfer. Those are OpenClaw-specific and have different formats in Hermes.\n\n---\n\n## Quick Migration\n\n```bash\n# Preview what would happen (no files changed)\nhermes claw migrate --dry-run\n\n# Run the full migration (includes API keys)\nhermes claw migrate\n\n# Exclude API keys (safer for shared machines)\nhermes claw migrate --preset user-data\n```\n\nThe migration reads from `~\u002F.openclaw\u002F` by default. If you have legacy `~\u002F.clawdbot\u002F` or `~\u002F.moldbot\u002F` directories, those are detected automatically.\n\n---\n\n## Migration Options\n\n| Option | What It Does | Default |\n|--------|-------------|---------|\n| `--dry-run` | Preview without writing anything | off |\n| `--preset full` | Include API keys and secrets | yes |\n| `--preset user-data` | Exclude API keys | no |\n| `--overwrite` | Overwrite existing Hermes files on conflicts | skip |\n| `--migrate-secrets` | Include API keys explicitly | on with `--preset full` |\n| `--source \u003Cpath>` | Custom OpenClaw directory | `~\u002F.openclaw\u002F` |\n| `--workspace-target \u003Cpath>` | Where to place `AGENTS.md` | current directory |\n| `--skill-conflict \u003Cmode>` | `skip`, `overwrite`, or `rename` | `skip` |\n| `--yes` | Skip confirmation prompt | off |\n\n---\n\n## Step-by-Step Walkthrough\n\n### 1. Dry Run First\n\nAlways preview before committing:\n\n```bash\nhermes claw migrate --dry-run\n```\n\nThis shows you exactly what files would be created, overwritten, or skipped. Review the output carefully.\n\n### 2. Run the Migration\n\n```bash\nhermes claw migrate\n```\n\nThe tool will:\n1. Detect your OpenClaw installation\n2. Map config keys to Hermes equivalents\n3. Merge memory files (deduplicating entries)\n4. Copy skills to `~\u002F.hermes\u002Fskills\u002Fopenclaw-imports\u002F`\n5. Migrate API keys (if `--preset full`)\n6. Report what was done\n\n### 3. Handle Conflicts\n\nIf a skill already exists in Hermes with the same name:\n\n- **`--skill-conflict skip`** (default): Leaves the Hermes version, skips the import\n- **`--skill-conflict overwrite`**: Replaces the Hermes version with the OpenClaw version\n- **--skill-conflict rename`**: Creates a `-imported` copy alongside the Hermes version\n\n```bash\n# Example: rename on conflict so you can compare\nhermes claw migrate --skill-conflict rename\n```\n\n### 4. Verify After Migration\n\n```bash\n# Check your personality loaded\ncat ~\u002F.hermes\u002FSOUL.md\n\n# Check memory entries merged\ncat ~\u002F.hermes\u002Fmemories\u002FMEMORY.md | head -50\n\n# Check skills imported\nls ~\u002F.hermes\u002Fskills\u002Fopenclaw-imports\u002F\n\n# Test the agent\nhermes chat -q \"What do you remember about me?\"\n```\n\n---\n\n## What Doesn't Transfer\n\n| Item | Why | What to Do |\n|------|-----|-----------|\n| Session transcripts | Different format | Archive manually if needed |\n| Cron job definitions | Different scheduler | Recreate with `hermes cron` |\n| Plugin configs | Plugin system changed | Reconfigure in Hermes |\n| OpenClaw-specific features | May not exist yet | Check Hermes docs for equivalents |\n\n---\n\n## Config Key Mapping\n\nFor reference, here's how OpenClaw config maps to Hermes:\n\n| OpenClaw Config | Hermes Config | Notes |\n|----------------|---------------|-------|\n| `agents.defaults.model` | `model` | String or `{primary, fallbacks}` |\n| `agents.defaults.timeoutSeconds` | `agent.max_turns` | Divided by 10, capped at 200 |\n| `agents.defaults.verboseDefault` | `agent.verbose` | off \u002F on \u002F full |\n| `agents.defaults.thinkingDefault` | `reasoning.mode` | off \u002F low \u002F high |\n| `models.providers.*.baseUrl` | `custom_providers.*.base_url` | Direct mapping |\n| `models.providers.*.apiType` | `custom_providers.*.api_type` | openai → chat_completions, anthropic → anthropic_messages |\n\n---\n\n## Troubleshooting\n\n### \"No OpenClaw installation found\"\n\nMake sure your OpenClaw data is at `~\u002F.openclaw\u002F`. If it's elsewhere:\n\n```bash\nhermes claw migrate --source \u002Fpath\u002Fto\u002Fyour\u002Fopenclaw\n```\n\n### Memory entries look duplicated\n\nThe migration deduplicates by content similarity, but if your OpenClaw memory had near-duplicates, they might not merge perfectly. Clean up manually:\n\n```bash\n# Edit memory directly\nnano ~\u002F.hermes\u002Fmemories\u002FMEMORY.md\n```\n\n### Skills have import errors\n\nOpenClaw skills may reference modules or patterns that don't exist in Hermes. Open the skill file and check the imports:\n\n```bash\ncat ~\u002F.hermes\u002Fskills\u002Fopenclaw-imports\u002Fskill-name\u002FSKILL.md\n```\n\nMost skills work as-is since they're markdown-based instructions. Skills with code that imports OpenClaw-specific modules need manual updating.\n\n---\n\n## What's Next\n\n- **Want smarter memory?** → [Part 3: LightRAG Setup](#part-3-lightrag--graph-rag-that-actually-works)\n- **Need mobile access?** → [Part 4: Telegram Setup](#part-4-telegram-setup-chat-from-anywhere)\n- **Want the agent to self-improve?** → [Part 5: On-the-Fly Skills](#part-5-on-the-fly-skills-let-hermes-build-its-own-playbook)\n\n---\n\n## Part 3: LightRAG — Graph RAG That Actually Works\n\n## The Problem With Basic Memory\n\nHermes ships with vector-based memory search. It finds documents that are textually similar to your query. That works for simple lookups, but it has a fundamental ceiling: **it finds what's similar, not what's connected.**\n\nAsk \"what hardware decisions were made and why?\" and vector search returns files that all mention GPUs. It can't traverse from a decision → the person who made it → the project it affected → the lesson learned afterward.\n\n**Graph RAG fixes this.** It builds a knowledge graph (entities + relationships) alongside your vector database, then searches both simultaneously.\n\n### Naive RAG vs Graph RAG\n\n| | Naive RAG (Default) | Graph RAG (LightRAG) |\n|---|---|---|\n| **Indexes** | Text chunks as vectors | Entities, relationships, AND text chunks |\n| **Retrieves** | Similar text (cosine similarity) | Connected knowledge (graph traversal + similarity) |\n| **Answers** | \"Here's what the docs say about X\" | \"Here's how X relates to Y, who decided Z, and why\" |\n| **Scales** | Degrades at 500+ docs (too many partial matches) | Improves with more docs (richer graph) |\n| **Cost** | Cheap (embedding only) | More expensive upfront (LLM extracts entities) but cheaper at query time |\n\n---\n\n## LightRAG: The Best Graph RAG For Personal Use\n\n[LightRAG](https:\u002F\u002Fgithub.com\u002FHKUDS\u002FLightRAG) is an open-source graph RAG framework from HKU (EMNLP 2025 paper). It competes with Microsoft's GraphRAG at a fraction of the cost.\n\n**Why LightRAG over alternatives:**\n\n| Tool | Graph | Vector | Web UI | Self-Hosted | API | Cost |\n|------|-------|--------|--------|-------------|-----|------|\n| **LightRAG** | Yes | Yes | Yes | Yes | REST API | Free |\n| Microsoft GraphRAG | Yes | Yes | No | Yes | No | 10-50x more |\n| Graphiti + Neo4j | Yes | No (separate) | No (Neo4j browser) | Yes | Build your own | Free but manual |\n| Plain vector search | No | Yes | No | Yes | Yes | Free |\n\nLightRAG does vector DB + knowledge graph **in parallel** during ingestion. One system, both capabilities.\n\n---\n\n## Installation\n\n### Prerequisites\n\n- Python 3.11+\n- An LLM API key (for entity extraction during ingestion — OpenAI, Anthropic, or any OpenAI-compatible provider)\n- An embedding API key (Fireworks recommended for high-quality 4096-dim embeddings, or use local Ollama)\n\n### Install LightRAG\n\n```bash\n# Create a dedicated directory\nmkdir -p ~\u002F.hermes\u002Flightrag\ncd ~\u002F.hermes\u002Flightrag\n\n# Clone LightRAG\ngit clone https:\u002F\u002Fgithub.com\u002FHKUDS\u002FLightRAG.git\ncd LightRAG\n\n# Install dependencies\npip install -e \".[api]\"\n```\n\n### Set Up Environment\n\nCreate `~\u002F.hermes\u002Flightrag\u002F.env`:\n\n```bash\n# LLM for entity extraction (during ingestion)\nLLM_BINDING=openai\nLLM_MODEL=kimi-2.5                    # What we actually use — great quality\u002Fcost ratio\nLLM_BINDING_API_KEY=\u003Cyour-api-key>\n\n# Embedding model (for vector storage)\nEMBEDDING_BINDING=fireworks\nEMBEDDING_MODEL=accounts\u002Ffireworks\u002Fmodels\u002Fqwen3-embedding-8b\nEMBEDDING_API_KEY=\u003Cyour-fireworks-api-key>\n\n# Or use local Ollama (free, no API key needed):\n# EMBEDDING_BINDING=ollama\n# EMBEDDING_MODEL=nomic-embed-text\n```\n\n> **Security tip:** Set restrictive permissions on this file: `chmod 600 ~\u002F.hermes\u002Flightrag\u002F.env`\n\n### Entity Extraction Model — What to Use\n\nThis is the LLM that reads your documents and pulls out entities and relationships during ingestion. Quality here directly determines how good your knowledge graph is.\n\n| Model | Speed | Quality | Cost | Recommendation |\n|-------|-------|---------|------|----------------|\n| **Kimi 2.5** | Fast | Excellent | Cheap | **What we use.** Great balance of quality, speed, and cost for entity extraction |\n| **Cerebras + Qwen 3** | Blazing fast | Very good | Very cheap | **Fastest option in the world.** Cerebras inference at 2000+ tok\u002Fs makes bulk ingestion fly |\n| GPT-4.1-mini | Fast | Good | Cheap | Solid fallback, well-tested |\n| Claude Sonnet 4 | Medium | Excellent | Mid-range | Overkill for ingestion but works great |\n| **Ollama local** | Depends on GPU | Unpredictable | Free | Untested for this use case — might mess up entity extraction quality. Use at your own risk |\n\n> **Our recommendation:** Kimi 2.5 for quality, Cerebras + Qwen 3 if you're ingesting a lot of documents and speed matters. Both are cheap and reliable. We haven't tested local Ollama for entity extraction — it's free but the extraction quality is unverified and you might get a messy graph.\n\n> **Embedding quality matters.** If you have a GPU with 8GB+ VRAM, run `nomic-embed-text` locally via Ollama for free. If you want the best quality, use Fireworks' Qwen3-Embedding-8B (4096 dimensions) — the search accuracy difference is dramatic.\n\n---\n\n## Running the Server\n\n### Start the REST API\n\n```bash\ncd ~\u002F.hermes\u002Flightrag\u002FLightRAG\n\n# Start the API server (binds to localhost by default)\nlightrag-server --host 127.0.0.1 --port 9623\n```\n\nThe server starts on `http:\u002F\u002Flocalhost:9623` with:\n- **REST API** for ingestion and querying\n- **Web UI** at `http:\u002F\u002Flocalhost:9623\u002Fwebui` for browsing the knowledge graph\n- **Health check** at `http:\u002F\u002Flocalhost:9623\u002Fhealth`\n\n> **Security warning:** The LightRAG REST API has **no built-in authentication**. Always bind to `127.0.0.1` (localhost only) — never `0.0.0.0`. If you need remote access, put it behind a reverse proxy (nginx, Caddy) with authentication, or use SSH tunneling. Anyone who can reach this port can query, ingest, or delete your knowledge graph data.\n\n### Run as a Background Service\n\n```bash\n# Using nohup\nnohup lightrag-server --port 9623 > ~\u002F.hermes\u002Flightrag\u002Fserver.log 2>&1 &\n\n# Or use hermes to manage it\nhermes background \"cd ~\u002F.hermes\u002Flightrag\u002FLightRAG && lightrag-server --port 9623\"\n```\n\n---\n\n## Ingesting Your Knowledge\n\n### How Ingestion Works\n\n```\nDocument (markdown, text, PDF, etc.)\n    ↓\nChunking (text split into segments)\n    ↓\n┌─────────────────┐    ┌──────────────────┐\n│ Embedding Model │    │ LLM Entity       │\n│ (vector storage)│    │ Extraction       │\n└────────┬────────┘    └────────┬─────────┘\n         ↓                      ↓\n   Vector Database       Knowledge Graph\n   (similarity search)   (entity relationships)\n```\n\nFor each document, LightRAG:\n1. Chunks the text and embeds it (standard vector RAG)\n2. Uses an LLM to extract **entities** (people, tools, projects, concepts) and **relationships** (who decided what, what depends on what)\n3. Stores both in parallel — vectors for similarity, graph for structure\n\n### Ingest Documents via API\n\n```bash\n# Ingest a single file\ncurl -X POST http:\u002F\u002Flocalhost:9623\u002Fdocuments\u002Fupload \\\n  -F \"file=@\u002Fpath\u002Fto\u002Fyour\u002Fdocument.md\"\n\n# Ingest a text string directly\ncurl -X POST http:\u002F\u002Flocalhost:9623\u002Fdocuments\u002Ftext \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"text\": \"Your knowledge content here...\", \"description\": \"Source description\"}'\n\n# Ingest all files in a directory\nfor file in ~\u002F.hermes\u002Fmemories\u002F*.md; do\n  curl -X POST http:\u002F\u002Flocalhost:9623\u002Fdocuments\u002Fupload -F \"file=@$file\"\n  echo \"Ingested: $file\"\ndone\n```\n\n### What to Ingest\n\nFeed LightRAG everything your agent needs to \"know\":\n\n- **Memory files** — `~\u002F.hermes\u002Fmemories\u002F*.md`\n- **Project docs** — README files, design docs, decision logs\n- **Chat summaries** — Exported conversation summaries\n- **Notes** — Any markdown\u002Ftext knowledge you want searchable\n- **Code comments** — Extracted from important codebases\n\n> **Start with your memory files and project docs.** These give the graph the most value — decisions, people, projects, and their relationships.\n\n---\n\n## Querying the Graph\n\n### Query Modes\n\nLightRAG has four query modes:\n\n| Mode | Best For | How It Works |\n|------|----------|-------------|\n| `naive` | Simple keyword lookups | Vector search only (like basic RAG) |\n| `local` | Specific entity facts | Entity-focused graph traversal |\n| `global` | Cross-document relationships | Relationship-focused traversal |\n| `hybrid` | General questions (default) | Both local + global combined |\n\n### Query via API\n\n```bash\n# Hybrid query (recommended default)\ncurl -X POST http:\u002F\u002Flocalhost:9623\u002Fquery \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"query\": \"What infrastructure decisions were made and why?\",\n    \"mode\": \"hybrid\",\n    \"only_need_context\": false\n  }'\n\n# Local mode — specific entity facts\ncurl -X POST http:\u002F\u002Flocalhost:9623\u002Fquery \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"query\": \"Tell me about the 5090 PC setup\",\n    \"mode\": \"local\"\n  }'\n\n# Global mode — relationship discovery\ncurl -X POST http:\u002F\u002Flocalhost:9623\u002Fquery \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"query\": \"How do the different projects relate to each other?\",\n    \"mode\": \"global\"\n  }'\n```\n\n### Get Just the Context (for your own LLM)\n\n```bash\ncurl -X POST http:\u002F\u002Flocalhost:9623\u002Fquery \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"query\": \"What models are running on what hardware?\",\n    \"mode\": \"hybrid\",\n    \"only_need_context\": true\n  }'\n```\n\nThis returns the raw context chunks without generating an answer — useful for feeding into your own pipeline or Hermes' LLM.\n\n---\n\n## Integrating With Hermes\n\n### Create a LightRAG Skill\n\nCreate `~\u002F.hermes\u002Fskills\u002Fresearch\u002Flightrag\u002FSKILL.md`:\n\n```markdown\n---\nname: lightrag\ndescription: Query the LightRAG knowledge graph for past decisions, infrastructure, projects, and lessons learned. Use before saying \"I don't remember.\"\n---\n\n# LightRAG Knowledge Graph\n\nQuery the LightRAG knowledge graph for past decisions, infrastructure, projects, and lessons learned.\n\n## When To Use\n- User asks about past work, decisions, or \"what happened with X\"\n- Need context on projects, hardware, or configurations\n- Remembering lessons learned or past issues\n- Any question where you'd say \"I don't remember\" — use this FIRST\n\n## Usage\n```bash\ncurl -s -X POST http:\u002F\u002Flocalhost:9623\u002Fquery \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"query\": \"YOUR QUERY\", \"mode\": \"hybrid\", \"only_need_context\": true}'\n```\n\n## Search Modes\n- `hybrid` (default): Combined vector + graph search\n- `local`: Entity-focused (specific facts)\n- `global`: Relationship-focused (how things connect)\n- `naive`: Vector-only (simple lookups)\n\n## Important\n- ALWAYS search this before saying \"I don't remember\"\n- Results supersede general knowledge about the setup\n- Reference entity names when citing results\n```\n\n### Query from a Script\n\nCreate `~\u002F.hermes\u002Fskills\u002Fresearch\u002Flightrag\u002Fscripts\u002Flightrag_search.py`:\n\n```python\n#!\u002Fusr\u002Fbin\u002Fenv python3\n\"\"\"LightRAG search script for Hermes skill integration.\"\"\"\nimport json\nimport sys\nimport urllib.request\n\ndef search(query: str, mode: str = \"hybrid\") -> str:\n    url = \"http:\u002F\u002Flocalhost:9623\u002Fquery\"\n    payload = json.dumps({\n        \"query\": query,\n        \"mode\": mode,\n        \"only_need_context\": True\n    }).encode()\n    \n    req = urllib.request.Request(url, data=payload, headers={\"Content-Type\": \"application\u002Fjson\"})\n    try:\n        with urllib.request.urlopen(req, timeout=30) as resp:\n            result = json.loads(resp.read())\n            return result.get(\"response\", result.get(\"data\", str(result)))\n    except Exception as e:\n        return f\"LightRAG query failed: {e}\"\n\nif __name__ == \"__main__\":\n    query = \" \".join(sys.argv[1:]) if len(sys.argv) > 1 else \"\"\n    if not query:\n        print(\"Usage: lightrag_search.py \u003Cquery>\")\n        sys.exit(1)\n    print(search(query))\n```\n\n---\n\n## Optimizing Search Quality\n\n### 1. Tune Entity Extraction\n\nThe quality of your graph depends on entity extraction. In LightRAG's config:\n\n```yaml\n# More entities = richer graph, slower ingestion\nentity_extract_max_gleaning: 5    # Default: 3. Higher = more thorough\n\n# Chunk size affects entity density\nchunk_token_size: 1200             # Default: 1200. Smaller = more entities per doc\nchunk_overlap_token_size: 100      # Default: 100\n```\n\n### 2. Use High-Quality Embeddings\n\nEmbedding quality directly impacts vector search accuracy:\n\n| Model | Dimensions | Quality | Cost |\n|-------|-----------|---------|------|\n| nomic-embed-text (Ollama) | 768 | Good | Free (local) |\n| Qwen3-Embedding-8B (Fireworks) | 4096 | Excellent | ~$0.001\u002F1K tokens |\n| text-embedding-3-large (OpenAI) | 3072 | Very Good | ~$0.00013\u002F1K tokens |\n\n> **If search quality matters, use 4096-dimension embeddings.** The difference between 768 and 4096 dims is like the difference between 720p and 4K — you catch details you'd otherwise miss.\n\n### 3. Reindex After Bulk Changes\n\nAfter ingesting a large batch of new documents:\n\n```bash\n# Check entity count\ncurl http:\u002F\u002Flocalhost:9623\u002Fgraph\u002Flabel\u002Flist | python3 -c \"import sys,json; d=json.load(sys.stdin); print(f'{len(d)} entities')\"\n```\n\n### 4. Use the Right Query Mode\n\nDon't always default to `hybrid`. Use:\n- `local` when asking about a specific thing (\"Tell me about the GPU setup\")\n- `global` when asking about connections (\"How do the projects relate?\")\n- `hybrid` for general questions (\"What decisions were made last week?\")\n\n### 5. Monitor and Prune\n\nThe Web UI at `http:\u002F\u002Flocalhost:9623\u002Fwebui` lets you:\n- Browse the knowledge graph visually\n- See entity relationships\n- Identify orphaned or redundant entities\n\n---\n\n## Web UI\n\nOnce the server is running, open `http:\u002F\u002Flocalhost:9623\u002Fwebui` in your browser. You can:\n\n- **Search** the graph with any query mode\n- **Visualize** entity relationships as a network graph\n- **Browse** all entities and their connections\n- **Inspect** raw chunks and their source documents\n\nHere's what a populated LightRAG knowledge graph looks like in the Web UI (screenshot from the [LightRAG project](https:\u002F\u002Fgithub.com\u002FHKUDS\u002FLightRAG)):\n\n![LightRAG Knowledge Graph Web UI](.\u002Fscreenshots\u002Flightrag_webui.png)\n\n*The Web UI showing entity extraction, graph relationships, and document indexing. Once you ingest your own data, your graph fills up with your specific entities — people, projects, decisions, hardware, configs — all connected by the relationships LightRAG extracts automatically.*\n\n---\n\n## Troubleshooting\n\n### \"Connection refused\" on query\n\nThe server isn't running. Start it:\n```bash\ncd ~\u002F.hermes\u002Flightrag\u002FLightRAG && lightrag-server --port 9623\n```\n\n### Slow ingestion\n\nEntity extraction is LLM-bound. Speed it up:\n- Use a faster model for ingestion (Cerebras + Qwen 3 is the fastest option, or Kimi 2.5)\n- Process documents in parallel batches\n- Use a local model if you have GPU capacity\n\n### Empty or irrelevant results\n\n- Check that documents were actually ingested (Web UI → entities)\n- Try different query modes (`local` vs `global` vs `hybrid`)\n- Rephrase your query — be more specific about entities\n- Check embedding model is actually running (`curl http:\u002F\u002Flocalhost:11434\u002Fapi\u002Ftags` for Ollama)\n\n### Duplicate entities after re-ingestion\n\nLightRAG merges similar entities automatically, but exact duplicates can happen. Use the Web UI to manually clean up, or reindex from scratch:\n```bash\n# Nuclear option: wipe and reingest\nrm -rf ~\u002F.hermes\u002Flightrag\u002FLightRAG\u002Frag_storage\u002F*\n# Then re-ingest your documents\n```\n\n---\n\n## What's Next\n\n- **Need mobile access?** → [Part 4: Telegram Setup](#part-4-telegram-setup-chat-from-anywhere)\n- **Want the agent to self-improve?** → [Part 5: On-the-Fly Skills](#part-5-on-the-fly-skills-let-hermes-build-its-own-playbook)\n\n---\n\n## Part 4: Telegram Setup (Chat From Anywhere)\n\n## Why Telegram\n\nYour agent is only useful if you can access it. Sitting at a terminal works until you need to:\n\n- Check something from your phone while away from your desk\n- Get notified when a long-running task finishes\n- Use Hermes in a group chat with your team\n- Send voice memos that get auto-transcribed and processed\n- Receive scheduled task results (cron jobs) on mobile\n\nTelegram is the best messaging platform for Hermes bots — it supports text, voice, images, files, inline buttons, and group chats with minimal setup.\n\n---\n\n## Step 1: Create a Bot via BotFather\n\nEvery Telegram bot requires an API token from [@BotFather](https:\u002F\u002Ft.me\u002FBotFather), Telegram's official bot management tool.\n\n1. Open Telegram and search for **@BotFather**, or visit [t.me\u002FBotFather](https:\u002F\u002Ft.me\u002FBotFather)\n2. Send `\u002Fnewbot`\n3. Choose a **display name** (e.g., \"Hermes Agent\") — this can be anything\n4. Choose a **username** — this must be unique and end in `bot` (e.g., `my_hermes_bot`)\n5. BotFather replies with your **API token**. It looks like this:\n\n```\n123456789:ABCdefGHIjklMNOpqrSTUvwxYZ\n```\n\n> **Keep your bot token secret.** Anyone with this token can control your bot. If it leaks, revoke it immediately via `\u002Frevoke` in BotFather.\n\n---\n\n## Step 2: Customize Your Bot (Optional)\n\nThese BotFather commands improve the user experience:\n\n| Command | Purpose |\n|---------|---------|\n| `\u002Fsetdescription` | The \"What can this bot do?\" text shown before chatting |\n| `\u002Fsetabouttext` | Short text on the bot's profile page |\n| `\u002Fsetuserpic` | Upload an avatar for your bot |\n| `\u002Fsetcommands` | Define the command menu (the `\u002F` button in chat) |\n\nFor `\u002Fsetcommands`, a useful starting set:\n\n```\nhelp - Show help information\nnew - Start a new conversation\nsethome - Set this chat as the home channel\nstatus - Show agent status\n```\n\n---\n\n## Step 3: Privacy Mode (Critical for Groups)\n\nTelegram bots have **privacy mode** enabled by default. This is the single most common source of confusion.\n\n**With privacy mode ON**, your bot can only see:\n- Messages that start with a `\u002F` command\n- Replies directly to the bot's own messages\n- Service messages (member joins\u002Fleaves, pinned messages)\n\n**With privacy mode OFF**, the bot receives every message in the group.\n\n### How to Disable Privacy Mode\n\n1. Message **@BotFather**\n2. Send `\u002Fmybots`\n3. Select your bot\n4. Go to **Bot Settings → Group Privacy → Turn off**\n\n> **You must remove and re-add the bot to any group** after changing the privacy setting. Telegram caches the privacy state when a bot joins a group — it won't update until removed and re-added.\n\n> **Alternative:** Promote the bot to **group admin**. Admin bots always receive all messages regardless of privacy settings.\n\n---\n\n## Step 4: Find Your User ID\n\nHermes uses numeric Telegram user IDs to control access. Your user ID is **not** your username — it's a number like `123456789`.\n\n**Method 1 (recommended):** Message [@userinfobot](https:\u002F\u002Ft.me\u002Fuserinfobot) — it instantly replies with your user ID.\n\n**Method 2:** Message [@get_id_bot](https:\u002F\u002Ft.me\u002Fget_id_bot) — another reliable option.\n\nSave this number; you'll need it for the next step.\n\n---\n\n## Step 5: Configure Hermes\n\n### Option A: Interactive Setup (Recommended)\n\n```bash\nhermes gateway setup\n```\n\nSelect **Telegram** when prompted. The wizard asks for your bot token and allowed user IDs, then writes the configuration for you.\n\n### Option B: Manual Configuration\n\nAdd the following to `~\u002F.hermes\u002F.env`:\n\n```bash\nTELEGRAM_BOT_TOKEN=\u003Cyour-bot-token-from-botfather>\nTELEGRAM_ALLOWED_USERS=\u003Cyour-numeric-user-id>    # Comma-separated for multiple users\n```\n\nFor groups, also add the group chat ID (negative number, like `-1001234567890`):\n\n```bash\nTELEGRAM_ALLOWED_CHATS=-1001234567890\n```\n\n---\n\n## Step 6: Start the Gateway\n\n```bash\nhermes gateway\n```\n\nThe bot should come online within seconds. Send it a message on Telegram to verify.\n\n---\n\n## Gateway Management\n\n```bash\n# Check gateway status\nhermes gateway status\n\n# Stop the gateway\nhermes gateway stop\n\n# Restart after config changes\nhermes gateway restart\n\n# Run as a system service (auto-start on boot)\nhermes gateway install   # Sets up systemd\u002Flaunchd service\n```\n\n---\n\n## Features Available on Telegram\n\n### Text Chat\nFull conversation support — the bot processes your messages the same as the CLI.\n\n### Voice Messages\nSend a voice memo and Hermes:\n1. Auto-transcribes it using Whisper\n2. Processes the transcription as a text message\n3. Responds with text (or voice via TTS)\n\n### Image Analysis\nSend a photo and Hermes analyzes it using vision models. Describe what you want to know about the image in the caption.\n\n### File Attachments\nSend documents, code files, or data files — Hermes can read and process them.\n\n### Inline Buttons\nFor dangerous commands, Hermes shows confirmation buttons instead of executing immediately.\n\n### Slash Commands\nThe bot supports Telegram's native command menu (the `\u002F` button in chat).\n\n### Scheduled Messages\nCron job results are delivered directly to your Telegram chat:\n\n```bash\n# Deliver cron results to Telegram\nhermes cron create --deliver telegram \"Check server status every hour\" --schedule \"every 1h\"\n```\n\n---\n\n## Webhook Mode (For Cloud Deployments)\n\nBy default, Hermes uses **long polling** — the gateway makes outbound requests to Telegram. This works for local and always-on servers.\n\nFor **cloud deployments** (Fly.io, Railway, Render), **webhook mode** is better. These platforms auto-wake on inbound HTTP traffic but not on outbound connections.\n\n### Configuration\n\nAdd to `~\u002F.hermes\u002F.env`:\n\n```bash\nTELEGRAM_WEBHOOK_URL=https:\u002F\u002Fyour-app.fly.dev\nTELEGRAM_WEBHOOK_SECRET=\u003Cgenerate-with-command-below>\n```\n\nGenerate a strong secret — never use a guessable value:\n\n```bash\nopenssl rand -hex 32\n```\n\nCopy the output and paste it as your `TELEGRAM_WEBHOOK_SECRET` value.\n\n> **Warning:** A weak or default webhook secret lets attackers forge Telegram webhook requests and inject messages into your agent. Always use a cryptographically random value.\n\n| | Polling (default) | Webhook |\n|---|---|---|\n| Direction | Gateway → Telegram | Telegram → Gateway |\n| Best for | Local, always-on servers | Cloud platforms |\n| Extra config | None | `TELEGRAM_WEBHOOK_URL` |\n| Idle cost | Machine must stay on | Machine can sleep |\n\n---\n\n## Multi-User Setup\n\nTo allow multiple users to interact with the bot:\n\n```bash\nTELEGRAM_ALLOWED_USERS=123456789,987654321,555555555\n```\n\nEach user gets their own conversation session. The bot tracks sessions per user ID.\n\n---\n\n## Troubleshooting\n\n### Bot not responding\n\n1. Check the token is correct: `echo $TELEGRAM_BOT_TOKEN`\n2. Verify the gateway is running: `hermes gateway status`\n3. Check logs: `hermes gateway logs`\n\n### Bot in group but not seeing messages\n\nPrivacy mode is still on. You must:\n1. Disable privacy in BotFather (`\u002Fmybots` → Bot Settings → Group Privacy → Turn off)\n2. **Remove the bot from the group**\n3. **Re-add the bot to the group**\n\n### Voice messages not transcribed\n\nHermes needs `ffmpeg` for audio conversion. The installer includes it, but if you installed manually:\n\n```bash\nsudo apt install ffmpeg   # Ubuntu\u002FDebian\nbrew install ffmpeg        # macOS\n```\n\n### Rate limiting\n\nTelegram limits bots to 30 messages\u002Fsecond to different chats and 20 messages\u002Fminute to the same group. If you're hitting limits, add a delay:\n\n```bash\nhermes config set telegram.rate_limit_delay 1\n```\n\n---\n\n## What's Next\n\n- **Want the agent to self-improve?** → [Part 5: On-the-Fly Skills](#part-5-on-the-fly-skills-let-hermes-build-its-own-playbook)\n\n---\n\n## Part 5: On-the-Fly Skills (Let Hermes Build Its Own Playbook)\n\n## What Are Skills\n\nSkills are procedural knowledge — step-by-step instructions that teach Hermes how to handle specific tasks. Unlike memory (which is factual), skills are **how-to guides** the agent follows automatically.\n\n**Skills vs Memory:**\n\n| | Skills | Memory |\n|---|---|---|\n| **What** | How to do things | What things are |\n| **When** | Loaded on demand, only when relevant | Injected every session automatically |\n| **Size** | Can be large (hundreds of lines) | Should be compact (key facts only) |\n| **Cost** | Zero tokens until loaded | Small but constant token cost |\n| **Examples** | \"How to deploy to Kubernetes\" | \"User prefers dark mode, lives in EST\" |\n| **Who creates** | You, the agent, or installed from Hub | The agent, based on conversations |\n\n**Rule of thumb:** If you'd put it in a reference document, it's a skill. If you'd put it on a sticky note, it's memory.\n\n---\n\n## The Skill Creation Workflow\n\nHermes can create skills itself. Here's how it works:\n\n### 1. Do a Complex Task\n\nAsk Hermes to do something multi-step. For example:\n\n```\nSet up a monitoring script that checks my server health every 5 minutes\nand alerts me on Telegram if CPU goes above 90% or memory above 80%.\n```\n\nHermes will:\n- Research the best approach\n- Write the script\n- Test it\n- Set up the cron job\n- Fix any issues along the way\n\n### 2. Hermes Offers to Save It\n\nAfter completing a complex task (5+ tool calls), fixing a tricky error, or discovering a non-trivial workflow, Hermes will offer:\n\n```\nThis was a multi-step process. Want me to save this as a skill\nso I can reuse it next time?\n```\n\n### 3. Say Yes\n\nThe agent uses `skill_manage` to create a new skill file at `~\u002F.hermes\u002Fskills\u002F\u003Ccategory>\u002F\u003Cskill-name>\u002FSKILL.md`. This file contains:\n\n- **When to use** — the trigger conditions\n- **Exact steps** — commands, files, configurations\n- **Pitfalls** — problems encountered and how to fix them\n- **Verification** — how to confirm it worked\n\n### 4. It's Available Immediately\n\nThe skill appears in `skills_list` and becomes available as a slash command. Next time you (or the agent) encounter a similar task, the skill is loaded automatically.\n\n---\n\n## How to Ask Hermes to Create a Skill\n\n### Direct Request\n\nJust ask:\n\n```\nCreate a skill for deploying Docker containers to my server.\nInclude the build, push, SSH deploy, and health check steps.\n```\n\nHermes will:\n1. Research the best deployment workflow\n2. Create the skill directory at `~\u002F.hermes\u002Fskills\u002F`\n3. Write `SKILL.md` with the full procedure\n4. Add reference files, templates, or scripts if needed\n5. Test that it works\n\n### After Solving a Problem\n\nIf Hermes just solved a tricky problem for you:\n\n```\nSave that as a skill so you remember how to do it next time.\n```\n\nThe agent captures:\n- The exact steps taken\n- The errors encountered and fixes\n- The configuration needed\n- Edge cases discovered\n\n### Iterative Improvement\n\nIf a skill is outdated or incomplete:\n\n```\nThat skill doesn't cover the new deployment method. Update it\nwith what we just learned.\n```\n\nHermes patches the skill with new information using `skill_manage(action='patch')`.\n\n---\n\n## Skill Structure\n\nEvery skill is a directory with a `SKILL.md` file:\n\n```\n~\u002F.hermes\u002Fskills\u002F\n├── my-category\u002F\n│   ├── my-skill\u002F\n│   │   ├── SKILL.md              # Main instructions (required)\n│   │   ├── references\u002F           # Supporting docs (optional)\n│   │   │   ├── api-docs.md\n│   │   │   └── examples.md\n│   │   ├── templates\u002F            # Template files (optional)\n│   │   │   └── config.yaml\n│   │   └── scripts\u002F              # Executable scripts (optional)\n│   │       └── setup.sh\n│   └── another-skill\u002F\n│       └── SKILL.md\n└── openclaw-imports\u002F             # Migrated from OpenClaw\n    └── old-skill\u002F\n        └── SKILL.md\n```\n\n### SKILL.md Format\n\n```markdown\n---\nname: my-skill\ndescription: Brief description of what this skill does\nversion: 1.0.0\nmetadata:\n  hermes:\n    tags: [deployment, docker, devops]\n    category: my-category\n---\n\n# My Skill\n\n## When to Use\nUse this skill when the user asks to deploy containers or manage Docker services.\n\n## Procedure\n1. Check Docker is running: `docker ps`\n2. Build the image: `docker build -t app:latest .`\n3. Push to registry: `docker push registry\u002Fapp:latest`\n4. SSH to server and pull: `ssh server 'docker pull registry\u002Fapp:latest && docker-compose up -d'`\n5. Health check: `curl -f http:\u002F\u002Fserver:8080\u002Fhealth`\n\n## Pitfalls\n- Docker build fails if Dockerfile has COPY paths wrong — fix by checking working directory\n- SSH needs key-based auth — set up with `ssh-keygen` and `ssh-copy-id`\n- Health check may take 10s to respond — add retry logic\n\n## Verification\nRun `docker ps` on the server and confirm the container is `Up` and healthy.\n```\n\n---\n\n## Using Skills\n\n### Via Slash Command\n\nEvery skill becomes a slash command automatically:\n\n```bash\n\u002Fmy-skill deploy the latest version to production\n```\n\n### Via Natural Conversation\n\nJust ask Hermes to use a skill:\n\n```\nUse the docker-deploy skill to push the new build.\n```\n\nHermes loads the skill via `skill_view` and follows its instructions.\n\n### Automatic Loading\n\nHermes scans available skills at session start. When your request matches a skill's \"When to Use\" conditions, it loads automatically — you don't need to explicitly invoke it.\n\n---\n\n## Managing Skills\n\n### List All Skills\n\n```bash\n\u002Fskills\n# Or\nhermes skills list\n```\n\n### Search for a Skill\n\n```bash\n\u002Fskills search docker\n\u002Fskills search deployment\n```\n\n### View a Skill's Content\n\n```bash\n\u002Fskills view my-skill\n```\n\n### Enable\u002FDisable Per Platform\n\n```bash\nhermes skills\n```\n\nThis opens an interactive TUI where you can enable or ","Hermes Optimization Guide 是一个用于设置、迁移和优化 Hermes Agent 的指南项目。它提供了包括LightRAG集成、Telegram机器人配置以及技能创建等核心功能，并通过Shell脚本实现了一键部署，支持从全新安装到生产环境的全流程操作。该项目特别适合需要快速搭建高效AI代理服务的开发者或团队使用，能够在多种平台上运行并整合多个插件和服务，同时控制成本。此外，项目内含实际可运行的文件如技能模板和配置示例，极大简化了部署过程。","2026-06-11 02:43:01","CREATED_QUERY"]