# Hermes session acquisition

AIWG supports Hermes under canonical provider `hermes`, preferring the native export:

```sh
hermes sessions export session.jsonl --format jsonl --session-id <id> --redact --yes
aiwg sessions import session.jsonl --provider hermes --source-id hermes-session
```

Hermes JSONL writes one full session per line. Current native exports omit a schema
marker, encode SQLite Boolean fields as `0`/`1`, and may emit `null` for optional
message metadata. The adapter normalizes those representations at its boundary,
validates them as native schema 23, and exposes AIWG parser schema `1.0.0`. Exports
with an explicit schema marker still undergo schema-major validation. The adapter
preserves canonical session/message/tool
IDs, gateway routing identity, workspace and Git fields, compression lineage, archive
and inactive state, token and cost totals, model configuration, reasoning metadata,
opaque content, and additive unknown fields.

Active exports are provisional. Ended, archived, inactive, and provider-deleted
sessions are complete snapshots. Archive, compaction lineage, deletion of an exported
file, and deletion from Hermes remain separate metadata:

- archive hides a session while retaining messages and search data;
- compaction creates a continuation linked to its parent;
- removing an export does not affect `state.db`;
- `hermes sessions delete` removes provider data and is not invoked by AIWG.

## SQLite and local API fallback

Hermes's canonical `state.db` runs in WAL mode. AIWG rejects a raw database copy
because omitting or racing `state.db-wal` can yield a partial snapshot. A SQLite
fallback must first be created with SQLite's backup API and converted to the documented
snapshot JSONL form carrying `snapshotConsistency: "sqlite-backup"`.

## Native discovery (synthetic physical schema v1, unqualified)

```sh
aiwg sessions discover --workspace /work/project \
  --expected-providers hermes --hermes-root /home/operator/.hermes --json
aiwg sessions import-discovered --workspace /work/project --confirm --json
```

`--hermes-root` authorizes `<root>/state.db` for a read-only backup snapshot
(needs the optional sqlite backend). The live database is never opened for
writing and never streamed directly: AIWG takes a `backup()` snapshot into
owned workspace staging (`.aiwg/sessions/staging/hermes/`), projects only
workspace-matching sessions to snapshot JSONL, then deletes the whole-DB
backup. Nothing else under the Hermes home is read. The backup transiently
copies the whole session database, including other workspaces, before
filtering; an operator who cannot accept that scope can keep supplying a
workspace-specific export instead.

Two platform boundaries are enforced and tested. First, WAL reads need the
provider's shared-memory index, and any first read would create it as a
provider-tree write — so a database without `state.db-shm` present refuses
*before any SQLite contact*. In practice native discovery needs Hermes running
(or at least its sidecars present); a stopped provider fails closed with an
actionable error and the export fallback covers it. Second, only the synthetic
physical schema v1 (`meta.native_schema = 'hermes-synthetic-v1'` with the
allowlisted `sessions`/`messages` columns) projects; real store tables were
never inspected, so anything else fails closed. Sessions without a resolvable
workspace `cwd` stay excluded. Fixture seed:
`test/fixtures/sessions/hermes/state-db-seed.sql` (materialized into mkdtemp).

A caller may instead inject a local Sessions API transport, but it remains unavailable
until explicitly configured and authorized with operation
`hermes.local.sessions.read`. The standard CLI import performs no network operations.

## Evidence and tested boundary

Verified 2026-07-27 against:

- [Hermes Sessions guide](https://hermes-agent.nousresearch.com/docs/user-guide/sessions/)
- [Hermes session-storage developer guide](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/developer-guide/session-storage.md)
- [Hermes CLI commands and consistent backup behavior](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/reference/cli-commands.md)

Synthetic fixtures cover current native output, explicit schema-23 active/ended
sessions, parent/compression lineage,
archived/inactive state, tools, opaque content, consistent and inconsistent snapshots,
unknown-major drift, malformed input, redaction, replay, and deletion limitations.
