All plugins

xmemo

Native XMemo memory provider for Hermes Agent — durable, identity-aware cross-session memory with semantic search. Disclosure — cloud memory provider: sends each user prompt (for recall and the search tools), model-written memories and mirrored built-in Hermes memory writes, plus a stable install ID, to xmemo.dev (Yonro Co., Ltd.); keeps a local SQLite cache of recalled results and a queue of unsent writes in $HERMES_HOME/xmemo_cache.db, partitioned by a hashed account identity; reads the key from XMEMO_KEY (also MEMORY_OS_API_KEY / MEMORY_OS_MCP_TOKEN) and, if none is set, falls back to the xmemo login token in ~/.config/xmemo/credentials.json (a catalog rule 11 deviation kept for existing users); workflow and destructive tools and timeline capture are off by default and opt-in.

yonro8Memoryv1.2.1Updated 1 month ago

About

Native XMemo memory provider for Hermes Agent — durable, identity-aware cross-session memory with semantic search. Disclosure — cloud memory provider: sends each user prompt (for recall and the search tools), model-written memories and mirrored built-in Hermes memory writes, plus a stable install ID, to xmemo.dev (Yonro Co., Ltd.); keeps a local SQLite cache of recalled results and a queue of unsent writes in $HERMES_HOME/xmemo_cache.db, partitioned by a hashed account identity; reads the key from XMEMO_KEY (also MEMORY_OS_API_KEY / MEMORY_OS_MCP_TOKEN) and, if none is set, falls back to the xmemo login token in ~/.config/xmemo/credentials.json (a catalog rule 11 deviation kept for existing users); workflow and destructive tools and timeline capture are off by default and opt-in.

XMemo Memory Provider for Hermes

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

This directory is the provider bundle installed under
$HERMES_HOME/plugins/xmemo/. It participates directly in Hermes' memory
lifecycle and connects the active profile to XMemo.

Discovery

ResourceURL
Agent discoveryhttps://xmemo.dev/.well-known/agent-discovery.json
Hermes configurationhttps://xmemo.dev/v1/mcp/config/hermes
Hosted MCP fallbackhttps://xmemo.dev/mcp
Source repositoryhttps://github.com/yonro/hermes-xmemo-plugin

For Hermes, prefer this native provider. The hosted MCP endpoint is a portable
fallback for MCP-only clients and does not provide Hermes lifecycle hooks.

Setup

Recommended:

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

Direct PyPI installation:

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

The setup flow:

  • installs the provider under $HERMES_HOME/plugins/xmemo/;
  • sets memory.provider to xmemo;
  • stores non-secret settings in $HERMES_HOME/xmemo.json;
  • reuses the user-scoped credential from xmemo login when available;
  • can sync the token to $HERMES_HOME/.env as XMEMO_KEY for compatibility.

Hosted MCP is not configured by default. Use
xmemo setup hermes --with-mcp only when that fallback is intentional.

Lifecycle

  1. Before a turn — prefetch a bounded context pack from memories visible to
    the current XMemo account.
  2. During a turn — expose explicit search, recall, remember, and working
    state tools. Hermes built-in memory writes are mirrored while XMemo is the
    active provider.
  3. After a turn — optionally capture high-signal timeline events.
  4. At session end — capture a restart snapshot and schedule a final outbox
    sync.

Prefetch state is isolated per Hermes profile and session.

Tools

Default

ToolPurpose
xmemo_recall_contextBuild a bounded, ranked context pack
xmemo_searchSearch durable memories semantically
xmemo_getRetrieve full untruncated content of a single memory by ID
xmemo_listList memories under an optional path prefix or category
xmemo_rememberSave a durable fact, preference, or decision
xmemo_update_stateSave active task, next action, or blocker with TTL

Temporal retrieval options

Both xmemo_search and xmemo_recall_context accept these optional fields:

FieldMeaning
sinceInclusive start, RFC3339 timestamp with timezone offset
untilExclusive end, RFC3339 timestamp with timezone offset; must be later than since
time_orderasc (oldest first) or desc (newest first)
owner_timezoneNon-empty IANA name such as Asia/Tokyo; the server validates the name
reference_timeReference instant in RFC3339 with timezone offset
temporal_axis_modecreated_at, updated_at, or split_filter_created_order_updated
query_modetopic for relevant memories, or activity_log for a bounded event feed
hypothetical_answerNon-empty semantic expansion; xmemo_recall_context only

The interval is half-open: [since, until). Use an explicit offset, for example
2026-10-01T00:00:00+09:00 or 2026-09-30T15:00:00Z; naive timestamps are rejected.
query_mode=activity_log requires both since and until. Invalid or missing
required bounds are rejected locally without sending a request.

Omit unused fields; do not send empty strings. Existing calls without temporal
fields remain backward compatible. Read-cache keys bind account identity and
temporal fields. Background prefetch does not infer temporal filters from
text such as “last week”, “yesterday”, or “上周”; use explicit tool arguments when
you need a bounded time interval.

Optional workflow tools

Set "enable_workflow_tools": true in xmemo.json:

ToolPurpose
xmemo_record_eventAppend a timeline event or milestone
xmemo_create_reminderCreate a TODO or action item
xmemo_list_remindersList reminders
xmemo_complete_reminderComplete a reminder

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

Configuration

Non-secret configuration lives in $HERMES_HOME/xmemo.json:

KeyDefaultPurpose
agent_idhermesAgent family identifier
agent_instance_idgeneratedStable, opaque installation identifier
bucketworkNamespace for new Hermes-authored writes
scopehermes/defaultScope for new Hermes-authored writes
read_bucket%Recall/search bucket filter
read_scopeunsetRecall/search scope filter
timeout_seconds5.0REST request timeout
prefetch_max_items5Maximum recalled items
prefetch_max_tokens900Maximum recalled context tokens
enable_workflow_toolsfalseExpose reminder and event tools
enable_destructive_toolsfalseExpose xmemo_forget
capture_timelinefalseRecord high-signal turns
enable_non_idempotent_replayfalseAuto-replay queued non-idempotent writes

Supported environment overrides:

XMEMO_KEY
XMEMO_URL
XMEMO_AGENT_ID
XMEMO_AGENT_INSTANCE_ID
XMEMO_BUCKET
XMEMO_SCOPE
XMEMO_READ_BUCKET
XMEMO_READ_SCOPE
XMEMO_TIMEOUT_SECONDS
XMEMO_PREFETCH_MAX_ITEMS
XMEMO_PREFETCH_MAX_TOKENS

Legacy MEMORY_OS_API_KEY, MEMORY_OS_MCP_TOKEN, and MEMORY_OS_URL
variables remain accepted.

Credentials

Credential priority is:

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

API keys are never read from or written to xmemo.json. Do not place tokens in
git-tracked files, logs, or shell history.

Reliability

The provider stores its local reliability state in
$HERMES_HOME/xmemo_cache.db:

  • search reuses matching fresh results for 5 minutes;
  • recall_context and prefetch are online first; cached context is used only on offline/transient failures;
  • marked stale results can be used for up to 24 hours during transient
    failures;
  • transiently failed writes enter an outbox with stable idempotency keys;
  • idempotent writes retry up to 5 times with exponential backoff;
  • non-idempotent writes are held by default to prevent duplicates;
  • sent records are retained for 24 hours, failed records for 7 days, and the
    failed queue is capped at 100.

Read-cache keys isolate base_url, a one-way credential/agent identity
fingerprint, and retrieval parameters including temporal fields. Credential
changes stop reuse. Opening the cache removes legacy entries without identity
and entries past the fallback window, while preserving the write outbox.
Fresh search hits do not contact the server; remote permission changes are
observed on the next online request.

Queued writes are bound to a one-way fingerprint of the initiating credentials
and agent identity. After an account switch, another identity cannot replay
them; they remain queued for the original identity to return. On upgrade,
unsent legacy writes without an owner identity are preserved as held with automatic
replay disabled, for manual recovery.

The SQLite database stores cached responses and queued payloads as plain-text
JSON. It never stores credentials, but the Hermes home directory should still
be protected as private user data.

Privacy boundaries

  • The provider reads XMemo memories the user saved or authorized. It does not
    read another client's built-in private memory.
  • New Hermes-authored writes use the configured Hermes bucket and scope.
  • Timeline capture and destructive tools are disabled by default.
  • A circuit breaker and bounded timeouts keep service failures from blocking
    the conversation.

Disable

hermes config set memory.provider ""

Re-enable:

hermes config set memory.provider xmemo

Full project documentation:
https://github.com/yonro/hermes-xmemo-plugin

README from the reviewed commit 499a383; it updates when the author re-pins.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section