ConnectConnectHermes

MCP Client

Hermes

Connect Hermes Agent through its native memory plugin on PyPI with session checkpointing, auto-capture, and durable project memory.

Who this is for and concrete interface

This guide connects Hermes Agent to XMemo persistent memory. Hermes integrates through the maintained native memory plugin package hermes-xmemo (version 1.1.3) on PyPI, anchored to the active repository yonro/hermes-xmemo-plugin @ 30fe1bc20a (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md). Note that the archived repository yonro/xmemo-hermes-plugin @ eb47797a08 is a legacy migration reference only; all new installations use hermes-xmemo.

Prerequisites

Ensure the following runtime dependencies and tools are present before connecting:

  • Hermes Agent CLI and runtime installed (Python 3.10+).
  • Python package installer (pip).
  • Valid XMemo account at https://xmemo.dev.
  • Network access to https://xmemo.dev/mcp over HTTPS.

Installation

Install the maintained hermes-xmemo provider package using pip, then run the setup command documented in README lines 98-107:

pip install hermes-xmemo
hermes memory setup xmemo

Authorization and credential configuration

Configure authentication using an environment variable or Hermes configuration. Never check raw bearer tokens into version control:

  • Environment variable (recommended): Set XMEMO_KEY in the shell or environment launching Hermes (export XMEMO_KEY='<your-xmemo-token>').
  • Hermes setup wizard: Running hermes memory setup xmemo prompts for credentials and configures ~/.hermes/config.yaml.
  • Configuration check: Verify that ~/.hermes/config.yaml contains memory.provider set to xmemo.

Load and restart behavior

Daemon restart or session reload procedures are not explicitly documented in the hermes-xmemo plugin README (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md); refer to the Hermes Agent host documentation or restart your active Hermes terminal session.

Connection check (read-only)

Verify connectivity with a read-only recall request before writing durable data. This check does not modify memory state:

  • Check: Start a test Hermes session and issue a read-only active recall query for existing project context.
  • Success signal: Hermes returns structured memory results with valid Reference and Location fields from the authorized workspace.

First useful task: Synthetic memory lifecycle

Verify memory persistence, stateless session transition, source-attributed recall, and correction:

  • 1. Save synthetic fact: Store a project convention ("Hermes demo conventions: UTC logging with ISO 8601 timestamps.") to "projects/demo-hermes/conventions".
  • 2. Stateless transition: End the current Hermes conversation and start a new session.
  • 3. Recall with source attribution: Query "demo conventions timestamp format". Confirm returned Reference and Location.
  • 4. Correct memory: Update the remembered convention using update_memory with updated formatting rules.
  • 5. Optional cleanup: Soft-delete (forget) the demo convention when onboarding verification completes.

Automatic capture and duplicate prevention

Hermes Agent provides automatic context capture across execution boundaries:

  • Session checkpointing: When enabled in ~/.hermes/config.yaml, Hermes captures session summaries and key decisions at session boundary milestones.
  • Duplicate prevention: Built-in content-hash deduplication ensures identical facts and decisions are not repeatedly written during iterative execution loops.
  • Scope boundary: Every captured memory is strictly isolated to the authenticated user's workspace and active project scope.

Provider conflicts and storage boundaries

Understand runtime isolation and storage ownership:

  • Provider conflicts: Do not enable multiple memory providers simultaneously in ~/.hermes/config.yaml. Running overlapping providers causes split-brain recall.
  • Storage ownership: All durable memories reside in the user-owned XMemo cloud backend. Hermes maintains only short-lived local cache for session responsiveness.
  • Offline and replay limits: Transient network interruptions are handled by a bounded local write buffer; offline writes fail when the buffer limit or token expiration is reached, and uncommitted actions do not replicate to other agents until reconnected.

Recovery, update, and removal

Troubleshooting, update, and removal procedures for Hermes:

  • Recovery (401 invalid_token): Verify XMEMO_KEY is set in the current shell environment or Hermes configuration.
  • Update: Plugin update commands are not documented in the hermes-xmemo plugin README (https://github.com/yonro/hermes-xmemo-plugin/blob/30fe1bc20a/README.md); run pip install --upgrade hermes-xmemo or consult Hermes host documentation.
  • Removal (README line 292): To disable the memory provider in Hermes, run the documented removal command: hermes config set memory.provider "".
  • Removal vs Remote deletion: Disabling the local provider does not delete stored remote memories or revoke API credentials; delete memories or revoke keys at https://xmemo.dev/me.
hermes config set memory.provider ""

Source: Hermes integration