Sessions
What it is
Separate conversation/work containers that keep projects and contexts independent.
In plain terms
Think of every conversation as its own locker in a shared locker room rather than one big open bin: each locker has its own combination, its own contents, and its own running tally, even though every locker sits against the same wall. A Hermes session is that locker — a boundary that keeps one project’s back-and-forth, cost tracking, and history from leaking into another’s.
Why it matters
Keeping one project’s conversation from bleeding into another’s is a sessions problem structurally — each session is its own container with its own history, artifacts, and state. Project isolation actually depends on this at a mechanical level: without separate sessions, keeping a client’s data out of an unrelated project’s context would need discipline rather than being enforced by the runtime itself. Agent team delegation and kanban execution both reference specific sessions deliberately, since which session a subagent works in determines exactly what context it inherits.
How it works
Sessions live as rows in a SQLite database (state.db) managed by the SessionDB class in hermes_state.py, with columns for the working directory, model, running token and dollar-cost totals, an optional parent_session_id linking forked or resumed conversations, and an archived flag rather than hard deletion by default. The dashboard exposes this over REST: GET /api/sessions/{session_id} fetches one, GET /api/sessions/{session_id}/messages paginates its transcript, PATCH renames or archives it, and DELETE removes it outright, all resolving short or partial IDs to the exact stored id first (hermes_cli/web_server.py). An optional profile query parameter lets these same endpoints reach into another profile’s own state.db, since each profile keeps a separate session store entirely.
A concrete example
Someone is juggling two unrelated efforts in Hermes: debugging a client’s API integration and planning a personal trip. Each gets its own session, so switching between them swaps in a completely different message history and cost total. When the debugging session forks into a deeper investigation, the new session records the original as its parent, so its lineage is traceable later. Renaming the trip-planning session to ‘Portugal 2026’ doesn’t touch the debugging session, and archiving the finished debugging session just hides it — the row and its messages remain.
How it connects
This note belongs to the Interfaces family. Its closest neighboring concepts are: Profiles, Artifacts, Agent Runtime, Personal OS.
Source evidence
route:DELETE:/api/sessions/{session_id}— Explicit Source Map scope boundary: The web server route is outside the approved Core scope.
Workflows
- Kanban Agent Execution
- Gateway Mobile Command Center
- Agent Team Delegation
Related articles
- Mastering Hermes Desktop: From Local Chat App to an Always-On Agent Control Center
- Inside Hermes: How the Agent Loop, Context, Memory, Gateways, and Cron Jobs Work Together
- Building a Personal AI System with Hermes, Local Models, Automation, and a Shared Knowledge Base