From e518e2e65acd1e68a50cf9d5e802d5a6afd8fb13 Mon Sep 17 00:00:00 2001 From: Drew Cain Date: Mon, 18 May 2026 10:06:25 -0500 Subject: [PATCH 1/4] 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) --- content/6.integrations/11.hermes.md | 201 ++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 content/6.integrations/11.hermes.md diff --git a/content/6.integrations/11.hermes.md b/content/6.integrations/11.hermes.md new file mode 100644 index 0000000..3b34ed7 --- /dev/null +++ b/content/6.integrations/11.hermes.md @@ -0,0 +1,201 @@ +--- +title: "Hermes Plugin" +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." +--- + +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. +The plugin is open source — browse the source on [GitHub](https://github.com/basicmachines-co/hermes-basic-memory). + +::tip +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). +:: + +--- + +## Installation + +Install the plugin: + +```bash +hermes plugins install basicmachines-co/hermes-basic-memory +``` + +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 +``` + +```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`. +:: + +--- + +## Configuration + +Defaults are reasonable for local use — no configuration required. To override, write `~/.hermes/basic-memory.json` or run `hermes memory setup basic-memory`: + +| Key | Default | Description | +|--------|---------|-------------| +| `mode` | `local` | `local` (in-process) or `cloud` (route through Basic Memory Cloud) | +| `project` | `hermes-memory` | Basic Memory project name | +| `project_path` | `~/hermes-memory/` | Local mode only — where the project's files live | +| `capture_per_turn` | `true` | Append every user/assistant exchange to a session transcript note | +| `capture_session_end` | `true` | Write a summary note when the session ends | +| `capture_folder` | `hermes-sessions` | Folder for auto-captured session notes | +| `remember_folder` | `bm-remember` | Folder for `/bm-remember` quick captures (kept separate from session transcripts) | + +```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 10 tools (a curated subset of Basic Memory's MCP surface): + +| Tool | Description | +|------|-------------| +| `bm_search` | Semantic + full-text search; the agent calls this before answering | +| `bm_read` | Read a note by title, permalink, or `memory://` URL | +| `bm_write` | Create a note (decisions, meeting notes, insights) | +| `bm_edit` | Incremental edits — append, prepend, find/replace, replace-section | +| `bm_context` | Navigate the graph via `memory://` URLs to find related notes | +| `bm_delete` | Delete a note | +| `bm_move` | Move a note to a different folder | +| `bm_recent` | List notes updated within a timeframe (default `7d`) | +| `bm_projects` | List available projects with their UUIDs for routing | +| `bm_workspaces` | List Basic Memory Cloud workspaces | + +::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. +:: + +--- + +## Slash Commands + +For direct, in-session use without going through the agent: + +| Command | Description | +|---------|-------------| +| `/bm-search ` | Search the knowledge graph | +| `/bm-read ` | Read a note by title, permalink, or `memory://` URL | +| `/bm-context ` | Show the context graph for a note | +| `/bm-recent [timeframe]` | Recently updated notes (default `7d`) | +| `/bm-status` | Plugin/provider status — mode, project, capture flags | +| `/bm-remember ` | Quick-capture a note (title from the first line) | +| `/bm-project` | List available projects; the active one is marked | +| `/bm-workspace` | List Basic Memory Cloud workspaces (cloud mode) | + +--- + +## Bundled Skill + +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`. + +--- + +## Next Steps + +:::card-group +::card +--- +title: MCP Tools Reference +icon: i-lucide-wrench +to: /reference/mcp-tools-reference +--- +Full reference for all Basic Memory MCP tools. +:: + +::card +--- +title: Local & Cloud Routing +icon: i-lucide-cloud +to: /cloud/routing +--- +Run some projects locally and others in the cloud. +:: + +::card +--- +title: Memory URLs +icon: i-lucide-link +to: /concepts/memory-urls +--- +How `memory://` addressing and permalinks work. +:: + +::card +--- +title: OpenClaw Plugin +icon: i-lucide-plug +to: /integrations/openclaw +--- +The sibling plugin for OpenClaw agents. +:: + +::card +--- +title: GitHub Repository +icon: i-lucide-github +to: https://github.com/basicmachines-co/hermes-basic-memory +--- +Source code, issues, and contributing guide. +:: +::: From c894fd369732aeac293a49abe4ce1907329b02b3 Mon Sep 17 00:00:00 2001 From: Drew Cain Date: Mon, 18 May 2026 10:10:37 -0500 Subject: [PATCH 2/4] docs: warn about slash-command monkeypatch on Hermes page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Prominent ::warning after the intro: bm_* agent tools and auto-capture work out of the box, but /bm-* slash commands need a Hermes Agent-side patch (MONKEYPATCH.md) on releases through v0.14.0 / v2026.5.16 — the exclusive memory-provider loader doesn't register commands during gateway slash-command discovery, and the plugin's built-in reach-in isn't sufficient for that startup path. Also adds a short ::note in the Slash Commands section pointing back to the warning, for readers who jump straight there. Co-Authored-By: Claude Opus 4.7 (1M context) --- content/6.integrations/11.hermes.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/6.integrations/11.hermes.md b/content/6.integrations/11.hermes.md index 3b34ed7..73325f0 100644 --- a/content/6.integrations/11.hermes.md +++ b/content/6.integrations/11.hermes.md @@ -6,6 +6,10 @@ description: "Give Hermes Agent persistent Basic Memory: search-before-answer re 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. The plugin is open source — browse the source on [GitHub](https://github.com/basicmachines-co/hermes-basic-memory). +::warning +**Slash commands need a Hermes Agent-side patch on current releases.** The plugin's agent tools (`bm_*`) and auto-capture work as documented once installed. The native `/bm-*` **slash commands**, however, do not appear in gateway sessions on Hermes Agent releases through `v0.14.0` / `v2026.5.16` (verified 2026-05-16). This is a Hermes Agent plugin-loading gap — exclusive memory-provider plugins aren't loaded during gateway slash-command discovery — not a plugin bug. The plugin ships a best-effort workaround, but it isn't sufficient for gateway startup discovery in affected builds. Until the upstream Hermes fix lands, apply the Hermes Agent-side patch documented in [MONKEYPATCH.md](https://github.com/basicmachines-co/hermes-basic-memory/blob/main/MONKEYPATCH.md). This affects only the slash-command surface; nothing else in this page depends on it. +:: + ::tip 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). :: @@ -130,6 +134,10 @@ Every read/write tool also accepts `project` / `project_id` for per-call routing ## Slash Commands +::note +On Hermes Agent releases through `v0.14.0` / `v2026.5.16`, these commands require the Hermes Agent-side patch in [MONKEYPATCH.md](https://github.com/basicmachines-co/hermes-basic-memory/blob/main/MONKEYPATCH.md) — see the warning at the top of this page. The agent tools above are unaffected. +:: + For direct, in-session use without going through the agent: | Command | Description | From 61eb27b55a0150b9a4121ba49f4f8208dab9fd01 Mon Sep 17 00:00:00 2001 From: Drew Cain Date: Mon, 18 May 2026 10:15:18 -0500 Subject: [PATCH 3/4] docs: add Hermes plugin announcement to What's New MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds content/2.whats-new/1.hermes-plugin.md as a short announcement (modeled on the OpenClaw What's New entry) positioned just below v0.20.0. The full integration guide stays at /integrations/hermes; the announcement teases capabilities and links to it — matching how OpenClaw is structured (announcement + guide). Renumbered the existing What's New entries down by one to open the slot below v0.20.0. Numeric prefixes only drive nav order, not URLs, so no links break. Updated the one CLAUDE.md reference that cited the changelog by its old numeric path (2.→3.changelog.md). The announcement carries a brief note about the slash-command Hermes-side patch and points to the full guide's warning for detail. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 2 +- content/2.whats-new/1.hermes-plugin.md | 58 +++++++++++++++++++ .../2.whats-new/{1.cloud.md => 2.cloud.md} | 0 .../{2.changelog.md => 3.changelog.md} | 0 .../{3.agent-skills.md => 4.agent-skills.md} | 0 ...penclaw-plugin.md => 5.openclaw-plugin.md} | 0 ...friendly-docs.md => 6.ai-friendly-docs.md} | 0 7 files changed, 59 insertions(+), 1 deletion(-) create mode 100644 content/2.whats-new/1.hermes-plugin.md rename content/2.whats-new/{1.cloud.md => 2.cloud.md} (100%) rename content/2.whats-new/{2.changelog.md => 3.changelog.md} (100%) rename content/2.whats-new/{3.agent-skills.md => 4.agent-skills.md} (100%) rename content/2.whats-new/{4.openclaw-plugin.md => 5.openclaw-plugin.md} (100%) rename content/2.whats-new/{5.ai-friendly-docs.md => 6.ai-friendly-docs.md} (100%) diff --git a/CLAUDE.md b/CLAUDE.md index ddfd5c4..742ce75 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -176,7 +176,7 @@ When updating docs for a new Basic Memory release, update all of the following: 1. **Homepage version badge** — `content/index.md`: update the version text (e.g., `v0.20 →`) and the `to:` link to point to the new release notes page 2. **Release notes page** — `content/2.whats-new/0.v.md`: rename and update with new release content (the `0.` prefix keeps it first in the nav) -3. **Changelog** — `content/2.whats-new/2.changelog.md` auto-fetches from GitHub releases API, no manual update needed +3. **Changelog** — `content/2.whats-new/3.changelog.md` auto-fetches from GitHub releases API, no manual update needed 4. **Deploy** — push to main auto-deploys to development; production requires manual workflow dispatch via GitHub Actions ## Documentation Status & Priorities diff --git a/content/2.whats-new/1.hermes-plugin.md b/content/2.whats-new/1.hermes-plugin.md new file mode 100644 index 0000000..9b2b12b --- /dev/null +++ b/content/2.whats-new/1.hermes-plugin.md @@ -0,0 +1,58 @@ +--- +title: Hermes Plugin +description: Give Hermes Agent persistent Basic Memory — search-before-answer recall, auto-capture, and 10 agent tools. +--- + +The [hermes-basic-memory](https://github.com/basicmachines-co/hermes-basic-memory) plugin gives [Hermes Agent](https://github.com/NousResearch/hermes-agent) a persistent knowledge graph across sessions. + +[Basic Memory](/start-here/what-is-basic-memory) is a knowledge base that you and your AI share. Hermes ships with no external memory provider by default — this plugin replaces that with a real graph your agent reads from and writes to as plain Markdown. + +## Key Capabilities + +- **Search before answering** — The agent recalls prior decisions and context before responding, instead of starting cold +- **Automatic capture** — Every exchange is logged to a session transcript; an end-of-session summary is written and linked back +- **10 agent tools** — search, read, write, edit, context, delete, move, recent, projects, workspaces +- **8 slash commands** — `/bm-search`, `/bm-read`, `/bm-context`, `/bm-recent`, `/bm-status`, `/bm-remember`, `/bm-project`, `/bm-workspace` +- **Cross-project & workspace routing** — Read or write any project per call via `project` / `project_id`, with transparent local/cloud routing +- **Bundled skill** — A `basic-memory` skill teaching the note format, routing, and a worked discovery → write → verify recipe + +## Quick Install + +```bash +hermes plugins install basicmachines-co/hermes-basic-memory +``` + +Activate it in `~/.hermes/config.yaml`: + +```yaml +memory: + provider: basic-memory +``` + +Restart the gateway (`hermes gateway restart`) and verify with `hermes memory status`. + +::note +The agent tools and auto-capture work out of the box. The native `/bm-*` slash commands need a Hermes Agent-side patch on releases through `v0.14.0` / `v2026.5.16` — see the warning in the full guide. +:: + +## Next Steps + +:::card-group +::card +--- +title: Hermes Plugin Guide +icon: i-lucide-puzzle +to: /integrations/hermes +--- +Full guide with configuration, tool reference, slash commands, and the slash-command patch. +:: + +::card +--- +title: GitHub Repository +icon: i-lucide-github +to: https://github.com/basicmachines-co/hermes-basic-memory +--- +Source code, issues, and contributing guide. +:: +::: diff --git a/content/2.whats-new/1.cloud.md b/content/2.whats-new/2.cloud.md similarity index 100% rename from content/2.whats-new/1.cloud.md rename to content/2.whats-new/2.cloud.md diff --git a/content/2.whats-new/2.changelog.md b/content/2.whats-new/3.changelog.md similarity index 100% rename from content/2.whats-new/2.changelog.md rename to content/2.whats-new/3.changelog.md diff --git a/content/2.whats-new/3.agent-skills.md b/content/2.whats-new/4.agent-skills.md similarity index 100% rename from content/2.whats-new/3.agent-skills.md rename to content/2.whats-new/4.agent-skills.md diff --git a/content/2.whats-new/4.openclaw-plugin.md b/content/2.whats-new/5.openclaw-plugin.md similarity index 100% rename from content/2.whats-new/4.openclaw-plugin.md rename to content/2.whats-new/5.openclaw-plugin.md diff --git a/content/2.whats-new/5.ai-friendly-docs.md b/content/2.whats-new/6.ai-friendly-docs.md similarity index 100% rename from content/2.whats-new/5.ai-friendly-docs.md rename to content/2.whats-new/6.ai-friendly-docs.md From 95d0e5e54a9a5d4af8a45881a5ae2eec6e565270 Mon Sep 17 00:00:00 2001 From: Drew Cain Date: Mon, 18 May 2026 10:22:48 -0500 Subject: [PATCH 4/4] docs: prominent full-guide link on plugin announcements Both the Hermes and OpenClaw What's New announcements only linked to their full integration guides via a Next Steps card at the bottom. Add a ::tip callout right after the intro so the path to the full guide is visible immediately, not just after scrolling past all the capabilities. Bottom card-group link stays for end-of-page context. Used ::tip (proven on these pages) rather than :::u-button, which is only used in index.md's hero slots and unverified in regular content bodies. Co-Authored-By: Claude Opus 4.7 (1M context) --- content/2.whats-new/1.hermes-plugin.md | 4 ++++ content/2.whats-new/5.openclaw-plugin.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/content/2.whats-new/1.hermes-plugin.md b/content/2.whats-new/1.hermes-plugin.md index 9b2b12b..775f939 100644 --- a/content/2.whats-new/1.hermes-plugin.md +++ b/content/2.whats-new/1.hermes-plugin.md @@ -7,6 +7,10 @@ The [hermes-basic-memory](https://github.com/basicmachines-co/hermes-basic-memor [Basic Memory](/start-here/what-is-basic-memory) is a knowledge base that you and your AI share. Hermes ships with no external memory provider by default — this plugin replaces that with a real graph your agent reads from and writes to as plain Markdown. +::tip +**[Read the full Hermes Plugin guide →](/integrations/hermes)** — installation, configuration, the complete tool reference, slash commands, and the slash-command patch. +:: + ## Key Capabilities - **Search before answering** — The agent recalls prior decisions and context before responding, instead of starting cold diff --git a/content/2.whats-new/5.openclaw-plugin.md b/content/2.whats-new/5.openclaw-plugin.md index cb4674d..31cec03 100644 --- a/content/2.whats-new/5.openclaw-plugin.md +++ b/content/2.whats-new/5.openclaw-plugin.md @@ -7,6 +7,10 @@ The [openclaw-basic-memory](https://github.com/basicmachines-co/openclaw-basic-m [Basic Memory](/start-here/what-is-basic-memory) is a knowledge base that you and your AI share. This plugin connects it to OpenClaw so your agent remembers past conversations, decisions, and context. +::tip +**[Read the full OpenClaw Plugin guide →](/integrations/openclaw)** — configuration options, the complete tool reference, slash commands, and bundled skills. +:: + ## Key Capabilities - **Search across everything** — Searches your notes, knowledge graph, and active tasks at once