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..775f939 --- /dev/null +++ b/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. +:: +::: 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 91% rename from content/2.whats-new/4.openclaw-plugin.md rename to content/2.whats-new/5.openclaw-plugin.md index cb4674d..31cec03 100644 --- a/content/2.whats-new/4.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 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 diff --git a/content/6.integrations/11.hermes.md b/content/6.integrations/11.hermes.md new file mode 100644 index 0000000..73325f0 --- /dev/null +++ b/content/6.integrations/11.hermes.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 ` | 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. +:: +:::