yonro/hermes-xmemo-plugin
XMemo memory provider for Hermes Agent — durable cross-session AI memory with semantic search
hermes-xmemo is a native XMemo memory provider for Hermes Agent. It supports pre-turn context recall, explicit memory tools, mirroring Hermes built-in memory writes to XMemo, and session-end snapshots.
- Runs inside Hermes and communicates with XMemo over HTTPS.
- Provides ranked, bounded context recall before a turn.
- Includes a local SQLite reliability layer.
full readme from github
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
| Package | hermes-xmemo |
| Hermes provider | xmemo |
| Runtime role | Native memory provider |
| Configuration | $HERMES_HOME/xmemo.json |
| Cloud service | https://xmemo.dev |
| Python | 3.10+ |
| License | MIT |
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
- Before a turn — Hermes starts a background prefetch and injects a bounded XMemo context pack when it is ready.
- During a turn — the agent can search, remember, or update working state
with explicit tools. Writes through Hermes' built-in
memorytool are mirrored to XMemo while this provider is active. - After a turn — high-signal timeline capture is available as an opt-in.
- 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?
| Native provider | Hosted MCP | |
|---|---|---|
| Best for | Hermes Agent | MCP-only clients |
| Hermes lifecycle hooks | Yes | No |
| Pre-turn context injection | Yes | Client-dependent |
| Built-in memory mirroring | Yes | No |
| Local cache and outbox | Yes | Client-dependent |
| Endpoint | Installed plugin | https://xmemo.dev/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
| Tool | Purpose |
|---|---|
xmemo_recall_context |
Build a bounded, ranked context pack |
xmemo_search |
Search durable memories semantically |
xmemo_get |
Retrieve full untruncated content of a single memory by ID |
xmemo_list |
List memories under an optional path prefix or category |
xmemo_remember |
Save a durable fact, preference, or decision |
xmemo_update_state |
Save active task, next action, or blocker with TTL |
Temporal retrieval options
Both xmemo_search and xmemo_recall_context accept these optional fields:
| Field | Meaning |
|---|---|
since |
Inclusive start, RFC3339 timestamp with timezone offset |
until |
Exclusive end, RFC3339 timestamp with timezone offset; must be later than since |
time_order |
asc (oldest first) or desc (newest first) |
owner_timezone |
Non-empty IANA name such as Asia/Tokyo; the server validates the name |
reference_time |
Reference instant in RFC3339 with timezone offset |
temporal_axis_mode |
created_at, updated_at, or split_filter_created_order_updated |
query_mode |
topic for relevant memories, or activity_log for a bounded event feed |
hypothetical_answer |
Non-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:
| Tool | Purpose |
|---|---|
xmemo_record_event |
Append a timeline event or milestone |
xmemo_create_reminder |
Create a TODO or action item |
xmemo_list_reminders |
List open or completed reminders |
xmemo_complete_reminder |
Mark a reminder complete |
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:
| Key | Default | Purpose |
|---|---|---|
agent_id |
hermes |
Agent family identifier |
agent_instance_id |
generated | Stable, opaque installation identifier |
bucket |
work |
Namespace for new Hermes-authored writes |
scope |
hermes/default |
Scope for new Hermes-authored writes |
read_bucket |
% |
Recall/search bucket filter (% means all visible) |
read_scope |
unset | Recall/search scope filter (unset means all visible) |
timeout_seconds |
5.0 |
REST request timeout |
prefetch_max_items |
5 |
Maximum recalled items |
prefetch_max_tokens |
900 |
Maximum recalled context tokens |
enable_workflow_tools |
false |
Expose reminder and event tools |
enable_destructive_tools |
false |
Expose xmemo_forget |
capture_timeline |
false |
Record high-signal turns |
enable_non_idempotent_replay |
false |
Auto-replay non-idempotent queued writes |
Example:
{
"bucket": "work",
"scope": "hermes/default",
"read_bucket": "%",
"prefetch_max_items": 5,
"prefetch_max_tokens": 900,
"enable_workflow_tools": false
}
Environment overrides
| Variable | Overrides |
|---|---|
XMEMO_KEY |
API key |
XMEMO_URL |
Service base URL |
XMEMO_AGENT_ID |
agent_id |
XMEMO_AGENT_INSTANCE_ID |
agent_instance_id |
XMEMO_BUCKET |
bucket |
XMEMO_SCOPE |
scope |
XMEMO_READ_BUCKET |
read_bucket |
XMEMO_READ_SCOPE |
read_scope |
XMEMO_TIMEOUT_SECONDS |
timeout_seconds |
XMEMO_PREFETCH_MAX_ITEMS |
prefetch_max_items |
XMEMO_PREFETCH_MAX_TOKENS |
prefetch_max_tokens |
Legacy MEMORY_OS_API_KEY, MEMORY_OS_MCP_TOKEN, and MEMORY_OS_URL
variables remain accepted.
Credential resolution
Credentials are resolved in this order:
XMEMO_KEY, then the supported legacy environment variables.- 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.
| Layer | Behavior |
|---|---|
| Fresh search cache | Search reuses matching results for 5 minutes |
| Recall and prefetch | Online first; cached context is used only for offline/transient-failure fallback |
| Stale fallback | Returns marked cache results during transient failures, up to 24 hours old |
| Write outbox | Queues transiently failed writes with stable idempotency keys |
| Replay | Retries idempotent writes up to 5 times with exponential backoff capped at 1 hour |
| Non-idempotent writes | Held by default to avoid duplicate reminders or events |
| Dead letters | Permanent failures and exhausted retries are retained for diagnosis |
| Retention | Sent entries: 24 hours; failed entries: 7 days; failed queue capped at 100 |
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.
Read-cache entries are isolated by endpoint (base_url), a one-way credential
and agent identity fingerprint, and retrieval parameters including temporal
filters. Changing credentials invalidates reuse. Legacy entries without identity
and entries beyond the 24-hour fallback window are removed when the cache opens;
queued writes are preserved. A fresh search hit does not contact the server, so
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.
[!WARNING]
xmemo_cache.dbcontains cached memory responses and queued write payloads as plain-text JSON. It never stores API credentials, but$HERMES_HOMEshould still be readable only by the owning user.
Security
| Control | Default |
|---|---|
| Credentials outside project configuration | Enabled |
| Destructive memory tool | Disabled |
| Automatic timeline capture | Disabled |
| Exact ID required for deletion | Enabled |
| Per-session prefetch isolation | Enabled |
| Bounded network timeout | 5 seconds |
| Circuit breaker | Enabled |
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
| Field | Value |
|---|---|
| Package | hermes-xmemo |
| Provider name | xmemo |
| Recommended mode | hermes_plugin_preferred |
| Agent discovery | https://xmemo.dev/.well-known/agent-discovery.json |
| Hermes configuration | https://xmemo.dev/v1/mcp/config/hermes |
| MCP fallback | https://xmemo.dev/mcp |
| Repository | https://github.com/yonro/hermes-xmemo-plugin |
Links
License
MIT © XMemo contributors.