# Hermes Plugin

> Give Hermes Agent persistent Basic Memory: search-before-answer recall, per-turn capture, end-of-session summaries, agent tools, slash commands, and a bundled skill.

The [hermes-basic-memory](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes) plugin connects Basic Memory to [Hermes Agent](https://github.com/NousResearch/hermes-agent), giving agents a persistent knowledge graph stored as plain Markdown. Hermes ships with no external memory provider by default; this plugin replaces that with a real graph — search-before-answer recall, automatic conversation capture, end-of-session summaries, and a curated set of `bm_*` tools the agent can call directly.
The plugin is open source and lives in the basic-memory monorepo — browse the source in [`integrations/hermes`](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes).

<warning>

**Slash commands may need a Hermes Agent-side patch.** The plugin's agent tools (`bm_*`) and auto-capture work as documented once installed. On affected Hermes Agent releases, the native `/bm-*` **slash commands** don't appear in gateway sessions — a Hermes plugin-loading gap (exclusive memory-provider plugins aren't loaded during gateway slash-command discovery), not a plugin bug. **How to tell if you're affected:** install the plugin, restart the gateway, and type `/bm-` — if no commands autocomplete, apply the Hermes Agent-side patch in [MONKEYPATCH.md](https://github.com/basicmachines-co/basic-memory/blob/main/integrations/hermes/MONKEYPATCH.md) (it also lists affected versions). This affects only the slash-command surface; nothing else on this page depends on it.

</warning>

<tip>

[Hermes Agent](https://github.com/NousResearch/hermes-agent) (see the installation note below — managed install is blocked on every current release) and [`uv`](https://docs.astral.sh/uv/) on your PATH. The plugin auto-installs the `bm` CLI on first init via `uv tool install basic-memory` (a one-time ~10s pause if it isn't already present).

</tip>

---

## Installation

<warning>

**Managed install is currently blocked upstream.** This plugin ships
`manifest_version: 2`, but `hermes plugins install` caps at version 1 on every
released Hermes Agent (latest: v0.20.5 / `v2026.8.19`), so the command fails with
*"requires manifest_version 2, but this installer only supports up to 1."* The fix
is [an open pull request](https://github.com/NousResearch/hermes-agent/pull/85893)
that has not shipped in a release yet, so updating Hermes will not help.

Until it lands, clone the repo and link the plugin in directly — the Hermes
*runtime* loads manifest v2 without trouble; only the installer is capped:

```bash
git clone https://github.com/basicmachines-co/basic-memory.git
ln -snf "$PWD/basic-memory/integrations/hermes" ~/.hermes/plugins/basic-memory
```

</warning>

Install the plugin:

```bash
hermes plugins install basicmachines-co/basic-memory/integrations/hermes
```

Then activate it in `~/.hermes/config.yaml`:

```yaml
memory:
  provider: basic-memory
```

If you run the gateway, restart it:

```bash
hermes gateway restart
```

Verify the plugin is live:

```bash
hermes memory status
```

### Using Basic Memory Cloud

By default the plugin runs in **local** mode and writes to a project on that
machine. In cloud mode, tool calls route directly through the Basic Memory Cloud
API — no local file mirror, no bisync.

Sign in, then create a cloud-routed project:

```bash
bm cloud login
bm project add hermes-memory-cloud
bm project set-cloud hermes-memory-cloud --workspace "My Workspace"
```

`--workspace` is required if you belong to more than one; otherwise it resolves
the only one available.

Then point the plugin at it in `~/.hermes/basic-memory.json` (or run
`hermes memory setup basic-memory`):

```json
{
  "mode": "cloud",
  "project": "hermes-memory-cloud"
}
```

Restart the gateway and confirm with `hermes memory status`. Check the routing
with `bm project list` — the project's **Route** column should read `cloud`.

<note>

In cloud mode the plugin does **not** create the project for you, unlike local
mode. Create it first with the commands above, or initialization fails.

</note>

```text
Provider:  basic-memory
  Plugin:    installed ✓
  Status:    available ✓
```

<note>

The plugin needs the `mcp` Python package in the Hermes venv. `hermes plugins install` usually installs it from the plugin's `pip_dependencies`. If it doesn't, run `uv pip install --python ~/.hermes/hermes-agent/venv/bin/python mcp`.

</note>

---

## Configuration

Defaults are reasonable for local use — no configuration required. To override, write `~/.hermes/basic-memory.json` or run `hermes memory setup basic-memory`:

<table>
<thead>
  <tr>
    <th>
      Key
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        mode
      </code>
    </td>
    
    <td>
      <code>
        local
      </code>
    </td>
    
    <td>
      <code>
        local
      </code>
      
       (in-process) or <code>
        cloud
      </code>
      
       (route through Basic Memory Cloud)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        project
      </code>
    </td>
    
    <td>
      <code>
        hermes-memory
      </code>
    </td>
    
    <td>
      Basic Memory project name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        project_path
      </code>
    </td>
    
    <td>
      <code>
        ~/hermes-memory/
      </code>
    </td>
    
    <td>
      Local mode only — where the project's files live
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capture_per_turn
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Append every user/assistant exchange to a session transcript note
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capture_session_end
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      Write a summary note when the session ends
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capture_folder
      </code>
    </td>
    
    <td>
      <code>
        hermes-sessions
      </code>
    </td>
    
    <td>
      Folder for auto-captured session notes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        remember_folder
      </code>
    </td>
    
    <td>
      <code>
        bm-remember
      </code>
    </td>
    
    <td>
      Folder for <code>
        /bm-remember
      </code>
      
       quick captures (kept separate from session transcripts)
    </td>
  </tr>
</tbody>
</table>

```json
{
  "mode": "local",
  "project": "hermes-memory",
  "project_path": "~/hermes-memory/",
  "capture_per_turn": true,
  "capture_session_end": true,
  "capture_folder": "hermes-sessions",
  "remember_folder": "bm-remember"
}
```

---

## How It Works

### Search-Before-Answer Recall

Before the agent answers a question about prior work, it searches the knowledge graph so it can build on what's already documented instead of starting cold. Recall is injected into context automatically each turn.

### Auto-Capture

Every user/assistant exchange is appended to a running session-transcript note. When the session ends, a separate summary note is written and linked back to the transcript via a `summary_of` relation — so a session is both fully logged and quickly skimmable.

### Persistent Connection

The plugin holds a long-lived `bm mcp` process open over stdio for the agent's lifetime (~0.1s per tool call). Shelling out to the `bm` CLI would spawn a fresh Python process per call (1–2s cold start) and bypass automatic capture — so the agent is steered to use the `bm_*` tools directly.

### Cross-Project & Workspace Routing

Every read/write tool accepts an optional `project` (name, optionally workspace-qualified like `"personal/main"`) or `project_id` (UUID from `bm_projects`). The agent can read or write against any project in your knowledge base without reconfiguring the plugin — and disambiguate same-named projects across cloud workspaces. See [local/cloud routing](/cloud/routing) for how project modes work.

In practice the Hermes agent gets:

- **Its own long-term memory** — auto-captured conversations and summaries that persist across sessions
- **Access to external projects** — search and write notes in any project, routed per call
- **Local/cloud hybrid** — keep the agent's memory local while routing shared projects through Basic Memory Cloud; the tools behave identically either way

---

## Agent Tools

The plugin exposes a curated subset of Basic Memory's MCP surface:

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        bm_search
      </code>
    </td>
    
    <td>
      Semantic + full-text search; the agent calls this before answering
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bm_read
      </code>
    </td>
    
    <td>
      Read a note by title, permalink, or <code>
        memory://
      </code>
      
       URL
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bm_write
      </code>
    </td>
    
    <td>
      Create a note (decisions, meeting notes, insights)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bm_edit
      </code>
    </td>
    
    <td>
      Incremental edits — append, prepend, find/replace, replace-section
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bm_context
      </code>
    </td>
    
    <td>
      Navigate the graph via <code>
        memory://
      </code>
      
       URLs to find related notes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bm_delete
      </code>
    </td>
    
    <td>
      Delete a note
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bm_move
      </code>
    </td>
    
    <td>
      Move a note to a different folder
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bm_recent
      </code>
    </td>
    
    <td>
      List notes updated within a timeframe (default <code>
        7d
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bm_projects
      </code>
    </td>
    
    <td>
      List available projects with their UUIDs for routing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bm_workspaces
      </code>
    </td>
    
    <td>
      List Basic Memory Cloud workspaces
    </td>
  </tr>
</tbody>
</table>

<note>

Every read/write tool also accepts `project` / `project_id` for per-call routing. `bm_projects` and `bm_workspaces` are discovery tools — they list across everything and take no routing arguments.

</note>

---

## Slash Commands

<note>

On affected Hermes Agent releases, these commands require the Hermes Agent-side patch in [MONKEYPATCH.md](https://github.com/basicmachines-co/basic-memory/blob/main/integrations/hermes/MONKEYPATCH.md) — see the warning at the top of this page. The agent tools above are unaffected.

</note>

For direct, in-session use without going through the agent:

<table>
<thead>
  <tr>
    <th>
      Command
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        /bm-search <query>
      </code>
    </td>
    
    <td>
      Search the knowledge graph
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /bm-read <identifier>
      </code>
    </td>
    
    <td>
      Read a note by title, permalink, or <code>
        memory://
      </code>
      
       URL
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /bm-context <identifier>
      </code>
    </td>
    
    <td>
      Show the context graph for a note
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /bm-recent [timeframe]
      </code>
    </td>
    
    <td>
      Recently updated notes (default <code>
        7d
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /bm-status
      </code>
    </td>
    
    <td>
      Plugin/provider status — mode, project, capture flags
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /bm-remember <text>
      </code>
    </td>
    
    <td>
      Quick-capture a note (title from the first line)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /bm-project
      </code>
    </td>
    
    <td>
      List available projects; the active one is marked
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /bm-workspace
      </code>
    </td>
    
    <td>
      List Basic Memory Cloud workspaces (cloud mode)
    </td>
  </tr>
</tbody>
</table>

---

## Bundled Skill

The plugin ships a `basic-memory` skill — a longer reference doc on top of the short usage guidance the plugin always injects into the agent's context. It covers the note format, cross-project routing, permalink shapes, and a worked discovery → route → write → verify recipe. It's opt-in via `skill:view basic-memory:basic-memory`.

---

## Next Steps

<card-group>
<card icon="i-lucide-wrench" title="MCP Tools Reference" to="/reference/mcp-tools-reference">

Full reference for all Basic Memory MCP tools.

</card>

<card icon="i-lucide-cloud" title="Local & Cloud Routing" to="/cloud/routing">

Run some projects locally and others in the cloud.

</card>

<card icon="i-lucide-link" title="Memory URLs" to="/concepts/memory-urls">

How `memory://` addressing and permalinks work.

</card>

<card icon="i-lucide-plug" title="OpenClaw Plugin" to="/integrations/openclaw">

The sibling plugin for OpenClaw agents.

</card>

<card icon="i-lucide-github" title="GitHub Repository" to="https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes">

Source code, issues, and contributing guide.

</card>
</card-group>