Hermes integration
The Hermes integration connects Hermes sessions to claude-mem so Hermes can recall shared project memory and record new work. It combines a Python memory provider with local-worker or hosted-server transport, an installer that manages Hermes configuration, and an MCP entry that exposes search tools.
This page is part of Agent integrations and distribution. Related integration pages cover plugin hooks and agent modes, Cursor, Grok Bot, Cowork, OpenClaw, native harnesses, other agents, installation and the npx CLI, and external notifications.
Integration model
The integration treats Hermes as another agent in the shared claude-mem memory system. It uses the session working directory as the project identity, so Hermes and other agents can read and write the same project memory without a separate project name.
The integration has four main responsibilities:
- Session provider: supplies recent and prompt-matched memory to Hermes and records primary-agent work.
- Transport: sends session events and memory notes to the local worker or hosted server.
- Installer: copies the provider and updates Hermes configuration.
- Search interface: starts claude-mem's MCP server so Hermes can search stored memory.
References: hermes/…/__init__.py• L1-18 hermes/…/client.py• L1-13 src/…/HermesInstaller.ts• L20-35
Session memory flow
The provider adds shared context at session start, finds related notes for each turn, and records the primary Hermes session as it runs. The flow keeps memory useful without making Hermes wait for each write.
The session lifecycle is:
- Hermes initializes the provider with a session id and working directory.
- The provider adds recent project work to the system prompt.
- A turn prompt is recorded and related notes are fetched for the current query.
- Tool calls and explicit Hermes memory writes are recorded as session data or notes.
- Session end or session switch sends the final assistant text and closes the session.
This diagram shows how Hermes activity becomes shared memory and how existing memory returns to Hermes.
flowchart LR
H[Hermes session] --> P[claude-mem memory provider]
P --> R[Recent project context]
P --> Q[Prompt-matched notes]
P --> W[Session prompts, tools, and notes]
W --> T[Worker or hosted server]
T --> M[Shared project memory]
M --> R
M --> Q
The provider records only the primary agent context. Scheduled jobs and other non-primary agents can read memory but do not add session records. It also ignores memory-tool calls and delegated calls that do not belong to the active session.
References: hermes/…/__init__.py• L101-228 hermes/…/__init__.py• L231-258 hermes/…/README.md• L6-24
Session event mapping
Hermes lifecycle events map to claude-mem operations that preserve prompt order and session boundaries.
| Hermes event | Shared memory result |
|---|---|
| Turn start | Starts or updates the session with the user prompt |
| Tool completion | Stores the tool name, input, and bounded result |
| Memory write | Stores an explicit Hermes note |
| Session start | Provides recent project context |
| Prompt prefetch | Provides notes related to the current prompt |
| Session end or switch | Stores the final assistant message and closes the session |
References: hermes/…/README.md• L6-15 hermes/…/__init__.py• L154-212
Python client transport
The Python client is the transport boundary between the Hermes provider and claude-mem. It resolves settings, removes internal context from data, selects the local worker or hosted server, and makes bounded requests that fail softly.
The client sends writes through one background queue in event order. Reads wait for a short, fixed period. If the destination fails three times in a row, a 30-second breaker pause prevents a stopped worker from slowing Hermes turns.
The transport supports these destinations:
| Destination | Selection | Main purpose |
|---|---|---|
| Local worker | Default runtime | Store and query memory through the worker HTTP API |
| Hosted server | Server runtime with URL, key, and project id | Store and query memory through the hosted /v1 API |
References: hermes/…/client.py• L192-230 hermes/…/client.py• L261-293 hermes/…/client.py• L340-391
Data protection and project scope
Before data leaves the Hermes process, the client removes private blocks and other internal context blocks from strings and nested values. It also applies the configured excluded-project patterns locally, so excluded checkout data does not leave Hermes in either runtime.
The local worker can resolve the project from the working directory. The hosted path sends a checkout key based on the Git root and worktree. This keeps project sharing aligned with the other claude-mem integrations.
References: hermes/…/client.py• L35-80 hermes/…/client.py• L134-184 hermes/…/client.py• L393-396
Configuration generation
The installer makes Hermes select claude-mem as its memory provider and adds an MCP server entry for claude-mem search tools. It edits only the configuration keys it owns and preserves other settings and comments.
The generated configuration connects Hermes to the Node MCP server and passes the selected claude-mem data directory when Hermes filters the child process environment. The provider itself reads its runtime settings from environment variables or claude-mem settings.json.
References: src/…/HermesInstaller.ts• L105-110 hermes/…/__init__.py• L8-14 hermes/…/client.py• L88-124
Configuration ownership
The installer records the previous provider and the exact MCP entry that it added. On uninstall, it restores the provider and removes the MCP entry only while that entry still matches the install receipt. A user-edited entry or a provider selected after install is left in place.
The configuration editor supports block-style YAML and preserves line endings, byte-order marks, comments, and unrelated keys. If the file shape is unsafe to edit, installation fails without changing config.yaml.
References: src/…/HermesInstaller.ts• L33-49 src/…/HermesInstaller.ts• L123-169 src/…/hermes-config-yaml.ts• L1-10 src/…/hermes-config-yaml.ts• L184-203 src/…/hermes-config-yaml.ts• L261-274
Installer lifecycle
The installer places the plugin in Hermes's user plugin directory and updates Hermes's configuration as one managed operation. It uses the marketplace copy by default and permits a checkout copy only through an explicit development setting.
The normal install path is:
- Find a complete shipped provider bundle.
- Read the current Hermes configuration and prior receipt.
- Plan provider and MCP changes before writing anything.
- Copy the provider files and write the ownership receipt.
- Write the changed configuration while keeping its file permissions.
- Ask the user to start a new Hermes session.
Hermes home defaults to ~/.hermes on Unix and the platform's local application data directory on Windows. HERMES_HOME overrides that location.
References: src/…/HermesInstaller.ts• L51-79 src/…/HermesInstaller.ts• L90-103 src/…/HermesInstaller.ts• L112-173
CLI integration
The claude-mem install --ide hermes command invokes the installer, while the general uninstall command invokes its matching cleanup. The package publishes the Hermes provider bundle so a packaged install can copy it into Hermes's home.
References: src/…/install.ts• L421-435 src/…/uninstall.ts• L416-424 package.json• L35-61
Worker integration
The local worker exposes the session, context, and memory operations that the Hermes client uses. This gives Hermes the same shared-memory path as other native integrations while keeping Hermes-specific session identity in platformSource: hermes.
The end-to-end contract is verified by installing the real provider into an isolated Hermes home, playing a Python-loaded Hermes session against a real worker, and searching the resulting memory through the MCP server entry written by the installer. The same check confirms that Hermes receives a note recorded by another agent in the same checkout.
References: hermes/…/client.py• L421-575 hermes/…/client.py• L579-619 tests/…/hermes-worker-e2e.test.ts• L140-233
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the provider event order aligned with the worker session contract and the hosted
/v1event contract. - Keep the project-key rules aligned between local checkout paths and hosted server folder-project queries.
- Keep the installer receipt format aligned with both provider restoration and MCP ownership checks.
- Keep the generated MCP command and data-directory handoff aligned with the packaged server path.
- Keep tag filtering and excluded-project checks consistent across local and hosted runtimes.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Worker or server requests fail repeatedly | Hermes stops receiving or recording memory for the breaker window | Request timeouts, quiet failure handling, and a three-failure breaker |
| A project matches the excluded-project patterns | Its prompts, tools, and notes are not sent | Client-side exclusion check before each operation |
| Hermes config uses an unsupported YAML shape | Install does not change the config | Shape validation and an explicit install error |
| A user edits the installed MCP entry | Uninstall leaves that entry in place | Receipt match is required before removal |
| A provider prompt is private or only contains injected memory | The prompt and its tool calls are not recorded | Tagged-section stripping and prompt anchoring |
Key files
| File | Why to read it |
|---|---|
| hermes/…/__init__.py | Defines the Hermes memory provider and lifecycle callbacks |
| hermes/…/client.py | Defines settings, transport, filtering, project scope, and worker/server calls |
| hermes/…/plugin.yaml | Declares the Hermes plugin and its hook requirement |
| hermes/…/README.md | Summarizes event mapping, install behavior, and runtime choices |
| src/…/HermesInstaller.ts | Controls plugin installation, configuration ownership, and uninstall behavior |
| src/…/hermes-config-yaml.ts | Defines safe, comment-preserving edits to Hermes YAML |
| tests/…/hermes-worker-e2e.test.ts | Shows the full installer-to-worker-to-search contract |