📋 Table of Contents

  1. Before You Start

  2. The 5 Pillars

  3. Installation

  4. Setup Step by Step

  5. Prompts to Use It

  6. Commands Reference

  7. Daily Workflow

  8. Tips

  9. Troubleshooting

  10. Quick Reference

✅ Before You Start

Accounts

  • LLM provider account — Anthropic, OpenAI, OpenRouter, or any OpenAI-compatible API

  • (Optional) Telegram account — for the messaging gateway

  • (Optional) Browserbase account — for cloud browser automation

  • (Optional) GitHub account — for nightly repo sync crons

System Requirements

  • Linux, macOS, WSL2 (Windows), or Android via Termux

  • Native Windows is not supported — use WSL2

  • Git installed

  • Python, Node.js, and other dependencies are installed automatically by the installer

What Gets Installed Automatically

  • Python (correct version)

  • Node.js

  • SQLite (for session storage, memory, skills)

  • All Hermes runtime dependencies

🏗 The 5 Pillars

Pillar 1 — Memory: Two Files That Solve the Stateless Problem

Two Markdown files load at the start of every session:

File

Purpose

Size cap

MEMORY.md

Active projects, business context, key facts, ongoing work

~2,200 chars

USER.md

Your name, preferences, communication style, things to never do

~1,375 chars

❝

⚠️ Stale memory is the #1 cause of weird agent behaviour. If Hermes starts acting off, check MEMORY.md first. Old project context actively confuses it.

The agent updates these files automatically from conversation — and you can direct it explicitly:

  • "Chuck that in memory"

  • "Add this to user.md — never use bullet points in my reports"

Long-term recall uses FTS5 full-text search across all past sessions with LLM summarisation, so "what did we decide about the API?" actually works across sessions.

Pillar 2 — Skills: Procedural Memory as Reusable Recipes

A skill is a Markdown file with YAML front matter. The front matter tells the agent what the skill is for — so it can decide whether to invoke it without loading the full file into context. This is called progressive disclosure.

yaml

---
name: daily-github-sync
description: Push all uncommitted changes to GitHub every night at midnight
triggers:
  - nightly sync
  - push to github
  - daily commit
---
## Steps
1. Run `git add -A`
2. Commit with message: "Auto-sync: {date}"
3. Push to origin main
4. Report result to Telegram

Hermes ships with 91 built-in skills. The community skills hub has 520+ additional skills, including 16 official Anthropic-contributed skills.

Install any skill by pasting its URL into chat and saying "install this."

Skills evolve: give feedback on how a skill performed and Hermes updates the YAML. The library reflects how you actually work.

Pillar 3 — Soul: Personality as Infrastructure

soul.md defines the agent's tone, register, and personality. Multiple agents can share the same model but behave differently based on their soul file.

markdown

# Soul

You are a senior technical researcher. You write concisely. You use British English. 
You never use bullet points in executive summaries. You flag uncertainty explicitly.
You push back on vague requests and ask for precision.

Every tone correction you give — "too verbose," "wrong register," "stop being formal" — updates the soul file. Run "read me your soul file" at any time to inspect it.

Pillar 4 — Crons: Natural Language Scheduling

"Every night at 12am Central, push changes to this GitHub repo."

That single sentence creates both a skill file and a cron job. No YAML syntax. No crontab. No infrastructure setup beyond the initial server.

How cron sessions work:

  • Spins up a fresh isolated session at trigger time

  • Runs the skill

  • Sends the result to your messaging channel

  • Updates relevant files

  • Cannot create new cron jobs from inside a cron session (prevents runaway loops)

Examples of what you can schedule:

  • Daily news briefings sent to Telegram

  • Nightly GitHub syncs

  • YouTube comment monitoring runs

  • Server health checks every 10 minutes

  • Time-bounded runs: "For the next 12 hours, check comments every 10 min, then stop"

Pillar 5 — The Self-Improving Loop

The loop: you work → agent learns → you correct mistakes → agent encodes corrections → next session is better.

❝

⚠️ Automatic does not mean magic. Passive use produces some improvement. Active use — correcting mistakes, asking it to save things, letting it create skills after complex work — produces compounding improvement.

Every piece of feedback is a data point that gets encoded somewhere persistent. The agent isn't just executing tasks. It's building a model of how you want tasks executed.

💻 Installation

macOS / Linux / WSL2 / Android (Termux)

bash

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

bash

# Reload your shell after install
source ~/.bashrc   # or source ~/.zshrc

# Choose your model/provider interactively
hermes model

# Diagnose any setup issues
hermes doctor

# Start your first session
hermes chat
❝

⚠️ Windows: Native Windows is not supported. Install WSL2 first, then run the Linux commands above.

Connecting a Local Model (Ollama)

bash

hermes model
# → Select "Custom Endpoint"
# → API base URL: http://127.0.0.1:11434/v1
# → API key: press Enter (no key needed)
# → Select your local model from the list

🔧 Setup Step by Step

Step 1 — Set your secrets

bash

# Secrets file — API keys live here, never in chat
cat > ~/.hermes/.env <<'EOF'
OPENROUTER_API_KEY=your-key-here
BROWSERBASE_API_KEY=your-key-here
BROWSERBASE_PROJECT_ID=your-project-id
API_SERVER_ENABLED=true
API_SERVER_KEY=your-local-dev-key
EOF
❝

⚠️ Never paste API keys into the chat. Always use hermes config set KEY value or write directly to ~/.hermes/.env. Keys stored in chat appear in session logs.

Step 2 — Configure main settings

yaml

# ~/.hermes/config.yaml
model: anthropic/claude-sonnet-4-6  # Replace with your provider/model

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  container_persistent: true

browser:
  inactivity_timeout: 120

memory:
  memory_enabled: true
  user_profile_enabled: true

approvals:
  mode: manual   # Require approval for sensitive actions

security:
  allow_private_urls: false   # Blocks SSRF attacks

display:
  streaming: true

Step 3 — Onboard yourself (10 minutes, do this first)

Start a chat session and tell it:

Tell Hermes:
- Your name
- Your role and what you're building
- Your team structure (if relevant)
- Your preferred output format (CSV, markdown, etc.)
- Your English variant (British / American)
- 3 things you never want it to do
- Your current active project and its status

This populates user.md and memory.md with enough context that every subsequent session starts with a working model of you.

Step 4 — Set up your first cron (do this immediately)

"Every night at 12am, push all changes to my GitHub repo and send me a summary on Telegram."

This is your safety net. Do it before you build anything else.

Step 5 — Connect Telegram (optional but recommended)

bash

hermes gateway setup
# → Select Telegram
# → Follow the BotFather instructions in your terminal
# → Test by messaging the bot: "hello"

Step 6 — Give each agent its own credentials

bash

hermes config set GITHUB_TOKEN ghp_your_token_here
hermes config set NOTION_API_KEY secret_your_key_here

Treat each agent like a new hire: scoped access, named credentials, no sharing your personal accounts.

💬 Prompts to Use It

Memory Management

Remember that I want all reports in CSV format, British English, and concise executive summaries.
Add to user.md: never use bullet points in my deliverables.
What output format, English variant, and language do I prefer?
Read me your soul file.

Scheduling

Every weekday at 08:30, read ~/reports/daily_sales.csv, summarise anomalies, and send the result to my home channel.
For the next 12 hours, check my GitHub issues every 30 minutes and DM me anything tagged "urgent".
Every Sunday at 9am, pull the top 10 posts from Hacker News and email me a digest.

Research & Web Browsing

Open https://news.ycombinator.com, list the top 5 stories, click the first one, then summarise the article's core claim and any obvious caveats.
Search for the 5 most recent papers on agent memory systems, fetch each one, and write a comparative summary.

Sub-agent Delegation

Delegate this task to a sub-agent: scrape the pricing pages of our top 3 competitors and return a comparison table. Return only the final table to me.

Skill Creation

Turn what we just did into a skill. The trigger should be "competitor pricing audit". Save it to my skills folder.
Install this skill: [paste URL]
What did we decide about the database schema last week?
Find all sessions where we discussed the authentication flow.

📋 Commands Reference

Command

What it does

hermes chat

Start an interactive chat session

hermes model

Select or change your LLM provider and model

hermes doctor

Diagnose setup issues

hermes config set KEY value

Set a config value (routes to correct file automatically)

hermes cron list

List all scheduled cron jobs

hermes cron status

Show status of all cron jobs

hermes cron run <job_id>

Run a cron job immediately

hermes cron pause <job_id>

Pause a cron job

hermes gateway setup

Set up a messaging gateway (Telegram, Discord, Slack, etc.)

hermes skills list

List installed skills

📅 Daily Workflow

Morning (automated)

  • Hermes has already run overnight crons: GitHub sync, news digest, health checks

  • Check your Telegram for the overnight summary

Start of work session

  • hermes chat

  • Hermes loads memory.md and user.md — it already knows your context

  • Describe today's task. It picks up where you left off.

During work

  • Notice when it invokes a skill — which one? Right call?

  • If it should have used a skill and didn't: "Update the YAML front matter for [skill] so it recognises this trigger next time"

  • Correct mistakes in the moment: "That summary was too long — add that to my soul file"

End of session

  • "Save anything important to memory before we close"

  • The nightly GitHub cron handles persistence automatically

💡 Tips

1. When to split agents — the decision test Spin up a separate agent only if the new function needs: different permissions/API keys, separate long-term memory, or it's ongoing repeated work with a distinct audience. Otherwise, stay in one agent. One mega-agent with all the keys and 20 crons running simultaneously is a debugging nightmare.

2. Skills live in files — migrations are free When you're ready to split a function into its own agent, copy the relevant skill files over. No state transfer, no database migration. The agent's knowledge is in files you can move.

3. Context compression at 50% Hermes compresses the conversation context once it exceeds 50% of the available context window, preserving recent messages and grouping related tool calls. If a session feels like it's losing context, this is why — start a fresh session and it reloads cleanly from memory.md.

4. Progressive disclosure keeps context lean Skills use YAML front matter for selection — Hermes decides whether a skill is relevant without loading the full file. If a skill isn't firing, the trigger description in the front matter is wrong. Fix the description, not the body.

5. Parallel tool execution Hermes executes multiple tool calls in parallel via ThreadPoolExecutor (up to 8 workers). For research tasks with multiple web fetches, let it run — don't prompt it to do them one at a time.

6. Use execute_code for heavy lifting The execute_code tool lets the model write and run a Python script that calls other Hermes tools via a local RPC bridge. A 12-step web research task that would take a dozen model turns can be done in one.

🛠 Troubleshooting

Agent behaving oddly or contradicting itself

Cause: Stale memory.md — old project context that no longer applies
Fix: hermes chat → "Read me your memory.md" → "Remove the entry about [old project]"

Skill not firing on the right prompt

Cause: YAML front matter triggers don't match your phrasing
Fix: "Update the triggers in [skill name]'s front matter to include: [your phrasing]"

Cron jobs not running

Cause: Gateway service not running persistently after SSH close
Fix: Set up cron as a persistent background service
     sudo systemctl enable hermes-gateway
     sudo systemctl start hermes-gateway

Private URL blocked

Cause: allow_private_urls: false in config.yaml (correct security default)
Fix for dev use only: hermes config set security.allow_private_urls true
     ⚠️ Never enable on a public-facing server

Model rate limit / authentication error

Cause: API key issue or provider rate limit
Fix: Hermes automatically retries and can fall back to alternate models
     Check ~/.hermes/.env for correct key
     Run: hermes doctor

Session search returning empty results

Cause: FTS5 index not yet built for older sessions
Fix: hermes chat → "Search for sessions about [topic]"
     If still empty, the sessions predate the FTS5 index — use date-based filtering

Context window filling mid-task

Cause: Long session approaching context limit (compression triggers at 50%)
Fix: Start a fresh session — memory.md reloads your full context cleanly
     For very long tasks, use sub-agent delegation to keep each agent's context lean

⚡ Quick Reference

bash

# Install
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc

# First run
hermes model          # set your LLM provider
hermes doctor         # verify setup
hermes chat           # start session

# Secrets (never in chat)
hermes config set GITHUB_TOKEN your-token
hermes config set OPENAI_API_KEY your-key

# Crons
hermes cron list
hermes cron run <id>
hermes cron pause <id>

# Gateway (messaging)
hermes gateway setup  # follow prompts for Telegram/Discord/Slack

# Skills
hermes skills list

# In-session commands
"read me your memory.md"
"read me your soul file"
"install this skill: [URL]"
"save that to memory"
"create a cron for this"
"delegate this to a sub-agent"

@bestapps.ai — we find tools before everyone else

Keep Reading

View more
caret-right