Session Storage, Search, and Lineage

Hermes stores session metadata and full message history in a profile-scoped SQLite database. That database supports resume, search, usage accounting, and parent-child lineage when long conversations are split or compressed.

Official documentation: https://hermes-agent.nousresearch.com/docs/developer-guide/session-storage

Storage model

Sessions and messages are separate records. Session rows hold source, model, token, cost, title, timing, and lineage metadata. Message rows preserve roles, tool calls, tool names, reasoning fields, timestamps, and finish state. Full-text indexes make content and tool activity searchable without scanning every session file.

SQLite runs in WAL mode and Hermes includes contention handling because CLI agents, gateways, and parallel work can share the same profile database. Profile isolation still matters: searching the default profile does not prove another profile has no matching history.

Storage checklist

• Use the active profile's resolved Hermes home.
• Let schema migrations run through supported startup paths.
• Preserve parent session IDs during splits or compression.
• Search with source and role filters when intent is narrow.
• Treat exports as potentially sensitive conversation records.
• Prune only ended sessions that meet the retention rule.
• Back up the database before manual recovery work.
• Avoid direct writes while active Hermes processes are running.

Pitfalls

• Searching one profile and concluding a conversation never existed.
• Copying only the main database file while WAL data is active.
• Deleting parent sessions without understanding lineage.
• Publishing exports that contain prompts, paths, or tool output.
• Treating a unique session title as a permanent identifier across migrations.

Verification steps

1. Start a disposable session and give it a distinctive harmless phrase.
2. Confirm the session and messages appear in the active profile database.
3. Search for the phrase and verify source, role, and surrounding context.
4. Resume the session and confirm message order and model metadata.
5. Trigger or simulate a lineage boundary only in a test profile.
6. Confirm parent and child sessions remain discoverable.
7. Export the disposable session, inspect it locally, and delete it through a supported path.