Skip to content

Instantly share code, notes, and snippets.

@corywilkerson

corywilkerson/hermes-learning-guide.md

Created April 8, 2026 01:11
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save corywilkerson/413f4c459fce200fd9f8f4be14558817 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save corywilkerson/413f4c459fce200fd9f8f4be14558817 to your computer and use it in GitHub Desktop.
Download ZIP
Practical Hermes Agent learning guide: platform overview, workflows, and best practices
Raw
hermes-learning-guide.md

Hermes Agent Learning Guide

A practical guide to understanding Hermes Agent, using it well, and developing workflows that actually compound over time.

1. What Hermes is

Hermes is not just a chatbot in a terminal.

It is an autonomous agent framework with five big ideas:

  1. It can use tools.

    • terminal
    • file editing
    • browser automation
    • web search/extract
    • code execution
    • memory
    • skills
    • cron
    • delegation
    • MCP tools

  2. It can persist context across sessions.

    • USER memory = preferences about you
    • MEMORY = facts about your environment, projects, conventions, and lessons learned

  3. It can learn reusable procedures.

    • Hermes stores these as skills
    • skills are basically procedural memory and reusable playbooks

  4. It can operate across interfaces.

    • local CLI
    • Telegram, Discord, Slack, WhatsApp, email, and other gateways
    • ACP / editor integrations

  5. It can run long-lived and remotely.

    • local machine
    • VPS
    • Docker / SSH / Modal / Daytona / other backends

The simplest way to think about it:

Hermes = model + tools + memory + skills + automation + multi-surface access.

That combination is what makes it feel more like an operator than a chat window.

2. Mental model: how to use Hermes well

A strong Hermes workflow usually has 4 layers.

Layer 1: Ask for one-off help

  • answer a question
  • inspect a repo
  • fix a bug
  • summarize a page

Layer 2: Let it act with tools

  • run shell commands
  • read and edit files
  • browse websites
  • execute Python
  • call MCP servers

Layer 3: Make it stateful

  • save preferences in memory
  • add project rules in AGENTS.md
  • define your durable personality in SOUL.md

Layer 4: Make it compound

  • save good procedures as skills
  • schedule recurring jobs with cron
  • access it from messaging platforms
  • use profiles for separate roles or environments

If you only use layer 1, Hermes is “pretty nice.” If you consistently use layers 3 and 4, Hermes starts getting seriously good.

3. Fast start

Install:

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

Initial setup:

hermes model
hermes tools
hermes setup

Core commands to remember:

hermes                # open interactive chat
hermes chat -q "..." # one-shot query
hermes model          # change provider/model
hermes tools          # enable/disable toolsets
hermes doctor         # diagnose issues
hermes config edit    # edit config.yaml
hermes sessions list  # see old sessions

Best first prompt:

Inspect this repo, explain what it does, identify the highest leverage improvements, and propose a plan before making changes.

That prompt gets you a lot more value than “what can you do?”

4. The core building blocks

4.1 Models and providers

Hermes is provider-agnostic. You can swap models without changing your workflow.

That matters because you can optimize for:

  • reliability
  • cost
  • reasoning quality
  • coding quality
  • latency

Useful commands:

hermes model
/model

Good practical pattern:

  • use a reliable default model for daily work
  • temporarily switch to a stronger or cheaper model for specific jobs
  • keep the workflow constant, swap the brain underneath

4.2 Toolsets

Toolsets determine what Hermes can actually do.

High-value defaults:

  • terminal
  • file
  • web
  • browser
  • code_execution
  • skills
  • memory
  • session_search
  • delegation
  • cronjob

General rule:

  • enable only what you actually want available
  • after tool changes, start a fresh session (/reset) so prompt caching stays consistent

4.3 Memory

Hermes has two bounded stores:

  • USER.md: your preferences, style, habits
  • MEMORY.md: environment facts, project facts, conventions, lessons

This is not a giant dumping ground. It is supposed to stay curated and compact.

Best uses for memory:

  • preferred commit identity
  • preferred response style
  • stable repo locations
  • house rules like “always run tests before commit”
  • environment quirks like “Docker is installed, but use local backend by default”

Bad uses for memory:

  • temporary task progress
  • giant logs
  • session transcripts
  • things easily rediscovered from files

4.4 Skills

Skills are one of Hermes’s best features.

A skill is a reusable playbook with:

  • when to use it
  • step-by-step procedure
  • pitfalls
  • verification

Use skills when you notice repetition.

Examples:

  • PR workflow
  • release process
  • deploy-staging
  • oncall triage
  • daily market watch
  • research brief format
  • local dev environment bootstrap

The ideal pattern is:

  1. solve something once
  2. refine the approach
  3. save it as a skill
  4. reuse it forever

Useful commands:

hermes skills list
hermes skills browse
/skills
/skill <name>

4.5 Context files

Two files matter a lot.

SOUL.md

  • durable instance-wide personality and communication style
  • lives in ~/.hermes/SOUL.md

AGENTS.md

  • project-specific rules and context
  • lives in repo root
  • automatically loaded per project

Use SOUL.md for “who the agent is.” Use AGENTS.md for “how this repo works.”

A great AGENTS.md usually includes:

  • architecture notes
  • coding conventions
  • test commands
  • file layout rules
  • deployment or safety constraints
  • what to never do

4.6 Profiles

Profiles let you run separate Hermes personas/configs/memory stores.

Use profiles when you want isolation between:

  • work vs personal
  • coding vs research
  • local dev vs production ops
  • different clients or teams

Commands:

hermes profile list
hermes profile create work
hermes profile use work

Profiles are underrated. They prevent context pollution.

4.7 MCP

MCP is how Hermes gains external tool ecosystems without you writing every tool natively.

This is a huge unlock.

Use MCP when you want Hermes to interact with:

  • GitHub
  • databases
  • browser stacks
  • internal APIs
  • filesystem servers
  • custom business systems

Think of MCP as “plugging in new hands.”

Best practice:

  • add narrowly scoped MCP servers
  • filter exposed tools per server
  • avoid dumping giant unsafe toolsets into every session

5. Ideal workflows

Here are the workflows where Hermes is strongest.

Workflow A: Repo operator

Best for:

  • debugging
  • feature implementation
  • code review
  • refactors
  • test fixing

Setup:

  • terminal + file + code_execution + skills
  • AGENTS.md in repo root
  • reliable coding model

Prompt pattern:

Inspect the repo, identify the relevant files, explain the issue, propose the smallest correct fix, implement it, run verification, and summarize the change.

Why this works:

  • Hermes can search, edit, run tests, and verify
  • AGENTS.md keeps it aligned with project conventions
  • repeated patterns can be promoted into skills

Ideal loop:

  1. Ask Hermes to inspect before coding
  2. Have it write or confirm a plan
  3. Let it execute
  4. Require verification
  5. Save durable workflows as skills

Workflow B: Research and monitoring agent

Best for:

  • topic watches
  • news summaries
  • competitor tracking
  • market or technical research
  • recurring digests

Setup:

  • web + browser + skills + cronjob + messaging gateway

Prompt pattern:

Track this topic daily, filter for what actually matters, and deliver a concise brief with links and implications.

Why this works:

  • Hermes can gather info, summarize it, and deliver results on a schedule
  • cron makes it recurring
  • messaging makes it accessible anywhere

Ideal loop:

  1. manually prototype the brief in chat
  2. improve the format over 2-3 runs
  3. save the procedure as a skill
  4. attach the skill to a cron job
  5. deliver to Telegram/Discord/email/origin

This is one of the most “rad” use cases in the whole platform.

Workflow C: Remote operator on a server or VPS

Best for:

  • long-running autonomous tasks
  • background research
  • remote dev and automation
  • persistent assistants you message from your phone

Setup:

  • run Hermes on VPS or cloud box
  • install gateway
  • configure Telegram or Discord
  • optionally use Docker/SSH backend for safer command execution

Why this works:

  • Hermes is not tied to your laptop session
  • you can message it while it works remotely
  • cron + gateway + memory makes it feel like a living system

Ideal loop:

  1. install Hermes on a persistent machine
  2. set up a gateway
  3. define a small number of trusted automations
  4. use cron for recurring tasks
  5. review outputs, tighten skills, repeat

Workflow D: Team or project-specific specialist

Best for:

  • support engineering
  • incident response
  • internal platform docs
  • company-specific workflows
  • repos with lots of conventions

Setup:

  • profile per project/team
  • AGENTS.md per repo
  • MCP connections to internal tools
  • curated memory and custom skills

Why this works:

  • Hermes becomes specialized without fine-tuning
  • skills + AGENTS.md + MCP do most of the work

Ideal loop:

  1. encode project conventions in AGENTS.md
  2. add external systems via MCP
  3. teach repeated processes as skills
  4. isolate with a profile
  5. use session_search and memory to keep continuity

Workflow E: Multi-agent execution

Best for:

  • parallel research
  • splitting backend/frontend work
  • context-heavy tasks
  • keeping main context clean

Use:

  • delegate_task for bounded subtasks
  • worktree mode (-w) when multiple code agents touch a repo
  • full spawned Hermes sessions only for long, truly separate missions

Rule of thumb:

  • use delegate_task for quick parallel reasoning
  • use spawned Hermes processes for longer autonomous jobs

6. My recommended “ideal setup” for most power users

If you want Hermes to feel great quickly, I would do this:

  1. Pick a reliable provider/model you trust.
  2. Enable toolsets: terminal, file, web, browser, code_execution, skills, memory, delegation, cronjob.
  3. Put good defaults in SOUL.md.
  4. Add AGENTS.md to every serious repo.
  5. Save any workflow that took real iteration as a skill.
  6. Use a messaging gateway for remote access.
  7. Set up 2-5 cron jobs that create recurring leverage.
  8. Use profiles to separate domains.

This setup is where Hermes stops being “chat with tools” and starts becoming infrastructure.

7. Recommended command and prompt patterns

7.1 Good one-shot commands

hermes chat -q "Summarize the architecture of this repository and identify the 3 highest-risk areas."

hermes chat -q "Review the last 10 git commits and propose a clean changelog."

hermes chat -q "Read the docs for tool X and explain the ideal setup for our use case."

7.2 Good interactive prompts

For coding:

Inspect first. Do not make changes until you can explain the likely root cause and the smallest robust fix.

For research:

Be opinionated about signal vs noise. I care about implications, not just summaries.

For automation:

Prototype the workflow manually first. Once the format is good, turn it into a reusable skill and suggest a cron schedule.

7.3 Good slash commands

/help
/model
/tools
/skill <name>
/title my-session
/compress
/voice on

8. Best practices that matter most

  1. Be specific in requests. Mention files, goals, constraints, and verification.

  2. Let Hermes inspect before acting. Especially for code, infra, or docs.

  3. Put recurring instructions in files, not repeated prompts.

    • SOUL.md for personality
    • AGENTS.md for project rules

  4. Save high-value workflows as skills. If something took multiple iterations, it is a skill candidate.

  5. Use cron only after you like the manual result. Never automate a sloppy prompt.

  6. Use profiles to avoid contamination. Different domains should not all share the same assumptions.

  7. Use MCP surgically. Only expose tools the agent should actually see.

  8. Prefer verification loops. Ask for tests run, outputs checked, or evidence collected.

  9. Treat memory as precious. Save only durable, high-value facts.

  10. Keep the system compounding. The best Hermes users are constantly converting successful work into reusable structure.

9. Anti-patterns

Avoid these:

  • Using Hermes like a plain chatbot and never enabling useful tools
  • Repeating the same instructions every session instead of using AGENTS.md or skills
  • Storing temporary junk in memory
  • Attaching too many unsafe or irrelevant MCP tools
  • Automating bad prompts with cron before validating the output quality
  • Running many code-editing agents in one repo without worktree isolation
  • Using one profile for everything

10. A 7-day learning path

Day 1

  • install Hermes
  • pick a model
  • enable core toolsets
  • do 3 one-shot tasks

Day 2

  • use Hermes in a real repo
  • add AGENTS.md
  • have it inspect, plan, edit, and verify

Day 3

  • customize SOUL.md
  • test slash commands
  • resume an old session

Day 4

  • create or install 1-2 useful skills
  • ask Hermes to save a successful workflow as a skill

Day 5

  • connect one MCP server
  • try a narrowly scoped external tool workflow

Day 6

  • set up a messaging gateway
  • message Hermes remotely

Day 7

  • build one recurring cron job that produces a genuinely useful daily or weekly output

After that, the platform starts clicking.

11. The highest-leverage use cases

If someone asked me where Hermes is most differentiated, I would say:

  1. Long-lived coding and repo work with memory + skills
  2. Personalized recurring research briefs
  3. Remote agent workflows through messaging
  4. Project-specific specialists built with AGENTS.md + MCP + profiles
  5. Converting successful work into durable skills

That compounding loop is the main thing to internalize.

12. My opinionated bottom line

The ideal Hermes workflow is:

  • stable personality in SOUL.md
  • project context in AGENTS.md
  • reliable core toolsets enabled
  • real tasks executed with tools, not just chat
  • durable facts saved into memory sparingly
  • repeated workflows turned into skills
  • recurring value delivered through cron
  • remote access through a gateway
  • profiles used to isolate domains

In short:

Use Hermes first as an operator, then as a system, then as a compounding asset.

That is where the platform gets rad.

13. Useful links

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment