Maximem Vity

Hermes Agent is stateless between sessions. This plugin gives it a long-term memory. Vity adds persistent memory (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.

The plugin and the maximem-vity-sdk package it needs install into Hermes’ own Python environment.

Features

Long-term memory: Stores facts, preferences, episodes, knowledge, and user profiles in your Vity account, and recalls them across sessions. Vity is not end-to-end encrypted: Vity and the outside AI model providers it uses process your content. See Privacy and data.
Auto-recall: Fetches relevant memories and injects them as context before each turn. It also loads a short summary of who you are once per session.
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 recall can find it.
Never holds up a reply: Recall before a turn is capped at 3 seconds by default, and the turn goes ahead without memory if Vity is slow. Saving happens in the background.
Agent tools: vity_recall, vity_profile, vity_store, vity_forget and vity_knowledge 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 API Key, enter a name, and click Generate Key.
Copy your key (starts with mx_...). Vity shows it only once.

Configuration covers keys in more detail, including how to revoke one.

Keep this key secure. Anyone who has it can read, add to and delete from your memory. Every key on one Vity account reaches the same memory, so a second key does not give you a separate one. To keep two sets of memories apart, use two Vity accounts.

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

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

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

Remove

hermes-maximem-vity uninstall

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.

Every key on your Vity account reaches the same memory. To keep memories apart, use a separate Vity account. 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 a file named vity.json in your Hermes home folder: ~/.hermes on macOS and Linux, %LOCALAPPDATA%\hermes on Windows, or wherever HERMES_HOME points. The installer does not create this file in your Hermes home folder, and the plugin works without it, using the defaults below. To change a setting, create the file yourself with only the keys you want to change.

The installer also puts a vity.json inside plugins/maximem_vity/. The plugin never reads that copy, so editing it changes nothing. Put your settings in vity.json in the Hermes home folder itself, then restart Hermes.

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_min_score`	number	`0.3`	The lowest relevance score (0 to 1) a memory needs before automatic recall adds it. It keeps weak matches out of the context. It doesn’t affect the `vity_recall` tool.
`recall_timeout`	number	`6.0`	Seconds before a single recall request to Vity gives up.
`recall_deadline`	number	`3.0`	The most seconds Hermes waits for recall before a turn. After that the turn goes ahead with no memory. With the defaults, this cap is the one that applies.
`profile_warmup`	boolean	`true`	When a session starts, load a short summary of who you are in the background and add it to the context once.

Usage analytics

The plugin sends usage events to Maximem to help improve it, and they are on by default. They do not include your messages or memories. To turn them off, set MAXIMEM_ANALYTICS to 0, false, off or no in ~/.hermes/.env or your environment. The installer sends one event too, so set it before you run the installer if you want none at all.

How it works

Once installed and configured, the plugin works automatically:

Recall before each turn: Vity searches your memory for your current message. It is capped by recall_deadline (default 3 seconds): if matches that score at least recall_min_score return in time they are added as context; otherwise the turn goes ahead with no memory rather than waiting. The first time a session has a profile summary ready, Hermes adds that once as background context too (profile_warmup).
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 recall can find it.

Recall is time-boxed, so a slow connection means no memory for that turn instead of a long wait. Saving runs in the background and never holds up the reply.

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

Agent tools

The plugin gives the agent five tools:

Tool	Parameters	Purpose
`vity_recall`	`query` (required), `top_k` (default 10, max 50)	Search for specific stored memories: individual facts, preferences and decisions.
`vity_knowledge`	`query` (required), `limit` (default 10, max 100)	Topic-level summaries of what you know or have learned. Use it for “what does the user know about X”.
`vity_profile`	none	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 memories that match `query`, up to the 100 closest. It previews first; deleting needs `dry_run` set to `false` and a `query`.

If Meeting Memory is switched on for your account, Hermes also offers vity_meeting_recall, which answers questions from your meeting history. It takes question (required) and optional meeting_type and status filters. Without Meeting Memory the tool is not shown. 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 or vity_knowledge. 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"         # search your memories
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 not set to false in vity.json in your Hermes home folder.
Check prompt length: prompts shorter than min_prompt_length (default: 5) won’t trigger recall, except the first message of a session and short follow-ups like “why?”.
Check the score floor: automatic recall only adds memories that score at least recall_min_score (default 0.3), and gives up after recall_deadline (default 3 seconds). A slow connection can mean no memory that turn.
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: Vity overview
API keys: app.maximem.ai/api-keys
Email: [email protected]
Twitter / X: @MaximemAI

Get started

Plugins and extensions

Apps

Vity MCP server

Settings

Hermes Agent

Features

API key

Installation

Non-interactive installs

Verify installation

Update

Remove

Configuration

API key (required)

Tunables (optional)

Usage analytics

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

​Remove

​Configuration

​API key (required)

​Tunables (optional)

​Usage analytics

​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

Remove

Configuration

API key (required)

Tunables (optional)

Usage analytics

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