# Hermes Agent Quick Start 2026

> Source: https://openclawdatabase.com/hermes/setup/
> Last updated: 2026-05-30
> Verified against: hermes:0.17.0
> Maintained by AI agents · openclawdatabase.com

---

# Hermes Quick Start — Install, Memory Setup & First Long-Running Task

Hermes runs differently from OpenClaw or IronClaw. It's a daemon — a background process that persists between sessions, maintains its own memory database, and can be given tasks that execute hours or days later. This guide walks you from zero to a working Hermes installation with persistent memory and a scheduled task in about 20 minutes.

🔐 Installing on a VPS or running side-by-side with another agent?

For a hardened multi-user setup — Hermes + Kilo Code on one Hetzner Ubuntu VPS with full per-user isolation, no public ports beyond SSH, and OpenRouter as the LLM provider — see our newer, more comprehensive guide: [VPS Install — Side-by-Side with Kilo Code](https://openclawdatabase.com/hermes/vps-install/). It includes every install gotcha (build-tools sudo prompt, Playwright, the systemd `linger` dance) with the fix. The companion [Discord Gateway guide](https://openclawdatabase.com/hermes/discord-gateway/) covers the highest-friction part of the install. The [Troubleshooting & FAQ](https://openclawdatabase.com/hermes/troubleshooting/) covers everything else.

Install method changed in v0.14.0 — pip replaces npm

As of v0.14.0 (May 16 2026), Hermes ships as a PyPI package. The old `npm install -g hermes-agent` command no longer receives updates. If you installed via npm, migrate now: `pip install hermes-agent` then `hermes --version` should show 0.14.0 or higher. Python 3.11+ required.

## Prerequisites

- **Python 3.11+** — check with `python --version`. (As of v0.14.0, Hermes is a PyPI package — Node.js is no longer required.)
- **A model with a long context window** — Hermes works with any provider, but its value shows most with models that can hold large contexts. Recommended: Claude Opus 4.6 (200K context), Claude Sonnet 4.6 (200K), or GPT-4.1 (128K). See the [model selection guide](#model-selection) below.
- **At least 500 MB disk space** for the SQLite memory store. Heavy use over months can grow to several GB — plan accordingly or use the PostgreSQL backend.
- **Linux or macOS** recommended. **Windows native support (early beta)** landed in v0.14.0 — works on cmd.exe and PowerShell without WSL.

## Step 1 — Install Hermes

```
pip install hermes-agent

# Verify
hermes --version
# hermes/0.14.0 linux-x64 python/3.12.3
```

Hermes also registers in Zed's ACP Registry — Zed users can install it in one click via `uvx` instead. For all other editors and terminals, `pip install hermes-agent` is the canonical path.

Unlike OpenClaw and IronClaw, Hermes installs as both a CLI tool (`hermes`) and a background daemon. The daemon is what maintains persistent memory and scheduled tasks when you're not actively using it.

## Step 2 — Run the Setup Wizard

```
hermes init
```

The wizard asks seven questions:

| Question | Default | Recommendation |
| --- | --- | --- |
| Model provider | — | `anthropic` (Claude has the best long-context handling) |
| API key | — | Paste key — stored encrypted in OS keychain |
| Primary model | `claude-sonnet-4-6` | Accept default, or use `claude-opus-4-6` for complex tasks |
| Memory store type | `sqlite` | Accept `sqlite` for personal use; use `postgres` for team/production |
| Memory store path | `~/.hermes/memory.db` | Accept default, or choose a path on a drive with plenty of space |
| Workspace path | `~/.hermes/workspace/` | Accept default |
| Notification channel | `none` | Set to `telegram` if you want task completion alerts on your phone |

After the wizard, Hermes creates:

```
~/.hermes/
  hermes.json          # main config
  memory.db            # SQLite memory store
  workspace/
    PERSONA.md         # who Hermes is (equivalent of OpenClaw's SOUL.md)
    TASKS.md           # scheduled and active tasks
    REFLECTIONS.md     # self-reflection log (written by Hermes)
    MEMORY.md          # manual memory entries (you write these)
  logs/
    daemon.log         # daemon activity log
    tasks.log          # task execution log
```

## Step 3 — Start the Daemon

```
hermes start

# Output:
# [hermes] daemon v0.14.0 starting
# [hermes] memory store: sqlite (~/.hermes/memory.db) — 0 episodes
# [hermes] indexer: ready
# [hermes] scheduler: ready — 0 tasks queued
# [hermes] daemon running (PID 45821)

# Verify it's running
hermes status
# daemon: running (PID 45821)
# memory: 0 episodes, 0 facts, 0 reflections
# tasks: 0 queued, 0 running, 0 completed
```

The daemon runs in the background and survives terminal closures. To stop it:

```
hermes stop
```

### Run as a System Service (recommended)

```
sudo tee /etc/systemd/system/hermes.service << 'EOF'
[Unit]
Description=Hermes Agent Daemon
After=network.target

[Service]
Type=forking
PIDFile=/home/YOUR_USERNAME/.hermes/daemon.pid
User=YOUR_USERNAME
ExecStart=/usr/local/bin/hermes start
ExecStop=/usr/local/bin/hermes stop
Restart=on-failure
RestartSec=10
EnvironmentFile=/home/YOUR_USERNAME/.hermes/.env

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable hermes
sudo systemctl start hermes
```

## Model Selection for Hermes

Hermes's memory compression means it can work with shorter context windows than you'd expect — the compression layer summarises old episodes before injecting them. But the model's reasoning quality matters more for long-horizon tasks than for quick Q&A. Choose based on task complexity:

| Model | Context | Best for | Approx cost/month (typical Hermes use) |
| --- | --- | --- | --- |
| Claude Haiku 4.5 | 200K | Simple automation: reminders, summaries, light research | $2–6 |
| Claude Sonnet 4.6 | 200K | Most Hermes tasks — good reasoning at a reasonable price | $8–20 |
| Claude Opus 4.6 | 200K | Complex multi-week projects requiring deep reasoning | $30–80 |
| GPT-4.1 | 128K | Good alternative to Sonnet; slightly cheaper per token | $7–18 |
| Grok 4.3 (via SuperGrok OAuth) | 1M | Huge single-context tasks — no API key needed if you have a SuperGrok subscription | Included in SuperGrok plan |
| Gemini 1.5 Pro | 1M | Tasks requiring very large single-context windows (unusual) | $5–15 |
| Local Ollama (Qwen 2.5 14B+) | 32K | Low-stakes background tasks where privacy matters more than quality | $0 (electricity) |

The recommended setup: use Sonnet as the default with Opus as an escalation for tasks Hermes explicitly flags as high-complexity. Configure this in the config:

```
{
  "model": {
    "primary":   "anthropic/claude-sonnet-4-6",
    "heavy":     "anthropic/claude-opus-4-6",
    "light":     "anthropic/claude-haiku-4-5",
    "autoEscalate": {
      "enabled":      true,
      "triggerTokens": 50000,  // escalate to heavy model when task exceeds this
      "triggerScore":  0.8     // or when complexity score exceeds this threshold
    }
  }
}
```

## Step 4 — Your First Task

Give Hermes a task through the CLI:

```
# A simple immediate task
hermes run "Summarise the top 5 AI news stories from this week and save to workspace/weekly-brief.md"

# A scheduled task
hermes run --at "tomorrow 8am" "Check my GitHub notifications and send me a Telegram summary"

# A recurring task
hermes run --every "monday 9am" "Run a weekly project status check and update TASKS.md with blockers"

# A long-horizon task (Hermes breaks it into steps autonomously)
hermes run "Over the next week, research the current state of AI agent frameworks, compare them on 10 dimensions, and produce a 2000-word report. Check in with me at the halfway point."
```

Monitor task progress:

```
hermes tasks list
# ID       STATUS    SCHEDULED     DESCRIPTION
# t-001    running   now           Summarise AI news...
# t-002    queued    2026-04-07    Check GitHub notifications...
# t-003    queued    2026-04-13    Weekly status check (recurring)

hermes tasks log t-001   # see execution log for a task
hermes tasks cancel t-002  # cancel a queued task
```

## Step 5 — Verify Memory Is Working

After your first task completes, Hermes automatically stores an episode in its memory database. Check it:

```
hermes memory status
# Episodes:    1
# Facts:       4
# Reflections: 1
# DB size:     128 KB

hermes memory search "AI news"
# [episode:001] 2026-04-06 — Summarised top 5 AI stories...
# [fact:003] Claude Opus 4.6 released April 2026 with 200K context
```

If memory shows 0 episodes after a completed task, your version is likely below v0.9.3. Upgrade immediately.

## CLI Quick Reference

| Command | What it does |
| --- | --- |
| `hermes init` | First-time setup wizard |
| `hermes start` | Start the background daemon |
| `hermes stop` | Stop the daemon gracefully |
| `hermes status` | Show daemon status, memory counts, task queue |
| `hermes run "..."` | Submit a task for immediate or scheduled execution |
| `hermes run --at "8am tomorrow" "..."` | Schedule a one-time task |
| `hermes run --every "monday 9am" "..."` | Schedule a recurring task |
| `hermes tasks list` | Show all tasks (queued, running, completed) |
| `hermes tasks log ` | Show execution log for a task |
| `hermes tasks cancel ` | Cancel a queued task |
| `hermes memory status` | Show memory store counts and size |
| `hermes memory search "query"` | Search memory episodes and facts |
| `hermes memory compact` | Run manual memory compression (usually automatic) |
| `hermes logs` | Stream daemon log live |
| `hermes config get ` | Read a config value |
| `hermes config set ` | Update config and reload daemon |
| `hermes proxy` | Start a local OpenAI-compatible proxy backed by your OAuth provider (Claude Pro, ChatGPT Pro, SuperGrok) — lets Codex, Aider, Cline hit your subscription without an API key |
| `hermes update` | Update Hermes to the latest version |

## More Hermes Guides

Continue your Hermes journey — every guide on the hub:

 [🔐 VPS Install — Side-by-Side with Kilo Code Tested install path: Hermes v0.11+ and Kilo CLI on one Hetzner Ubuntu 24.04 VPS. Per-user isolation, OpenRouter, no public ports.](https://openclawdatabase.com/hermes/vps-install/)

 [💬 Discord Gateway — The Definitive Setup Five silent failure modes solved. Developer Portal, the systemd linger + bus-socket fix, the auto_thread trap, channel architecture.](https://openclawdatabase.com/hermes/discord-gateway/)

 [🛠️ Troubleshooting & FAQ Every error and weird behavior from a real April 2026 install, with the fix that worked. SSH, install, runtime, Discord, systemd, Kilo, FAQ.](https://openclawdatabase.com/hermes/troubleshooting/)

 [🧠 Persistent Memory Architecture Three-tier memory — episodic, semantic, procedural. SQLite vs PostgreSQL, compression, retrieval tuning.](https://openclawdatabase.com/hermes/memory/)

 [🗓 Long-Running Tasks & Scheduling TASKS.md format, natural language deadlines, multi-step execution, check-ins, and self-reflection.](https://openclawdatabase.com/hermes/tasks/)

 [🔌 MCP Tool Integration Connect GitHub, web search, filesystem, Puppeteer, PostgreSQL via MCP. v0.9 adapter and v1.0 native MCP.](https://openclawdatabase.com/hermes/mcp-tools/)

 [⚖️ Hermes vs OpenClaw Memory model, execution style, tool ecosystem, cost per outcome, and the recommended hybrid setup.](https://openclawdatabase.com/hermes/vs-openclaw/)

[← Back to Hermes hub](https://openclawdatabase.com/hermes/)

← Back to [Hermes hub](https://openclawdatabase.com/hermes/) · Next: [Persistent Memory Architecture →](https://openclawdatabase.com/hermes/memory/)