mirror of
https://github.com/basicmachines-co/basic-memory
synced 2026-06-21 13:47:35 +00:00
phernandez
236 lines
11 KiB
Markdown
236 lines
11 KiB
Markdown
# hermes-basic-memory
|
|
|
|
[](https://www.gnu.org/licenses/agpl-3.0)
|
|
|
|
Hermes Memory Provider plugin that gives [Hermes Agent](https://github.com/NousResearch/hermes-agent) a persistent knowledge graph backed by [Basic Memory](https://github.com/basicmachines-co/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.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
hermes plugins install basicmachines-co/basic-memory --path integrations/hermes
|
|
```
|
|
|
|
Then activate it in `~/.hermes/config.yaml`:
|
|
|
|
```yaml
|
|
memory:
|
|
provider: basic-memory
|
|
```
|
|
|
|
If you run the gateway, restart it (`hermes gateway restart`). Done.
|
|
|
|
If your installed Hermes build does not support `--path`, use the final deprecated `basicmachines-co/hermes-basic-memory` pointer release until Hermes subpath installs are available. Ongoing development now lives in [`basic-memory/integrations/hermes`](https://github.com/basicmachines-co/basic-memory/tree/main/integrations/hermes).
|
|
|
|
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.
|
|
|
|
### Prerequisites
|
|
|
|
- [Hermes Agent](https://github.com/NousResearch/hermes-agent)
|
|
- [`uv`](https://docs.astral.sh/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:
|
|
```bash
|
|
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python mcp
|
|
```
|
|
|
|
### Verify
|
|
|
|
```bash
|
|
hermes memory status
|
|
```
|
|
|
|
Expected:
|
|
```
|
|
Provider: basic-memory
|
|
Plugin: installed ✓
|
|
Status: available ✓
|
|
```
|
|
|
|
## What the agent gets
|
|
|
|
Ten tools (curated subset of Basic Memory's MCP surface):
|
|
|
|
| Tool | Use |
|
|
|---|---|
|
|
| `bm_search` | Semantic + full-text search; **call this before answering** |
|
|
| `bm_read` | Fetch a note by title, permalink, or `memory://` URL |
|
|
| `bm_write` | Create a new note (capture decisions, meeting notes, insights) |
|
|
| `bm_edit` | Append, prepend, find/replace, replace-section |
|
|
| `bm_context` | Navigate 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 recently (default `7d`; accepts natural-language timeframes) |
|
|
| `bm_projects` | List available projects with their UUIDs (for cross-project routing) |
|
|
| `bm_workspaces` | List Basic Memory Cloud workspaces |
|
|
|
|
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`.
|
|
|
|
## Slash commands
|
|
|
|
For direct, in-session use without going through the agent (requires Hermes ≥ v0.11.0):
|
|
|
|
| Command | Use |
|
|
|---|---|
|
|
| `/bm-search <query>` | Search the knowledge graph; returns compact title/permalink/preview rows. |
|
|
| `/bm-read <identifier>` | Read a note by title, permalink, or `memory://` URL. |
|
|
| `/bm-context <identifier>` | Build context for a note (target + related). |
|
|
| `/bm-recent [timeframe]` | Recently updated notes. Default `7d`; accepts `"2 weeks"`, `"yesterday"`, etc. |
|
|
| `/bm-status` | Plugin/provider state: mode, project, capture flags, bm CLI path. |
|
|
| `/bm-remember <text>` | Capture a quick note. Title = first line (≤80 chars), folder = `remember_folder` (default `bm-remember`), tagged `manual-capture`. |
|
|
| `/bm-project` | List all known projects; the active one is marked. |
|
|
| `/bm-workspace` | List BM Cloud workspaces. Cloud mode only — prints an explanatory line in local mode. |
|
|
|
|
Examples:
|
|
|
|
```text
|
|
/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.
|
|
|
|
### Known issue: `/bm-*` commands may not appear in some Hermes gateway builds
|
|
|
|
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](https://github.com/NousResearch/hermes-agent/issues/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](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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Configuration
|
|
|
|
Defaults are reasonable for local use:
|
|
|
|
| Key | Default | Notes |
|
|
|---|---|---|
|
|
| `mode` | `local` | `local` (in-process) or `cloud` (route through BM Cloud API) |
|
|
| `project` | `hermes-memory` | BM project name |
|
|
| `project_path` | `~/hermes-memory/` | Local mode only — where session notes land |
|
|
| `capture_folder` | `hermes-sessions` | Folder within the project for session notes |
|
|
| `capture_per_turn` | `true` | Append every turn to a session transcript |
|
|
| `capture_session_end` | `true` | Write a summary note when the session ends |
|
|
| `remember_folder` | `bm-remember` | Folder where `/bm-remember` captures land (kept separate from session transcripts) |
|
|
|
|
To override, write `~/.hermes/basic-memory.json` or run `hermes memory setup basic-memory`:
|
|
|
|
```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"
|
|
}
|
|
```
|
|
|
|
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.
|
|
|
|
### Cloud mode
|
|
|
|
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:
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
## Updating / removing
|
|
|
|
```bash
|
|
hermes plugins update basic-memory
|
|
hermes plugins remove basic-memory # then revert memory.provider in config.yaml
|
|
```
|
|
|
|
## Foot-guns
|
|
|
|
- **`<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".
|
|
|
|
## Development
|
|
|
|
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`):
|
|
|
|
```bash
|
|
git clone https://github.com/basicmachines-co/basic-memory ~/code/basic-memory
|
|
mkdir -p ~/.hermes/plugins
|
|
ln -snf ~/code/basic-memory/integrations/hermes ~/.hermes/plugins/basic-memory
|
|
```
|
|
|
|
### Running tests
|
|
|
|
```bash
|
|
# From the monorepo root
|
|
just package-check-hermes
|
|
|
|
# Or from integrations/hermes
|
|
just check
|
|
|
|
# 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.
|
|
|
|
## License
|
|
|
|
AGPL-3.0-or-later, matching [basic-memory](https://github.com/basicmachines-co/basic-memory). See [LICENSE](LICENSE).
|