{"id":49754936,"url":"https://github.com/basicmachines-co/hermes-basic-memory","last_synced_at":"2026-05-10T19:58:02.496Z","repository":{"id":356972632,"uuid":"1234749543","full_name":"basicmachines-co/hermes-basic-memory","owner":"basicmachines-co","description":"Hermes Memory Provider plugin backed by Basic Memory","archived":false,"fork":false,"pushed_at":"2026-05-10T17:47:03.000Z","size":89,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-10T19:57:33.116Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/basicmachines-co/basic-memory","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/basicmachines-co.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-10T15:39:13.000Z","updated_at":"2026-05-10T17:47:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/basicmachines-co/hermes-basic-memory","commit_stats":null,"previous_names":["basicmachines-co/hermes-basic-memory"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/basicmachines-co/hermes-basic-memory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fhermes-basic-memory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fhermes-basic-memory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fhermes-basic-memory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fhermes-basic-memory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basicmachines-co","download_url":"https://codeload.github.com/basicmachines-co/hermes-basic-memory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fhermes-basic-memory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32869721,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"ssl_error","status_checked_at":"2026-05-10T13:40:02.145Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-10T19:58:01.911Z","updated_at":"2026-05-10T19:58:02.488Z","avatar_url":"https://github.com/basicmachines-co.png","language":"Python","funding_links":[],"categories":["Skills, Plugins, and Extensions"],"sub_categories":["Plugins and add-ons"],"readme":"# hermes-basic-memory\n\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n\nHermes 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).\n\nThe plugin replaces Hermes's \"no external memory provider\" with a real graph: search-before-answer recall, per-turn capture, end-of-session summaries, and seven `bm_*` tools the agent can call directly. Local mode by default; one CLI flip switches to true cloud routing through Basic Memory Cloud.\n\n## Install\n\n```bash\nhermes plugins install basicmachines-co/hermes-basic-memory\n```\n\nThen activate it in `~/.hermes/config.yaml`:\n\n```yaml\nmemory:\n  provider: basic-memory\n```\n\nIf you run the gateway, restart it (`hermes gateway restart`). Done.\n\nThe 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.\n\n### Prerequisites\n\n- [Hermes Agent](https://github.com/NousResearch/hermes-agent)\n- [`uv`](https://docs.astral.sh/uv/) on PATH (used for the bootstrap install)\n- 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:\n  ```bash\n  uv pip install --python ~/.hermes/hermes-agent/venv/bin/python mcp\n  ```\n\n### Verify\n\n```bash\nhermes memory status\n```\n\nExpected:\n```\n  Provider:  basic-memory\n  Plugin:    installed ✓\n  Status:    available ✓\n```\n\n## What the agent gets\n\nSeven tools (curated subset of Basic Memory's MCP surface):\n\n| Tool | Use |\n|---|---|\n| `bm_search` | Semantic + full-text search; **call this before answering** |\n| `bm_read` | Fetch a note by title, permalink, or `memory://` URL |\n| `bm_write` | Create a new note (capture decisions, meeting notes, insights) |\n| `bm_edit` | Append, prepend, find/replace, replace-section |\n| `bm_context` | Navigate via `memory://` URLs to find related notes |\n| `bm_delete` | Delete a note |\n| `bm_move` | Move a note to a different folder |\n\nPlus automatic capture:\n- **Per turn**: every user/assistant exchange appends to a running session-transcript note\n- **End of session**: a separate summary note is written, linked back to the transcript via a `summary_of` relation\n\nA bundled skill (`skill:view basic-memory:basic-memory`) gives the agent a longer reference doc on top of the always-on `system_prompt_block`.\n\n## Configuration\n\nDefaults are reasonable for local use:\n\n| Key | Default | Notes |\n|---|---|---|\n| `mode` | `local` | `local` (in-process) or `cloud` (route through BM Cloud API) |\n| `project` | `hermes-memory` | BM project name |\n| `project_path` | `~/hermes-memory/` | Local mode only — where session notes land |\n| `capture_folder` | `hermes-sessions` | Folder within the project for session notes |\n| `capture_per_turn` | `true` | Append every turn to a session transcript |\n| `capture_session_end` | `true` | Write a summary note when the session ends |\n\nTo override, write `~/.hermes/basic-memory.json` or run `hermes memory setup basic-memory`:\n\n```json\n{\n  \"mode\": \"local\",\n  \"project\": \"hermes-memory\",\n  \"project_path\": \"~/hermes-memory/\",\n  \"capture_per_turn\": true,\n  \"capture_session_end\": true,\n  \"capture_folder\": \"hermes-sessions\"\n}\n```\n\nIn 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.\n\n### Cloud mode\n\nWhen `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:\n\n```bash\n# Authenticate (OAuth) or save an API key\nbm cloud login                     # OAuth — interactive\n# OR for headless/automation:\nbm cloud create-key \"hermes\"\nbm cloud set-key bmc_...\n\n# Create the project, then flip it to cloud routing.\n# --workspace is required if you belong to more than one workspace\n# (otherwise BM auto-resolves the only one available).\nbm project add hermes-memory-cloud\nbm project set-cloud hermes-memory-cloud --workspace Personal\n\n# Point the plugin at it\ncat \u003e ~/.hermes/basic-memory.json \u003c\u003cEOF\n{\n  \"mode\": \"cloud\",\n  \"project\": \"hermes-memory-cloud\",\n  \"capture_per_turn\": true,\n  \"capture_session_end\": true,\n  \"capture_folder\": \"hermes-sessions\"\n}\nEOF\n\nhermes gateway restart\n```\n\nTool calls now route from `bm mcp` → `\u003ccloud_host\u003e/proxy` over HTTPS using your OAuth token (or API key). Notes never touch local disk.\n\n**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.\n\n## Updating / removing\n\n```bash\nhermes plugins update basic-memory\nhermes plugins remove basic-memory     # then revert memory.provider in config.yaml\n```\n\n## Foot-guns\n\n- **`\u003cmemory-context\u003e` tags in notes**: Hermes's streaming output scrubber strips literal `\u003cmemory-context\u003e...\u003c/memory-context\u003e` 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.\n- **Single external provider**: Hermes accepts only one external memory provider at a time. Activating basic-memory displaces any other.\n- **CLI cold start**: `hermes -z ...` invocations spawn `bm mcp` per run (~2-5s). Long-running gateway sessions amortize this.\n- **Multiple cloud workspaces**: if your BM Cloud account belongs to more than one workspace, `bm project set-cloud` must be invoked with `--workspace \u003cname\u003e`. Otherwise tool calls fail with \"Multiple workspaces are available\".\n\n## Development\n\nThe 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.\n\nFor local development (point Hermes at your working tree instead of going through `hermes plugins install`):\n\n```bash\ngit clone https://github.com/basicmachines-co/hermes-basic-memory ~/code/hermes-basic-memory\nmkdir -p ~/.hermes/plugins\nln -snf ~/code/hermes-basic-memory ~/.hermes/plugins/basic-memory\n```\n\n### Running tests\n\n```bash\n# Unit tests (fast, hermetic — no Hermes or bm required)\nuv run --with pytest pytest\n\n# Integration tests (gated — exercise every tool against a real bm MCP server)\nBM_INTEGRATION=1 uv run --with pytest --with mcp pytest tests/test_integration.py\n```\n\nThe 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.\n\nIntegration 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.\n\n## License\n\nAGPL-3.0-or-later, matching [basic-memory](https://github.com/basicmachines-co/basic-memory). See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasicmachines-co%2Fhermes-basic-memory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasicmachines-co%2Fhermes-basic-memory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasicmachines-co%2Fhermes-basic-memory/lists"}