# Hermes

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

- Canonical: https://docs.xmemo.dev/docs/connect/hermes
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 1440952fac8d821537cc142fcfcc5ab39d05556b02f7ee2eb9fb5aa4a807990c
- Edition-Digest: 7a91633d885f9637a978631cd268adf53be6c1311bdc1a7512d058b62fdffdfc
- Source-Revision: sha256:2f9a9ba995dbc34197eee37be9c6ad47d8a413c9d6684967298705aa32a5f866

## 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:

```bash
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.

```bash
hermes config set memory.provider ""
```