> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maximem.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent

> Persistent, cross-session semantic memory for the Hermes Agent, distributed as a standalone plugin.

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](https://github.com/NousResearch/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.

<Note>
  Built on the [`maximem-vity-sdk`](https://pypi.org/project/maximem-vity-sdk/) Python client. The plugin and its dependencies install into Hermes' own Python environment.
</Note>

## 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.

1. Sign up or log in at [app.maximem.ai](https://app.maximem.ai).
2. Open **API Keys** in the sidebar.
3. Click **Generate New Key**.
4. Copy your key (starts with `mx_...`).

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

## Installation

```bash theme={null}
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`.

<Note>
  Already had Hermes (or the gateway) running during install? Restart it to load the newly-activated provider — gateway users run `hermes gateway restart`.
</Note>

### Non-interactive installs

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

```bash theme={null}
hermes-maximem-vity install --api-key mx_your_key
```

<Accordion title="Hitting a PEP-668 &#x22;externally-managed-environment&#x22; or &#x22;pip: command not found&#x22; error?">
  System Python (e.g. Homebrew) blocks global `pip install`. Use **pipx** (recommended) or a virtual environment:

  ```bash theme={null}
  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.
</Accordion>

### Verify installation

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

1. **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.
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.

<Note>
  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.
</Note>

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.

```bash theme={null}
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
```

<Tip>
  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.
</Tip>

## Troubleshooting

### "API key not found" error

Confirm the key and connection:

```bash theme={null}
hermes maximem_vity status
```

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

```bash theme={null}
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:

```bash theme={null}
hermes-maximem-vity install
hermes-maximem-vity status     # confirm: SDK available to Hermes ✓
```

### 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:**

   ```bash theme={null}
   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:

```bash theme={null}
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:

```powershell theme={null}
$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](https://docs.maximem.ai/vity)
* **API keys**: [app.maximem.ai/api-keys](https://app.maximem.ai/api-keys)
* **Email**: [support@maximem.ai](mailto:support@maximem.ai)
* **Twitter / X**: [@MaximemAI](https://twitter.com/maximem_ai)