Maximem Vity

Hermes Agent is stateless between sessions. This plugin gives it a long-term memory. Vity adds a persistent memory graph (facts, preferences, episodes, knowledge, and profile) to Hermes Agent. It automatically recalls relevant context before each turn and captures the conversation after each turn, so the agent remembers users and projects across separate sessions.

Built on the maximem-vity-sdk Python client. The plugin and its dependencies install into Hermes’ own Python environment.

Features

Long-term memory: Stores facts, preferences, episodes, knowledge, and user profiles in a private cloud-vault. Recalls them semantically across sessions.
Auto-recall: Fetches relevant memories and injects them as context before each turn.
Auto-capture: Saves the user/assistant exchange to long-term memory after each turn.
Memory mirroring: When Hermes’ built-in memory tool records a fact, it is also stored in Vity so it participates in semantic recall.
Bounded, non-blocking: Recall is time-boxed and degrades to no-memory-this-turn rather than hanging; captures and mirroring run on background threads, so the reply is never blocked.
Agent tools: vity_recall, vity_profile, vity_store, vity_forget for agent-driven memory operations.
CLI commands: Terminal memory management with hermes maximem_vity.

API key

You’ll need a Maximem API key to use this plugin.

Sign up or log in at app.maximem.ai.
Open API Keys in the sidebar.
Click Generate New Key.
Copy your key (starts with mx_...).

Keep this key secure. It owns the memory space — use a separate key per account that needs isolated memories.

Installation

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

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

Copies the plugin into ~/.hermes/plugins/maximem_vity/, where Hermes discovers it.
Prompts for your API key and saves it to ~/.hermes/.env (no duplicates).
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 run hermes gateway restart.

Non-interactive installs

Pass the key as a flag to skip the prompt — useful for scripted or CI setups:

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

Hitting a PEP-668 "externally-managed-environment" or "pip: command not found" error?

System Python (e.g. Homebrew) blocks global pip install. Use pipx (recommended) or a virtual environment:

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

You don’t need to match Python versions — the maximem-vity-sdk dependency is installed into Hermes’ own environment automatically.

Verify installation

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 or remove

The installer always overwrites, so re-running it is how you upgrade:

pip install -U hermes-maximem-vity && hermes-maximem-vity install   # update
hermes-maximem-vity uninstall                                       # remove

Configuration

API key (required)

The API key is a secret and is stored in ~/.hermes/.env.

Env var	Required	Description
`MAXIMEM_API_KEY`	Yes	Your Maximem API key (`mx_...`). `VITY_API_KEY` is also accepted.

The API key owns the memory space — use a separate key per account that needs isolated memories. Changing 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 options live in $HERMES_HOME/vity.json, which is created on install.

Key	Type	Default	Description
`auto_recall`	boolean	`true`	Inject relevant memories before each turn. Recommended: keep enabled.
`auto_capture`	boolean	`true`	Capture the conversation after each turn. Recommended: keep enabled.
`max_recall_tokens`	number	`1000`	Token budget for recalled context. Higher = more context, more API usage.
`min_prompt_length`	number	`5`	Skip recall for very short prompts. Prevents recall on messages like “hi”.
`recall_timeout`	number	`6.0`	Max seconds to wait for pre-turn recall before proceeding with no memory.

Self-hosted backend (optional)

To point the plugin at a non-default Maximem API URL, set MAXIMEM_ENDPOINT (or endpoint in vity.json).

How it works

Once installed and configured, the plugin works automatically:

Recall before each turn — a semantic search runs against your current message. It is bounded by recall_timeout (default 6s): if matches return in time they 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 time-boxed, 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.

No manual action needed. Use the tools and CLI below when you want direct control.

Agent tools

The plugin exposes four tools to the agent:

Tool	Parameters	Purpose
`vity_recall`	`query` (required), `top_k` (default 10, max 50)	Semantic search of stored memories.
`vity_profile`	—	Retrieve the user’s full stored memory profile.
`vity_store`	`content` (required), `memory_type` (`fact` / `preference` / `emotion` / `episode` / `knowledge` / `profile`)	Save a new memory.
`vity_forget`	`query`, `dry_run` (default `true`)	Delete matching memories (previews first).

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. Example interaction:

You: "Remember that I prefer concise answers and I'm working on the Hermes migration."

Agent: Got it — I've saved your preference for concise answers and noted the Hermes migration project.

CLI commands

Manage memory directly from your 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 or pasted terminal input can drop the selection and leave the provider unset.

Troubleshooting

”API key not found” error

Confirm the key and connection:

hermes maximem_vity status

If the connection check fails, re-run the installer with your key:

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

`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 (e.g. 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 ✓

Memories not being recalled

Check config: ensure auto_recall is true in $HERMES_HOME/vity.json.
Check prompt length: prompts shorter than min_prompt_length (default: 5) won’t trigger recall.
Verify the provider is active:
hermes memory status
Confirm maximem_vity shows as active. If not, run hermes config set memory.provider maximem_vity.

Provider unset after setup

The interactive hermes memory setup wizard can drop pasted input. Set the provider directly instead:

hermes config set memory.provider maximem_vity

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 current PowerShell session, 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 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.

Support

Documentation: docs.maximem.ai/vity
API keys: app.maximem.ai/api-keys
Email: [email protected]
Twitter / X: @MaximemAI

​Features

​API key

​Installation

​Non-interactive installs

​Verify installation

​Update or remove

​Configuration

​API key (required)

​Tunables (optional)

​Self-hosted backend (optional)

​How it works

​Agent tools

​CLI commands

​Troubleshooting

​”API key not found” error

​maximem-vity-sdk not installed even after pip install

​Memories not being recalled

​Provider unset after setup

​Windows: hermes-maximem-vity is “not recognized as a command”

​Support

Features

API key

Installation

Non-interactive installs

Verify installation

Update or remove

Configuration

API key (required)

Tunables (optional)

Self-hosted backend (optional)

How it works

Agent tools

CLI commands

Troubleshooting

”API key not found” error

`maximem-vity-sdk not installed` even after `pip install`

Memories not being recalled

Provider unset after setup

Windows: `hermes-maximem-vity` is “not recognized as a command”

Support