hermes-toolkit

name	hermes-toolkit
description	Production toolkit for Hermes Agent — orchestration patterns, memory management, tool selection, prompt engineering, and performance optimization
version	1.0.0
license	MIT
metadata	{"author":"azizaeffendi","hermes":{"tags":["toolkit","orchestration","memory","prompt-engineering","performance","multi-agent","production","configuration"],"category":"productivity","requires_toolsets":["terminal"]}}

The operational toolkit for running Hermes Agent in production. Covers how to orchestrate multiple agents, manage memory effectively, select the right tool for each task, write better system prompts, and optimize for speed and cost.

Think of this as the "how to get the most out of Hermes" reference — loaded when questions are about configuration, patterns, and operation rather than specific task domains.

The Core Principle

Match the tool to the task. An agent that uses the terminal for everything it could do with a file read tool wastes tokens. An agent that spawns subagents for every task it could handle inline wastes time. This toolkit teaches the agent to make the right calls.

When to Use

• User asks how to configure Hermes: "how do I set up memory?", "how do I customize the agent?", "what config options are there?"
• User asks about performance: "why is the agent slow?", "how do I reduce token usage?", "how do I make it cheaper?"
• User wants multi-agent workflows: "can I run multiple agents?", "how do I orchestrate agents?", "I need parallel work"
• User asks about prompting: "how do I write a good system prompt?", "what's SOUL.md?", "how do I tune the agent's personality?"
• User asks about memory: "how does memory work?", "why doesn't the agent remember X?", "how do I make it remember?"
• User asks which tool to use: "should I use terminal or web_extract?", "what's the right tool for this?"

Quick Reference

# Check current Hermes config
hermes config show

# List installed skills
hermes skill list

# Check memory usage
hermes memory stats

# Start with a specific model
hermes --model nous/hermes-4-70b

# Run in a specific profile
hermes --profile work

# Spawn a subagent from within a session
# In conversation: "spawn an agent to do X in parallel"

# Check tool availability
hermes toolset list

# Run a skill directly
hermes chat --toolsets skills -q "Use the hermes-security skill to audit this project"

Toolkit Domains

01 — Agent Orchestration When and how to spawn subagents, sequential vs parallel workflows, result aggregation, context passing between agents, error handling in multi-agent setups. → Load: references/agent-orchestration.md

02 — Memory Management Hermes three-tier memory system, configuring memory behavior, search and recall, pruning stale memories, cross-session continuity, Honcho user modeling. → Load: references/memory-management.md

03 — Tool Selection Decision guide for every tool class: terminal, web_extract, read_file, write_file, execute_code, skill_view, search. When each is optimal and when it wastes tokens. → Load: references/tool-selection.md

04 — Prompt Engineering System prompt structure, SOUL.md personality configuration, per-task context injection, few-shot examples, instruction clarity, constraint framing. → Load: references/prompt-engineering.md

05 — Performance Optimization Model selection by task complexity, context window management, compression triggers, batching tool calls, reducing round trips, cost optimization patterns. → Load: references/performance-optimization.md

Core Instructions

• When answering configuration questions, always show the exact config.yaml key and its default value.
• When explaining multi-agent patterns, always show a concrete example with expected timing.
• For performance questions, always quantify: "this reduces token usage by ~30%" not "this is more efficient."
• For memory questions, check the current state with hermes memory stats before recommending changes.
• When suggesting SOUL.md changes, explain the behavioral impact: "this makes the agent more concise by..."

Configuration Reference

Key config.yaml Settings

# Model and inference
model: nous/hermes-4-70b          # default model
context_budget: 100000             # soft limit before compression
compress_at: 0.5                   # compress at 50% of context budget

# Skills
skills:
  auto_create: true                # create skills from complex tasks
  auto_improve: true               # self-improve skills during use
  inline_shell: false              # allow !cmd in skill bodies

# Memory
memory:
  fts_search: true                 # full-text search across sessions
  user_model: true                 # Honcho user modeling
  nudge_interval: 15               # tool calls between memory nudges

# Terminal backend
terminal:
  backend: local                   # local | docker | ssh | modal | daytona

# Gateway (messaging platforms)
gateway:
  enabled: false
  platforms: []                    # telegram | discord | slack | whatsapp

SOUL.md Template

# Identity
[One sentence describing who the agent is]

# Core Behaviors
- [Behavior 1]
- [Behavior 2]
- [Behavior 3]

# Expertise
- Primary: [main domain]
- Secondary: [supporting domains]

# Communication Style
- [Style guideline 1]
- [Style guideline 2]

# Constraints
- [What the agent should NOT do]

Multi-Agent Patterns Quick Reference

Pattern 1: Sequential Pipeline
  task → agent-A → result-A → agent-B(result-A) → final

Pattern 2: Parallel Fan-Out
  task → [agent-A, agent-B, agent-C] (all run simultaneously)
       → aggregator → merged-result

Pattern 3: Specialist Router
  task → orchestrator → classify task type
       → /security  → security-agent
       → /deploy    → devops-agent
       → /debug     → debugging-agent

Pattern 4: Iterative Refinement
  draft → reviewer → feedback → reviser → final

Pitfalls

• Over-spawning subagents — spawning an agent for a task you could do in 2 tool calls wastes 30+ seconds of cold start time. Spawn when the task is genuinely parallel or requires isolation.
• SOUL.md too long — SOUL.md loads on every turn. Keep it under 500 tokens. Move detailed domain knowledge into skills, not personality.
• context_budget too high — setting context_budget to the model's maximum means the agent never compresses, costs more, and gets slower as sessions grow. Keep it at 50–70% of max.
• auto_create skills without review — auto-created skills can encode mistakes. Periodically run hermes skill list and review auto-created skills.
• Sharing profiles across users — each user should have their own profile (--profile username). Shared profiles mix memory and configuration.
• Using terminal for file reads — cat file.txt costs 1 terminal tool call + a subprocess. read_file is direct. Use the right tool.

Verification

# Agent is configured correctly
hermes config show | grep -E "model:|context_budget:|auto_create:"

# Skills are installed and visible
hermes skill list | grep -E "hermes-security|vibe-guard|hermes-automation|hermes-toolkit"

# Memory is working
hermes chat -q "What do you remember about me?"
# → Should recall recent session context

# Performance baseline
time hermes chat -q "What is 2+2?"
# → Should complete in < 3 seconds on local model

# Multi-agent test
hermes chat -q "Spawn two agents: one to read README.md and one to list files in this directory. Report both results."
# → Should complete both tasks in parallel

References

• references/agent-orchestration.md — Spawning agents, patterns, result merging, error handling
• references/memory-management.md — Memory tiers, search, pruning, user modeling
• references/tool-selection.md — Which tool to use when, decision guide, anti-patterns
• references/prompt-engineering.md — System prompts, SOUL.md, context injection
• references/performance-optimization.md — Speed, cost, context window management