fix: lazily initialize slash command provider

Author: groksrc

MONKEYPATCH.md

@@ -2,7 +2,7 @@
 
 This document describes the Hermes Agent-side patch needed when `/bm-*` slash commands do not appear in the gateway even though the Basic Memory provider itself is installed and working.
 
-Agents may use this file as a guide to add support for `/bm-*` slash commands.
+Agents may use this file as a guide to add support for `/bm-*` slash commands in Hermes Agent builds that do not yet include the upstream fix.
 
 ## Problem
 
@@ -42,7 +42,7 @@ hermes_cli/plugins.py
 plugins/memory/__init__.py
 ```
 
-Recommended tests to add/update:
+Recommended tests to add/update in Hermes Agent:
 
 ```text
 tests/hermes_cli/test_plugin_cli_registration.py

README.md

@@ -102,7 +102,7 @@ In plugin v0.2.0 the commands above are registered by this plugin, but some Herm
 
 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). Until the upstream Hermes fix is available in your installed Hermes version, use one of these workarounds:
 
-1. apply the Hermes-side patch described in [MONKEYPATCH.md](MONKEYPATCH.md), which loads the active memory provider during plugin command discovery; or
+1. apply the Hermes Agent-side patch described in [MONKEYPATCH.md](MONKEYPATCH.md), which loads the active memory provider during plugin command discovery; 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:

__init__.py

@@ -682,6 +682,13 @@ def initialize(self, session_id: str, **kwargs: Any) -> None:
         self._capture_folder = cfg.get("capture_folder") or "hermes-sessions"
         self._remember_folder = cfg.get("remember_folder") or "bm-remember"
 
+        if not _MCP_AVAILABLE:
+            logger.error(
+                "basic-memory: MCP SDK unavailable; provider will not initialize: %s",
+                _MCP_IMPORT_ERROR,
+            )
+            return
+
         # Bootstrap-install bm via uv if it's not already on disk. One-time cost
         # on a fresh machine; idempotent no-op once basic-memory is installed.
         if not _bm_binary_path():
@@ -1229,10 +1236,39 @@ def _format_result_rows(items: List[Any], header: str, empty_msg: str) -> str:
     return "\n".join(lines)
 
 
+_slash_init_lock = threading.Lock()
+
+
 def _slash_uninit(cmd: str) -> str:
     return f"{cmd}: basic-memory provider not initialized. Run `hermes memory status` to diagnose."
 
 
+def _ensure_slash_ready(provider: "BasicMemoryProvider", cmd: str) -> Optional[str]:
+    """Lazily initialize the provider for human-invoked /bm-* commands.
+
+    Hermes gateway command discovery can load memory-provider plugins before an
+    agent session initializes memory. Slash handlers close over that discovered
+    provider instance, so they need a small on-demand initialization path before
+    touching the BM MCP actor.
+    """
+    if provider._initialized and provider._actor is not None:
+        return None
+    with _slash_init_lock:
+        if provider._initialized and provider._actor is not None:
+            return None
+        try:
+            provider.initialize(
+                session_id=f"slash:{cmd}:{int(time.time())}",
+                hermes_home=os.path.expanduser("~/.hermes"),
+            )
+        except Exception as e:
+            logger.warning("basic-memory: slash init for /%s failed: %s", cmd, e)
+            return f"{cmd}: failed to initialize basic-memory provider: {e}"
+    if not provider._initialized or provider._actor is None:
+        return _slash_uninit(cmd)
+    return None
+
+
 def _remember_title(text: str) -> str:
     """Derive a note title from free-form text. First non-empty line, ≤80 chars."""
     for line in text.splitlines():
@@ -1255,8 +1291,8 @@ def _bm_search(raw_args: str) -> str:
         args = raw_args.strip()
         if not args or _is_help_arg(args):
             return _SLASH_USAGE["bm-search"]
-        if not provider._initialized or provider._actor is None:
-            return _slash_uninit("bm-search")
+        if err := _ensure_slash_ready(provider, "bm-search"):
+            return err
         try:
             raw = provider._actor.call(
                 "search_notes",
@@ -1282,8 +1318,8 @@ def _bm_read(raw_args: str) -> str:
         args = raw_args.strip()
         if not args or _is_help_arg(args):
             return _SLASH_USAGE["bm-read"]
-        if not provider._initialized or provider._actor is None:
-            return _slash_uninit("bm-read")
+        if err := _ensure_slash_ready(provider, "bm-read"):
+            return err
         try:
             raw = provider._actor.call(
                 "read_note",
@@ -1301,8 +1337,8 @@ def _bm_context(raw_args: str) -> str:
         args = raw_args.strip()
         if not args or _is_help_arg(args):
             return _SLASH_USAGE["bm-context"]
-        if not provider._initialized or provider._actor is None:
-            return _slash_uninit("bm-context")
+        if err := _ensure_slash_ready(provider, "bm-context"):
+            return err
         try:
             raw = provider._actor.call(
                 "build_context",
@@ -1321,8 +1357,8 @@ def _bm_recent(raw_args: str) -> str:
         if _is_help_arg(args):
             return _SLASH_USAGE["bm-recent"]
         timeframe = args or "7d"
-        if not provider._initialized or provider._actor is None:
-            return _slash_uninit("bm-recent")
+        if err := _ensure_slash_ready(provider, "bm-recent"):
+            return err
         try:
             raw = provider._actor.call(
                 "recent_activity",
@@ -1385,8 +1421,8 @@ def _bm_remember(raw_args: str) -> str:
         text = raw_args.strip()
         if not text or _is_help_arg(text):
             return _SLASH_USAGE["bm-remember"]
-        if not provider._initialized or provider._actor is None:
-            return _slash_uninit("bm-remember")
+        if err := _ensure_slash_ready(provider, "bm-remember"):
+            return err
         title = _remember_title(text)
         folder = provider._remember_folder or "bm-remember"
         try:
@@ -1410,8 +1446,8 @@ def _bm_remember(raw_args: str) -> str:
     def _bm_project(raw_args: str) -> str:
         if _is_help_arg(raw_args):
             return _SLASH_USAGE["bm-project"]
-        if not provider._initialized or provider._actor is None:
-            return _slash_uninit("bm-project")
+        if err := _ensure_slash_ready(provider, "bm-project"):
+            return err
         try:
             raw = provider._actor.call(
                 "list_memory_projects",
@@ -1452,8 +1488,8 @@ def _bm_workspace(raw_args: str) -> str:
                 "Workspaces are a Basic Memory Cloud concept. "
                 f"This plugin is in '{provider._mode}' mode — no workspaces to list."
             )
-        if not provider._initialized or provider._actor is None:
-            return _slash_uninit("bm-workspace")
+        if err := _ensure_slash_ready(provider, "bm-workspace"):
+            return err
         try:
             raw = provider._actor.call(
                 "list_workspaces",

tests/test_commands.py

@@ -353,14 +353,34 @@ def test_usage_returned_for_empty_or_help_args(bm, name, args):
     ("bm-remember", "a thought"),
     ("bm-project", ""),
 ])
-def test_handler_uninitialized_returns_message(bm, name, args):
+def test_handler_init_failure_returns_message(bm, monkeypatch, name, args):
     provider = bm.BasicMemoryProvider()
+    monkeypatch.setattr(provider, "initialize", lambda *a, **kw: None)
     handlers = _handlers_by_name(bm, provider)
     out = handlers[name](args)
     assert "not initialized" in out
     assert name in out  # message includes command name
 
 
+def test_handler_lazily_initializes_provider_for_slash_command(bm, monkeypatch):
+    provider = bm.BasicMemoryProvider()
+    calls = []
+
+    def fake_initialize(*args, **kwargs):
+        calls.append((args, kwargs))
+        session = FakeSession(default_response={"results": []})
+        actor = make_scripted_actor(bm, session=session)
+        actor.start()
+        provider._actor = actor
+        provider._initialized = True
+
+    monkeypatch.setattr(provider, "initialize", fake_initialize)
+    out = _handlers_by_name(bm, provider)["bm-search"]("widgets")
+    assert "No results" in out
+    assert len(calls) == 1
+    assert calls[0][1]["session_id"].startswith("slash:bm-search:")
+
+
 # ---- /bm-status ----
 
 def test_bm_status_renders_provider_state(bm, monkeypatch):