I spent way too many hours wrestling with Hermes Agent before things clicked. You know the feeling: "Why doesn't it remember what I told it yesterday?" or "Why does my sub-agent have no clue what's going on?"
Turns out, most of the pain comes from three simple misunderstandings. Once you internalize these, Hermes becomes a completely different beast.
Let me save you the struggle.
The Three Things Nobody Tells You
Before you touch a single config file, you need to understand how Hermes actually thinks. There are three mental models that change everything:
1. Memory is Agent-Curated, Not Automatic
This is the biggest trap. You assume the agent writes down everything you say. It doesn't.
Hermes uses agent-curated memory — the agent decides what's worth keeping. This isn't a bug. It's a deliberate design choice that prevents context pollution and reduces token costs.
The fix is dead simple. When something matters, say it explicitly:
"Remember this preference: all my code uses Python 3.11."
"Save our progress: we finished data cleaning and feature engineering. Next is model training."
Pro tip: if you're in a long session and worried about losing context midway, ask the agent to write a TASK_STATUS.md file in your project directory. It's the most reliable way to persist state across sessions.
2. A Skill Is Not Code — It's a Reusable SOP
I kept thinking of skills as plugins or scripts. They're not. A skill is a standard operating procedure — just markdown that tells the agent "here's how to handle this kind of task."
Every good skill has four elements:
| Element | What it does |
|---|---|
| Trigger | When should the agent use this? |
| Steps | What exactly should it do, in order? |
| Verification | How does it know it succeeded? |
| Warnings | What traps has it fallen into before? |
The pattern is: you repeat a workflow → the agent notices → you tell it to create a skill → it crystallizes the pattern into reusable knowledge.
3. Sub-agents Start From Zero Context
This one burned me repeatedly. You spawn a sub-agent and say "fix that TypeError," expecting it to magically know which file, which line, which Python version.
It won't. Sub-agents launch from a fresh conversation context. They inherit nothing from the parent. You must pass everything explicitly:
delegate_task(
goal="Fix the TypeError in api/handlers.py",
context="""
File: /home/user/myproject/api/handlers.py
Error: line 47, TypeError: 'NoneType' object has no attribute 'get'
Root cause: parse_body() returns None when Content-Type header is missing
Project: Python 3.11 + Flask
"""
)
Being lazy with the context field is the #1 reason sub-agent tasks fail.
The Memory System: What Goes Where
Hermes has four memory files, and putting the wrong thing in the wrong one will drive you insane.
| File | What belongs here | Who writes it |
|---|---|---|
| SOUL.md | Stable rules, identity, behavior guidelines | You |
| USER.md | Your preferences, habits, personal details | Agent |
| MEMORY.md | Working notes, environment facts, project context | Agent |
Critical rule: Never put permanent rules in MEMORY.md. The agent can and will reorganize or compress it. SOUL.md is your safe space for anything that should never change.
Keep MEMORY.md under 1,800 characters (out of 2,200 max) and USER.md under 1,100 characters (out of 1,375 max). Staying at 70-80% capacity gives the agent breathing room.
Skills: When and How to Create Them
You don't need to create a skill for every little thing. But when you catch yourself repeating the same workflow for the third time, that's your signal.
Four essential skill commands for beginners:
Create a new skill:
"Save this data processing workflow as a skill called data-pipeline. Include trigger conditions, steps, verification methods, and gotchas."
Crystallize from memory:
"I notice you've been tracking our deployment process. Create a reusable skill for it called deploy-workflow."
Surgical update (never rewrite the whole thing):
"Update the stock-daily-report skill. Add to the warnings: 'Friday closing data may be delayed until Saturday morning.'"
Periodic audit:
"Review all your skills. Find duplicates (merge them), unclear ones (rewrite), and outdated ones (update). Give me a report first — I'll confirm before you execute."
Multi-Agent Collaboration: The Rules
Concurrency: 2 is plenty, 3 is the ceiling
Don't try to spawn 10 sub-agents at once. Start with 2. Most API providers will rate-limit you. More importantly, cost spirals out of control fast.
Use this pattern for parallel work:
This task can run in parallel:
- Subtask A: Pull today's market data
- Subtask B: Calculate sentiment indicators
- Subtask C: Generate the summary report
Spawn 3 sub-agents to handle these in parallel, then aggregate the results.
Assign clear roles
In SOUL.md or AGENTS.md, define who does what:
## Multi-Agent Collaboration Rules
- Planner Agent: task decomposition and progress tracking only; no execution
- Executor Agent: data retrieval and processing only; no decision-making
- Reviewer Agent: quality checks and validation only; no modifications
This prevents agents from stepping on each other's toes.
Profiles: One Machine, Multiple Hermes
Profiles give you completely isolated environments — separate configs, separate memories, separate sessions. They share nothing.
| Command | What it does |
|---|---|
hermes profile create mybot |
Fresh empty profile |
hermes profile create work --clone |
Copy API key + model config, fresh memory |
hermes profile create backup --clone-all |
Copy everything including memory |
Pro move: run a coding assistant in one terminal and a research assistant in another. No context cross-contamination.
The Production Checklist
If you're deploying Hermes to production, run through this:
- [ ]
hermes doctor— no errors - [ ] API keys in
.env, NOT inconfig.yaml - [ ]
GATEWAY_HEARTBEAT=true— prevents silent failures - [ ] User whitelist configured (e.g.,
TELEGRAM_ALLOWED_USERS) - [ ] Approvals mode set:
smartfor convenience,manualfor strict audit - [ ] Server timezone verified —
timedatectlshould show your actual zone, not UTC - [ ] Cron tasks manually verified once before going live
The Quick-Fix Table
| Problem | Why | Fix |
|---|---|---|
| Agent never remembers things | Session too short / agent deemed it unimportant | Say "save this to long-term memory" |
| Sub-agent doesn't know the task | No context passed | Fill the context field completely |
| Cron job doesn't fire | Wrong timezone / Gateway not running | Check timedatectl → check Gateway → test manually |
| API costs are exploding | Too many concurrent agents | Cap at 2-3, use cheaper models for sub-tasks |
| Tirith blocks every command | Approval mode too strict | Switch to smart mode |
Debug Commands to Know
hermes doctor # Full health check — run this first
hermes memory status # Is the memory system working?
hermes mcp status # Are MCP connections alive?
hermes cron list # What cron jobs do I have?
hermes cron run [name] # Manually trigger a cron job to test it
hermes debug share # Generate a sanitized debug report
The Bottom Line
Hermes isn't magic. It's three things:
- Memory solves "I forgot" — but you have to tell it what matters
- Skills solve "how do I do this again?" — crystallize workflows into reusable SOPs
- Sub-agents solve "this is too much for one agent" — but only if you give them full context
Most beginners struggle because they skip #1 (expecting the agent to just remember everything) and #3 (throwing sub-agents at problems without proper briefs).
Fix those two things, and 80% of the pain disappears.
Built with Hermes Agent. Documented from real experience — all of it earned the hard way.
Top comments (0)