Vity Memory for Hermes Agent

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

Vity gives the agent a long-term memory graph covering facts, preferences, episodes, knowledge, and profile. It 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 (0.3.0 or newer).

Install

First, get an API key at app.maximem.ai/api-keys. It 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 without duplicates.
3. Activates the provider by setting memory.provider: maximem_vity.

It prints a confirmation when finished. Start the agent with hermes.

If Hermes or the gateway was already running during install, restart it to load the newly activated provider. Gateway users run hermes gateway restart.

For non-interactive or 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 as active
hermes maximem_vity status   # API key set, SDK installed, connection ok

Update

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

Re-running install is required: it refreshes the plugin files Hermes loads and upgrades maximem-vity-sdk in the Hermes environment if needed. Your API key and vity.json settings are kept. Restart Hermes afterwards.

Remove

hermes-maximem-vity uninstall

Troubleshooting

hermes maximem_vity status still reports 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 (such as Anaconda or system Python). The SDK must live in the Hermes environment, and hermes-maximem-vity install puts it there. Re-run it:

hermes-maximem-vity install
hermes-maximem-vity status     # confirm the SDK is available to Hermes

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

pip install --user on Windows places the console script in a Scripts folder that may not be on PATH. Add it for the session in 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

Alternatively, 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 defines the memory space. Use a separate key for each account that needs isolated memories.

To change the key, a plain re-install keeps the existing one. To replace it, pass the new key explicitly (it is written de-duplicated, so no stale copies remain):

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

You can also edit ~/.hermes/.env directly, then restart Hermes (gateway users run hermes gateway restart).

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

For a self-hosted backend, set MAXIMEM_ENDPOINT, or endpoint in vity.json, to a non-default Maximem API URL.

Usage telemetry

The plugin sends anonymous usage events (install, session start, recall latency and hit/miss, tool name and latency, capture outcome) to the Maximem API, authenticated with your API key. Events never include prompts, queries, responses or memory content. To turn this off, set MAXIMEM_ANALYTICS=0 in ~/.hermes/.env.

How it works

• Recall before each turn. A semantic search runs against the current message. If it completes within recall_deadline (default 3 seconds), the matches are injected as context; otherwise the turn proceeds with no memory rather than waiting. Only matches above recall_min_score are injected, so weak matches are not presented as fact.
• Follow-up resolution. A short follow-up such as "why?" or "tell me more" has no subject of its own to search on. The plugin detects these and prepends the last substantial message, so the search still finds the right memories. Self-contained messages are searched verbatim, so a clean topic change is never diluted.
• Profile at session start. When profile_warmup is on, a short "who is this user" summary is loaded off-turn and injected once at the start of a session as background context. It is cached across sessions for an hour to avoid repeated calls.
• Capture after each turn. The user and assistant exchange is saved to long-term memory on a background thread.
• Memory mirroring. When the 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_deadline, so a slow or unhealthy backend degrades to no memory for that turn instead of hanging. Capture, mirroring, and profile warm-load run on background threads and never block the reply.

Agent tools

The plugin exposes these tools to the agent:

vity_recall and vity_knowledge are complementary: use recall for a specific fact the user stated, and knowledge for what the user broadly knows about a topic. When Meeting Memory is enabled for the account, an additional vity_meeting_recall tool is offered for questions about meetings, decisions, and attendees.

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.

CLI

Manage memory directly from the terminal:

hermes maximem_vity status                          # config and 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 reactivate the provider, run hermes config set memory.provider maximem_vity. Avoid the interactive hermes memory setup wizard, since buffered or 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