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.jsonindex 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.jsonindex 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.mdindex 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-01Open 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.1diff --git a/__init__.py b/__init__.pyindex 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.mdindex 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.## Updatediff --git a/openclaw.plugin.json b/openclaw.plugin.jsonindex 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.jsonindex 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.yamlindex 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: truediff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.jsonindex 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.yamlindex 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: truediff --git a/pyproject.toml b/pyproject.tomlindex 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.pyindex 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