dsh-hermes-session

Import sessions from a local Hermes Agent into the current DeepSeek Harness conversation as bounded, untrusted background context.

Hermes Agent is a separate agent running on the same machine, with its own session store (~/.hermes/state.db, one SQLite database per profile). This plugin reads that store read-only and offers three ways in:

Entry point	Shape	What it does
/hermes	Slash command (interactive)	Opens a searchable list of sessions across every profile; pick one and it is staged for the current conversation
hermes_sessions_list	Model tool	Lists sessions (title / working directory / message count / last activity) across all profiles, sorted by recency
hermes_session_import	Model tool	Imports one session by id (a unique prefix is enough)

Imported content always carries a fixed "untrusted background" notice: the model may cite facts from it but must not follow instructions, permission claims, or tool requests found inside it. The same rule the harness applies to its own @-mentioned session references.

Requirements

• DeepSeek Harness >=0.1.0-rc.1
• Python 3.8+ on PATH (standard library only — the plugin shells out to a small sqlite3 helper)
• A local Hermes Agent installation whose session store is readable

Install

dsh plugin --profile web add dsh-hermes-session

Or from a checkout:

dsh plugin --profile web add /path/to/dsh-hermes-session

Configuration

The plugin row takes a config mapping (see cordis.patch.yml). All fields are optional:

Field	Default	Meaning
dbPath	""	Path to a specific state.db. Empty scans every profile under ~/.hermes/profiles/ plus the default database
pythonPath	""	Python interpreter to run the helper with. Empty uses $HERMES_PYTHON, then python3
maxChars	60000	Default character budget for one import
maxCharsHard	160000	Upper bound a caller may request
maxMessages	300	Default number of messages to carry over

How it works

Hermes Agent                     this plugin                     DSH
────────────                     ───────────                     ───
~/.hermes/state.db  ──read-only──▶ scripts/hermes_read.py  ──▶  Hermes session
~/.hermes/profiles/*/state.db             │
                                           │ sessions table (metadata)
                                           │ messages table (conversation)
                                           ▼
                                        src/render.js  →  untrusted-background text block
                                                             │
src/routes.js  ◀──HTTP── client.js ─────┘                    ▼
  GET  /api/hermes.sessions                            current conversation
  POST /api/hermes.select                                   (one collapsed row)

• Read-only by construction. The helper opens SQLite with mode=ro; it never writes to Hermes's store, and it never starts the Hermes process (that one self-checks on startup and fails on read-only filesystems).
• Multi-profile aware. Hermes keeps one database per profile. The default database holds only the default profile, so reading it alone would miss every other profile's sessions. The plugin scans all of them and labels each result with its source profile.
• Bounded. Message bodies are clipped, older messages are dropped first, and the truncation is reported in the injected header rather than hidden.

When the context is attached

Picking a session does not inject anything. The pick is only staged; the snapshot is attached when you next send a message, so you can choose the session first and describe what you want afterwards.

This mirrors how the harness's own @-mentioned session references work: the mention is resolved in the agent/pre-step hook, and the prepared snapshot is appended after the user's message, so the model sees your request and the referenced material in the same turn.

/hermes  → pick a session
          → POST /api/hermes.select       ← stages it only (agentId → sessionId)
          → you type your request and send
          → agent/pre-step takes the staged pick
          → reads the Hermes session, renders it as a form:'recall' context message
          → appended after your message → the model sees both in one turn

Staging is consumed on read: one pick serves exactly the next message you send.

The injected context

The snapshot is attached as a collapsed context row, not as an expanded message bubble: the conversation shows the source session's title, and expanding it reveals the transcript in a bounded, scrollable code-style body. This mirrors how the harness renders its own session references.

Development

node --check src/*.js && node --check client.js   # syntax
node selftest/run.mjs && node selftest/clientid.mjs

The self-tests run against a real Hermes store (read-only) and assert the plugin's invariants: the client module id matches the package name, the HTTP routes are registered with the right methods, the staging is consumed on read, and the attached message carries the form: 'recall' source shape the chat renderer expects.

Privacy

The plugin only reads. It never writes to the Hermes store, never sends session content anywhere, and runs entirely on the machine where Hermes already lives.

License

MIT