This repo has been moved to a monorepo under basic-memory

https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes

Hermes Memory Provider plugin that gives Hermes Agent a persistent knowledge graph backed by Basic Memory.

The plugin replaces Hermes's "no external memory provider" with a real graph: search-before-answer recall, per-turn capture, end-of-session summaries, and ten bm_* tools the agent can call directly. Local mode by default; one CLI flip switches to true cloud routing through Basic Memory Cloud.

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). Done.

The plugin self-installs the basic-memory CLI on first init via uv tool install basic-memory (one-time ~10s pause if it isn't already present). The bm binary lands at ~/.local/bin/bm — the same location a manual uv tool install basic-memory would produce, so a later manual install or upgrade is a no-op rather than a second install.

• Hermes Agent
• uv on PATH (used for the bootstrap install)
• The mcp Python package in the Hermes venv. If hermes plugins install doesn't auto-install it (it follows pip_dependencies in plugin.yaml), run:

  uv pip install --python ~/.hermes/hermes-agent/venv/bin/python mcp

hermes memory status

Expected:

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

Ten tools (curated subset of Basic Memory's MCP surface):

Every read/write tool also accepts optional project / project_id for per-call routing — write or read against a project other than the configured one without reconfiguring the plugin.

Plus automatic capture:

• Per turn: every user/assistant exchange appends to a running session-transcript note
• End of session: a separate summary note is written, linked back to the transcript via a summary_of relation

A bundled skill (skill:view basic-memory:basic-memory) gives the agent a longer reference doc on top of the always-on system_prompt_block.

For direct, in-session use without going through the agent (requires Hermes ≥ v0.11.0):

Examples:

/bm-search Q3 OKRs
/bm-read decisions/auth-rewrite
/bm-recent yesterday
/bm-remember Reminder: switch the staging job to the new image after the rebase lands.

/bm-project and /bm-workspace are read-only in 0.2.0 — mid-session switching is intentionally not supported because auto-capture would otherwise land in the wrong place. Tracked as a follow-up.

Plugin v0.2.0 and later register the commands above, but some Hermes Agent gateway builds do not discover slash commands contributed by an exclusive memory-provider plugin during startup. The symptoms are:

• the memory tools work for the agent (bm_search, bm_read, etc.);
• hermes memory status shows Provider: basic-memory and Status: available; but
• Discord/native slash command pickers do not show /bm-search, /bm-read, /bm-context, and the other /bm-* commands after hermes gateway restart.

This is a Hermes Agent plugin-discovery issue, not a Basic Memory runtime issue. It is tracked upstream in NousResearch/hermes-agent#23603. Updating the Basic Memory plugin alone cannot fix affected gateway startup discovery; Hermes Agent itself must include or receive the compatibility patch. Until the upstream Hermes fix is available in your installed Hermes version, use one of these workarounds:

1. apply the Hermes Agent-side patch described in MONKEYPATCH.md, which includes compatibility notes for Hermes Agent v0.13.x and v0.14.0; or
2. use the agent tools directly (bm_search, bm_read, bm_recent, etc.) instead of native slash commands.

After applying an updated or patched Hermes build, restart the gateway so Discord/native slash commands are re-synced:

hermes gateway restart

If Discord still does not show the commands immediately, type /bm directly or reload the Discord client; global command propagation can lag briefly.

Defaults are reasonable for local use:

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"
}

In local mode the plugin auto-creates the BM project on first init via bm project add. In cloud mode it doesn't — you create the cloud-routed project yourself (see below) and the plugin verifies it's registered before initializing.

When mode: cloud, tool calls route directly through the BM cloud API — no local file mirror, no bisync. You set this up once with the BM CLI:

# Authenticate (OAuth) or save an API key
bm cloud login                     # OAuth — interactive
# OR for headless/automation:
bm cloud create-key "hermes"
bm cloud set-key bmc_...

# Create the project, then flip it to cloud routing.
# --workspace is required if you belong to more than one workspace
# (otherwise BM auto-resolves the only one available).
bm project add hermes-memory-cloud
bm project set-cloud hermes-memory-cloud --workspace Personal

# Point the plugin at it
cat > ~/.hermes/basic-memory.json <<EOF
{
  "mode": "cloud",
  "project": "hermes-memory-cloud",
  "capture_per_turn": true,
  "capture_session_end": true,
  "capture_folder": "hermes-sessions"
}
EOF

hermes gateway restart

Tool calls now route from bm mcp → <cloud_host>/proxy over HTTPS using your OAuth token (or API key). Notes never touch local disk.

Don't confuse cloud mode with bm cloud bisync. Bisync is rclone-style two-way file sync between a local project and cloud storage, intended for keeping local working copies. For agent-driven capture you want true cloud routing (set-cloud), not bisync.

hermes plugins update basic-memory
hermes plugins remove basic-memory     # then revert memory.provider in config.yaml

• <memory-context> tags in notes: Hermes's streaming output scrubber strips literal <memory-context>...</memory-context> blocks from assistant text. If a note contains those tags and the assistant echoes the body verbatim, the echoed copy gets eaten mid-stream. Tool results inbound are unaffected. Avoid those tags in BM notes; if you must include them, fence in a code block.
• Single external provider: Hermes accepts only one external memory provider at a time. Activating basic-memory displaces any other.
• CLI cold start: hermes -z ... invocations spawn bm mcp per run (~2-5s). Long-running gateway sessions amortize this.
• Multiple cloud workspaces: if your BM Cloud account belongs to more than one workspace, bm project set-cloud must be invoked with --workspace <name>. Otherwise tool calls fail with "Multiple workspaces are available".

The plugin is a single-file Python module at __init__.py. The Hermes plugin loader expects register(ctx) and grep-detects either register_memory_provider or MemoryProvider in the file.

For local development (point Hermes at your working tree instead of going through hermes plugins install):

git clone https://github.com/basicmachines-co/hermes-basic-memory ~/code/hermes-basic-memory
mkdir -p ~/.hermes/plugins
ln -snf ~/code/hermes-basic-memory ~/.hermes/plugins/basic-memory

# Unit tests (fast, hermetic — no Hermes or bm required)
uv run --with pytest pytest

# Integration tests (gated — exercise every tool against a real bm MCP server)
BM_INTEGRATION=1 uv run --with pytest --with mcp pytest tests/test_integration.py

The unit suite stubs out Hermes-internal imports (agent.memory_provider, tools.registry) so it runs without a Hermes install. mcp is optional at unit-test time — its absence just makes is_available() return False, which the tests verify.

Integration tests require BM_INTEGRATION=1, bm CLI on PATH, and mcp Python package importable. Each session creates a unique throwaway BM project (under tempfile.mkdtemp) and removes it on teardown, so they never touch your real BM projects.

AGPL-3.0-or-later, matching basic-memory. See LICENSE.