The Mental Model
You're not chatting with an AI. You're chatting with an orchestration layer that assembles a package — system prompt, memory, skills, tools, and history — and hands it to a model every single turn.
The single most important idea: Hermes is not a chatbot. On every message you send, it builds a "context package" from your SOUL.md (personality), your memory files (who you are + what I've learned), a skills index, the full tool catalog, and the entire conversation history. Then it hands the whole thing to an LLM — for every turn.
Three consequences: (1) every word you've ever typed is re-sent on every turn, so wordiness is paid in tokens × turns. (2) You're writing a spec — goal, constraints, done-when — not a letter. (3) Context is the real budget; the art is knowing what to keep in memory vs. what lives in a skill vs. what belongs only in the session.
Prompt Craft
Maximize signal-to-noise. Every word must either change the output or prevent a wrong guess. If a word does neither, delete it.
The reliable skeleton: Goal (one sentence, verb first) · Context (only what the model can't infer) · Constraints (non-negotiables) · Done when (the acceptance test). Most prompts need 2–5 sentences.
The trim test: before sending, delete every word whose removal wouldn't change what comes back. Tone words ("kind of," "I was wondering") never change output — they only invite the model to hedge. Precision beats politeness.
Anti-pattern: burying the goal under pleasantries. Pattern: leading with the verb. The model reads the beginning and end most attentively — put your goal at the top.
OpenRouter & /auto
auto is not a model — it's a router that classifies your prompt, ranks models by community spend for that task type, and picks one. Great for mixed workloads; costly for long, personality-sensitive conversations.
OpenRouter is an aggregator: one API key, hundreds of models. openrouter/auto classifies each prompt into ~30 task types, then routes to what the community actually spends on for that task — a live market signal. Session stickiness keeps the model consistent within a conversation, but a different prompt can still flip it.
The hidden cost: prompt caching is per-model. Every flip breaks the cache, forcing a full re-read of the conversation at full price. In one real session, /auto bounced across three providers and achieved only a 2–7% cache hit rate; in another session that stuck to one model, cache hit 99–100%.
Best practice: match model choice to the profile's job. Long, voice-sensitive work (a teacher persona) wants a fixed model. Short, heterogeneous tasks (a shopping bot) shine on /auto.
Memory
Two files injected into every session: MEMORY.md (my notes — environment, conventions, quirks) and USER.md (your profile — identity, preferences, style). Bounded, curated, frozen at session start for cache efficiency.
Memory is not a log. If a fact can be re-discovered in one second (a config file says your model default), it doesn't belong here. If it's a procedure, put it in a skill (Lesson 6). If it's historical "what did we decide?", use session search (SQLite, unlimited, zero token cost).
The bucket rule: MEMORY.md gets environment facts, tool quirks, project locations. USER.md gets your name, communication style, work preferences. Both have hard character caps — when you hit ~80% full, consolidate: merge overlapping entries, remove stale facts, shorten what's left.
Maintenance cadence: ~80%-trigger consolidation, a weekly glance, and a sweep after each completed project. Hermes nudges after every 10 turns without a save.
SOUL.md & Profiles
SOUL.md is your agent's personality — injected as the system prompt. Profiles are isolated Hermes homes that let you run multiple agents on one machine, each with its own config, memory, and skills.
SOUL.md defines who the agent is: its role, mission, communication style, and constraints. A good SOUL.md is a short mission statement, not a novel. Mine is 7 lines: "The Professor — educator for all things AI, agents, and Omarchy. Plain language, first principles. Patient."
Profiles are separate Hermes home directories under ~/.hermes/profiles/<name>/. Each gets its own config.yaml, .env, SOUL.md, memories, sessions, skills, and cron jobs. They're fully isolated — perfect for running a coding assistant, a research bot, and a teacher simultaneously without state bleeding across them.
Skills
Skills are reusable procedures that load into context only when relevant. They're how Hermes learns from experience — the self-improvement loop that makes each session smarter than the last.
When I learn a workflow during a task — deploy commands, a known pitfall, the right way to configure something — I save it as a skill. Next time that kind of task comes up, the skill loads automatically. Skills live on disk under skills/ and are loaded on-demand, so they don't bloat the system prompt like memory does.
The skill lifecycle: (1) I discover or am taught a procedure. (2) After the task succeeds, I save the workflow as a SKILL.md. (3) Future sessions load it when the task type matches. (4) When a skill has outdated steps, I update it. This is Hermes' self-improving core — it's why you shouldn't have to re-teach me how to deploy your app.
Tune-up
Your config.yaml is the control panel. A 15-minute weekly pass — checking model defaults, memory usage, compression settings, and skills health — keeps everything running smoothly without constant vigilance.
Key knobs worth knowing: model.default (your main model, set per-profile), memory.memory_char_limit & memory.user_char_limit (the caps we consolidated under in Lesson 4), compression.threshold (when context compresses — 0.5 = 50% of window), and agent.reasoning_effort (how hard the model thinks).
A weekly maintenance checklist: check memory usage% in the system prompt header for both stores; review the dashboard's Usage analytics to see which models are costing what; prune skills that haven't been used in weeks (the .usage.json file tracks this); and verify your API key/credits aren't close to expiry.