ultramemory-hermes 1.0.0

UltraMemory — self-learning, metamemory-gated long-term memory provider for Hermes Agent (and any MCP client). One API key = your own private tenant.

UltraMemory — Hermes memory provider

The deep, premium integration for Hermes Agent. Where the MCP server is the universal, pull-based front door, this provider plugs into Hermes' lifecycle so memory just works:

Hook	What it does
prefetch	Metamemory-gated recall injected before each turn — when memory is unsure or empty it injects nothing (abstain-and-retrieve, not confabulate).
sync_turn	Auto-captures each completed turn (server dedupes by content hash).
on_memory_write	Mirrors Hermes' built-in memory tool (add/replace) into UltraMemory.
on_pre_compress	Surfaces durable facts so they survive context compression.
on_session_end	Persists a recall-able session digest; the server consolidates nightly.
tools	memory_write, memory_recall, recall_gated, playbook_recall for explicit use.

Tenancy

One UltraMemory API key = one tenant, resolved at the single server-side chokepoint (the provider never sends a tenant id). Your Hermes agent_workspace (or agent_identity) maps to a per-agent scope within that tenant, so separate agents/workspaces keep separate memory under one account. The provider is synchronous (Hermes runs these hooks on its own threads) and never raises out of a hook — a backend hiccup degrades gracefully instead of breaking the agent.

Install & enable

Quickest — pip install, then one command

pip install ultramemory-hermes
ultramemory enable --key um_live_…

The distribution name is ultramemory-hermes (the bare ultramemory name is taken on PyPI by an unrelated project); it installs an importable ultramemory package and an ultramemory console command. ultramemory enable:

• writes ULTRAMEMORY_API_KEY=<key> into $HERMES_HOME/.env (chmod 600 — the secret never lands in world-readable JSON),
• records the non-secret options in $HERMES_HOME/ultramemory.json,
• sets memory.provider: ultramemory in your Hermes config ($HERMES_HOME/config.yaml, falling back to ~/.hermes/config.yaml).

Restart Hermes (or start a new session) to pick it up. Get a key at https://ultramemory.us.

Flags (all optional): --base-url URL, --recall-k N (facts per turn), --gated/--no-gated, --auto-capture/--no-auto-capture, --hermes-home PATH. The key is also read from $ULTRAMEMORY_API_KEY if you omit --key.

Alternative — bundle the plugin directory

1. Copy this directory to plugins/memory/ultramemory/ in your Hermes install (bundled) or to $HERMES_HOME/plugins/ultramemory/ (user-installed).
2. Get an API key at https://ultramemory.us.
3. Run setup and pick ultramemory: hermes memory setup — this installs httpx, stores your key in $HERMES_HOME/.env, writes non-secret options to $HERMES_HOME/ultramemory.json, and sets memory.provider: ultramemory in ~/.hermes/config.yaml.

Or configure by environment variables only (no setup wizard, no CLI):

export ULTRAMEMORY_API_KEY=um_live_…        # required
export ULTRAMEMORY_BASE_URL=https://api.ultramemory.us   # optional (default)
export ULTRAMEMORY_GATED=true               # gated recall for auto-inject (default true)
export ULTRAMEMORY_AUTO_CAPTURE=true        # persist each turn (default true)
export ULTRAMEMORY_RECALL_K=8               # facts per turn (default 8)

Then set memory.provider: ultramemory in ~/.hermes/config.yaml.

Tests

python -m pytest plugins/memory/ultramemory/test_provider.py -q

The tests stub the Hermes host modules and mock the UltraMemory API (httpx.MockTransport), so they run without Hermes installed and without network.