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 and lives in the basic-memory monorepo — browse the source in integrations/hermes.

Installation

git clone https://github.com/basicmachines-co/basic-memory.git
ln -snf "$PWD/basic-memory/integrations/hermes" ~/.hermes/plugins/basic-memory

Install the plugin:

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

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

Using Basic Memory Cloud

By default the plugin runs in local mode and writes to a project on that machine. In cloud mode, tool calls route directly through the Basic Memory Cloud API — no local file mirror, no bisync.

Sign in, then create a cloud-routed project:

bm cloud login
bm project add hermes-memory-cloud
bm project set-cloud hermes-memory-cloud --workspace "My Workspace"

--workspace is required if you belong to more than one; otherwise it resolves the only one available.

Then point the plugin at it in ~/.hermes/basic-memory.json (or run hermes memory setup basic-memory):

{
  "mode": "cloud",
  "project": "hermes-memory-cloud"
}

Restart the gateway and confirm with hermes memory status. Check the routing with bm project list — the project's Route column should read cloud.

  Provider:  basic-memory
  Plugin:    installed ✓
  Status:    available ✓

Configuration

Defaults are reasonable for local use — no configuration required. To override, write ~/.hermes/basic-memory.json or run hermes memory setup basic-memory:

{
  "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 a curated subset of Basic Memory's MCP surface:

Slash Commands

For direct, in-session use without going through the agent:

Bundled Skill

The plugin ships a basic-memory skill — a longer reference doc on top of the short usage guidance the plugin always injects into the agent's context. It covers 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