Introducing a new way to review your PRs.

Read the announcement

thedotmack / claude-mem

Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More

View on GitHub

47 documents · Updated Nov 20, 2026

docs / hermes-integration

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:

  1. Hermes initializes the provider with a session id and working directory.
  2. The provider adds recent project work to the system prompt.
  3. A turn prompt is recorded and related notes are fetched for the current query.
  4. Tool calls and explicit Hermes memory writes are recorded as session data or notes.
  5. 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 eventShared memory result
Turn startStarts or updates the session with the user prompt
Tool completionStores the tool name, input, and bounded result
Memory writeStores an explicit Hermes note
Session startProvides recent project context
Prompt prefetchProvides notes related to the current prompt
Session end or switchStores 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:

DestinationSelectionMain purpose
Local workerDefault runtimeStore and query memory through the worker HTTP API
Hosted serverServer runtime with URL, key, and project idStore 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:

  1. Find a complete shipped provider bundle.
  2. Read the current Hermes configuration and prior receipt.
  3. Plan provider and MCP changes before writing anything.
  4. Copy the provider files and write the ownership receipt.
  5. Write the changed configuration while keeping its file permissions.
  6. 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 /v1 event 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

TriggerConsequenceGuard
Worker or server requests fail repeatedlyHermes stops receiving or recording memory for the breaker windowRequest timeouts, quiet failure handling, and a three-failure breaker
A project matches the excluded-project patternsIts prompts, tools, and notes are not sentClient-side exclusion check before each operation
Hermes config uses an unsupported YAML shapeInstall does not change the configShape validation and an explicit install error
A user edits the installed MCP entryUninstall leaves that entry in placeReceipt match is required before removal
A provider prompt is private or only contains injected memoryThe prompt and its tool calls are not recordedTagged-section stripping and prompt anchoring

Key files

FileWhy to read it
hermes/…/__init__.pyDefines the Hermes memory provider and lifecycle callbacks
hermes/…/client.pyDefines settings, transport, filtering, project scope, and worker/server calls
hermes/…/plugin.yamlDeclares the Hermes plugin and its hook requirement
hermes/…/README.mdSummarizes event mapping, install behavior, and runtime choices
src/…/HermesInstaller.tsControls plugin installation, configuration ownership, and uninstall behavior
src/…/hermes-config-yaml.tsDefines safe, comment-preserving edits to Hermes YAML
tests/…/hermes-worker-e2e.test.tsShows the full installer-to-worker-to-search contract