Architecture
Hermes listens to an event stream and acts with four tools.
Home Assistantyour existing install: entities, automations and the two APIs below. A non-admin HA user issues the token.
WebSocket · state-change eventsthe gateway platform. Filtered by
platforms.homeassistant.extra: watch_domains, watch_entities, watch_all, ignore_entities, cooldown_seconds (default 30). Events are pushed, so nothing polls.REST · the four HA tools
ha_list_entities · ha_get_state · ha_list_services · ha_call_service. They switch on once HASS_TOKEN is in ~/.hermes/.env.events ↓ ↑ tool calls
Hermes gateway daemon
hermes gateway, installable as a systemd or launchd service. Each event that passes the filter and cooldown becomes a model turn. Route it to a cheap model.consults ↓
Memory
~/.hermes/memories/MEMORY.md (2,200-char cap) + USER.md (1,375) go into the system prompt; the memory tool edits them; session_search over full history in ~/.hermes/state.db (SQLite FTS5).Approvals
approvals.mode = smart | manual | off; approvals.deny fnmatch globs over tool patterns. See setup.you build thisHouse-map skilla
SKILL.md under ~/.hermes/skills/ mapping everyday names to exact entity IDs. Hermes writes it with skill_manage (prompt 1).you build thisPattern distillera nightly cron job (
hermes cron create, jobs live in ~/.hermes/cron/) that reviews recent event sessions via session_search and folds patterns into memory (prompt 3).speaks via ↓
Telegram (or any gateway platform)nudges out, approvals back. Discord, Signal, WhatsApp, ntfy and about 20 others work the same way.
The four tools
As of v0.19.0 the Home Assistant toolset is exactly:
| Tool | What it does in this build |
|---|---|
ha_list_entities | The census. Builds the house map in prompt 1; rerun when you add devices. |
ha_get_state | Checks before acting, like whether a window is open. |
ha_list_services | Shows what a domain can do, so the agent doesn’t guess service names. |
ha_call_service | The only way to change anything, which is what makes approvals workable. |
How it learns
There’s no vector store and no fine-tuning. It has three parts:
- Memory in the prompt.
MEMORY.mdholds about 15 to 25 short rules and is added to every turn. The 2,200-character cap forces it to distill. - Search for everything else. Every session, every event
included, is searchable with
session_search(full-text, no embeddings). - A nightly job you schedule. It connects the two: search recent sessions, propose patterns, keep the good ones and trim stale ones. You define it in prompt 3.
If you outgrow the cap, there are memory plugins (Mem0, Honcho and others), but start without one.
When it’s down. If the model API or gateway goes down, events go unnoticed and HA keeps running its own automations. That’s why safety logic stays in HA (product spec).