ADR 13: Conversational agents
Client bots and the personal agent, and the wall between them.
Status: adopted (2026-07-21)
Decision
Two agent surfaces, never sharing a runtime, credential, or memory store:
- Client bots: a Hermes profile per client on ops-1 (
hermes profile create <client>), each with its own SOUL.md personality, memory, and a DEDICATED WhatsApp number paired by QR (hermes whatsapp). The bot is a contact the client adds to chats and groups, the OpenClaw pattern. Owner decision 2026-07-21: personal-style pairing over the Business Cloud API, accepting the unofficial-link ban risk; use a dedicated prepaid/eSIM number per bot, never a person’s own number, so a ban costs nothing.hermes whatsapp-cloudremains available for any compliance-sensitive client. The Chatwoot bot runtime (Backpack-Ops/bots, bots-silk.vercel.app, verified) is repositioned for website live chat through iese inboxes. - The personal agent: the
davidHermes profile on ops-1, channels Telegram first (WhatsApp/Signal/Discord available), model via OpenRouter or the gateway. It holds the owner’s accounts and life; client bots hold client data only. This wall is absolute.
Go-live runbook (per profile)
- Model: set an OpenRouter key,
hermes modelto pick (kimi-k2 class for cost). Separate keys per trust domain for clean billing. - Personality: edit
~/.hermes/profiles/<name>/SOUL.md. - Channels:
hermes whatsappinside the profile shows a QR in the terminal; scan it with the WhatsApp app on the bot’s dedicated number’s phone within the expiry window. Telegram: token from BotFather into the gateway setup. hermes gateway install && hermes gateway startfor the profile; verify withhermes gateway status.
Bot behavior contract (website-chat runtime)
- Replies short and human, voice rules apply (no em dashes, nothing AI-sounding).
- Only facts from the persona file; unknowns get an honest answer and a handoff.
- Handoff (marker-based) flips the Chatwoot conversation to open: humans take over, bot goes silent. Bot only ever speaks while the conversation is pending.
- Webhook is token-guarded per client; errors return 200 so Chatwoot never retry-loops.
iMessage (the Mac relay)
iMessage requires a Mac. Pattern: the old Mac Studio runs BlueBubbles Server signed into the owner’s Apple ID, reachable from ops-1 over Tailscale only, bridged into Hermes with a small adapter. Optional, personal-agent only; client bots never touch iMessage.
Why Hermes over reviving OpenClaw
Same chassis-vs-model logic as ADR 12: Hermes is MIT, multi-channel, model-agnostic (the old cost problem was the raw Anthropic API, not the harness), has memory/skills/cron/subagents, and runs headless on the VPS instead of being chained to a laptop.
Channels beyond WhatsApp (2026-07-21 addendum)
Not every client lives on WhatsApp, and that changes nothing structurally. The channel is a per-profile setting, not an architecture fork: the same Hermes profile can speak WhatsApp, Telegram, Discord, Slack, or Signal, chosen in that client’s channels list. One client bot, whatever surface their business already uses. Spinning up a new Skippy is still one profile plus one channel pairing.
Propagation: how customization reaches every bot
The customization built for the personal agent (voice rules, conduct rules, escalation protocol, mention gating) must not be hand-copied per client, or the fleet drifts. The system of record is the infra repo:
infra/ops-1/hermes/SOUL-client-template.md: the shared brain. Voice, conduct, escalation live here once.infra/ops-1/hermes/clients/<name>.yaml: per-client facts only (bot name, business name, business facts, channels).infra/ops-1/hermes/render-souls.py --deploy: renders every client SOUL from template plus vars and pushes each to ops-1, restarting that profile’s gateway. Improve the template, rerun, every bot updates./root/patches/*.patchedplus/root/apply-patches.shon ops-1: the WhatsApp gating and context-buffer patches are hermes-level (shared by all profiles automatically). After anyhermes update, runapply-patches.shto reapply them.
Rule: never edit a client SOUL on the box. Edit the template or the client yaml in infra and rerun the renderer.
Cost monitoring
AI spend is now part of the daily morning-status report: the cron queries the OpenRouter key endpoint and reports dollars used to date. Fleet plan as clients come online: one OpenRouter provisioning key mints a named runtime key per client with a monthly dollar limit. That gives per-client cost attribution for billing and a hard cap so no bot can run away with spend. Infra costs are flat and known (ops-1 VPS, Vercel free tier), so the variable to watch is tokens.