docs: add Hermes plugin integration page (#18)

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

* docs: warn about slash-command monkeypatch on Hermes page

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) <noreply@anthropic.com>

* docs: add Hermes plugin announcement to What's New

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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: groksrc

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

content/2.whats-new/1.hermes-plugin.md

@@ -0,0 +1,62 @@
+---
+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.
+
+::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
+- **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.
+::
+:::

content/2.whats-new/1.cloud.md content/2.whats-new/2.cloud.mdcontent/2.whats-new/1.cloud.md renamed to content/2.whats-new/2.cloud.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

content/2.whats-new/2.changelog.md content/2.whats-new/3.changelog.mdcontent/2.whats-new/2.changelog.md renamed to content/2.whats-new/3.changelog.md

@@ -0,0 +1,209 @@
+---
+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).
+
+::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).
+::
+
+---
+
+## 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
+
+::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 |
+|---------|-------------|
+| `/bm-search <query>` | Search the knowledge graph |
+| `/bm-read <identifier>` | Read a note by title, permalink, or `memory://` URL |
+| `/bm-context <identifier>` | 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 <text>` | 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.
+::
+:::