Hermes (Nous Research): how session transcripts are stored and resumed
Part of Session Store Research. Produced by running RESEARCH_PROMPT. Evidence snapshot: local checkout of NousResearch/hermes-agent at commit d9165d7a678d4105f42921a7fc1886df3804531b (committed 2026-07-23), the source of Nous Research's self-improving terminal/gateway agent ("Hermes"). Every citation below was re-verified against this exact commit on 2026-07-23 (working tree clean, origin/main). The session subsystem is not a pluggable adapter: it is one concrete class, SessionDB, in the repo-root module hermes_state.py (~442 KB, the single source of truth for persistence), with call sites in run_agent.py (the agent write/flush path), gateway/session.py (the gateway transcript queue), hermes_cli/* (slash commands, resume, listing), and tools/async_delegation.py (durable subagent-completion outbox). Citations use repo-relative path:line shorthand.
The storage model
The durable session is a single per-profile SQLite database, {HERMES_HOME}/state.db (hermes_state.py:154, DEFAULT_DB_PATH = get_hermes_home() / "state.db"). A session is one row in the sessions table (hermes_state.py:999-1048) plus an ordered set of rows in the messages table (hermes_state.py:1050-1072), joined by messages.session_id → sessions.id. The class docstring states it plainly: "SQLite-backed session storage with FTS5 search. Thread-safe for the common gateway pattern (multiple reader threads, single writer via WAL mode)" (hermes_state.py:1510-1515).
This is best described as session-as-row-set (a relational record with a child message table), not session-as-log and not session-as-directory. The transcript is append-dominant but mutable: messages are almost always added by INSERT (append_message, hermes_state.py:5627), but the durable record is edited in place through three flag columns rather than being a pure immutable log:
active INTEGER NOT NULL DEFAULT 1-- live vs. soft-deleted (hermes_state.py:1069).compacted INTEGER NOT NULL DEFAULT 0-- summarized-away vs. normal (hermes_state.py:1070).
The two flags encode three durable states, spelled out in the code: active=1 (live), active=0, compacted=0 ("the user took it back" -- rewind/undo), and active=0, compacted=1 ("summarized away" -- compaction-archived) (hermes_state.py:5941-5946, 7151-7156). Rewind and compaction therefore mutate existing rows (UPDATE ... SET active=0) rather than appending markers, so the on-disk row set is authoritative and the "log" is reconstructed by filtering flags at read time.
What is authoritative vs. derived:
- Authoritative: the
sessionsandmessagesrows. Nothing is rebuilt from an external source of truth; the rows are the truth. - Derived / rebuildable: the FTS5 indexes (
messages_fts,messages_fts_trigram,messages_fts_cjk) are external-content indexes kept in sync by triggers and fully rebuildable frommessagesvia the FTS5'rebuild'command (rebuild_fts,hermes_state.py:9570; runtime auto-repair,hermes_state.py:2083-2130). The per-session denormalized counters on thesessionsrow (message_count,tool_call_count, token totals) are maintained at write time and are a projection of the message rows. - Sidecar / ephemeral: gateway request dumps and per-session log files (
{session_id}.json,{session_id}.jsonl,request_dump_{session_id}_*.json,logs_dir/session_{sid}.json) are debug artifacts the store deletes on session deletion (_remove_session_files,hermes_state.py:8437-8461;run_agent.py:2768), never the source of truth.
Keying and identity
- Store scope: one SQLite file per Hermes home/profile. Profiles are separated by
HERMES_HOME(get_hermes_home,hermes_constants.py:106-131); there is no cwd- or project-encoded path in the key. All sessions for a profile -- CLI, gateway platforms, subagents, branches -- live in the samestate.dband are distinguished by columns, not directories. - Primary key:
sessions.id TEXT PRIMARY KEY(hermes_state.py:1000). - Id minting: client-supplied, generated as
f"{timestamp_str}_{short_uuid}"wheretimestamp_str = strftime("%Y%m%d_%H%M%S")andshort_uuid = uuid.uuid4().hex[:6](cli.py:4208-4210,cli.py:7393, branch pathhermes_cli/cli_commands_mixin.py:900-903). The scheme encodes wall-clock ordering in the lexical prefix but is not a UUIDv7 and carries only 6 hex of entropy (~24 bits), so ordering is second-resolution and collisions within the same second are theoretically possible. Resume reuses the existing id verbatim (cli.py:4204-4206). - Secondary identity for gateway routing:
source,user_id,session_key,chat_id,chat_type,thread_id,origin_json(hermes_state.py:1001-1008) address a session by its external messaging origin (Telegram/Discord/Slack/etc.).gateway_routing(a separate table,hermes_state.py:1101-1107) maps a(scope, session_key)to a JSON routing entry, andfind_session_by_origin/find_latest_gateway_session_for_peer(hermes_state.py:3625,3724) resolve a platform peer to its live session id. - Listing scope: global within the profile DB.
list_sessions_rich(hermes_state.py:5171) queries the wholesessionstable with optionalsource/cwd_prefixfilters; there is no per-directory enumeration. A read-only cross-profile aggregation path exists (open another profile'sstate.dbmode=ro,hermes_state.py:1574-1591). - Relocation / rename reconciliation:
cwd,git_branch,git_repo_rootare plain columns updated in place (update_session_cwd,hermes_state.py:3865); moving a working directory does not change identity because the key is not path-derived. Renames areset_session_title(hermes_state.py:4909), a metadata update, not an identity change.
The store interface
There is no pluggable store protocol; SessionDB is a concrete class and callers invoke its methods directly. The reconstructed operational contract (every method opens its own cursor; all mutations go through _execute_write, which wraps BEGIN IMMEDIATE + commit + jittered retry, hermes_state.py:1997-2065) is:
Session lifecycle:
create_session(session_id, source, **kwargs) -> str(hermes_state.py:3441) -- INSERT asessionsrow (via_insert_session_row,hermes_state.py:3294, an UPSERT withON CONFLICTmerge).ensure_session(...)(hermes_state.py:4587) -- idempotent create-or-touch used before the first append.end_session(session_id, end_reason)/reopen_session(session_id)(hermes_state.py:3789,3807) -- set/clearended_at,end_reason.promote_to_session_reset(...)(hermes_state.py:3816) -- compression-continuation bookkeeping.update_session_cwd / _meta / _model / _billing_route / set_session_title / set_session_archived(hermes_state.py:3865, 4244, 4272, 4286, 4909, 4937) -- in-place metadata mutation.
Message write:
append_message(session_id, role, content, ...) -> int(hermes_state.py:5627) -- INSERT one message row, return autoincrement id, bump session counters. The single normal write path.replace_messages(session_id, messages, active_only=False)(hermes_state.py:5851) -- destructive DELETE-then-INSERT of the whole (or live-only) transcript, one transaction. Used by /retry, /undo, /compress.archive_and_compact(session_id, compacted_messages) -> int(hermes_state.py:5913) -- non-destructive soft-archive (active=0, compacted=1) of live rows then INSERT the compacted set.set_latest_user_api_content(...)(hermes_state.py:5965) -- backfill theapi_contentsidecar onto the newest active user row.
Message read:
get_messages(session_id, include_inactive=False, limit, offset)(hermes_state.py:5997) -- ordered by autoincrementid(insertion order).get_messages_as_conversation(session_id, include_ancestors, include_inactive, repair_alternation)(hermes_state.py:6334) -- OpenAI role/content format for replay.resolve_resume_session_id(session_id) -> str(hermes_state.py:6245) -- redirect a resume target forward across the compression-continuation chain.get_resume_conversations / get_ancestor_display_prefix / get_conversation_root / _session_lineage_root_to_tip / get_compression_lineage(hermes_state.py:6512, 6561, 6602, 6616, 7942) -- lineage walks.
History mutation (retroactive):
rewind_to_message(session_id, target_message_id) -> dict(hermes_state.py:6656) -- soft-delete (active=0) every row withid >= target, bumprewind_count.restore_rewound(session_id, since_message_id) -> int(hermes_state.py:6743) -- undo a rewind (flip back toactive=1).clear_messages(session_id)(hermes_state.py:8424) -- DELETE all rows for a session.
Listing / search / count:
list_sessions_rich(...) -> list(hermes_state.py:5171),search_sessions(...)(hermes_state.py:7794),search_sessions_by_id(...)(hermes_state.py:7747),search_messages(query, ...)(hermes_state.py:7049, FTS5),session_count / message_count(hermes_state.py:7834, 7892),distinct_session_cwds(hermes_state.py:5145).
Deletion / retention:
delete_session(session_id, sessions_dir)(hermes_state.py:8463),delete_session_if_empty(hermes_state.py:8504),delete_sessions([...])(hermes_state.py:8546),delete_empty_sessions(hermes_state.py:8654),archive_sessions(hermes_state.py:8869),prune_sessions(older_than_days=90, ...)(hermes_state.py:8895).
Import / export:
export_session / export_session_lineage / export_all(hermes_state.py:7987, 7995, 8015) -- dict / JSONL shapes.import_sessions([...]) -> dict(hermes_state.py:8097) -- bounded restore (caps athermes_state.py:1545-1549).
Consistency guarantees for all of the above: single writer connection guarded by a Python threading.Lock plus SQLite BEGIN IMMEDIATE (hermes_state.py:2018-2019); ordering by autoincrement id; no expected-version precondition on any operation.
Write and append path (ordering, durability, concurrency, delivery)
- Commit shape: every new turn is an
INSERTintomessagesplus anUPDATE sessions SET message_count = message_count + 1(andtool_call_count), inside one_execute_writetransaction (append_message,hermes_state.py:5709-5754). Full rewrites (replace_messages) and compaction (archive_and_compact) are the only non-append writes and are single transactions. - Ordering: positional by
messages.id INTEGER PRIMARY KEY AUTOINCREMENT(hermes_state.py:1051). Reads order byid, nottimestamp, deliberately -- "Ordered by AUTOINCREMENT id (true insertion order) rather than timestamp -- see c03acca50 for the WSL2 clock-regression rationale" (hermes_state.py:6011-6012).timestamp REALis stored but advisory. - Durability / atomicity: WAL journal mode with a DELETE-mode fallback for WAL-incompatible filesystems (
apply_wal_with_fallback,hermes_state.py:464-527); on macOS a checkpoint barrier andsynchronous=FULLare enforced (hermes_state.py:505-514).BEGIN IMMEDIATEtakes the write lock at transaction start so contention surfaces immediately (hermes_state.py:2007-2008). A malformed/corrupt-FTS write triggers a one-shot in-place FTS rebuild and retry, preserving canonical message rows (hermes_state.py:2049-2061,2083-2130). An offline schema-repair path backs up and de-duplicates a malformedsqlite_master(hermes_state.py:827-991, invoked from__init__athermes_state.py:1616-1628). - Concurrency: designed as single-writer-per-DB, multi-reader ("single writer via WAL mode",
hermes_state.py:1514). Multiple processes (gateway + CLI sessions + worktree agents) share onestate.db, so contention is handled at the application level: SQLite timeout is kept at 1s and retries use random 20–150 ms jitter over up to 15 attempts to break the convoy effect (hermes_state.py:1517-1528,2036-2048). There is no optimistic-concurrency / expected-position precondition anywhere; correctness under concurrent writers to the same session relies on the app keeping one logical writer per session. - Delivery semantics: from the live agent, best-effort. The flush (
_flush_messages_to_session_db_unlocked,run_agent.py:1871-2096) walks the in-memory conversation, skips already-persisted dicts, appends the rest, and swallows exceptions ("Session DB append_message failed: %s",run_agent.py:2095-2096). Idempotence/dedup is an in-memory intrinsic marker_DB_PERSISTED_MARKERstamped on each written dict (run_agent.py:1878-1889, 1970-1976, 2089), not a durable dedup key -- there is no unique constraint on message content, so a re-flush after a process restart that lost the marker could duplicate rows. The gateway path adds a bounded in-memory retry queue per session (_dirty_transcripts,_MAX_PENDING_PER_SESSION; drops oldest on overflow) with retry-on-failure and FTS-rebuild recovery (gateway/session.py:2600-2687) -- at-least-once with a bounded buffer, not a durable outbox.
Read and resume path
- Resume reads the durable store directly; there is no separate local cache.
--resume {id}reuses the id (cli.py:4204-4206), then the conversation is rebuilt byget_messages_as_conversation(session_id, ...)(hermes_state.py:6334), a single orderedSELECToveractive=1message rows transformed into OpenAI role/content dicts. - Full ordered read, not incremental cursor replay: the whole active transcript is materialized on resume (the agent then tracks
_last_flushed_db_idxto know which tail is new going forward,run_agent.py:2094). - Resume redirects forward across compression continuations:
resolve_resume_session_idfollowsget_compression_tipand theparent_session_idchain (depth cap 32) to the descendant holding the live messages, so resuming a compressed parent lands on the continuation child (hermes_state.py:6245-6332). repair_alternation=Truerunsrepair_message_sequenceover the loaded list for live replay so a durableuser;usergap doesn't re-trigger repair every request (hermes_state.py:6349-6355).- Pagination/bounds:
get_messagesacceptslimit/offset(hermes_state.py:5997-6002); import caps bound restore size (hermes_state.py:1545-1549), but there is no hard cap on live transcript size -- growth is managed by compaction, below.
Listing, summaries, and search
- Listing is a single SQL query with correlated subqueries, not N queries and not a directory scan (
list_sessions_rich, "Uses a single query with correlated subqueries instead of N+2 queries",hermes_state.py:5194). Child sessions (subagent runs, compression continuations) are hidden by default; a recursive CTE walks compression-continuation edges soLIMIT/OFFSETstill apply and one logical conversation surfaces as one row projected to its live tip (hermes_state.py:5196-5213).compact_rows=Trueomits thesystem_promptblob from the SELECT to avoid copying tens of KB per row (hermes_state.py:5221-5225). No scale numbers are quoted in-source. - Summary sidecar: there is no separate summary file -- the
sessionsrow is the denormalized read model. It carriestitle,started_at,ended_at,message_count,tool_call_count, token totals, cost fields,cwd,git_branch,git_repo_root,model,profile_name,archived,rewind_count, handoff state (hermes_state.py:999-1048). Counters are kept consistent by being updated in the same transaction as the message insert (hermes_state.py:5741-5751). - Search is a first-class, separately-indexed FTS5 subsystem with three virtual tables:
messages_fts(unicode61),messages_fts_trigram(substring / CJK), andmessages_fts_cjk(a loadablecjk_unicode61bigram tokenizer from~/.hermes/lib/libfts5_cjk.so) (hermes_state.py:1186-1360). They are external-content indexes synced by INSERT/DELETE/UPDATE triggers onmessages, so they never store the canonical text and are fully rebuildable (rebuild_fts,hermes_state.py:9570). Query routing chooses FTS5 / trigram / CJK / LIKE-scan by script and token length, with slow-query logging (_describe_search_path,hermes_state.py:7097-7117;search_messagesinstrumentation,hermes_state.py:7060-7095). Rewound rows (active=0, compacted=0) are excluded; compaction-archived rows (active=0, compacted=1) remain discoverable (hermes_state.py:7151-7156). Index maintenance is amortized: PASSIVE WAL checkpoint every 50 writes and FTS5optimizeevery 1000 writes to stop segment fragmentation from lengthening write-lock holds (hermes_state.py:1529-1540,2031-2034). - FTS layout versioning is a separate ratchet from the schema version (see next section):
fts_storage_versioninstate_meta, advanced only on a fresh DB or explicithermes sessions optimize-storage, with legacy DBs left on an inline layout until the user opts in (hermes_state.py:156-165).
Entry/message structure and versioning
- Message row shape (
hermes_state.py:1050-1072): envelope-ish flat columns --id(autoincrement, the ordering + identity field),session_id,role,content(TEXT; multimodal lists are JSON-encoded via_encode_content),tool_call_id,tool_calls(JSON),tool_name,effect_disposition,timestamp REAL,token_count,finish_reason,reasoning,reasoning_content,reasoning_details(JSON),codex_reasoning_items/codex_message_items(JSON -- provider-specific reasoning payloads),platform_message_id(external platform id, e.g. Telegram update_id -- distinct from the PK),observed,active,compacted, andapi_content(the exact bytes sent to the API when they differ fromcontent, a "byte-fidelity sidecar for prompt-cache-stable replay",hermes_state.py:5660-5666). - Store interpretation: the entry is not opaque -- the store parses and interprets it. It distinguishes message types by
role/tool_*, JSON-encodes structured fields, scrubs lone surrogates sqlite3 cannot bind (_scrub_surrogates), and strips base64 images to a text summary before persisting multimodal tool results (run_agent.py:2051-2064). The identity / dedup field the store relies on is the autoincrementid; live-agent dedup additionally uses the in-memory_DB_PERSISTED_MARKER. - Chaining: messages link to a session by
session_idand to each other only by insertion order (id); there is no per-message parent/uuid pointer. Cross-session lineage is carried on thesessionsrow viaparent_session_id(FK tosessions.id,hermes_state.py:1013, 1047) plus JSON markers inmodel_config(_branched_from,_delegate_from). - Schema evolution:
SCHEMA_VERSION = 23(hermes_state.py:156). Column additions are declarative and self-healing, not version-gated: on every startup_reconcile_columnsdiffs livePRAGMA table_infoagainstSCHEMA_SQLandALTER TABLE ... ADD COLUMNs any missing ones (the Beets/sqlite-utils pattern,hermes_state.py:2812-2854). Theschema_versiontable is retained only for row-transforming data migrations (hermes_state.py:2866-2867).schema_versionis advanced forward on open for all non-FTS migrations (hermes_state.py:3182-3195). This is effectively a one-way forward ratchet (no down-migrations); legacy pre-activeDBs backfillactive=1(hermes_state.py:2909).
Compaction and history management
- Compaction shrinks the model-visible view while keeping the durable record. The preferred path,
archive_and_compact, keeps one session id for life (#38763): it soft-archives the live turns (UPDATE ... SET active=0, compacted=1) and inserts the compacted summary set as freshactive=1rows, atomically (hermes_state.py:5940-5961). The live-context load filtersactive=1, so the model reloads only the compacted set; the archived pre-compaction turns stay on disk, stay in the FTS index (flippingactiveis a content-preserving UPDATE that doesn't fire the FTS delete trigger), and stay searchable and recoverable viaget_messages(..., include_inactive=True)(hermes_state.py:5926-5933). - Compaction is an upstream (agent) concern that calls the store: the summary payload (
compacted_messages) is produced bytrajectory_compressor.pyand handed toarchive_and_compact. The durable artifact it leaves is the flag flip plus the inserted summary rows -- an in-place soft rewrite, not an external snapshot file or an appended marker line. - An older compaction mode still exists: ending the current session and forking a continuation child linked by
parent_session_idwithend_reason='compression'(resolve_resume_session_id,hermes_state.py:6245-6287; lineage viaget_compression_lineage,hermes_state.py:7942). The whole chain is one logical conversation for listing/export (export_session_lineage,hermes_state.py:7995-8013). - Resume behavior across the boundary: normal resume just loads the
active=1set (post-compaction). Crossing back requiresinclude_inactive=True, which reads the archived rows. There is no fold-time reconstruction from a raw log, because there is no raw log -- the archived rows are the history. replace_messages(hermes_state.py:5851) is the destructive alternative used by /retry, /undo, /compress: it DELETEs and reinserts, so it does not preserve pre-compaction history and is explicitly warned against for compaction.
Rewind, checkpoints, and fork
- Rewind is a non-destructive, reversible soft-delete, not a destructive edit and not an appended marker:
rewind_to_messageflips every row withid >= targettoactive=0, keeps them on disk "for audit / forensic inspection", and bumpssessions.rewind_count(hermes_state.py:6656-6725). It is idempotent on theactiveflag and reversible viarestore_rewound(flip back toactive=1,hermes_state.py:6743-6763; noted as "not wired to a slash command in v1"). Rewound rows (active=0, compacted=0) are hidden from live load and search, distinguishing them from compaction-archived rows. - File-state / environment checkpoints: there is no per-turn file-content checkpoint stored in the session store. A separate git-native shadow-repo checkpoint system lives under
~/.hermes/checkpoints/with opportunistic auto-prune (cli.py:4195-4198), outsidestate.db; it is not tied to message rows and was not traced to a durable per-turn snapshot in the transcript. - Fork / branch is copy-plus-lineage, not a shared-prefix reference. The
/branchcommand mints a new session id, ends the parent withend_reason='branched', creates the child withparent_session_idand amodel_config._branched_frommarker, then copies every message row into the new id (including theapi_contentsidecar so the branch's first turn replays the parent's exact wire bytes for cache warmth) (hermes_cli/cli_commands_mixin.py:879-974). Lineage metadata recorded:parent_session_id+_branched_from. Compression continuation is the same shape withend_reason='compression'; delegate subagents use_delegate_from.
Subagents and nested sessions
- A subagent / delegate is a first-class sibling session in the same
state.db, not nested storage and not entries in the parent transcript. It gets its ownsessionsrow and its ownmessagesrows, linked to the parent byparent_session_idplus amodel_config._delegate_frommarker (tools/delegate_tool.py:1391-1429, 2839, 3016). The child has its own isolated transcript. - Async delegation additionally has a durable outbox table,
async_delegations(hermes_state.py:1116-1135), which is the closest thing in Hermes to an event-sourced delivery log. It recordsdelegation_id(PK),origin_session,parent_session_id,state,dispatched_at/completed_at,event_json/result_json, and a full at-least-once delivery protocol:delivery_state(pending/…),delivery_attempts,delivered_at,delivery_claim+delivery_claimed_at(a claim token for exactly-once-per-consumer delivery), andowner_pid+owner_started_atfor crash detection (tools/async_delegation.py:300-426). - Crash reconciliation:
recover_abandoned_delegations(tools/async_delegation.py:226-270) scansrunning/finalizingrows, checks whether the owner pid is still alive (matchingowner_started_atto defeat pid reuse), and reclassifies dead-owner delegations tostate='unknown'with a synthetic "outcome unknown" result anddelivery_state='pending'.restore_undelivered_completions(tools/async_delegation.py:273-297) re-enqueues durable pending completions on the next process, stampedrestored(in-memory only) and gated on positive ownership so a new session can't adopt a dead session's results (#64484). - Nesting bound: not enforced by the store schema (any session may have a
parent_session_id); depth caps live in the delegation tool layer, notSessionDB. - Parent delete cascade:
delete_sessioncascade-deletes delegate children (_delegate_from) so they don't resurface as orphans, but orphans branch/compression children (parent_session_id → NULL) so they stay independently accessible (hermes_state.py:8463-8495).prune_sessionsorphans out-of-window children rather than cascading (hermes_state.py:8927-8929).
Retention, deletion, and multi-host
- Retention is product-driven, not store-enforced. There is no background TTL sweeper inside
SessionDB; retention isprune_sessions(older_than_days=90, ...)(hermes_state.py:8895) invoked from the CLI (hermes_cli/main.py:16027), the web dashboard (hermes_cli/web_server.py:11676), and an internal caller athermes_state.py:9679. It deletes only ended sessions matching a rich filter set (age, title/model/branch substrings, message/token/cost bounds, cwd prefix, archived tri-state). Thecompression_lockstable has anexpires_atTTL (hermes_state.py:1113, default 300 s) but that is a lock lease, not session retention. - Delete behavior:
delete_sessionDELETEs themessagesthen thesessionsrow in one transaction (FK-satisfying: cascade delegate children, orphan the rest), then best-effort removes on-disk sidecar files outside the transaction (hermes_state.py:8463-8501).delete_session_if_emptyguards CLI churn (ported from gemini-cli#27770,hermes_state.py:8504-8543). Bulk delete is one transaction (delete_sessions,hermes_state.py:8546).session_model_usagerows cascade viaON DELETE CASCADE(hermes_state.py:1075). - Multi-host / multi-process: the design assumes a shared local filesystem, one
state.dbopened by many processes. WAL is the fast path; network filesystems (NFS/SMB/FUSE) fall back to DELETE journal mode because WAL's shared-memory index needs coherent mmap + reliable POSIX locks that those mounts don't provide (apply_wal_with_fallback,hermes_state.py:464-527). There is a guard against a known SQLite WAL-reset corruption bug that refuses to enable WAL on fresh files on vulnerable builds (hermes_state.py:496-498, 530-560). Cross-host is not a first-class path: no remote writeback, no distributed coordination -- remote/serverless deployment (Modal, Daytona, SSH) hibernates a single host's filesystem rather than sharing the DB across hosts. A separatehermes_cli/active_sessions.pytracks open sessions with lease ids and atomic-rename temp files (active_sessions.py:162, 247) for crash/liveness detection, analogous to a pid registry.
Interop with foreign session stores
Not applicable. Hermes does not read other agent products' native session stores to discover, import, or resume them. The only "Codex" / "Anthropic" references in scope are OAuth credential import for provider auth (hermes_cli/auth_commands.py), and provider-specific reasoning payloads persisted in Hermes's own message columns (codex_reasoning_items, codex_message_items, hermes_state.py:1065-1066) -- not foreign-store ingestion. Hermes's own import/export (import_sessions/export_session, hermes_state.py:8097, 7987) round-trips its own JSON/JSONL dump format only.
What this implies for our Session Store (our inference)
(Our inference, clearly marked as such.) Hermes is the corpus's clearest example of session-as-mutable-relational-record, and the least event-sourced of the products studied: the durable session is a SQLite row plus a child message table in one per-profile state.db, and retroactive operations (rewind, compaction) are implemented as in-place soft-flag UPDATEs on existing rows (active/compacted) rather than as appended events interpreted at fold time. The "log" is reconstructed by filtering flags, which is expressive enough for rewind/undo/compaction-with-audit but gives up the properties our event-sourced design is built on. Implications:
- It validates the read-model-as-denormalized-row pattern: the
sessionsrow is the listing/summary projection, maintained transactionally with the message insert, and search is a cleanly-separate rebuildable FTS index synced by triggers -- the same authoritative-vs-derived split our design draws, achieved without a separate projection store. The FTS layout ratchet (fts_storage_versiontracked independently of the schema version) is a useful precedent for versioning a derived index apart from the log. - It shows the cost of not being append-only: concurrency is single-writer by convention with no optimistic-concurrency / expected-position precondition, so correctness under concurrent same-session writers depends entirely on the app serializing them; dedup/idempotence is an in-memory marker with no durable key, so a crash mid-flush risks duplicate or lost rows (the gateway's bounded in-memory retry queue is a mitigation, not a durable outbox). An event store with OCC on expected version and idempotent append by event id closes exactly these gaps.
- Fork is copy-plus-lineage (full row copy +
parent_session_id), not a shared-prefix reference -- simple and cache-friendly but O(history) in storage per branch; it argues for our design keeping fork as lineage metadata over a shared event prefix rather than physical copy. - Subagents as first-class sibling sessions with a
parent_session_idlink matches ADR 0031's child-Session direction, and theasync_delegationstable is a concrete, well-thought-out durable outbox with at-least-once delivery, claims, and pid-based crash reconciliation -- the one genuinely event-log-shaped component here, and a good reference for how we express delegation-completion facts and their delivery lifecycle. - Retention is a blunt product-invoked
prune_sessions(older_than_days=90)DELETE, not a data-model-tied lifecycle policy -- the same anti-pattern grok's mtime janitor showed; our design should tie retention to the log/projection model rather than a periodic bulk DELETE of "ended" rows.
Open questions
- Message-write idempotence across a crash: the durable schema has no unique constraint or dedup key on
messages, and dedup relies on the in-memory_DB_PERSISTED_MARKER(run_agent.py:1878-1889). Whether a process restart mid-flush can duplicate or drop rows in practice was not exercised here. - The session id scheme (
YYYYMMDD_HHMMSS_+ 6 hex,cli.py:4208-4210) has only ~24 bits of entropy per second; the collision-handling behavior ofcreate_session/_insert_session_row's UPSERT on a same-second id clash was not fully traced. - The relationship/overlap between the two compaction modes (
archive_and_compactin-place vs. the fork-a-continuation-child mode) and which is the current default at what trigger was not pinned to a single dispatch site. - The git-native checkpoint system under
~/.hermes/checkpoints/(cli.py:4195-4198) was not traced to a durable per-turn file-state snapshot linked to message rows; whether rewind restores file state or only conversation state is unresolved. - No down-migration / reversible-migration path was found;
schema_versionappears to be a strict forward ratchet, but the exact behavior when an older binary opens a newerstate.dbwas not verified. - Cross-host concurrent access to one
state.db(as opposed to one host's many processes) is assumed unsupported; no test or code path was found that coordinates writers across hosts.
