Skip to content

Commit a5e813b

Browse files
groksrcclaude
groksrc
and
claude
committed
docs: add Hermes plugin integration page
Documents the hermes-basic-memory plugin: install + config.yaml activation, the ~/.hermes/basic-memory.json config keys, the 10 bm_* agent tools, 8 /bm-* slash commands, cross-project/workspace routing, auto-capture behavior, and the bundled skill. Modeled on the existing OpenClaw integration page (the sibling plugin). Slots in as 11.hermes.md after 10.openclaw.md; nav is auto-generated from the numbered prefix so no .navigation.yml change is needed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 48e992c commit a5e813b

1 file changed

Lines changed: 201 additions & 0 deletions

File tree

‎content/6.integrations/11.hermes.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
---
2+
title: "Hermes Plugin"
3+
description: "Give Hermes Agent persistent Basic Memory: search-before-answer recall, per-turn capture, end-of-session summaries, 10 agent tools, slash commands, and a bundled skill."
4+
---
5+
6+
The [hermes-basic-memory](https://github.com/basicmachines-co/hermes-basic-memory) 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.
7+
The plugin is open source — browse the source on [GitHub](https://github.com/basicmachines-co/hermes-basic-memory).
8+
9+
::tip
10+
Requires [Hermes Agent](https://github.com/NousResearch/hermes-agent) 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).
11+
::
12+
13+
---
14+
15+
## Installation
16+
17+
Install the plugin:
18+
19+
```bash
20+
hermes plugins install basicmachines-co/hermes-basic-memory
21+
```
22+
23+
Then activate it in `~/.hermes/config.yaml`:
24+
25+
```yaml
26+
memory:
27+
provider: basic-memory
28+
```
29+
30+
If you run the gateway, restart it:
31+
32+
```bash
33+
hermes gateway restart
34+
```
35+
36+
Verify the plugin is live:
37+
38+
```bash
39+
hermes memory status
40+
```
41+
42+
```text
43+
Provider: basic-memory
44+
Plugin: installed ✓
45+
Status: available ✓
46+
```
47+
48+
::note
49+
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`.
50+
::
51+
52+
---
53+
54+
## Configuration
55+
56+
Defaults are reasonable for local use — no configuration required. To override, write `~/.hermes/basic-memory.json` or run `hermes memory setup basic-memory`:
57+
58+
| Key | Default | Description |
59+
|--------|---------|-------------|
60+
| `mode` | `local` | `local` (in-process) or `cloud` (route through Basic Memory Cloud) |
61+
| `project` | `hermes-memory` | Basic Memory project name |
62+
| `project_path` | `~/hermes-memory/` | Local mode only — where the project's files live |
63+
| `capture_per_turn` | `true` | Append every user/assistant exchange to a session transcript note |
64+
| `capture_session_end` | `true` | Write a summary note when the session ends |
65+
| `capture_folder` | `hermes-sessions` | Folder for auto-captured session notes |
66+
| `remember_folder` | `bm-remember` | Folder for `/bm-remember` quick captures (kept separate from session transcripts) |
67+
68+
```json
69+
{
70+
"mode": "local",
71+
"project": "hermes-memory",
72+
"project_path": "~/hermes-memory/",
73+
"capture_per_turn": true,
74+
"capture_session_end": true,
75+
"capture_folder": "hermes-sessions",
76+
"remember_folder": "bm-remember"
77+
}
78+
```
79+
80+
---
81+
82+
## How It Works
83+
84+
### Search-Before-Answer Recall
85+
86+
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.
87+
88+
### Auto-Capture
89+
90+
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.
91+
92+
### Persistent Connection
93+
94+
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.
95+
96+
### Cross-Project & Workspace Routing
97+
98+
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.
99+
100+
In practice the Hermes agent gets:
101+
102+
- **Its own long-term memory** — auto-captured conversations and summaries that persist across sessions
103+
- **Access to external projects** — search and write notes in any project, routed per call
104+
- **Local/cloud hybrid** — keep the agent's memory local while routing shared projects through Basic Memory Cloud; the tools behave identically either way
105+
106+
---
107+
108+
## Agent Tools
109+
110+
The plugin exposes 10 tools (a curated subset of Basic Memory's MCP surface):
111+
112+
| Tool | Description |
113+
|------|-------------|
114+
| `bm_search` | Semantic + full-text search; the agent calls this before answering |
115+
| `bm_read` | Read a note by title, permalink, or `memory://` URL |
116+
| `bm_write` | Create a note (decisions, meeting notes, insights) |
117+
| `bm_edit` | Incremental edits — append, prepend, find/replace, replace-section |
118+
| `bm_context` | Navigate the graph via `memory://` URLs to find related notes |
119+
| `bm_delete` | Delete a note |
120+
| `bm_move` | Move a note to a different folder |
121+
| `bm_recent` | List notes updated within a timeframe (default `7d`) |
122+
| `bm_projects` | List available projects with their UUIDs for routing |
123+
| `bm_workspaces` | List Basic Memory Cloud workspaces |
124+
125+
::note
126+
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.
127+
::
128+
129+
---
130+
131+
## Slash Commands
132+
133+
For direct, in-session use without going through the agent:
134+
135+
| Command | Description |
136+
|---------|-------------|
137+
| `/bm-search <query>` | Search the knowledge graph |
138+
| `/bm-read <identifier>` | Read a note by title, permalink, or `memory://` URL |
139+
| `/bm-context <identifier>` | Show the context graph for a note |
140+
| `/bm-recent [timeframe]` | Recently updated notes (default `7d`) |
141+
| `/bm-status` | Plugin/provider status — mode, project, capture flags |
142+
| `/bm-remember <text>` | Quick-capture a note (title from the first line) |
143+
| `/bm-project` | List available projects; the active one is marked |
144+
| `/bm-workspace` | List Basic Memory Cloud workspaces (cloud mode) |
145+
146+
---
147+
148+
## Bundled Skill
149+
150+
The plugin ships a `basic-memory` skill that gives the agent a longer reference doc on top of the always-on guidance: 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`.
151+
152+
---
153+
154+
## Next Steps
155+
156+
:::card-group
157+
::card
158+
---
159+
title: MCP Tools Reference
160+
icon: i-lucide-wrench
161+
to: /reference/mcp-tools-reference
162+
---
163+
Full reference for all Basic Memory MCP tools.
164+
::
165+
166+
::card
167+
---
168+
title: Local & Cloud Routing
169+
icon: i-lucide-cloud
170+
to: /cloud/routing
171+
---
172+
Run some projects locally and others in the cloud.
173+
::
174+
175+
::card
176+
---
177+
title: Memory URLs
178+
icon: i-lucide-link
179+
to: /concepts/memory-urls
180+
---
181+
How `memory://` addressing and permalinks work.
182+
::
183+
184+
::card
185+
---
186+
title: OpenClaw Plugin
187+
icon: i-lucide-plug
188+
to: /integrations/openclaw
189+
---
190+
The sibling plugin for OpenClaw agents.
191+
::
192+
193+
::card
194+
---
195+
title: GitHub Repository
196+
icon: i-lucide-github
197+
to: https://github.com/basicmachines-co/hermes-basic-memory
198+
---
199+
Source code, issues, and contributing guide.
200+
::
201+
:::

0 commit comments

Comments
 (0)