XMemo for Hermes Agent

Native, user-owned long-term memory for Hermes Agent.

Recall across sessions, preserve working state, and keep Hermes connected to the same private memory layer as your other AI agents.

Quick start · Architecture · Tools · Configuration · Reliability · Security

hermes-xmemo is the native XMemo memory provider for Hermes Agent. It joins Hermes' memory lifecycle directly: pre-turn recall, explicit memory tools, built-in memory mirroring, per-session working context, and session-end snapshots.

[!NOTE] This provider reads memories that you saved or authorized in XMemo. It does not read the private built-in memory of ChatGPT, Claude, or another client.

At a glance

Why a native provider?

• First-class lifecycle — recall starts before a turn and snapshots happen when a session ends.
• Cross-agent continuity — Hermes can recall user-approved XMemo memories written by other connected agents.
• Bounded context — recall is ranked and limited before it reaches the prompt.
• Write isolation — Hermes-authored entries use a dedicated bucket and scope while reads can span all memories visible to the account.
• Graceful degradation — timeouts, a circuit breaker, local read cache, and a write outbox keep memory failures from blocking the conversation.

Quick start

1. Install with XMemo CLI (recommended)

npm install -g @xmemo/client
xmemo login
xmemo setup hermes

This installs or updates the Python package, deploys the native provider into Hermes, and reuses your user-scoped XMemo credential. Hosted MCP is not added by default.

For a custom Hermes home:

xmemo setup hermes --hermes-home /path/to/.hermes

2. Install directly from PyPI

pip install hermes-xmemo
hermes-xmemo install
hermes memory setup xmemo

3. Install without cloning

curl -fsSL https://raw.githubusercontent.com/yonro/hermes-xmemo-plugin/main/install-remote.sh | bash
hermes memory setup xmemo

The native Hermes setup wizard remains supported. If xmemo login has already stored a shared credential, the wizard can reuse it; otherwise it asks for an XMemo token.

Architecture

The provider runs inside Hermes and communicates with XMemo over bounded HTTPS requests. Its local SQLite reliability layer belongs to the Hermes profile; it is not a second source of truth.

Lifecycle

1. Before a turn — Hermes starts a background prefetch and injects a bounded XMemo context pack when it is ready.
2. During a turn — the agent can search, remember, or update working state with explicit tools. Writes through Hermes' built-in memory tool are mirrored to XMemo while this provider is active.
3. After a turn — high-signal timeline capture is available as an opt-in.
4. At session end — the provider captures a restart snapshot and schedules a final outbox sync.

Prefetch state is isolated by profile and session, preventing one concurrent Hermes session from receiving another session's recall context.

Native provider or hosted MCP?

Use the native provider for Hermes. Add xmemo setup hermes --with-mcp only when you deliberately want the portable MCP fallback as well.

Tools

Default

Optional workflow tools

Set "enable_workflow_tools": true in xmemo.json:

Optional destructive tool

Set "enable_destructive_tools": true to expose xmemo_forget. Deletion requires an exact memory ID and stays disabled by default.

Configuration

Most installations need no manual configuration. Non-secret settings live in $HERMES_HOME/xmemo.json:

Example:

{
  "bucket": "work",
  "scope": "hermes/default",
  "read_bucket": "%",
  "prefetch_max_items": 5,
  "prefetch_max_tokens": 900,
  "enable_workflow_tools": false
}

Environment overrides

Legacy MEMORY_OS_API_KEY, MEMORY_OS_MCP_TOKEN, and MEMORY_OS_URL variables remain accepted.

Credential resolution

Credentials are resolved in this order:

1. XMEMO_KEY, then the supported legacy environment variables.
2. The user-scoped credential saved by xmemo login.

Secrets are never read from or written to xmemo.json. The setup flow can sync the active token to $HERMES_HOME/.env for Hermes compatibility.

Reliability

The plugin maintains $HERMES_HOME/xmemo_cache.db so temporary service or network failures degrade safely.

Fallback responses are explicitly marked with stale: true and source: "cache" so the agent does not confuse an offline cache result with fresh cloud state.

[!WARNING] xmemo_cache.db contains cached memory responses and queued write payloads as plain-text JSON. It never stores API credentials, but $HERMES_HOME should still be readable only by the owning user.

Security

Avoid committing $HERMES_HOME/.env, xmemo.json, or runtime cache files. Treat the XMemo token like any other service credential.

Operations

Disable XMemo without removing files:

hermes config set memory.provider ""

Re-enable it:

hermes config set memory.provider xmemo

Remove the installed provider:

rm -rf "${HERMES_HOME:-$HOME/.hermes}/plugins/xmemo"

Development

git clone https://github.com/yonro/hermes-xmemo-plugin.git
cd hermes-xmemo-plugin
python -m pip install -e .
python -m pytest -q
python -m build

The implementation shipped to Hermes lives in src/hermes_xmemo/xmemo/. Keep its bundled README aligned with this repository README whenever installation or configuration behavior changes.

Agent-readable metadata

Links

• XMemo
• PyPI package
• Hermes memory-provider documentation
• Agent discovery
• Issue tracker

License

MIT © XMemo contributors.