hermes-mindgraph-plugin 0.1.0__tar.gz

hermes_mindgraph_plugin-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hermes_mindgraph_plugin-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/

hermes_mindgraph_plugin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MindGraph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_mindgraph_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: hermes-mindgraph-plugin
+Version: 0.1.0
+Summary: MindGraph semantic graph memory plugin for Hermes Agent
+Project-URL: Homepage, https://mindgraph.cloud
+Project-URL: Repository, https://github.com/shuruheel/hermes-mindgraph-plugin
+Project-URL: Issues, https://github.com/shuruheel/hermes-mindgraph-plugin/issues
+Author-email: Shan Rizvi <shan@rizvi.nu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,hermes,memory,mindgraph,plugin,semantic-graph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: mindgraph-sdk>=0.1.4
+Description-Content-Type: text/markdown
+
+# hermes-mindgraph-plugin
+
+Semantic graph memory plugin for [Hermes Agent](https://github.com/NousResearch/hermes-agent). Gives any Hermes-powered agent persistent memory across sessions using [MindGraph](https://mindgraph.cloud).
+
+## What it does
+
+This plugin hooks into Hermes Agent's lifecycle to provide:
+
+- **Session context** — Active goals, open decisions, governance policies, weak claims, and user profile are injected into the agent's context at the start of each conversation.
+- **Per-turn retrieval** — Score-gated semantic search finds topic-relevant knowledge from the graph and injects it ephemerally (never persisted to conversation history, no prompt cache breakage).
+- **Session lifecycle** — Automatically opens and closes MindGraph sessions aligned with Hermes conversations.
+
+## Install
+
+```bash
+pip install hermes-mindgraph-plugin
+```
+
+The plugin is auto-discovered via the `hermes_agent.plugins` entry point. No configuration beyond the API key is needed.
+
+## Setup
+
+1. Get a MindGraph API key at [mindgraph.cloud](https://mindgraph.cloud)
+2. Add it to your Hermes environment:
+
+```bash
+echo "MINDGRAPH_API_KEY=mg_your_key_here" >> ~/.hermes/.env
+```
+
+3. Verify the plugin is loaded:
+
+```bash
+hermes plugins list
+```
+
+## How it works
+
+The plugin registers three [lifecycle hooks](https://hermes.nousresearch.com/docs/user-guide/features/plugins):
+
+| Hook | When | What |
+|------|------|------|
+| `on_session_start` | New conversation begins | Opens a MindGraph session, pre-fetches goals/decisions/policies |
+| `pre_llm_call` | Before each agent turn | Returns session context (first turn) + semantic retrieval (every turn) |
+| `on_session_end` | Conversation ends | Closes the MindGraph session |
+
+Context is injected **ephemerally** into the system prompt — it's never persisted to the session database and doesn't break Anthropic's prompt cache prefix.
+
+All MindGraph API calls are wrapped in try/except. A MindGraph failure never breaks the conversation.
+
+## Manual install (alternative)
+
+If you prefer not to use pip, copy the plugin directly:
+
+```bash
+mkdir -p ~/.hermes/plugins/mindgraph
+# Copy plugin.yaml and __init__.py into that directory
+```
+
+See the `plugin.yaml` in this repo for the manifest format.
+
+## Development
+
+```bash
+git clone https://github.com/shuruheel/hermes-mindgraph-plugin
+cd hermes-mindgraph-plugin
+pip install -e ".[dev]"
+pytest
+```
+
+## Requirements
+
+- Hermes Agent ≥ v0.5.0 (plugin lifecycle hooks)
+- Python ≥ 3.10
+- `mindgraph-sdk` ≥ 0.1.4
+- `MINDGRAPH_API_KEY` environment variable
+
+## License
+
+MIT

hermes_mindgraph_plugin-0.1.0/README.md

@@ -0,0 +1,79 @@
+# hermes-mindgraph-plugin
+
+Semantic graph memory plugin for [Hermes Agent](https://github.com/NousResearch/hermes-agent). Gives any Hermes-powered agent persistent memory across sessions using [MindGraph](https://mindgraph.cloud).
+
+## What it does
+
+This plugin hooks into Hermes Agent's lifecycle to provide:
+
+- **Session context** — Active goals, open decisions, governance policies, weak claims, and user profile are injected into the agent's context at the start of each conversation.
+- **Per-turn retrieval** — Score-gated semantic search finds topic-relevant knowledge from the graph and injects it ephemerally (never persisted to conversation history, no prompt cache breakage).
+- **Session lifecycle** — Automatically opens and closes MindGraph sessions aligned with Hermes conversations.
+
+## Install
+
+```bash
+pip install hermes-mindgraph-plugin
+```
+
+The plugin is auto-discovered via the `hermes_agent.plugins` entry point. No configuration beyond the API key is needed.
+
+## Setup
+
+1. Get a MindGraph API key at [mindgraph.cloud](https://mindgraph.cloud)
+2. Add it to your Hermes environment:
+
+```bash
+echo "MINDGRAPH_API_KEY=mg_your_key_here" >> ~/.hermes/.env
+```
+
+3. Verify the plugin is loaded:
+
+```bash
+hermes plugins list
+```
+
+## How it works
+
+The plugin registers three [lifecycle hooks](https://hermes.nousresearch.com/docs/user-guide/features/plugins):
+
+| Hook | When | What |
+|------|------|------|
+| `on_session_start` | New conversation begins | Opens a MindGraph session, pre-fetches goals/decisions/policies |
+| `pre_llm_call` | Before each agent turn | Returns session context (first turn) + semantic retrieval (every turn) |
+| `on_session_end` | Conversation ends | Closes the MindGraph session |
+
+Context is injected **ephemerally** into the system prompt — it's never persisted to the session database and doesn't break Anthropic's prompt cache prefix.
+
+All MindGraph API calls are wrapped in try/except. A MindGraph failure never breaks the conversation.
+
+## Manual install (alternative)
+
+If you prefer not to use pip, copy the plugin directly:
+
+```bash
+mkdir -p ~/.hermes/plugins/mindgraph
+# Copy plugin.yaml and __init__.py into that directory
+```
+
+See the `plugin.yaml` in this repo for the manifest format.
+
+## Development
+
+```bash
+git clone https://github.com/shuruheel/hermes-mindgraph-plugin
+cd hermes-mindgraph-plugin
+pip install -e ".[dev]"
+pytest
+```
+
+## Requirements
+
+- Hermes Agent ≥ v0.5.0 (plugin lifecycle hooks)
+- Python ≥ 3.10
+- `mindgraph-sdk` ≥ 0.1.4
+- `MINDGRAPH_API_KEY` environment variable
+
+## License
+
+MIT

hermes_mindgraph_plugin-0.1.0/plugin.yaml

@@ -0,0 +1,19 @@
+# For manual installation: copy this file + __init__.py to
+# ~/.hermes/plugins/mindgraph/
+#
+# For pip installation, use: pip install hermes-mindgraph-plugin
+# (auto-discovered via entry points, no manual copy needed)
+
+name: mindgraph
+version: 0.1.0
+description: >
+  Semantic graph memory provider — injects session context (goals, decisions,
+  policies) and per-turn topic-relevant knowledge from MindGraph into the
+  agent's context via plugin lifecycle hooks.
+author: Shan Rizvi
+requires_env:
+  - MINDGRAPH_API_KEY
+provides_hooks:
+  - on_session_start
+  - pre_llm_call
+  - on_session_end

hermes_mindgraph_plugin-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hermes-mindgraph-plugin"
+version = "0.1.0"
+description = "MindGraph semantic graph memory plugin for Hermes Agent"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Shan Rizvi", email = "shan@rizvi.nu" },
+]
+keywords = ["hermes", "agent", "mindgraph", "memory", "semantic-graph", "plugin"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mindgraph-sdk>=0.1.4",
+]
+
+[project.urls]
+Homepage = "https://mindgraph.cloud"
+Repository = "https://github.com/shuruheel/hermes-mindgraph-plugin"
+Issues = "https://github.com/shuruheel/hermes-mindgraph-plugin/issues"
+
+[project.entry-points."hermes_agent.plugins"]
+mindgraph = "hermes_mindgraph_plugin"

hermes_mindgraph_plugin-0.1.0/src/hermes_mindgraph_plugin/__init__.py

@@ -0,0 +1,170 @@
+"""MindGraph semantic graph memory plugin for Hermes Agent.
+
+Bridges MindGraph (https://mindgraph.cloud) into Hermes Agent's plugin
+lifecycle hooks, giving any Hermes-powered agent persistent semantic memory
+across sessions.
+
+Install:
+    pip install hermes-mindgraph-plugin
+
+Configure:
+    Set MINDGRAPH_API_KEY in ~/.hermes/.env (get one at https://mindgraph.cloud)
+
+The plugin is auto-discovered via the ``hermes_agent.plugins`` entry point.
+It can also be installed manually by copying this package to
+``~/.hermes/plugins/mindgraph/`` with an accompanying ``plugin.yaml``.
+
+Hooks registered:
+    on_session_start  — Opens a MindGraph session, pre-fetches context.
+    pre_llm_call      — Injects session context (goals, decisions, policies)
+                        on first turn; score-gated semantic retrieval every turn.
+    on_session_end    — Closes the MindGraph session.
+"""
+
+__version__ = "0.1.0"
+
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# State — per-process, reset on session_start
+# ---------------------------------------------------------------------------
+
+_session_context_cache: Optional[str] = None
+_session_started: bool = False
+
+
+def _is_available() -> bool:
+    """Check if MindGraph is configured and ready."""
+    try:
+        from tools.mindgraph_tool import check_requirements
+        return check_requirements()
+    except ImportError:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# Hook callbacks
+# ---------------------------------------------------------------------------
+
+def _on_session_start(
+    *, session_id: str = "", model: str = "", platform: str = "", **kw
+):
+    """Open a MindGraph session and pre-fetch session context."""
+    global _session_context_cache, _session_started
+    _session_context_cache = None
+    _session_started = False
+
+    if not _is_available():
+        return
+
+    # Open session
+    try:
+        from tools.mindgraph_tool import auto_open_session
+
+        label = f"hermes-{session_id[:8]}" if session_id else "hermes-session"
+        sid = auto_open_session(label=label)
+        if sid:
+            logger.info("MindGraph session opened: %s", sid)
+            _session_started = True
+    except Exception as exc:
+        logger.debug("MindGraph session open failed (non-fatal): %s", exc)
+
+    # Pre-fetch session context (goals, decisions, policies, weak claims)
+    # so it's ready for the first pre_llm_call without blocking.
+    try:
+        from tools.mindgraph_tool import retrieve_session_context
+
+        _session_context_cache = retrieve_session_context()
+    except Exception as exc:
+        logger.debug("MindGraph session context prefetch failed: %s", exc)
+
+
+def _pre_llm_call(
+    *,
+    session_id: str = "",
+    user_message: str = "",
+    conversation_history: list = None,
+    is_first_turn: bool = False,
+    model: str = "",
+    platform: str = "",
+    **kw,
+) -> dict | None:
+    """Return context to inject into the agent's ephemeral system prompt.
+
+    First turn: cached session context (goals, decisions, policies, weak claims).
+    Every turn:  score-gated semantic retrieval for topic relevance.
+
+    Returns ``{"context": "..."}`` or ``None``.
+    """
+    if not _is_available():
+        return None
+
+    parts: list[str] = []
+
+    # --- Session context (first turn only) ---
+    if is_first_turn and _session_context_cache:
+        parts.append(_session_context_cache)
+        # Don't clear the cache — the gateway creates a fresh AIAgent per
+        # message, so is_first_turn may be True on every gateway turn for
+        # continuing sessions.  The cache stays valid for the process
+        # lifetime and is reset on the next on_session_start.
+
+    # --- Per-turn semantic retrieval ---
+    if user_message:
+        try:
+            from tools.mindgraph_tool import proactive_graph_retrieve
+
+            turn_ctx = proactive_graph_retrieve(user_message)
+            if turn_ctx:
+                parts.append(turn_ctx)
+        except Exception as exc:
+            logger.debug("MindGraph turn retrieval failed (non-fatal): %s", exc)
+
+    if parts:
+        return {"context": "\n\n".join(parts)}
+    return None
+
+
+def _on_session_end(
+    *,
+    session_id: str = "",
+    completed: bool = True,
+    interrupted: bool = False,
+    model: str = "",
+    platform: str = "",
+    **kw,
+):
+    """Close the MindGraph session."""
+    global _session_context_cache, _session_started
+
+    if not _session_started:
+        return
+
+    try:
+        from tools.mindgraph_tool import auto_close_session
+
+        auto_close_session(
+            summary=(
+                f"Session {session_id[:8] if session_id else 'unknown'} "
+                f"({'completed' if completed else 'interrupted' if interrupted else 'ended'})"
+            ),
+        )
+        _session_started = False
+        _session_context_cache = None
+    except Exception as exc:
+        logger.debug("MindGraph session close failed (non-fatal): %s", exc)
+
+
+# ---------------------------------------------------------------------------
+# Plugin entry point — called by Hermes plugin discovery
+# ---------------------------------------------------------------------------
+
+def register(ctx):
+    """Register MindGraph memory hooks with the Hermes plugin system."""
+    ctx.register_hook("on_session_start", _on_session_start)
+    ctx.register_hook("pre_llm_call", _pre_llm_call)
+    ctx.register_hook("on_session_end", _on_session_end)
+    logger.info("MindGraph memory plugin registered (3 lifecycle hooks)")

hermes_mindgraph_plugin-0.1.0/tests/test_plugin.py

@@ -0,0 +1,231 @@
+"""Tests for hermes-mindgraph-plugin."""
+
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import hermes_mindgraph_plugin as plugin
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def _reset_plugin_state():
+    """Reset module-level state between tests."""
+    plugin._session_context_cache = None
+    plugin._session_started = False
+    yield
+    plugin._session_context_cache = None
+    plugin._session_started = False
+
+
+# ---------------------------------------------------------------------------
+# register()
+# ---------------------------------------------------------------------------
+
+class TestRegister:
+
+    def test_registers_three_hooks(self):
+        ctx = MagicMock()
+        plugin.register(ctx)
+        assert ctx.register_hook.call_count == 3
+        hook_names = {call.args[0] for call in ctx.register_hook.call_args_list}
+        assert hook_names == {"on_session_start", "pre_llm_call", "on_session_end"}
+
+    def test_callbacks_are_callable(self):
+        ctx = MagicMock()
+        plugin.register(ctx)
+        for call in ctx.register_hook.call_args_list:
+            assert callable(call.args[1])
+
+
+# ---------------------------------------------------------------------------
+# on_session_start
+# ---------------------------------------------------------------------------
+
+class TestOnSessionStart:
+
+    @patch("hermes_mindgraph_plugin._is_available", return_value=False)
+    def test_noop_when_unavailable(self, _mock):
+        plugin._on_session_start(session_id="abc123")
+        assert not plugin._session_started
+        assert plugin._session_context_cache is None
+
+    @patch("hermes_mindgraph_plugin._is_available", return_value=True)
+    def test_opens_session_and_prefetches(self, _avail):
+        mock_open = MagicMock(return_value="sess-uid-123")
+        mock_ctx = MagicMock(return_value="## Goals\n- Ship it")
+
+        with patch.dict(sys.modules, {
+            "tools.mindgraph_tool": MagicMock(
+                auto_open_session=mock_open,
+                retrieve_session_context=mock_ctx,
+            ),
+        }):
+            plugin._on_session_start(session_id="abcdef99", model="test", platform="cli")
+
+        assert plugin._session_started is True
+        assert plugin._session_context_cache == "## Goals\n- Ship it"
+        mock_open.assert_called_once_with(label="hermes-abcdef99")
+
+    @patch("hermes_mindgraph_plugin._is_available", return_value=True)
+    def test_session_start_failure_is_nonfatal(self, _avail):
+        mock_open = MagicMock(side_effect=RuntimeError("connection refused"))
+
+        with patch.dict(sys.modules, {
+            "tools.mindgraph_tool": MagicMock(
+                auto_open_session=mock_open,
+                retrieve_session_context=MagicMock(return_value=None),
+            ),
+        }):
+            # Should not raise
+            plugin._on_session_start(session_id="test")
+
+        assert not plugin._session_started
+
+
+# ---------------------------------------------------------------------------
+# pre_llm_call
+# ---------------------------------------------------------------------------
+
+class TestPreLlmCall:
+
+    @patch("hermes_mindgraph_plugin._is_available", return_value=False)
+    def test_returns_none_when_unavailable(self, _mock):
+        result = plugin._pre_llm_call(
+            session_id="x", user_message="hello", is_first_turn=True,
+        )
+        assert result is None
+
+    @patch("hermes_mindgraph_plugin._is_available", return_value=True)
+    def test_returns_session_context_on_first_turn(self, _avail):
+        plugin._session_context_cache = "## Active Goals\n- Goal 1"
+        result = plugin._pre_llm_call(
+            session_id="x", user_message="hi",
+            conversation_history=[], is_first_turn=True,
+        )
+        assert result is not None
+        assert "Active Goals" in result["context"]
+
+    @patch("hermes_mindgraph_plugin._is_available", return_value=True)
+    def test_no_session_context_on_subsequent_turn(self, _avail):
+        plugin._session_context_cache = "## Active Goals\n- Goal 1"
+        result = plugin._pre_llm_call(
+            session_id="x", user_message="ok",
+            conversation_history=[{"role": "user"}], is_first_turn=False,
+        )
+        # Short message + not first turn = no retrieval, no session context
+        assert result is None
+
+    @patch("hermes_mindgraph_plugin._is_available", return_value=True)
+    def test_returns_turn_context_from_retrieval(self, _avail):
+        mock_retrieve = MagicMock(return_value="## Relevant: plugin hooks")
+
+        with patch.dict(sys.modules, {
+            "tools.mindgraph_tool": MagicMock(
+                proactive_graph_retrieve=mock_retrieve,
+            ),
+        }):
+            result = plugin._pre_llm_call(
+                session_id="x",
+                user_message="Tell me about the plugin lifecycle hooks",
+                conversation_history=[{"role": "user"}],
+                is_first_turn=False,
+            )
+
+        assert result is not None
+        assert "plugin hooks" in result["context"]
+        mock_retrieve.assert_called_once()
+
+    @patch("hermes_mindgraph_plugin._is_available", return_value=True)
+    def test_combines_session_and_turn_context(self, _avail):
+        plugin._session_context_cache = "## Goals\n- Ship plugin"
+        mock_retrieve = MagicMock(return_value="## Related: memory systems")
+
+        with patch.dict(sys.modules, {
+            "tools.mindgraph_tool": MagicMock(
+                proactive_graph_retrieve=mock_retrieve,
+            ),
+        }):
+            result = plugin._pre_llm_call(
+                session_id="x",
+                user_message="How does memory work in Hermes?",
+                conversation_history=[],
+                is_first_turn=True,
+            )
+
+        assert result is not None
+        ctx = result["context"]
+        assert "## Goals" in ctx
+        assert "## Related" in ctx
+
+    @patch("hermes_mindgraph_plugin._is_available", return_value=True)
+    def test_retrieval_failure_is_nonfatal(self, _avail):
+        with patch.dict(sys.modules, {
+            "tools.mindgraph_tool": MagicMock(
+                proactive_graph_retrieve=MagicMock(side_effect=Exception("timeout")),
+            ),
+        }):
+            result = plugin._pre_llm_call(
+                session_id="x",
+                user_message="Tell me about something complex",
+                is_first_turn=False,
+            )
+        # Should not raise, returns None
+        assert result is None
+
+    @patch("hermes_mindgraph_plugin._is_available", return_value=True)
+    def test_preserves_cache_across_calls(self, _avail):
+        """Session context cache is not cleared after first use."""
+        plugin._session_context_cache = "## Goals\n- Persist"
+
+        plugin._pre_llm_call(
+            session_id="x", user_message="hi",
+            conversation_history=[], is_first_turn=True,
+        )
+        # Cache should still be there
+        assert plugin._session_context_cache == "## Goals\n- Persist"
+
+
+# ---------------------------------------------------------------------------
+# on_session_end
+# ---------------------------------------------------------------------------
+
+class TestOnSessionEnd:
+
+    def test_noop_when_not_started(self):
+        plugin._session_started = False
+        # Should not raise or call anything
+        plugin._on_session_end(session_id="test", completed=True)
+        assert not plugin._session_started
+
+    @patch("hermes_mindgraph_plugin._is_available", return_value=True)
+    def test_closes_session(self, _avail):
+        plugin._session_started = True
+        plugin._session_context_cache = "some cached context"
+        mock_close = MagicMock()
+
+        with patch.dict(sys.modules, {
+            "tools.mindgraph_tool": MagicMock(auto_close_session=mock_close),
+        }):
+            plugin._on_session_end(
+                session_id="abcdef99", completed=True, interrupted=False,
+            )
+
+        assert not plugin._session_started
+        assert plugin._session_context_cache is None
+        mock_close.assert_called_once()
+
+    @patch("hermes_mindgraph_plugin._is_available", return_value=True)
+    def test_close_failure_is_nonfatal(self, _avail):
+        plugin._session_started = True
+        mock_close = MagicMock(side_effect=RuntimeError("api down"))
+
+        with patch.dict(sys.modules, {
+            "tools.mindgraph_tool": MagicMock(auto_close_session=mock_close),
+        }):
+            # Should not raise
+            plugin._on_session_end(session_id="test", completed=True)