runtime-memory 3.0.0__py3-none-any.whl

runtime_memory/hermes/__init__.py

@@ -0,0 +1,39 @@
+"""runtime-memory as a Hermes Agent memory provider.
+
+Hermes finds this package through the ``hermes_agent.memory_providers`` entry
+point declared in ``pyproject.toml``, so installing runtime-memory into the Hermes
+environment is enough to make it selectable:
+
+    pip install git+https://github.com/runtimenoteslabs/memory-layer.git
+    hermes config set memory.provider runtimememory
+
+See ``docs/hermes.md`` for configuration and the trace format.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runtime_memory.hermes._base import HERMES_AVAILABLE
+from runtime_memory.hermes.provider import (
+    PROVIDER_NAME,
+    RuntimeMemoryProvider,
+)
+
+
+def register(ctx: Any) -> None:
+    """Register the provider with Hermes' plugin loader.
+
+    Args:
+        ctx: The plugin context Hermes passes in. Only
+            ``register_memory_provider`` is used.
+    """
+    ctx.register_memory_provider(RuntimeMemoryProvider())
+
+
+__all__ = [
+    "HERMES_AVAILABLE",
+    "PROVIDER_NAME",
+    "RuntimeMemoryProvider",
+    "register",
+]

runtime_memory/hermes/_base.py

@@ -0,0 +1,154 @@
+"""Hermes plugin base classes, with a standalone fallback.
+
+The provider subclasses ``agent.memory_provider.MemoryProvider``, which only
+exists inside a Hermes Agent installation. runtime-memory is also installed on its
+own, so importing this package must not require Hermes. When Hermes is absent we
+fall back to a shim carrying the same surface, which keeps ``runtime_memory.hermes``
+importable and unit-testable anywhere.
+
+The shim is deliberately a copy of the contract, not a reimplementation of it. If
+Hermes changes the ABC, the real import is what the provider is validated
+against; ``HERMES_AVAILABLE`` tells tests which one is in play.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from agent.memory_provider import (  # type: ignore[import-not-found]
+        INDICATOR_GLYPH,
+        MemoryProvider,
+        RecallStatus,
+        is_trivial_prompt,
+    )
+
+    HERMES_AVAILABLE = True
+except ImportError:  # pragma: no cover - exercised only outside Hermes
+    HERMES_AVAILABLE = False
+
+    import re
+    from abc import ABC, abstractmethod
+    from dataclasses import dataclass
+
+    INDICATOR_GLYPH = "\N{BRAIN}"
+
+    @dataclass(frozen=True)
+    class RecallStatus:  # type: ignore[no-redef]
+        """What the last prefetch injected, for the recall indicator."""
+
+        provider_label: str
+        count: int
+        glyph: str = INDICATOR_GLYPH
+
+    _TRIVIAL_PROMPT_RE = re.compile(
+        r"^(yes|no|ok|okay|sure|thanks|thank you|y|n|yep|nope|yeah|nah|"
+        r"hi|hey|hello|yo|sup|"
+        r"continue|go ahead|do it|proceed|got it|cool|nice|great|done|next|lgtm|k)"
+        r"[\s!?.:;,\"'~]*$",
+        re.IGNORECASE,
+    )
+
+    def is_trivial_prompt(text: str | None) -> bool:  # type: ignore[misc]
+        """True for empty input, slash commands and bare acknowledgements."""
+        stripped = (text or "").strip()
+        if not stripped or stripped.startswith("/"):
+            return True
+        return bool(_TRIVIAL_PROMPT_RE.match(stripped))
+
+    class MemoryProvider(ABC):  # type: ignore[no-redef]
+        """Minimal stand-in for the Hermes memory provider contract.
+
+        The optional hooks below are deliberately concrete no-ops rather than
+        abstract methods: a provider overrides only the ones it needs, exactly as
+        in the real contract this mirrors.
+        """
+
+        pre_compress_checkpoint_api_version = 1
+
+        @property
+        @abstractmethod
+        def name(self) -> str: ...
+
+        @abstractmethod
+        def is_available(self) -> bool: ...
+
+        @abstractmethod
+        def initialize(self, session_id: str, **kwargs: Any) -> None: ...
+
+        @abstractmethod
+        def get_tool_schemas(self) -> list[dict[str, Any]]: ...
+
+        def unavailable_reason(self) -> str:
+            return ""
+
+        def system_prompt_block(self) -> str:
+            return ""
+
+        def prefetch(self, query: str, *, session_id: str = "") -> str:
+            return ""
+
+        def queue_prefetch(self, query: str, *, session_id: str = "") -> None: ...
+
+        def recall_status(self) -> RecallStatus | None:
+            return None
+
+        def sync_turn(
+            self,
+            user_content: str,
+            assistant_content: str,
+            *,
+            session_id: str = "",
+            messages: list[dict[str, Any]] | None = None,
+        ) -> None: ...
+
+        def handle_tool_call(self, tool_name: str, args: dict[str, Any], **kwargs: Any) -> str:
+            raise NotImplementedError
+
+        def shutdown(self) -> None: ...
+
+        def on_turn_start(self, turn_number: int, message: str, **kwargs: Any) -> None: ...
+
+        def on_session_end(self, messages: list[dict[str, Any]]) -> None: ...
+
+        def on_session_switch(
+            self,
+            new_session_id: str,
+            *,
+            parent_session_id: str = "",
+            reset: bool = False,
+            rewound: bool = False,
+            **kwargs: Any,
+        ) -> None: ...
+
+        def on_pre_compress(self, messages: list[dict[str, Any]]) -> str:
+            return ""
+
+        def on_delegation(
+            self, task: str, result: str, *, child_session_id: str = "", **kwargs: Any
+        ) -> None: ...
+
+        def get_config_schema(self) -> list[dict[str, Any]]:
+            return []
+
+        def save_config(self, values: dict[str, Any], hermes_home: str) -> None: ...
+
+        def on_memory_write(
+            self,
+            action: str,
+            target: str,
+            content: str,
+            metadata: dict[str, Any] | None = None,
+        ) -> None: ...
+
+        def backup_paths(self) -> list[str]:
+            return []
+
+
+__all__ = [
+    "HERMES_AVAILABLE",
+    "INDICATOR_GLYPH",
+    "MemoryProvider",
+    "RecallStatus",
+    "is_trivial_prompt",
+]

runtime_memory/hermes/bridge.py

@@ -0,0 +1,119 @@
+"""Sync-to-async bridge for the Hermes memory provider.
+
+Every method on the Hermes ``MemoryProvider`` contract is synchronous, while
+``MemoryEngine`` is fully async. The bridge owns one long-lived event loop on a
+daemon thread and marshals coroutines onto it.
+
+The loop is module-global and is deliberately never stopped by a provider's
+``shutdown()``. Hermes builds one provider per agent and one agent per concurrent
+chat session, so a per-provider teardown would strand every sibling provider's
+engine on a dead loop. The loop is a daemon thread and dies with the process.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import threading
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from runtime_memory.core.logging import get_logger
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+logger = get_logger(__name__)
+
+T = TypeVar("T")
+
+_loop: asyncio.AbstractEventLoop | None = None
+_loop_thread: threading.Thread | None = None
+_loop_lock = threading.Lock()
+
+DEFAULT_TIMEOUT = 30.0
+"""Seconds to wait for a bridged call before giving up."""
+
+
+def get_loop() -> asyncio.AbstractEventLoop:
+    """Return the shared background event loop, starting it if needed."""
+    global _loop, _loop_thread
+
+    with _loop_lock:
+        if _loop is not None and _loop.is_running():
+            return _loop
+
+        loop = asyncio.new_event_loop()
+
+        def _run() -> None:
+            asyncio.set_event_loop(loop)
+            loop.run_forever()
+
+        thread = threading.Thread(target=_run, daemon=True, name="memory-layer-loop")
+        thread.start()
+
+        _loop, _loop_thread = loop, thread
+        return loop
+
+
+def run_sync(coro: Coroutine[Any, Any, T], timeout: float = DEFAULT_TIMEOUT) -> T:
+    """Run *coro* on the shared loop and block until it finishes.
+
+    Args:
+        coro: The coroutine to run.
+        timeout: Seconds to wait before raising ``TimeoutError``.
+
+    Returns:
+        Whatever the coroutine returned.
+
+    Raises:
+        TimeoutError: If the coroutine does not finish within *timeout*.
+    """
+    future = asyncio.run_coroutine_threadsafe(coro, get_loop())
+    try:
+        return future.result(timeout=timeout)
+    except TimeoutError:
+        future.cancel()
+        raise
+
+
+def spawn(coro: Coroutine[Any, Any, Any], *, label: str = "task") -> None:
+    """Fire *coro* onto the shared loop without waiting for it.
+
+    Used for the write path, which must not block the agent's reply. Failures are
+    logged rather than raised, since there is no caller left to receive them.
+    """
+    future = asyncio.run_coroutine_threadsafe(coro, get_loop())
+
+    def _report(fut: Any) -> None:
+        try:
+            fut.result()
+        except Exception as exc:  # background work: log it, there is no caller left
+            logger.warning(f"Background {label} failed: {exc}")
+
+    future.add_done_callback(_report)
+
+
+def context_thread(target: Any, name: str) -> threading.Thread:
+    """Daemon thread running *target* inside a copy of the caller's context.
+
+    Threads otherwise start with an empty ``contextvars`` context, which loses the
+    profile scoping Hermes sets up for multi-profile installs.
+    """
+    return threading.Thread(
+        target=contextvars.copy_context().run,
+        args=(target,),
+        daemon=True,
+        name=name,
+    )
+
+
+def _reset_for_tests() -> None:
+    """Stop and clear the shared loop. Test-only."""
+    global _loop, _loop_thread
+
+    with _loop_lock:
+        if _loop is not None and _loop.is_running():
+            _loop.call_soon_threadsafe(_loop.stop)
+        if _loop_thread is not None:
+            _loop_thread.join(timeout=5.0)
+        _loop, _loop_thread = None, None

runtime_memory/hermes/plugin.yaml

@@ -0,0 +1,13 @@
+name: runtimememory
+version: 1.0.0
+description: "Runtime Memory - local SQLite memory with hybrid retrieval and outcome-based learning, shared across Claude Code, MCP clients and Hermes."
+
+# Hermes checks each entry by importing `dist_name.replace("-", "_")` unless it
+# has a mapping for the name. `runtime-memory` imports as `runtime_memory`, so
+# it resolves without an upstream mapping, unlike the bundled providers that
+# need one (honcho-ai -> honcho, mem0ai -> mem0).
+pip_dependencies: ["runtime-memory"]
+
+requires_env: []
+hooks:
+  - on_session_end