yonro/hermes-xmemo-plugin

XMemo Hermes Agent Memory Provider Plugin

XMemo is an identity-aware memory layer for AI agents: one persistent, user-owned memory space that works across ChatGPT, Copilot, Claude, Codex, Gemini, and here — Hermes Agent. Every memory entry knows who wrote it, so you can recall, audit, and control context without confusion or spillover.

This plugin connects Hermes Agent to your XMemo account, giving the agent durable memory that survives sessions and long-running workflows, with per-profile isolation.

Agent-readable summary

Use this section when a setup agent, package index, marketplace crawler, or Hermes-aware assistant needs to classify the integration quickly.

If the active runtime is Hermes Agent, prefer this native plugin over raw MCP configuration. The plugin participates in Hermes' memory lifecycle: pre-turn recall, native memory mirroring, working state, optional workflow tools, and session-end snapshots. Use the hosted MCP endpoint only as a portable fallback or for non-Hermes MCP clients.

Shared memory with ChatGPT

XMemo gives Hermes a way to work with the same user-owned cloud memory that can also be connected from ChatGPT. When a user saves useful ChatGPT brainstorms, project decisions, preferences, research notes, or handoff context into XMemo, Hermes can later recall that context through this native memory provider.

This is especially useful for long-running work: ChatGPT can help shape the idea, XMemo stores the durable context under the user's account, and Hermes can continue with the same memory layer during agent runs. This does not mean the plugin reads ChatGPT's built-in native memory directly. It reads XMemo memories that the user explicitly saved or authorized through the XMemo connection. Marketplace or official-connection claims should be made only when supported by public listing or review evidence.

What it does

• Cross-agent recall — Hermes prefetches relevant XMemo context from all visible memories in your XMemo account, including memories written by other connected agents.
• Semantic search — ask the agent to search saved facts with natural language (xmemo_search); results include provenance such as self or other_agent when XMemo returns it.
• Durable fact storage — store explicit facts, preferences, and decisions (xmemo_remember).
• Working state with TTL — save active task, next action, or blocker so future sessions can resume (xmemo_update_state).
• Built-in memory mirroring — when Hermes' native memory tool writes, the same fact is mirrored to XMemo.
• Session snapshots — captures a restart snapshot at session end for later restoration by compatible XMemo workflows.
• Reminders & timeline — optional workflow tools for TODOs and timeline events (opt-in via config).
• Hermes write scoping — new Hermes-authored memories are written to the configured Hermes scope so provenance stays clear.
• Resilient by default — circuit breaker pauses API calls after consecutive failures; background prefetch/sync never block the chat.

Install

Hermes looks for memory provider plugins in $HERMES_HOME/plugins/<name>/. The default HERMES_HOME is ~/.hermes.

pip install (recommended)

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

To install to a non-default Hermes home:

HERMES_HOME=/path/to/your/hermes-home hermes-xmemo install

One-liner (no pip)

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

Using install.sh (if you already cloned)

cd hermes-xmemo-plugin
bash install.sh

Manual install

# Remove any previous install first to avoid nested directories.
rm -rf "${HERMES_HOME:-$HOME/.hermes}/plugins/xmemo"
mkdir -p "${HERMES_HOME:-$HOME/.hermes}/plugins"
cp -r src/hermes_xmemo/xmemo "${HERMES_HOME:-$HOME/.hermes}/plugins/"

Configure

hermes memory setup xmemo

The setup wizard only asks for your XMemo token.

Or manually:

hermes config set memory.provider xmemo
echo "XMEMO_KEY=your-token" >> "${HERMES_HOME:-$HOME/.hermes}/.env"

Requirements

• Hermes Agent (the plugin is loaded by Hermes at runtime)
• httpx (already a dependency of Hermes)
• XMemo service token from xmemo.dev

How it works

1. Before the turn — Hermes calls prefetch() to retrieve relevant XMemo context across visible memories in your XMemo account and injects it into the conversation.
2. During the turn — the agent can call explicit XMemo tools (xmemo_search, xmemo_remember, etc.).
3. After the turn — high-signal turns can be recorded to the XMemo timeline if capture_timeline is enabled.
4. Session end — a restart snapshot is captured for later restoration by compatible XMemo workflows.

Automatic prefetch, turn sync, and session snapshots run in the background. Explicit tool calls and memory mirroring use bounded timeouts, with a circuit breaker protecting Hermes from repeated failures.

Configure

Most users do not need this section. Advanced settings are available in $HERMES_HOME/xmemo.json:

Environment variables

You can override most settings via environment variables (useful for CI or containerized setups):

Tools

Default tools

These tools are always available:

Optional workflow tools

Set enable_workflow_tools: true in xmemo.json to expose:

Optional destructive tool

Set enable_destructive_tools: true to expose:

Privacy & security

• API keys live in $HERMES_HOME/.env, never in xmemo.json.
• xmemo_forget requires an exact memory id and is disabled by default.
• Automatic timeline writes are disabled by default. When enabled, only high-signal turns (decisions, preferences, blockers, etc.) are recorded.
• Built-in memory tool writes are mirrored to XMemo only when the provider is active.
• Prefetch cache is isolated per session, so concurrent gateway sessions cannot cross-contaminate recall context.

Uninstall or disable

To disable XMemo without removing files:

hermes config set memory.provider ""

To remove the plugin entirely:

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

Learn more

• xmemo.dev — XMemo home
• XMemo agent discovery
• Hermes XMemo config
• XMemo hosted MCP fallback
• Hermes Agent docs: Memory Providers

License

MIT