Metadata-Version: 2.4
Name: ultramemory-hermes
Version: 1.2.0
Summary: UltraMemory — self-learning, metamemory-gated long-term memory provider for Hermes Agent (and any MCP client). One API key = your own private tenant.
Project-URL: Homepage, https://ultramemory.us
Project-URL: Documentation, https://ultramemory.us
Author-email: UltraMemory <support@ultramemory.us>
License: Proprietary
Keywords: agent,hermes,llm,mcp,memory,metamemory,rag
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: httpx
Description-Content-Type: text/markdown

# UltraMemory — Hermes memory provider

The deep, premium integration for [Hermes Agent](https://github.com/NousResearch/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). **Also closes the metamemory feedback loop** — sends an implicit used/ignored signal so the gate self-calibrates over time. |
| `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`, `playbook_outcome` 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

```bash
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):

```bash
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)
export ULTRAMEMORY_FEEDBACK=true            # close the metamemory feedback loop on sync_turn (default true)
```

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

## Tests

```bash
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.

## Changelog

- **1.1.0** — `sync_turn` now also closes the metamemory feedback loop (implicit used/ignored signal so the gate self-calibrates over time); add `ULTRAMEMORY_FEEDBACK` (default true).
- **1.2.0** — wire the playbook outcome loop — the agent reports strategy win/loss via playbook_outcome so Wilson credit-scoring + auto-retire run on real data.
