Skip to content

11.hermes.md

Latest commit

 

History

History
209 lines (157 loc) · 8.4 KB

11.hermes.md

File metadata and controls

209 lines (157 loc) · 8.4 KB
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 plugin connects Basic Memory to 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.

::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. This affects only the slash-command surface; nothing else in this page depends on it. ::

::tip Requires Hermes Agent and 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:

hermes plugins install basicmachines-co/hermes-basic-memory

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

memory:
  provider: basic-memory

If you run the gateway, restart it:

hermes gateway restart

Verify the plugin is live:

hermes memory status
  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) 
{
  "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 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 — 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. :: :::