Chapter 1 — Getting Started
What is Hermes Agent?
Hermes is an AI agent framework, a harness that wraps around language models and gives them persistent memory, tools, skills, and access to multiple platforms (Discord, Telegram, CLI).
Think of it this way: ChatGPT is a conversation. Hermes is a coworker. It remembers your preferences, has access to your tools, runs on your schedule, and communicates with you wherever you are.
What makes Hermes different:
| Feature | ChatGPT / Claude Web | Hermes |
|---|
| Memory | Per-session only | Persistent across sessions |
| Tools | Limited (web, code interpreter) | Anything you configure |
| Access | Browser only | CLI, Discord, Telegram, API |
| Automation | None | Cronjobs, scheduled tasks |
| Customization | System prompt only | SOUL.md, skills, plugins, profiles |
| Multi-model | One model per chat | Switch models per task/channel |
✓ Hermes makes sense when
- You use AI daily for work
- You need AI to remember context between sessions
- You want AI accessible from multiple platforms
- You want to automate repetitive AI tasks
- You need AI to interact with your tools and data
✗ Skip it when
- You use AI occasionally for simple questions
- You're comfortable with web interfaces
- You don't need persistence or automation
1.1 — Setup
Installation
Prerequisites: a machine running Linux or macOS, Node.js installed, and an API key from at least one AI provider (OpenAI, Anthropic, OpenRouter, etc.).
setup.sh
# Install Hermes
npm install -g hermes-agent
# Run initial setup
hermes setup
# Configure your model provider
hermes setup models
# Configure tools
hermes setup tools
# Start your first conversation
hermes
Verify installation:
This shows your active configuration: model, provider, tools, memory status, and connected platforms.
1.2 — Vocabulary
Key concepts
⚙
Profiles
Independent configurations. Each has its own skills, memory, plugins, and settings. Use a "work" profile and a "personal" profile.
★
Skills
Reusable procedures. When you figure out something complex, save it. Next time, Hermes loads the proven approach instead of reinventing it.
🧠
Memory
Persistent facts. Preferences, environment details, project conventions — anything that should survive between sessions. Injected automatically.
🔌
Gateway
Platform connections. Discord and Telegram gateways let you interact with Hermes from chat apps, not just the terminal.
Chapter 2 — SOUL.md Engineering
What is SOUL.md?
SOUL.md is your AI's personality file, a set of instructions that shapes how Hermes behaves in every conversation. It's the most powerful customization tool because it's injected into every session before you type a single word. Think of it as the employee handbook for your AI coworker.
✓ What goes in
- Communication style (formal, casual, direct, verbose)
- Behavioral rules (check memory first, never over-apologize)
- Output preferences (concise by default, expand on request)
- Boundaries (what to refuse, what to warn about)
- Language preferences (Indonesian, English, mixed)
- Domain-specific rules (coding conventions, writing style)
✗ What does NOT go in
- Temporary task instructions (use the conversation)
- Data or knowledge (use memory or skills)
- Complex procedures (use skills)
- Things that change frequently
2.1 — The four rules
How to write a good SOUL.md
Rule 1: Be specific, not vague.
✗ Bad
"Be helpful and concise"
"Write good code"
✓ Good
"Default to under 5 lines. Expand only when user says 'elaborate' or 'detail'."
"Use Python 3.11+. Type hints on all functions. Docstrings on public methods. Prefer stdlib over external packages."
Rule 2: Define behavior, not personality.
✗ Bad
"You are a friendly, enthusiastic assistant"
✓ Good
"Match the user's energy. Casual if they're casual. Formal if they're formal. Never start responses with 'Sure!' or 'Great question!'"
Rule 3: Include concrete examples.
✗ Bad
"Format output appropriately"
✓ Good
"When providing code, use this format: Problem [1 line] → Solution [code block] → Next [1 action]"
Rule 4: Set boundaries clearly.
✓ Good
"Never share API keys or credentials in output. Warn once if a command could delete data. If user confirms, execute without further warnings."
2.2 — Recipes
Common SOUL.md patterns
⚡ The operator
You are an execution agent. Bias toward delivery. No motivational fluff. No hedging. Code over explanation. If a task carries risk, ask once. If confirmed, execute.
✍️ The writer
Write in active voice. Short sentences. No em dashes. Strip AI-isms. Every paragraph must have a specific example.
🔬 The researcher
Always cite sources. Distinguish verified facts from inferences. Flag uncertainty with confidence levels. Present counterarguments.
Iterative improvement: SOUL.md is never "done." Notice patterns you repeatedly correct → convert them into rules → test → refine. After a month, it should feel like the AI truly knows how you work.
Chapter 3 — Skills & Memory
The memory system
Hermes has two types of persistent storage that survive between sessions:
📄 MEMORY.md
Your personal notes to the AI. Facts about the environment, project conventions, tool quirks, lessons learned. Injected into every session.
👤 USER.md
Who the user is. Name, role, preferences, communication style, pet peeves. Helps the AI personalize its behavior.
✓ Save
- User preferences ("Prefers Indonesian casual, lo/gue style")
- Environment facts ("Server runs Ubuntu 22.04, Python 3.11")
- Project conventions ("Uses pytest with xdist")
- Tool quirks ("OpenRouter 402 despite valid key — route through proxy")
✗ Don't save
- Task progress ("Fixed bug #123")
- Temporary state ("Currently working on feature X")
- Anything stale in 7 days
- Raw data dumps
The rule: if the fact will still be useful next month, save it. If it's only useful today, don't.
Skills are reusable procedures, step-by-step instructions for recurring tasks. Unlike memory (which is facts), skills are processes.
skill: deploy-to-vps.md
# Deploy to VPS
## When to use
User asks to deploy code to production VPS.
## Steps
1. Run tests: pytest -n 4
2. Commit: git add . && git commit -m "deploy"
3. Push: git push origin main
4. SSH to VPS: ssh user@YOUR_VPS_IP
5. Pull and restart: cd /app && git pull && systemctl restart app
## Pitfalls
- Always run tests BEFORE pushing
- Check branch is 'main', not 'master'
## Verification
- curl https://api.example.com/health returns 200
Skills vs Memory: Memory = facts ("The server is at YOUR_VPS_IP"). Skills = procedures ("How to deploy to the server").
Chapter 4 — Gateways
Reach Hermes everywhere
A gateway bridges a chat platform (Discord, Telegram) with Hermes. Instead of opening a terminal, you message Hermes like you'd message a friend.
You→
Telegram / Discord→
Hermes Gateway→
AI Model→
Response back to chat
💬 Telegram
Create a bot via @BotFather → get token → hermes setup telegram. Supports text, media, voice (speech-to-text), commands, and scheduled delivery.
🎮 Discord
Create a bot in the Developer Portal → get token → add to server → hermes setup discord. Supports threads (each = separate context), channel-model overrides, slash commands.
Multi-channel setup: with channel-model overrides, one Hermes instance serves multiple channels with different models.
channel routing
#general → Default model (fast, cheap)
#coding → Claude Opus (deep reasoning)
#research → GPT-4o with web search
#monitoring → Scheduled cronjob output
Configure overrides in your Hermes config, and routing happens automatically.
Chapter 5 — Multi-Agent & Automation
Subagents, scheduling & tools
Hermes can spawn subagents, separate AI workers that handle tasks in isolation and return results.
delegation
You: "Research these 3 topics simultaneously"
Hermes: Spawns 3 subagents
Subagent A → Research topic 1
Subagent B → Research topic 2
Subagent C → Research topic 3
(all run in parallel)
Hermes: Compiles all 3 results into one response
Each subagent has its own context, tools, and terminal session. They don't interfere with each other or with your main conversation.
Cronjobs & scheduling: run tasks on a schedule.
cronjob
Schedule: "every day at 9am"
Task: "Check server health at YOUR_VPS_IP.
Report: CPU, RAM, disk, running services.
Only send alert if anything is abnormal."
Delivery: Telegram
Delivery options: back to the same chat (default), to a specific Telegram chat or Discord channel, to local files only, or to all connected platforms simultaneously.
MCP (Model Context Protocol) is a standard for connecting AI models to external tools. Think of it as USB-C for AI — one standard connector that works with many devices. Hermes has its own broader tool system (terminal, files, web, browser automation, image generation) plus plugin support for anything you can code.
Chapter 6 — Real Examples
From terminal to everywhere
Problem
Hermes only worked in the terminal. Couldn't access from phone or when away from computer.
Result
Set up Telegram gateway. Questions that used to require sitting at a computer now get answered from the phone. Cronjob alerts arrive as Telegram notifications. The AI is always available.
Problem
Manually checking server status, bot health, and data quality every morning. Took 20–30 minutes.
Result
Cronjob at 9 AM checks metrics, verifies processes, scans logs. Normal days get a one-line "all clear." Abnormal days get a detailed alert. Saved 20 minutes daily, catches issues faster.
Problem
Different tasks need different models. Quick questions waste expensive tokens. Complex tasks get poor results from cheap models.
Result
Channel-model overrides route by channel. 60% reduction in API costs. Better quality on complex tasks. Faster responses on simple ones. Right model for right task, every time.
The Guide is complete. What comes next is up to you: build something, set up Hermes, or go deeper into any topic that interests you.
← Back to Home
Restart The Guide
