Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript

refactor(hermes): single intentional self-bootstrap for the plugin entrypoint (#63)

Sol Aitken23ff4fbc8301
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index a6b53061..9cef56e6 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.32.0",
+ "version": "0.32.1",
"description": "Plugin-first second brain package for AI agents and humans.",
"author": {
"name": "Open Second Brain contributors"
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 7a393256..988fe99d 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.32.0",
+ "version": "0.32.1",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"skills": "./skills",
"hooks": "./hooks/hooks.json",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc0107c2..5c7f83db 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.32.1] - 2026-06-02
+
+### Changed
+
+- The repo-root `__init__.py` now loads the `plugins/hermes` implementation
+ through a single, intentional self-bootstrap (file-path import under a private
+ package name) instead of a three-branch import cascade with a file-path
+ fallback. Loading no longer depends on the host runtime registering a parent
+ namespace for the plugin, so the entrypoint is host-agnostic and the
+ implementation keeps its small single-responsibility modules. Behaviour is
+ unchanged - the provider still discovers and loads on a stock Hermes install;
+ `tests/python/test_hermes_plugin.py` locks that it loads even when the parent
+ namespace is absent.
+
+### Notes
+
+- This supersedes the 0.32.0 "Temporary loader workaround" note: the file-path
+ load is now treated as the plugin's permanent load path, not a stopgap. An
+ upstream Hermes loader change (registering the `_hermes_user_memory` parent)
+ remains the route to fully-native relative imports as bundled providers use,
+ but it is a future enhancement, not a dependency for this plugin to work.
+
## [0.32.0] - 2026-06-01
Open Second Brain is now a native Hermes memory provider. The Hermes
@@ -3835,6 +3857,7 @@ plugin config (vault field)`, and exits with a clear
- Sandbox vault and plugin manifest fixtures for tests.
- GitHub release workflow for tag-based and manually dispatched releases.
+[0.32.1]: https://github.com/itechmeat/open-second-brain/compare/v0.32.0...v0.32.1
[0.32.0]: https://github.com/itechmeat/open-second-brain/compare/v0.31.2...v0.32.0
[0.31.2]: https://github.com/itechmeat/open-second-brain/compare/v0.31.1...v0.31.2
[0.31.1]: https://github.com/itechmeat/open-second-brain/compare/v0.31.0...v0.31.1
diff --git a/__init__.py b/__init__.py
index 8caa5f64..0a3cce83 100644
--- a/__init__.py
+++ b/__init__.py
@@ -1,79 +1,76 @@
-"""Hermes plugin entrypoint for OpenSecondBrain.
+"""Hermes plugin entrypoint for Open Second Brain.
-Hermes installs Git plugins by cloning the repository and loading the repository
-root as the plugin directory. The implementation lives in ``plugins/hermes`` so
-it can also be used directly by runtimes that expect an adapter subdirectory.
+Hermes installs Git plugins by cloning the repository and treating the
+repository root as the plugin directory, so this file is the entry the gateway
+loads first. The ``OpenSecondBrainMemoryProvider`` implementation and its
+``register``/health surface live in ``plugins/hermes``.
-TEMPORARY WORKAROUND (third import branch below)
-------------------------------------------------
-Hermes' external memory-provider loader (``plugins/memory/_load_provider_from_dir``)
-imports this file under a synthetic package name ``_hermes_user_memory.<plugin>``
-but never registers that parent namespace package. As a result ANY relative
-import in an external (user-installed) provider fails with
-``ModuleNotFoundError: No module named '_hermes_user_memory'`` — this affects a
-flat single-directory layout too, not just our ``plugins/`` subpackage. Bundled
-providers escape it only because they load as ``plugins.memory.<name>`` (that
-parent IS registered). The file-path fallback below sidesteps the broken parent
-chain so the provider loads.
+Self-bootstrap loading
+----------------------
+This entrypoint loads the implementation package from ``plugins/hermes`` by
+file path under a private, collision-free package name, with
+``submodule_search_locations`` set so the implementation's own relative imports
+(``from . import config``, ``from ._base import ...``) resolve against it. This
+is the plugin's single, intentional, host-agnostic load path.
-This is a Hermes-core limitation, not a plugin bug. The correct fix is upstream
-(``NousResearch/hermes-agent``): have the loader register the
-``_hermes_user_memory`` parent namespace. REMOVE the third ``except`` branch once
-that ships — the first two import branches are the real, native ones. The same
-limitation blocks the ``hermes open-second-brain`` diagnostic CLI subcommand;
-it will start working from the same upstream fix with no further changes here.
+Owning the bootstrap is deliberate. A host runtime that imports the plugin
+under a synthetic package without also registering that parent namespace cannot
+load a provider written with ordinary relative or absolute imports -- the first
+relative import raises ``ModuleNotFoundError`` for the missing parent. Hermes'
+external memory-provider loader behaves exactly this way today (it imports
+user-installed plugins as ``_hermes_user_memory.<name>`` without registering
+``_hermes_user_memory``). Bootstrapping our own package sidesteps that entirely
+and stays valid whether or not the host registers the parent, so the
+implementation keeps its small single-responsibility modules instead of being
+collapsed into one file to dodge the loader. ``OpenSecondBrainMemoryProvider``
+is referenced below so Hermes' text-scan discovery heuristic still recognises
+this file as a memory provider.
"""
from __future__ import annotations
-try:
- # Normal package import: adapter-subdir runtimes and Hermes' general
- # plugin manager load the repo root as a package, so the implementation
- # subpackage resolves relatively.
- from .plugins.hermes import (
- OpenSecondBrainMemoryProvider,
- check_health,
- health,
- register,
+import importlib.util as _importlib_util
+import os as _os
+import sys as _sys
+
+_IMPL_DIR = _os.path.join(
+ _os.path.dirname(_os.path.abspath(__file__)), "plugins", "hermes"
+)
+_IMPL_PKG = "_osb_hermes_impl"
+
+
+def _load_impl():
+ """Import ``plugins/hermes`` by file path under a private package name.
+
+ Idempotent: a second import in the same process reuses the cached module,
+ so a host that loads this entrypoint more than once gets one implementation.
+ """
+ module = _sys.modules.get(_IMPL_PKG)
+ if module is not None:
+ return module
+ spec = _importlib_util.spec_from_file_location(
+ _IMPL_PKG,
+ _os.path.join(_IMPL_DIR, "__init__.py"),
+ submodule_search_locations=[_IMPL_DIR],
)
-except ImportError:
- try:
- from plugins.hermes import (
- OpenSecondBrainMemoryProvider,
- check_health,
- health,
- register,
- )
- except ImportError:
- # === TEMPORARY WORKAROUND — remove with upstream Hermes loader fix ===
- # See the module docstring. Hermes' memory loader imports this file as
- # ``_hermes_user_memory.<plugin>`` without registering that parent
- # namespace, so the relative/absolute imports above raise
- # ``ModuleNotFoundError: No module named '_hermes_user_memory'``. Load
- # the implementation by file path under a collision-free package name;
- # ``submodule_search_locations`` lets its own relative imports
- # (``.provider``, ``._base``, …) resolve.
- import importlib.util as _ilu
- import os as _os
- import sys as _sys
+ module = _importlib_util.module_from_spec(spec)
+ _sys.modules[_IMPL_PKG] = module
+ spec.loader.exec_module(module)
+ return module
+
+
+_impl = _load_impl()
- _impl_dir = _os.path.join(
- _os.path.dirname(_os.path.abspath(__file__)), "plugins", "hermes"
- )
- _pkg = "_osb_hermes_impl"
- _mod = _sys.modules.get(_pkg)
- if _mod is None:
- _spec = _ilu.spec_from_file_location(
- _pkg,
- _os.path.join(_impl_dir, "__init__.py"),
- submodule_search_locations=[_impl_dir],
- )
- _mod = _ilu.module_from_spec(_spec)
- _sys.modules[_pkg] = _mod
- _spec.loader.exec_module(_mod)
- OpenSecondBrainMemoryProvider = _mod.OpenSecondBrainMemoryProvider
- check_health = _mod.check_health
- health = _mod.health
- register = _mod.register
+OpenSecondBrainMemoryProvider = _impl.OpenSecondBrainMemoryProvider
+check_health = _impl.check_health
+health = _impl.health
+register = _impl.register
+register_cli = _impl.register_cli
-__all__ = ["OpenSecondBrainMemoryProvider", "check_health", "health", "register"]
+__all__ = [
+ "OpenSecondBrainMemoryProvider",
+ "check_health",
+ "health",
+ "register",
+ "register_cli",
+]
diff --git a/install/hermes.md b/install/hermes.md
index ea205910..d180064d 100644
--- a/install/hermes.md
+++ b/install/hermes.md
@@ -95,11 +95,10 @@ hermes memory status
`available ✓` once active. Run the daily-identity check described in
`install/prerequisites.md`.
-> The dedicated `hermes open-second-brain status/config` subcommand is
-> not yet available: Hermes' loader cannot import an external provider's
-> `cli.py` (the same parent-namespace limitation noted in the root
-> `__init__.py`). It lights up automatically once that upstream fix
-> ships. Until then, use `hermes memory status` and `o2b doctor`.
+> A provider-specific `hermes open-second-brain` subcommand is not
+> surfaced on current Hermes. Use `hermes memory status` for provider
+> state and `o2b doctor` for the full readiness suite - together they
+> cover the same ground.
## Update
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index 13423404..4b109d91 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,7 +2,7 @@
"id": "open-second-brain",
"name": "Open Second Brain",
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults.",
- "version": "0.32.0",
+ "version": "0.32.1",
"activation": { "onStartup": true },
"skills": ["./skills"],
"contracts": {
diff --git a/package.json b/package.json
index d7610345..b5cc5262 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.32.0",
+ "version": "0.32.1",
"private": false,
"description": "Second brain for AI agents using Obsidian-compatible Markdown vaults. Works with Hermes, Claude Code, Codex, and OpenClaw.",
"keywords": [
diff --git a/plugin.yaml b/plugin.yaml
index 419f3cf6..a9cbde07 100644
--- a/plugin.yaml
+++ b/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.32.0"
+version: "0.32.1"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index b18bad5a..0dfbe3f2 100644
--- a/plugins/codex/.codex-plugin/plugin.json
+++ b/plugins/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "open-second-brain",
- "version": "0.32.0",
+ "version": "0.32.1",
"description": "Plugin-first second brain package for Codex, Hermes, Claude Code, OpenClaw, and other agent runtimes.",
"author": {
"name": "Open Second Brain contributors",
diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml
index 419f3cf6..a9cbde07 100644
--- a/plugins/hermes/plugin.yaml
+++ b/plugins/hermes/plugin.yaml
@@ -1,5 +1,5 @@
name: open-second-brain
-version: "0.32.0"
+version: "0.32.1"
description: "Open Second Brain - native Hermes memory provider backed by an Obsidian-compatible Markdown vault."
author: "Open Second Brain contributors"
memory_provider: true
diff --git a/pyproject.toml b/pyproject.toml
index 7800c04d..ea4fd3d8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
# CLI entry points (those moved to `package.json` `bin`).
[project]
name = "open-second-brain"
-version = "0.32.0"
+version = "0.32.1"
description = "Hermes Python shim for Open Second Brain. Most of the project (CLI, MCP server, OpenClaw plugin) is TypeScript on Bun; see package.json."
readme = "README.md"
requires-python = ">=3.11"
diff --git a/tests/python/test_hermes_plugin.py b/tests/python/test_hermes_plugin.py
index 1e89f767..c084b381 100644
--- a/tests/python/test_hermes_plugin.py
+++ b/tests/python/test_hermes_plugin.py
@@ -93,16 +93,15 @@ class RegisterTests(unittest.TestCase):
self.assertEqual(registered[0].name, PLUGIN_NAME)
-class LoaderFallbackTests(unittest.TestCase):
- """Guards the TEMPORARY file-path fallback in the root ``__init__.py``.
-
- Hermes' external memory-provider loader imports a plugin under a synthetic
- package name without registering its parent namespace, breaking the
- relative/absolute imports the root entrypoint tries first. The fallback
- loads ``plugins/hermes`` directly by file path with
- ``submodule_search_locations`` so its own relative imports still resolve.
- This locks that mechanism: if it ever stops yielding the provider (e.g. the
- fallback is removed before the upstream Hermes fix lands), this fails.
+class SelfBootstrapTests(unittest.TestCase):
+ """Locks the root entrypoint's single self-bootstrap load path.
+
+ The root ``__init__.py`` loads ``plugins/hermes`` by file path under a
+ private package name with ``submodule_search_locations`` so the
+ implementation's own relative imports resolve against it. This is the
+ plugin's one intentional, host-agnostic load path -- it does not depend on
+ the host runtime registering a parent namespace package for the plugin.
+ These tests pin that behaviour.
"""
def test_filepath_load_of_impl_yields_provider(self):
@@ -125,6 +124,39 @@ class LoaderFallbackTests(unittest.TestCase):
if name == spec.name or name.startswith(spec.name + "."):
sys.modules.pop(name, None)
+ def test_entrypoint_loads_without_parent_namespace_registered(self):
+ """Regression for the stock-Hermes load path.
+
+ Hermes' external memory-provider loader imports a user-installed plugin
+ as ``_hermes_user_memory.<name>`` but does NOT register the
+ ``_hermes_user_memory`` parent in ``sys.modules``. A provider written
+ with ordinary relative/absolute imports fails there with
+ ``ModuleNotFoundError: No module named '_hermes_user_memory'``. The
+ self-bootstrap must load regardless, so this mimics that exact loader
+ condition (synthetic child name, parent intentionally absent) and
+ asserts the entrypoint still yields a working provider and ``register``.
+ """
+ synthetic = "_hermes_user_memory.open-second-brain"
+ self.assertNotIn(
+ "_hermes_user_memory",
+ sys.modules,
+ "parent namespace must be absent to reproduce the stock loader",
+ )
+ spec = importlib.util.spec_from_file_location(
+ synthetic,
+ ROOT / "__init__.py",
+ submodule_search_locations=[str(ROOT)],
+ )
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[synthetic] = module
+ try:
+ spec.loader.exec_module(module) # must not raise ModuleNotFoundError
+ provider = module.OpenSecondBrainMemoryProvider()
+ self.assertEqual(provider.name, PLUGIN_NAME)
+ self.assertTrue(callable(module.register))
+ finally:
+ sys.modules.pop(synthetic, None)
+
def test_register_does_not_raise_on_minimal_context(self):
class Context:
pass