@atomicmemory/hermes-plugin 0.1.10

package/README.md

@@ -0,0 +1,157 @@
+# AtomicMemory for Hermes Agent
+
+AtomicMemory is a native Hermes memory provider. It participates in Hermes'
+memory lifecycle: background recall is prefetched for the next turn,
+completed turns are synced without blocking the chat loop, and the agent
+gets explicit tools for searching and storing durable facts.
+
+By default, recall is **shared** across every AtomicMemory tool the user
+has touched (Claude Code, Codex, the web extension, etc.). Set
+`memory_scope=siloed` to restrict Hermes to Hermes-ingested memories only.
+
+## Architecture
+
+```
+Hermes Agent (Python)
+  → plugins/memory/atomicmemory/__init__.py
+      → AtomicMemoryClient (Python protocol)
+          → PythonSdkAtomicMemoryClient
+              → published atomicmemory Python SDK MemoryClient
+```
+
+The Python provider owns Hermes lifecycle compatibility only — registration,
+hooks, tool schemas. Memory semantics flow through the published Python SDK.
+
+## Prerequisites
+
+- Hermes Agent installed and `HERMES_HOME` set
+- AtomicMemory core URL exported as `ATOMICMEMORY_API_URL`
+
+## Install (dev)
+
+The simplest dev install symlinks the plugin into Hermes' memory directory.
+Hermes installs the published `atomicmemory` SDK from `plugin.yaml`.
+
+```bash
+cd /path/to/atomicmemory-integrations
+mkdir -p "$HERMES_HOME/plugins/memory"
+ln -s "$(pwd)/plugins/hermes" "$HERMES_HOME/plugins/memory/atomicmemory"
+export ATOMICMEMORY_API_URL="http://localhost:3050"
+```
+
+Then select and verify the provider:
+
+```bash
+hermes memory setup
+# select "atomicmemory"
+hermes memory status
+# confirm "atomicmemory" is active
+```
+
+## Config
+
+Hermes' setup wizard prompts for a minimal pair (`scope_user`, `memory_scope`).
+Advanced settings live in `$HERMES_HOME/atomicmemory.json`.
+
+Connection details (`ATOMICMEMORY_API_URL`, `ATOMICMEMORY_API_KEY`) flow
+through environment variables into the Python SDK. The provider does not
+have a default API URL and fails to start if `ATOMICMEMORY_API_URL` is unset.
+
+### Environment
+
+| Env var | Purpose |
+|---|---|
+| `ATOMICMEMORY_API_URL` | AtomicMemory core URL. Required. |
+| `ATOMICMEMORY_API_KEY` | Bearer credential for AtomicMemory core. Optional. |
+| `ATOMICMEMORY_PROVIDER` | SDK provider name. Defaults to `atomicmemory`. |
+| `ATOMICMEMORY_SCOPE_USER` | Hermes user identity. Defaults to `$USER`. |
+| `ATOMICMEMORY_MEMORY_SCOPE` | `shared` (default) or `siloed`. |
+| `ATOMICMEMORY_MEMORY_MODE` | `hybrid` (default), `context`, or `tools`. |
+| `ATOMICMEMORY_PREFETCH_ENABLED` | `true`/`false`. Default `true`. |
+| `ATOMICMEMORY_PREFETCH_METHOD` | `context` (default) or `fast`. |
+| `ATOMICMEMORY_SEARCH_LIMIT` | Default search/list limit. |
+| `ATOMICMEMORY_TOKEN_BUDGET` | Default context-package token budget. |
+
+### Provider-local file
+
+`$HERMES_HOME/atomicmemory.json` accepts these keys (all optional):
+
+| Key | Description |
+|---|---|
+| `scope_user` | User identity. |
+| `scope_agent` | Hermes prompt label (does not change scoping). |
+| `memory_mode` | `hybrid` / `context` / `tools`. |
+| `memory_scope` | `shared` / `siloed`. |
+| `prefetch_enabled` | bool. |
+| `prefetch_method` | `context` / `fast`. |
+| `search_limit` | int. |
+| `token_budget` | int. |
+
+Secrets are never persisted here — `api_key` and `api_url` are deliberately
+not in the allowed key set.
+
+## Memory scope
+
+| Mode | Recall | Ingest |
+|---|---|---|
+| `shared` (default) | All AtomicMemory memories for the user | stamped `source_site=hermes` |
+| `siloed` | Only Hermes-ingested memories | stamped `source_site=hermes` |
+
+The `source_site` filter on recall is enforced through the Python SDK's
+AtomicMemory namespace handle. If the SDK is configured against a
+non-AtomicMemory provider (e.g. mem0), `siloed` mode fails loudly with
+`PROVIDER_UNSUPPORTED` rather than silently dropping the filter.
+
+## Memory mode
+
+`memory_mode` selects which Hermes surfaces AtomicMemory exposes:
+
+| Mode | Auto-recall + sync | Explicit tools |
+|---|---|---|
+| `hybrid` (default) | yes | yes |
+| `context` | yes | hidden |
+| `tools` | disabled | yes |
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `atomicmemory_search` | Search AtomicMemory by meaning. |
+| `atomicmemory_context` | Build an injection-ready context package. |
+| `atomicmemory_conclude` | Store one explicit durable fact verbatim. |
+| `atomicmemory_profile` | List recent records (description text varies by `memory_scope`). |
+
+## Lifecycle
+
+- `queue_prefetch(query)` searches AtomicMemory in a background thread, with
+  a generation counter so a slow earlier prefetch can't overwrite a faster
+  newer one.
+- `prefetch(query)` returns the most recent completed recall, then clears
+  the slot.
+- `sync_turn(user, assistant)` enqueues the turn to a single-writer worker
+  thread and returns immediately. The worker calls
+  `client.ingest_messages(...)` with `provenance.source = "hermes"` and
+  `provenance.sourceUrl = "hermes://session/<session_id>"`.
+- `on_session_end(messages)` drains the worker, then closes the SDK client.
+
+## Reliability
+
+A circuit breaker pauses SDK calls for two minutes after five
+consecutive failures and resets on the next success. Hermes continues to
+run while AtomicMemory is temporarily unavailable.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| Provider does not appear in `hermes memory setup` | Wrong install path. Memory providers must live under `$HERMES_HOME/plugins/memory/<name>/`, not `$HERMES_HOME/plugins/<name>/`. |
+| `is_available()` returns False | `ATOMICMEMORY_API_URL` unset, or the Hermes Python environment did not install the `atomicmemory` dependency from `plugin.yaml`. |
+| Import fails at startup | The Hermes Python environment is missing the SDK dependency from `plugin.yaml`. |
+| Calls fail with `PROVIDER_UNSUPPORTED` while `memory_scope=siloed` | The configured SDK provider is not the AtomicMemory core (e.g. it's `mem0`). Either switch `ATOMICMEMORY_PROVIDER=atomicmemory` or move to `memory_scope=shared`. |
+
+## Tests
+
+```bash
+# Python provider and SDK adapter (deterministic, no network)
+python3 -m unittest discover plugins/hermes/tests
+```

package/__init__.py

@@ -0,0 +1,333 @@
+"""AtomicMemory native memory provider for Hermes Agent (v2).
+
+Thin Python adapter over the AtomicMemory Python SDK. The provider owns Hermes
+lifecycle compatibility (provider registration, hook dispatch, tool schemas,
+worker supervision); all memory semantics flow through `AtomicMemoryClient`.
+
+Default scope is `shared` — Hermes recalls memories from every AtomicMemory
+tool the user has touched. Set `memory_scope=siloed` to restrict recall to
+Hermes-ingested memories only.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+from typing import Any, Callable
+
+from .breaker import CircuitBreaker
+from .client import (
+    AtomicMemoryClient,
+    BridgeError,
+    Message,
+    Provenance,
+)
+from .config import (
+    DEFAULT_USER_ID,
+    SOURCE_SITE,
+    ProviderConfig,
+    get_config_schema,
+    ingest_scope_dict,
+    load_config,
+    read_scope_kwargs,
+    save_config,
+)
+from .python_sdk import (
+    PythonSdkAtomicMemoryClient,
+    PythonSdkConfig,
+    sdk_is_available,
+)
+from .tools import (
+    CONCLUDE_SCHEMA,
+    CONTEXT_SCHEMA,
+    SEARCH_SCHEMA,
+    TOOL_HANDLERS,
+    format_memory_bullets,
+    profile_schema,
+)
+from .worker import IngestJob, IngestWorker
+
+
+try:
+    from agent.memory_provider import MemoryProvider  # type: ignore[import-not-found]
+except Exception:  # pragma: no cover — used only outside Hermes test runs.
+    class MemoryProvider:  # type: ignore[no-redef]
+        """Fallback base class so the provider can be unit-tested standalone."""
+
+
+try:
+    from tools.registry import tool_error  # type: ignore[import-not-found]
+except Exception:  # pragma: no cover — used only outside Hermes test runs.
+    def tool_error(message: str) -> str:
+        return json.dumps({"error": message})
+
+
+logger = logging.getLogger(__name__)
+
+
+class AtomicMemoryMemoryProvider(MemoryProvider):
+    """Hermes-compatible AtomicMemory memory provider."""
+
+    def __init__(
+        self,
+        *,
+        client_factory: Callable[[ProviderConfig], AtomicMemoryClient] | None = None,
+    ) -> None:
+        self._client_factory = client_factory or _default_client_factory
+        self._client: AtomicMemoryClient | None = None
+        self._config: ProviderConfig = ProviderConfig()
+        self._session_id: str = ""
+        self._user_id: str = DEFAULT_USER_ID
+
+        self._breaker = CircuitBreaker()
+        self._worker: IngestWorker | None = None
+
+        self._prefetch_lock = threading.Lock()
+        self._prefetch_result: str = ""
+        self._prefetch_generation: int = 0
+        self._prefetch_thread: threading.Thread | None = None
+
+    # ------------------------------------------------------------------
+    # Hermes provider contract
+    # ------------------------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        return "atomicmemory"
+
+    def is_available(self) -> bool:
+        if not os.environ.get("ATOMICMEMORY_API_URL"):
+            return False
+        return sdk_is_available()
+
+    def get_config_schema(self) -> list[dict[str, Any]]:
+        return get_config_schema()
+
+    def save_config(self, values: dict[str, Any], hermes_home: str) -> None:
+        save_config(values, hermes_home)
+
+    def initialize(self, session_id: str, **kwargs: Any) -> None:
+        hermes_home = kwargs.get("hermes_home")
+        self._config = load_config(hermes_home=hermes_home)
+        self._user_id = (
+            _clean_str(kwargs.get("user_id"))
+            or self._config.scope_user
+            or DEFAULT_USER_ID
+        )
+        self._session_id = session_id
+        client = self._client_factory(self._config)
+        client.initialize()
+        self._client = client
+        self._worker = IngestWorker(
+            run_job=self._run_ingest_job,
+            on_failure=self._on_ingest_failure,
+        )
+        self._worker.start()
+
+    def system_prompt_block(self) -> str:
+        action = (
+            "Use atomicmemory_search for targeted recall, atomicmemory_context for broad context, "
+            "and atomicmemory_conclude to store explicit durable facts."
+            if self._tools_enabled()
+            else "AtomicMemory recall is injected automatically; explicit AtomicMemory tools are disabled."
+        )
+        return (
+            "# AtomicMemory\n"
+            f"Active. User: {self._user_id}. Memory mode: {self._config.memory_mode}. "
+            f"Scope: {self._config.memory_scope}.\n"
+            f"{action}"
+        )
+
+    def queue_prefetch(self, query: str, *, session_id: str = "") -> None:
+        del session_id
+        if not self._context_enabled() or not self._config.prefetch_enabled:
+            return
+        if self._breaker.is_open() or not query:
+            return
+        with self._prefetch_lock:
+            self._prefetch_generation += 1
+            generation = self._prefetch_generation
+
+        def _run() -> None:
+            try:
+                result = self._prefetch_text(query)
+                if result:
+                    with self._prefetch_lock:
+                        if generation == self._prefetch_generation:
+                            self._prefetch_result = result
+                self._breaker.record_success()
+            except Exception as exc:  # noqa: BLE001
+                self._breaker.record_failure()
+                logger.debug("AtomicMemory prefetch failed: %s", exc)
+
+        self._prefetch_thread = threading.Thread(
+            target=_run, daemon=True, name="atomicmemory-prefetch",
+        )
+        self._prefetch_thread.start()
+
+    def prefetch(self, query: str, *, session_id: str = "") -> str:
+        del query, session_id
+        if not self._context_enabled():
+            return ""
+        thread = self._prefetch_thread
+        if thread is not None and thread.is_alive():
+            thread.join(timeout=3.0)
+        with self._prefetch_lock:
+            result = self._prefetch_result
+            self._prefetch_result = ""
+        return f"## AtomicMemory\n{result}" if result else ""
+
+    def sync_turn(self, user_content: str, assistant_content: str, *, session_id: str = "") -> None:
+        if not self._context_enabled() or self._breaker.is_open() or self._worker is None:
+            return
+        self._worker.submit(
+            IngestJob(
+                user_content=user_content,
+                assistant_content=assistant_content,
+                session_id=session_id or self._session_id,
+            ),
+        )
+
+    def on_session_end(self, messages: list[dict[str, Any]]) -> None:
+        del messages
+        self.shutdown()
+
+    def shutdown(self) -> None:
+        if self._worker is not None:
+            self._worker.shutdown()
+            self._worker = None
+        if self._client is not None:
+            try:
+                self._client.shutdown()
+            except Exception as exc:  # noqa: BLE001
+                logger.debug("AtomicMemory client shutdown failed: %s", exc)
+            self._client = None
+
+    def get_tool_schemas(self) -> list[dict[str, Any]]:
+        if not self._tools_enabled():
+            return []
+        return [
+            profile_schema(self._config.memory_scope),
+            SEARCH_SCHEMA,
+            CONTEXT_SCHEMA,
+            CONCLUDE_SCHEMA,
+        ]
+
+    def handle_tool_call(self, tool_name: str, args: dict[str, Any], **kwargs: Any) -> str:
+        del kwargs
+        if not self._tools_enabled():
+            return tool_error("AtomicMemory tools are disabled by memory_mode.")
+        if self._breaker.is_open():
+            return json.dumps(
+                {
+                    "error": (
+                        "AtomicMemory client temporarily unavailable after repeated failures. "
+                        "It will retry automatically."
+                    ),
+                },
+            )
+        handler = TOOL_HANDLERS.get(tool_name)
+        if handler is None:
+            return tool_error(f"Unknown tool: {tool_name}")
+        try:
+            result = handler(self, args)
+            self._breaker.record_success()
+            return result
+        except Exception as exc:  # noqa: BLE001
+            self._breaker.record_failure()
+            return tool_error(str(exc))
+
+    # ------------------------------------------------------------------
+    # Helpers shared with tools.py
+    # ------------------------------------------------------------------
+
+    def _context_enabled(self) -> bool:
+        return self._config.memory_mode in {"hybrid", "context"}
+
+    def _tools_enabled(self) -> bool:
+        return self._config.memory_mode in {"hybrid", "tools"}
+
+    def _require_client(self) -> AtomicMemoryClient:
+        if self._client is None:
+            raise BridgeError("AtomicMemory client not initialized", code="NOT_INITIALIZED")
+        return self._client
+
+    def _ingest_provenance(self, *, session_id: str) -> Provenance:
+        return Provenance(
+            source=SOURCE_SITE,
+            source_url=f"hermes://session/{session_id or self._session_id or 'default'}",
+        )
+
+    def _read_kwargs(self, *, limit_override: int | None = None) -> dict[str, Any]:
+        kwargs = read_scope_kwargs(memory_scope=self._config.memory_scope, user_id=self._user_id)
+        kwargs["limit"] = limit_override if limit_override is not None else self._config.search_limit
+        return kwargs
+
+    # ------------------------------------------------------------------
+    # Prefetch + ingest worker
+    # ------------------------------------------------------------------
+
+    def _prefetch_text(self, query: str) -> str:
+        client = self._require_client()
+        kwargs = read_scope_kwargs(memory_scope=self._config.memory_scope, user_id=self._user_id)
+        if self._config.prefetch_method == "fast":
+            page = client.search(
+                query=query,
+                scope=kwargs["scope"],
+                limit=self._config.search_limit,
+                source_site=kwargs.get("source_site"),
+            )
+            return format_memory_bullets(page)
+        package = client.package(
+            query=query,
+            scope=kwargs["scope"],
+            token_budget=self._config.token_budget,
+            source_site=kwargs.get("source_site"),
+        )
+        if package.injection_text:
+            return package.injection_text
+        return format_memory_bullets(package)
+
+    def _run_ingest_job(self, job: IngestJob) -> None:
+        if self._client is None:
+            return
+        try:
+            self._client.ingest_messages(
+                messages=[
+                    Message(role="user", content=job.user_content),
+                    Message(role="assistant", content=job.assistant_content),
+                ],
+                scope=ingest_scope_dict(user_id=self._user_id),
+                provenance=self._ingest_provenance(session_id=job.session_id),
+                metadata={"kind": "turn"},
+            )
+            self._breaker.record_success()
+        except Exception:
+            self._breaker.record_failure()
+            raise
+
+    def _on_ingest_failure(self, exc: BaseException) -> None:
+        logger.warning("AtomicMemory ingest failed: %s", exc)
+
+
+def _default_client_factory(config: ProviderConfig) -> AtomicMemoryClient:
+    return PythonSdkAtomicMemoryClient(
+        config=PythonSdkConfig(
+            provider=os.environ.get("ATOMICMEMORY_PROVIDER", "atomicmemory"),
+            api_url=os.environ.get("ATOMICMEMORY_API_URL"),
+            api_key=os.environ.get("ATOMICMEMORY_API_KEY"),
+        )
+    )
+
+
+def _clean_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    cleaned = str(value).strip()
+    return cleaned or None
+
+
+def register(ctx: Any) -> None:
+    ctx.register_memory_provider(AtomicMemoryMemoryProvider())

package/breaker.py

@@ -0,0 +1,57 @@
+"""Thread-safe circuit breaker — restored from v1, with a real lock.
+
+Wraps every SDK call. After `threshold` consecutive failures the breaker
+opens for `cooldown_seconds`; the next probing call after cooldown reads as
+closed (the counter is cleared eagerly on the read so a single success
+proves recovery).
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from dataclasses import dataclass
+
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CircuitBreaker:
+    threshold: int = 5
+    cooldown_seconds: float = 120.0
+    _consecutive_failures: int = 0
+    _open_until_monotonic: float = 0.0
+    _lock: threading.Lock = None  # type: ignore[assignment]
+
+    def __post_init__(self) -> None:
+        if self._lock is None:
+            self._lock = threading.Lock()
+
+    def is_open(self, *, now: float | None = None) -> bool:
+        clock = now if now is not None else time.monotonic()
+        with self._lock:
+            if self._consecutive_failures < self.threshold:
+                return False
+            if clock >= self._open_until_monotonic:
+                self._consecutive_failures = 0
+                return False
+            return True
+
+    def record_success(self) -> None:
+        with self._lock:
+            self._consecutive_failures = 0
+
+    def record_failure(self, *, now: float | None = None) -> None:
+        clock = now if now is not None else time.monotonic()
+        with self._lock:
+            self._consecutive_failures += 1
+            if self._consecutive_failures >= self.threshold:
+                self._open_until_monotonic = clock + self.cooldown_seconds
+                logger.warning(
+                    "AtomicMemory circuit breaker tripped after %d consecutive failures. "
+                    "Pausing calls for %.0fs.",
+                    self._consecutive_failures,
+                    self.cooldown_seconds,
+                )

package/client.py

@@ -0,0 +1,161 @@
+"""AtomicMemoryClient protocol.
+
+Narrow seam between the Hermes Python provider and the AtomicMemory Python SDK.
+The provider depends only on this interface so lifecycle code, tool handlers,
+scope policy, and tests are isolated from SDK-specific response shapes.
+
+The shapes here intentionally drop SDK fields the Hermes integration does
+not consume (importance, tier assignments, observability blocks). Add them
+when a call site needs them, not before.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+
+Scope = dict[str, Any]
+"""Scope dict matching the V3 MemoryClient shape: {user, agent?, namespace?, thread?}.
+
+Hermes uses user-only scope. Workspace scope is left available for future
+provider modes but is not exercised in v2.
+"""
+
+
+@dataclass(frozen=True)
+class Message:
+    """One turn message used by ingest_messages."""
+
+    role: str
+    content: str
+
+
+@dataclass(frozen=True)
+class Provenance:
+    """Ingest provenance. source is required by Hermes; everything else optional."""
+
+    source: str
+    source_url: str | None = None
+    source_id: str | None = None
+    extractor: str | None = None
+
+
+@dataclass(frozen=True)
+class MemoryItem:
+    """Minimal memory record consumed by Hermes tools (search/list/profile)."""
+
+    id: str | None
+    content: str
+    score: float | None = None
+    source_site: str | None = None
+    created_at: str | None = None
+
+
+@dataclass(frozen=True)
+class SearchPage:
+    memories: list[MemoryItem] = field(default_factory=list)
+    count: int = 0
+
+
+@dataclass(frozen=True)
+class ContextPackage:
+    injection_text: str = ""
+    memories: list[MemoryItem] = field(default_factory=list)
+    count: int = 0
+    estimated_context_tokens: int = 0
+    citations: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ListPage:
+    memories: list[MemoryItem] = field(default_factory=list)
+    count: int = 0
+
+
+@dataclass(frozen=True)
+class IngestResult:
+    created: list[str] = field(default_factory=list)
+    updated: list[str] = field(default_factory=list)
+    unchanged: list[str] = field(default_factory=list)
+
+
+class BridgeError(RuntimeError):
+    """Bridge call returned a typed error."""
+
+    def __init__(self, message: str, code: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class BridgeCrashedError(BridgeError):
+    """Client transport exited unexpectedly mid-call."""
+
+    def __init__(self, message: str = "AtomicMemory client transport exited") -> None:
+        super().__init__(message, code="BRIDGE_CRASHED")
+
+
+class ProviderUnsupportedError(BridgeError):
+    """Client returned PROVIDER_UNSUPPORTED — the active provider lacks a feature.
+
+    Today this happens when source_site is requested with a non-AtomicMemory
+    provider. The client fails loudly rather than silently dropping the filter.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, code="PROVIDER_UNSUPPORTED")
+
+
+class AtomicMemoryClient(Protocol):
+    """Narrow client surface used by the Hermes provider.
+
+    The production Python SDK implementation lives in python_sdk.py.
+    """
+
+    def initialize(self) -> None: ...
+
+    def shutdown(self) -> None: ...
+
+    def search(
+        self,
+        *,
+        query: str,
+        scope: Scope,
+        limit: int,
+        source_site: str | None = None,
+    ) -> SearchPage: ...
+
+    def package(
+        self,
+        *,
+        query: str,
+        scope: Scope,
+        token_budget: int,
+        source_site: str | None = None,
+    ) -> ContextPackage: ...
+
+    def list_recent(
+        self,
+        *,
+        scope: Scope,
+        limit: int,
+        source_site: str | None = None,
+    ) -> ListPage: ...
+
+    def ingest_messages(
+        self,
+        *,
+        messages: list[Message],
+        scope: Scope,
+        provenance: Provenance,
+        metadata: dict[str, Any] | None = None,
+    ) -> IngestResult: ...
+
+    def ingest_verbatim(
+        self,
+        *,
+        content: str,
+        scope: Scope,
+        provenance: Provenance,
+        metadata: dict[str, Any] | None = None,
+    ) -> IngestResult: ...