Hermes Plugin
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.
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.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 ✓
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 |
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
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.