hermes-mindgraph-plugin 0.1.0__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+hermes_mindgraph_plugin/__init__.py,sha256=QyhF_wB87qnzOvYawcfbLV0PDAu6miPjF71psb7pAJg,5652
+hermes_mindgraph_plugin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hermes_mindgraph_plugin-0.1.0.dist-info/METADATA,sha256=cJHb3ZaRdxTb10emc6wBt-jGasSGUhmuoq-fzlvQUdM,3569
+hermes_mindgraph_plugin-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hermes_mindgraph_plugin-0.1.0.dist-info/entry_points.txt,sha256=eERZ4MlnlFmrzPvpOwD709Aepe6DZi4bF3ajpR7AnEs,59
+hermes_mindgraph_plugin-0.1.0.dist-info/licenses/LICENSE,sha256=Ii6C3uBhgaTl3K8D_BMUjQsoVwmxeaYUv3RpYoiPJr4,1066
+hermes_mindgraph_plugin-0.1.0.dist-info/RECORD,,

hermes_mindgraph_plugin-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hermes_mindgraph_plugin-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hermes_agent.plugins]
+mindgraph = hermes_mindgraph_plugin

hermes_mindgraph_plugin-0.1.0.dist-info/licenses/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.