hydradb-hermes 1.0.1__tar.gz

hydradb_hermes-1.0.1/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+.venv/

hydradb_hermes-1.0.1/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 HydraDB Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

hydradb_hermes-1.0.1/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: hydradb-hermes
+Version: 1.0.1
+Summary: HydraDB memory provider for Hermes Agent.
+Project-URL: Homepage, https://hydradb.com
+Project-URL: Repository, https://github.com/hydra-db/hydradb-hermes
+Author-email: HydraDB <support@hydradb.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: hermes,hydradb,memory,recall,retain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.28
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Requires-Dist: responses>=0.24; extra == 'test'
+Description-Content-Type: text/markdown
+
+# HydraDB for Hermes Agent
+
+A [Hermes Agent](https://hermes-agent.nousresearch.com/docs/) **memory provider**
+backed by [HydraDB](https://hydradb.com): relevant context is recalled before
+each turn and completed turns are persisted - the proper native way to make
+HydraDB Hermes' long-term memory (like the supermemory / retaindb / ham providers).
+
+## How it works
+
+Implements Hermes' `MemoryProvider` contract:
+
+| Method | Role → HydraDB |
+|---|---|
+| `prefetch(query, *, session_id)` | **auto-recall** - returns context injected before the API call → hybrid `POST /query` (prefers server `llm_prompt`) |
+| `sync_turn(user, assistant, ...)` | persist the turn (**non-blocking**, off-thread) → `POST /context/ingest` |
+| `is_available()` | `bool(HYDRADB_API_KEY)` |
+| `get_config_schema()` / `save_config()` | setup wizard (api key, tenant) |
+| `name` | `"hydradb"` |
+
+Public API only (recall + knowledge ingest); no HydraDB SDK required.
+
+## Prerequisites
+
+- Python >= 3.10, a Hermes Agent install
+- A HydraDB account: API key + tenant ID ([hydradb.com](https://hydradb.com))
+
+## Install
+
+**Directory (drop-in):** copy the `hydradb_hermes/` folder into
+`~/.hermes/plugins/memory/hydradb/` (it contains `__init__.py` + `plugin.yaml`).
+
+**pip (entry point):** `pip install hydradb-hermes` - registered via the
+`hermes_agent.memory_providers` entry point.
+
+Then enable it in `config.yaml` (memory providers are single-select):
+
+```yaml
+memory:
+  provider: hydradb
+```
+
+Credentials come from the environment:
+
+```bash
+export HYDRADB_API_KEY="your-api-key"
+export HYDRADB_DATABASE="your-tenant-id"
+```
+
+## Test
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## MCP alternative
+
+For pull-style recall (agent-invoked tools) instead of automatic memory, point
+Hermes at the MCP server (see `hermes-mcp.snippet.json`). The provider gives
+automatic recall/retain, so MCP is optional.
+
+## License
+
+Apache-2.0 - Copyright (c) 2026 HydraDB

hydradb_hermes-1.0.1/README.md

@@ -0,0 +1,64 @@
+# HydraDB for Hermes Agent
+
+A [Hermes Agent](https://hermes-agent.nousresearch.com/docs/) **memory provider**
+backed by [HydraDB](https://hydradb.com): relevant context is recalled before
+each turn and completed turns are persisted - the proper native way to make
+HydraDB Hermes' long-term memory (like the supermemory / retaindb / ham providers).
+
+## How it works
+
+Implements Hermes' `MemoryProvider` contract:
+
+| Method | Role → HydraDB |
+|---|---|
+| `prefetch(query, *, session_id)` | **auto-recall** - returns context injected before the API call → hybrid `POST /query` (prefers server `llm_prompt`) |
+| `sync_turn(user, assistant, ...)` | persist the turn (**non-blocking**, off-thread) → `POST /context/ingest` |
+| `is_available()` | `bool(HYDRADB_API_KEY)` |
+| `get_config_schema()` / `save_config()` | setup wizard (api key, tenant) |
+| `name` | `"hydradb"` |
+
+Public API only (recall + knowledge ingest); no HydraDB SDK required.
+
+## Prerequisites
+
+- Python >= 3.10, a Hermes Agent install
+- A HydraDB account: API key + tenant ID ([hydradb.com](https://hydradb.com))
+
+## Install
+
+**Directory (drop-in):** copy the `hydradb_hermes/` folder into
+`~/.hermes/plugins/memory/hydradb/` (it contains `__init__.py` + `plugin.yaml`).
+
+**pip (entry point):** `pip install hydradb-hermes` - registered via the
+`hermes_agent.memory_providers` entry point.
+
+Then enable it in `config.yaml` (memory providers are single-select):
+
+```yaml
+memory:
+  provider: hydradb
+```
+
+Credentials come from the environment:
+
+```bash
+export HYDRADB_API_KEY="your-api-key"
+export HYDRADB_DATABASE="your-tenant-id"
+```
+
+## Test
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+## MCP alternative
+
+For pull-style recall (agent-invoked tools) instead of automatic memory, point
+Hermes at the MCP server (see `hermes-mcp.snippet.json`). The provider gives
+automatic recall/retain, so MCP is optional.
+
+## License
+
+Apache-2.0 - Copyright (c) 2026 HydraDB

hydradb_hermes-1.0.1/hermes-mcp.snippet.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "hydradb": {
+      "url": "https://mcp.hydradb.com",
+      "headers": { "Authorization": "Bearer ${HYDRADB_API_KEY}" }
+    }
+  }
+}

hydradb_hermes-1.0.1/hydradb_hermes/README.md

@@ -0,0 +1,49 @@
+# HydraDB memory provider for Hermes
+
+Long-term memory for [Hermes Agent](https://hermes-agent.nousresearch.com/docs/),
+backed by [HydraDB](https://hydradb.com). Context is recalled before each turn and
+completed turns are persisted, over the public HydraDB API.
+
+## How it works
+
+Registers a `MemoryProvider`:
+
+| Method | Role |
+|---|---|
+| `prefetch(query)` | recall relevant context before a turn via `POST /query` (uses the server `llm_prompt` when present) |
+| `sync_turn(user, assistant)` | persist the completed turn off-thread via `POST /context/ingest` |
+
+No tools, hooks, or middleware. Public API only; no HydraDB SDK required.
+
+## Setup
+
+Run `hermes memory setup` and pick `hydradb`, or set the environment directly:
+
+```bash
+export HYDRADB_API_KEY="your-api-key"
+export HYDRADB_DATABASE="your-tenant-id"
+# optional: HYDRADB_COLLECTION, HYDRADB_BASE_URL
+```
+
+Then enable it:
+
+```yaml
+memory:
+  provider: hydradb
+```
+
+## Configuration
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `HYDRADB_API_KEY` | yes | HydraDB API key (secret) |
+| `HYDRADB_DATABASE` | yes | database/tenant to read and write |
+| `HYDRADB_COLLECTION` | no | sub-tenant scope |
+| `HYDRADB_BASE_URL` | no | defaults to `https://api.hydradb.com` |
+
+The provider reports unavailable until `HYDRADB_API_KEY` and `HYDRADB_DATABASE`
+are both set.
+
+## License
+
+Apache-2.0, Copyright (c) 2026 HydraDB

hydradb_hermes-1.0.1/hydradb_hermes/__init__.py

@@ -0,0 +1,108 @@
+"""HydraDB as a Hermes Agent memory provider.
+
+Implements the ``MemoryProvider`` contract: ``prefetch`` recalls relevant context
+before each turn (auto-recall), ``sync_turn`` persists completed turns
+(non-blocking), over the public HydraDB API via the shared client.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+from typing import Any, Optional
+
+from .client import HydraDBClient
+
+#: Canonical HydraDB env var -> accepted deprecated aliases. The canonical name
+#: wins; the alias keeps older setups (and the pre-rename catalog entry) working.
+_ENV_ALIASES = {
+    "HYDRADB_DATABASE": ("HYDRADB_TENANT_ID",),
+    "HYDRADB_COLLECTION": ("HYDRADB_SUB_TENANT_ID",),
+}
+
+
+def _env(canonical: str, default: str = "") -> str:
+    """Resolve a HydraDB env var by canonical name, falling back to aliases."""
+    val = os.environ.get(canonical)
+    if val is not None:
+        return val
+    for alias in _ENV_ALIASES.get(canonical, ()):  # pragma: no branch
+        val = os.environ.get(alias)
+        if val is not None:
+            return val
+    return default
+
+
+try:
+    from agent.memory_provider import MemoryProvider as _BaseMemoryProvider
+except Exception:  # pragma: no cover
+
+    class _BaseMemoryProvider:
+        pass
+
+
+class HydraDBMemoryProvider(_BaseMemoryProvider):
+    """Recall/retain backed by HydraDB (public API only)."""
+
+    def __init__(self, client: Optional[HydraDBClient] = None) -> None:
+        self._client = client
+        self._search_mode = "knowledge"
+
+    @property
+    def name(self) -> str:
+        return "hydradb"
+
+    def is_available(self) -> bool:
+        return bool(os.environ.get("HYDRADB_API_KEY") and _env("HYDRADB_DATABASE"))
+
+    def initialize(self, session_id: str, **kwargs: Any) -> None:
+        if self._client is None:
+            self._client = HydraDBClient(
+                api_key=os.environ.get("HYDRADB_API_KEY", ""),
+                tenant_id=_env("HYDRADB_DATABASE"),
+                sub_tenant_id=_env("HYDRADB_COLLECTION"),
+                base_url=os.environ.get("HYDRADB_BASE_URL", "https://api.hydradb.com"),
+            )
+
+    def get_config_schema(self):
+        # Hermes reads the `env_var` key to persist each value into .env during
+        # `hermes memory setup`; the provider then resolves them from the
+        # environment on start (see is_available/initialize). Older
+        # HYDRADB_TENANT_ID / HYDRADB_SUB_TENANT_ID remain accepted as aliases.
+        return [
+            {"key": "api_key", "env_var": "HYDRADB_API_KEY", "secret": True, "required": True},
+            {"key": "database", "env_var": "HYDRADB_DATABASE", "required": True},
+            {"key": "collection", "env_var": "HYDRADB_COLLECTION", "required": False},
+        ]
+
+    def get_tool_schemas(self):
+        return []
+
+    def system_prompt_block(self) -> str:
+        return "HydraDB provides persistent long-term memory. Relevant memories are recalled automatically before each turn."
+
+    def prefetch(self, query: str, *, session_id: str = "") -> str:
+        if not query or self._client is None:
+            return ""
+        try:
+            return self._client.recall_prompt(query, kind=self._search_mode)
+        except Exception:
+            return ""
+
+    def sync_turn(self, user: str, assistant: str, *, session_id: str = "", messages: Any = None) -> None:
+        """Persist a completed turn. MUST be non-blocking, so ingest off-thread."""
+        if self._client is None:
+            return
+        client = self._client
+
+        def _persist() -> None:
+            try:
+                client.add_conversation(user, assistant, infer=False)
+            except Exception:
+                pass
+
+        threading.Thread(target=_persist, daemon=True).start()
+
+
+def register(ctx) -> None:
+    ctx.register_memory_provider(HydraDBMemoryProvider())

hydradb_hermes-1.0.1/hydradb_hermes/client.py

@@ -0,0 +1,273 @@
+"""Minimal HydraDB HTTP client - public API only.
+
+Wraps the three public endpoints these integrations need:
+
+* ``POST /query``          - hybrid recall over memory or knowledge (JSON body)
+* ``POST /context/ingest`` - write knowledge (multipart ``app_knowledge``)
+* ``DELETE /context``      - remove context by id (JSON body)
+
+Ingestion uses the public knowledge path (``app_knowledge``); the memory-family
+write route is not exposed on the public API, so text/conversations are stored
+as knowledge. Auth is ``Authorization: Bearer <api_key>``. Responses are the
+standard ``{"success", "data", "error", "meta"}`` envelope; recall results live
+in ``data.chunks``. Chunks are normalised so callers do not depend on the wire
+shape.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Iterable
+
+import requests
+
+DEFAULT_BASE_URL = "https://api.hydradb.com"
+
+
+class HydraDBError(RuntimeError):
+    """Raised when the HydraDB API returns an error envelope or bad status."""
+
+
+@dataclass
+class HydraChunk:
+    """A single recalled chunk, normalised across memory/knowledge results."""
+
+    text: str
+    score: float | None = None
+    source_title: str = ""
+    id: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class HydraDBClient:
+    """Thin, dependency-light client for HydraDB recall and ingestion."""
+
+    def __init__(
+        self,
+        api_key: str,
+        tenant_id: str,
+        sub_tenant_id: str = "",
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 15.0,
+        session: requests.Session | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        if not tenant_id:
+            raise ValueError("tenant_id is required")
+        self.api_key = api_key
+        self.tenant_id = tenant_id
+        self.sub_tenant_id = sub_tenant_id
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+
+    @property
+    def _auth_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+    def _unwrap(self, resp: requests.Response) -> dict[str, Any]:
+        try:
+            body = resp.json()
+        except ValueError:
+            raise HydraDBError(f"HTTP {resp.status_code}: {resp.text[:200]}")
+        if not body.get("success", False):
+            err = body.get("error") or {}
+            raise HydraDBError(
+                f"{err.get('code', 'ERROR')}: {err.get('message', resp.text[:200])}"
+            )
+        return body.get("data") or {}
+
+    def query(
+        self,
+        query: str,
+        kind: str = "memory",
+        mode: str = "fast",
+        max_results: int = 6,
+        alpha: float = 0.8,
+        recency_bias: float = 0.0,
+        graph_context: bool = True,
+    ) -> list[HydraChunk]:
+        """Hybrid recall. ``kind`` is ``"memory"`` or ``"knowledge"``."""
+        payload = {
+            "tenant_id": self.tenant_id,
+            "sub_tenant_id": self.sub_tenant_id,
+            "query": query,
+            "kind": kind,
+            "mode": mode,
+            "max_results": max_results,
+            "alpha": alpha,
+            "recency_bias": recency_bias,
+            "graph_context": graph_context,
+        }
+        resp = self._session.post(
+            f"{self.base_url}/query",
+            headers={**self._auth_headers, "Content-Type": "application/json"},
+            json=payload,
+            timeout=self.timeout,
+        )
+        data = self._unwrap(resp)
+        return [_to_chunk(c) for c in (data.get("chunks") or [])]
+
+    def recall_prompt(
+        self,
+        query: str,
+        kind: str = "knowledge",
+        mode: str = "fast",
+        max_results: int = 6,
+    ) -> str:
+        """Hybrid recall as a ready-to-inject string.
+
+        Prefers the server-rendered ``llm_prompt`` when present; otherwise builds
+        a compact block from the recalled chunks. Returns ``""`` when nothing is
+        recalled.
+        """
+        payload = {
+            "tenant_id": self.tenant_id,
+            "sub_tenant_id": self.sub_tenant_id,
+            "query": query,
+            "kind": kind,
+            "mode": mode,
+            "max_results": max_results,
+        }
+        resp = self._session.post(
+            f"{self.base_url}/query",
+            headers={**self._auth_headers, "Content-Type": "application/json"},
+            json=payload,
+            timeout=self.timeout,
+        )
+        data = self._unwrap(resp)
+        prompt = data.get("llm_prompt")
+        if isinstance(prompt, str) and prompt.strip():
+            return prompt
+        chunks = [_to_chunk(c) for c in (data.get("chunks") or [])]
+        lines = [f"- {c.text}" for c in chunks if c.text]
+        return "Relevant HydraDB memory:\n" + "\n".join(lines) if lines else ""
+
+    def add_knowledge(self, items: Iterable[dict[str, Any]]) -> dict[str, Any]:
+        """Ingest ``app_knowledge`` items via the public ``/context/ingest``.
+
+        Each item is ``{"id", "title", "content": {"text": ...}, "metadata",
+        "infer"}``. Ingestion is asynchronous: a success here means the sources
+        were accepted/queued, not yet indexed.
+        """
+        fields = {
+            "tenant_id": (None, self.tenant_id),
+            "sub_tenant_id": (None, self.sub_tenant_id),
+            "kind": (None, "knowledge"),
+            "app_knowledge": (None, json.dumps(list(items))),
+        }
+        resp = self._session.post(
+            f"{self.base_url}/context/ingest",
+            headers=self._auth_headers,
+            files=fields,
+            timeout=self.timeout,
+        )
+        return self._unwrap(resp)
+
+    def add_text(
+        self,
+        text: str,
+        infer: bool = True,
+        title: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        source_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Store a single note as knowledge. Returns the ingest ack."""
+        item = {
+            "id": source_id or f"note-{uuid.uuid4().hex}",
+            "title": title or "note",
+            "content": {"text": text},
+            "metadata": metadata or {},
+            "infer": infer,
+        }
+        return self.add_knowledge([item])
+
+    def add_conversation(
+        self, user: str, assistant: str, infer: bool = True
+    ) -> dict[str, Any]:
+        """Store a user/assistant turn as knowledge."""
+        return self.add_text(
+            f"User: {user}\nAssistant: {assistant}", infer=infer, title="conversation"
+        )
+
+    def delete(self, ids: list[str], kind: str = "knowledge") -> dict[str, Any]:
+        ids = [i for i in (ids or []) if i]
+        if not ids:
+            return {"deleted_count": 0, "results": []}
+        resp = self._session.delete(
+            f"{self.base_url}/context",
+            headers={**self._auth_headers, "Content-Type": "application/json"},
+            json={
+                "tenant_id": self.tenant_id,
+                "sub_tenant_id": self.sub_tenant_id,
+                "ids": ids,
+                "kind": kind,
+            },
+            timeout=self.timeout,
+        )
+        return self._unwrap(resp)
+
+
+def _to_chunk(raw: dict[str, Any]) -> HydraChunk:
+    """Normalise a wire chunk into :class:`HydraChunk`.
+
+    ``chunk_content`` is often a stored envelope whose prose lives at
+    ``content.text``; recall must yield the prose, not the JSON scaffolding
+    (mirrors the plugin's normalizeRetrievalResponse). Content that merely looks
+    JSON-ish but does not parse is passed through untouched.
+    """
+    raw_text = raw.get("chunk_content")
+    if raw_text is None:
+        raw_text = raw.get("text") or raw.get("content") or ""
+    return HydraChunk(
+        text=_extract_text(raw_text),
+        score=raw.get("relevancy_score") or raw.get("score") or raw.get("relevance_score"),
+        source_title=raw.get("source_title") or raw.get("title") or "",
+        id=raw.get("chunk_uuid") or raw.get("id") or "",
+        metadata=raw.get("metadata") or {},
+    )
+
+
+def _extract_text(value: Any) -> str:
+    """Unwrap a HydraDB content envelope to its prose, else return as-is.
+
+    Recall may return the stored envelope JSON followed by trailing graph
+    enrichment (``"\\n\\nExtra context: ..."``). The envelope is decoded from the
+    front with ``raw_decode`` so the trailing text no longer defeats the unwrap;
+    the prose is returned with any enrichment appended and the JSON dropped.
+    """
+    if isinstance(value, dict):
+        return _prose_from_envelope(value) or json.dumps(value)
+    if not isinstance(value, str):
+        return str(value)
+    stripped = value.strip()
+    if stripped.startswith("{"):
+        try:
+            obj, end = json.JSONDecoder().raw_decode(stripped)
+        except ValueError:
+            return value
+        prose = _prose_from_envelope(obj)
+        if prose is not None:
+            trailing = stripped[end:].strip()
+            return f"{prose}\n\n{trailing}" if trailing else prose
+    return value
+
+
+def _prose_from_envelope(obj: Any) -> str | None:
+    if not isinstance(obj, dict):
+        return None
+    content = obj.get("content")
+    if isinstance(content, dict):
+        for key in ("text", "markdown"):
+            val = content.get(key)
+            if isinstance(val, str) and val.strip():
+                return val
+    if isinstance(content, str) and content.strip():
+        return content
+    top = obj.get("text")
+    if isinstance(top, str) and top.strip():
+        return top
+    return None

hydradb_hermes-1.0.1/hydradb_hermes/plugin.yaml

@@ -0,0 +1,10 @@
+name: hydradb
+version: 1.0.0
+description: "HydraDB long-term memory for Hermes Agent: prompt-time recall (prefetch) and non-blocking turn capture (sync_turn) over the public HydraDB API. Registered as a MemoryProvider; no general tools or lifecycle hooks."
+requires_hermes: ">=0.21.5"
+provides_tools: []
+provides_hooks: []
+provides_middleware: []
+requires_env:
+  - HYDRADB_API_KEY
+  - HYDRADB_DATABASE

hydradb_hermes-1.0.1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hydradb-hermes"
+version = "1.0.1"
+description = "HydraDB memory provider for Hermes Agent."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "HydraDB", email = "support@hydradb.com" }]
+keywords = ["hydradb", "hermes", "memory", "recall", "retain"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["requests>=2.28"]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "responses>=0.24"]
+
+[project.entry-points."hermes_agent.memory_providers"]
+hydradb = "hydradb_hermes:register"
+
+[project.urls]
+Homepage = "https://hydradb.com"
+Repository = "https://github.com/hydra-db/hydradb-hermes"
+
+[tool.hatch.build.targets.wheel]
+packages = ["hydradb_hermes"]
+
+[tool.pytest.ini_options]
+addopts = "--import-mode=importlib"

hydradb_hermes-1.0.1/tests/test_smoke.py

@@ -0,0 +1,95 @@
+"""Offline tests for the HydraDB Hermes memory provider (no Hermes/network)."""
+
+import time
+
+import responses
+
+from hydradb_hermes import HydraDBMemoryProvider
+from hydradb_hermes.client import HydraDBClient
+
+BASE = "https://api.hydradb.com"
+
+
+def _provider():
+    client = HydraDBClient(api_key="k", tenant_id="test_beam", sub_tenant_id="")
+    return HydraDBMemoryProvider(client=client)
+
+
+@responses.activate
+def test_prefetch_prefers_server_llm_prompt():
+    responses.add(
+        responses.POST,
+        f"{BASE}/query",
+        json={
+            "success": True,
+            "data": {"llm_prompt": "# Query results\n- mascot is Hydrabyte", "chunks": []},
+            "error": None,
+        },
+        status=200,
+    )
+    out = _provider().prefetch("mascot", session_id="s1")
+    assert "mascot is Hydrabyte" in out
+
+
+@responses.activate
+def test_prefetch_falls_back_to_chunks():
+    responses.add(
+        responses.POST,
+        f"{BASE}/query",
+        json={
+            "success": True,
+            "data": {"chunks": [{"chunk_content": "deploy on Fridays", "chunk_uuid": "c1"}]},
+            "error": None,
+        },
+        status=200,
+    )
+    out = _provider().prefetch("deploy", session_id="s1")
+    assert "deploy on Fridays" in out
+
+
+@responses.activate
+def test_sync_turn_ingests_non_blocking():
+    responses.add(
+        responses.POST,
+        f"{BASE}/context/ingest",
+        json={"success": True, "data": {"success_count": 1}, "error": None},
+        status=200,
+    )
+    _provider().sync_turn("what is X?", "X is Y", session_id="s1")
+    for _ in range(50):
+        if responses.calls:
+            break
+        time.sleep(0.02)
+    assert responses.calls
+    body = responses.calls[0].request.body
+    assert b"app_knowledge" in body
+
+
+def test_is_available_requires_key_and_tenant(monkeypatch):
+    monkeypatch.delenv("HYDRADB_API_KEY", raising=False)
+    monkeypatch.delenv("HYDRADB_DATABASE", raising=False)
+    assert _provider().is_available() is False
+    monkeypatch.setenv("HYDRADB_API_KEY", "x")
+    assert _provider().is_available() is False
+    monkeypatch.setenv("HYDRADB_DATABASE", "t")
+    assert _provider().is_available() is True
+
+
+def test_name_and_schema():
+    p = _provider()
+    assert p.name == "hydradb"
+    assert any(f["key"] == "api_key" for f in p.get_config_schema())
+
+
+def test_extract_text_unwraps_envelope_with_trailing_context():
+    """Recall text may be an envelope JSON plus trailing 'Extra context'."""
+    from hydradb_hermes.client import _extract_text
+
+    raw = (
+        '{"content": {"text": "Ship Friday."}, "document_metadata": {"a": "b"}}'
+        "\n\nExtra context: The beta ships Friday."
+    )
+    out = _extract_text(raw)
+    assert out.startswith("Ship Friday.")
+    assert "Extra context:" in out
+    assert "document_metadata" not in out