Hermes Framework Guide

Hermes is a persistent-memory agent framework suited for assistants that learn over time, use tools, schedule work, and operate across messaging platforms.

Hermes uses the same Hatcher config surface as OpenClaw: pick a provider, pick a model, configure integrations, then launch. Personality builder and duplicate behavior fields are no longer separate required steps.

Quick Facts

Property	Value
Runtime	Hermes container managed by Hatcher
API port	8642
Config files	`config.yaml`, `.env`, `SOUL.md`, memory files
Hosted LLM	OpenRouter through the Hatcher LLM proxy
BYOK	OpenAI, Anthropic, Google, Groq, xAI, OpenRouter
Billing	Hosted usage spends AI Credits; BYOK does not

Create A Hermes Agent

Start in Chat-to-Hatch

Describe the agent you want to build and select Hermes if Chat-to-Hatch does not pick it automatically.

Review identity and model

Hatcher generates the agent identity files and model config. Choose the hosted provider/model, or switch to BYOK and paste your provider key.

Add integrations

Enable Telegram, Discord, Slack, Signal, Matrix, Email/SMS, Mattermost, and other automation connectors. Integrations are included on every tier.

Launch

Click Launch Agent. Hatcher writes the config, starts the container, monitors health, and stores logs/files on the persistent workspace volume.

Generated Configuration

Hatcher writes the Hermes config from dashboard fields. A simplified hosted setup looks like this:


model:
  default: hatcher-llm-proxy/provider/model
  context_length: 131072
 
terminal:
  backend: local
  timeout: 180
 
web:
  backend: tavily
 
memory:
  memory_enabled: true
  user_profile_enabled: true
 
compression:
  enabled: true
  threshold: 0.50
 
agent:
  max_turns: 30
 
streaming:
  enabled: true
 
approval_mode: "off"

The .env file receives either Hatcher proxy credentials or BYOK credentials. BYOK secrets are encrypted at rest and are not returned to the frontend after saving.

SOUL.md And Memory

Hermes uses:

SOUL.md for the agent identity and operating rules
MEMORY.md for facts about the agent
USER.md for remembered user context
Session memory for longer-running conversations and summaries

These files live in the agent workspace volume and survive container restarts. Deleting the agent deletes the workspace.

Tools

Hermes toolsets are included on every tier:

Toolset	Description
Web	Hosted web search, URL fetching, scraping
File	Workspace file read/write/list operations
Vision	Image analysis
Todo	Task list management
Memory	Persistent memory writes and recalls
Skills	Skill discovery and execution
Terminal	Sandboxed shell commands inside the container
Cron	Scheduled tasks

Hosted web/research tool usage spends AI Credits. If you configure BYOK/provider-paid tools, those costs are handled by your provider.

Integrations

All integrations are included on every Hatcher plan. You provide credentials:

Platform	Credential
Telegram	Bot token from @BotFather
Discord	Bot token and Message Content Intent
Slack	Bot token and app-level token
Signal	signal-cli HTTP bridge URL and account
Matrix	Homeserver and bot access token
Email/SMS	Mailbox app password or Twilio credentials
Webhooks	Hatcher-generated webhook URL

WhatsApp exists upstream in Hermes, but its pairing wizard currently requires an interactive TTY. In Hatcher, dashboard QR pairing is available on OpenClaw agents; Hermes users can still pair WhatsApp from the agent terminal with hermes whatsapp.

Resource Limits

Plan	CPU	RAM	Workspace	Runtime
Free	1 CPU	1 GB	2 GB	Sleeps after 12h idle
Starter	1 CPU	1.5 GB	10 GB	Always-on
Pro	1.5 CPU	4 GB	25 GB	Always-on
Business	4 CPU	6 GB	50 GB	Always-on
Founding Member	4 CPU	6 GB	40 GB	Always-on

Troubleshooting

Agent says it uses the wrong model

Restart the agent after saving model config. Hermes reads model environment/config at startup. The dashboard config should show the selected provider and model; hosted runtime IDs are normalized through the Hatcher LLM proxy.

Insufficient AI Credits

Hosted usage is blocked when the account balance is exhausted. Buy an AI Credit pack, upgrade your plan, or switch to BYOK.

Memory not saving

Check Logs for filesystem or workspace errors, then restart the agent. Memory persists only while the same agent/workspace exists.

Integrations not responding

Confirm the agent is Active, credentials are correct, and the container was restarted after credential changes.