Skip to main content
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 in the background 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.
  • Non-blocking: All network calls run on background threads, so the agent loop never blocks.
  • Agent tools: vity_recall, vity_profile, vity_store, vity_forget for agent-driven memory operations.
  • CLI commands: Terminal memory management with hermes vity.

​
API key

You’ll need a Maximem API key to use this plugin.
  1. Sign up or log in at app.maximem.ai.
  2. Open API Keys in the sidebar.
  3. Click Generate New Key.
  4. 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:
  1. Copies the plugin into ~/.hermes/plugins/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: vity).
It prints ✅ All set! when finished. Start the agent with hermes.

​
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
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 memory status     # shows: vity ← active
hermes vity status       # API key set ✓, connection ok ✓

​
Update or remove

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

​
Configuration

​
API key (required)

The API key is a secret and is stored in ~/.hermes/.env.
Env varRequiredDescription
MAXIMEM_API_KEYYesYour Maximem API key (mx_...). VITY_API_KEY is also accepted.

​
Tunables (optional)

Non-secret options live in $HERMES_HOME/vity.json, which is created on install.
KeyTypeDefaultDescription
auto_recallbooleantrueInject relevant memories before each turn. Recommended: keep enabled.
auto_capturebooleantrueCapture the conversation after each turn. Recommended: keep enabled.
max_recall_tokensnumber1000Token budget for recalled context. Higher = more context, more API usage.
min_prompt_lengthnumber5Skip recall for very short prompts. Prevents recall on messages like “hi”.

​
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:
  1. Recall before each turn — relevant memories are fetched in the background and injected as context, so the agent starts each turn already aware of the user.
  2. Capture after each turn — the user/assistant exchange is saved to long-term memory.
  3. Memory mirroring — when Hermes’ built-in memory tool records a fact, it is also stored in Vity so it participates in semantic recall.
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:
ToolParametersPurpose
vity_recallquery (required), top_k (default 10, max 50)Semantic search of stored memories.
vity_profile—Retrieve the user’s full stored memory profile.
vity_storecontent (required), memory_type (fact / preference / emotion / episode / knowledge / profile)Save a new memory.
vity_forgetquery, 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 vity status                          # config + live connection check
hermes vity search "favorite color"         # semantic search
hermes vity search "deadlines" --limit 20 --json
hermes vity store "I prefer dark mode" --type preference
hermes vity forget "old project"            # dry-run (preview)
hermes vity forget "old project" --yes      # confirm deletion
To (re)activate the provider, use hermes config set memory.provider 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

Ensure your API key is set correctly: 
hermes vity status
If the connection check fails, re-run the installer and re-enter your key: 
hermes-maximem-vity install --force

​
Memories not being recalled

  1. Check config: ensure auto_recall is true in $HERMES_HOME/vity.json.
  2. Check prompt length: prompts shorter than min_prompt_length (default: 5) won’t trigger recall.
  3. Verify the provider is active: 
    hermes memory status
    Confirm vity shows as active. If not, run hermes config set memory.provider 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 vity

​
Support