Vity Memory for Hermes Agent

Vity by Maximem AI — persistent, cross-session semantic memory for Hermes Agent, distributed as a standalone plugin.

Vity gives the agent a long-term memory graph (facts, preferences, episodes, knowledge, profile). It automatically recalls relevant context before each turn and captures the conversation after each turn, so the agent remembers users and projects across sessions.

Built on the maximem-vity-sdk Python client.

Install

First, get an API key at app.maximem.ai/api-keys (starts with mx_). Then:

pip install hermes-maximem-vity
hermes-maximem-vity install

hermes-maximem-vity install does everything in one step:

1. Copies the plugin into ~/.hermes/plugins/maximem_vity/, where Hermes discovers it.
2. Prompts for your API key and saves it to ~/.hermes/.env (no duplicates).
3. Activates the provider (memory.provider: maximem_vity).

It prints ✅ All set! when finished. Start the agent with hermes.

Already had Hermes (or the gateway) running during install? Restart it to load the newly-activated provider — gateway users: hermes gateway restart.

Non-interactive / scripted installs — pass the key as a flag to skip the prompt:

hermes-maximem-vity install --api-key mx_your_key

pipx install hermes-maximem-vity        # install pipx first if needed: brew install pipx
hermes-maximem-vity install

Verify

hermes-maximem-vity status   # plugin installed ✓, SDK available to Hermes ✓
hermes memory status         # shows: maximem_vity ← active
hermes maximem_vity status           # API key set ✓, SDK installed ✓, connection ok ✓

Update

Update (always overwrites):

pip install -U hermes-maximem-vity
hermes-maximem-vity install

Remove:

hermes-maximem-vity uninstall

Troubleshooting

hermes maximem_vity status still says maximem-vity-sdk not installed — even after pip install?

Hermes runs inside its own isolated environment, which is usually not the Python that ran pip install (Anaconda or system Python). The SDK must live in Hermes' environment, and hermes-maximem-vity install puts it there for you — just re-run it:

hermes-maximem-vity install
hermes-maximem-vity status     # confirm: SDK available to Hermes ✓

Windows: hermes-maximem-vity is "not recognized as a command"?

pip install --user on Windows drops the console script in a Scripts folder that isn't on PATH. Add it for the session (PowerShell), then run install:

$env:Path += ";$(python -m site --user-base)\Python$($(python -c 'import sys;print(f"{sys.version_info.major}{sys.version_info.minor}")'))\Scripts"
hermes-maximem-vity install

Or just call it by full path once: & "$(python -m site --user-base)\Python313\Scripts\hermes-maximem-vity.exe" install. To make it permanent, add that Scripts folder to your user PATH in Environment Variables.

Configuration

API key (secret — stored in ~/.hermes/.env):

The API key owns the memory space — use a separate key per account that needs isolated memories.

Change / update your key — a plain re-install keeps the existing key (you'll see already configured). To replace it, pass the new key explicitly (it's written de-duplicated, so no stale copies are left behind):

hermes-maximem-vity install --api-key mx_your_new_key

Or edit ~/.hermes/.env directly, then restart Hermes (gateway users: hermes gateway restart).

Tunables (optional, non-secret — $HERMES_HOME/vity.json, created on install):

Self-hosted backend (optional): set MAXIMEM_ENDPOINT (or endpoint in vity.json) to point at a non-default Maximem API URL.

How it works

• Recall before each turn — a semantic search runs against your current message and, if it returns within a short timeout (recall_timeout, default 6s), the matches are injected as context; otherwise the turn proceeds with no memory rather than waiting.
• Capture after each turn — the user/assistant exchange is saved to long-term memory.
• Memory mirroring — when Hermes' built-in memory tool records a fact, it is also stored in Vity so it participates in semantic recall.

Recall runs synchronously on the pre-turn path but is bounded by recall_timeout (default 6s), so a slow or unhealthy backend degrades to no-memory-this-turn instead of hanging. Capture and memory-mirroring writes run on background threads, so they never block the reply.

Agent tools

The plugin exposes four tools to the agent:

In chat, this is transparent: ask the agent to "remember that …" and it calls vity_store; ask "what do you know about …" and it calls vity_recall. No special commands are required.

CLI

Manage memory directly from the terminal:

hermes maximem_vity status                          # config + live connection check
hermes maximem_vity search "favorite color"         # semantic search
hermes maximem_vity search "deadlines" --limit 20 --json
hermes maximem_vity store "I prefer dark mode" --type preference
hermes maximem_vity forget "old project"            # dry-run (preview)
hermes maximem_vity forget "old project" --yes      # confirm deletion

To (re)activate the provider, use hermes config set memory.provider maximem_vity. Avoid the interactive hermes memory setup wizard — buffered/pasted terminal input can drop the selection and leave the provider unset.

Development

pip install -e ".[dev]"
pytest -q

Tests stub the Hermes host modules (agent.memory_provider, tools.registry, hermes_constants, utils) so they run without a full Hermes checkout — see tests/conftest.py.

Layout

License

MIT — see LICENSE.

Support

• Documentation: https://docs.maximem.ai/vity
• API keys: https://app.maximem.ai/api-keys