◆ Sparround

Architecture: the agent loop

There is no magic inside the agent — there is a loop. Every turn repeats the same five steps:

  • the system prompt is assembled — identity, tool guidance, the skill list, context files, memory
  • a provider is resolved — which model, which API key
  • the model is called — together with the whole conversation history
  • the model either answers or calls a tool — the tool call is executed and its result is put back into the conversation
  • the result is written to the session — into a SQLite database

The loop ends when the model stops calling tools, and you see the answer.

ComponentResponsibilityWhere its state lives
Prompt builderAssembles the system prompt in tiers: identity → tools → skills → context files → memoryRuntime
Provider resolutionMaps a model name to an API key and endpoint, manages the fallback chainconfig.yaml, .env, auth.json
Tool registryGroups dozens of tools into toolsets and exposes them to the model as schemasRuntime
Session storageStores conversations and provides full-text search (FTS5)~/.hermes/state.db

The same core runs in three processes: the CLI (interactive terminal), the gateway (a background process for messaging platforms) and subagents (fresh instances created when work is delegated). Each profile gets its own HERMES_HOME, config, memory, sessions and gateway process — so one machine can hold several agents that never mix.

Why this matters: the context window is refilled every turn. As a long session grows, every request gets more expensive — which is why Hermes has compression, prompt caching and memory limits. We open those up in the "Tokens and cost" topic.

Practice. Run one session, then look at the byte breakdown of the system prompt with hermes prompt-size: how many bytes go to tool schemas, the skill list and context files? Done means: you can name the three biggest contributors and know which of them you can switch off.

📚 Sources and documentation