@gamaze/hicortex 0.7.0 → 0.10.0

package/hermes-plugin/hicortex/client.py

@@ -0,0 +1,162 @@
+"""Thin HTTP client for the Hicortex memory server.
+
+Stdlib-only (no pip dependencies) so the plugin installs with zero friction.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Optional
+
+
+class HicortexClient:
+    """Stateless HTTP client for the Hicortex REST surface."""
+
+    def __init__(
+        self,
+        base_url: str,
+        auth_token: Optional[str] = None,
+        timeout: float = 5.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        # Omit the token when targeting localhost — the server bypasses auth there.
+        # Match the server's bypass list exactly (mcp-server.ts): IPv4, IPv6,
+        # and IPv4-mapped-IPv6 (which Node reports for v4 clients on a 0.0.0.0 bind).
+        host = urllib.parse.urlparse(self.base_url).hostname or ""
+        self.auth_token = (
+            None
+            if host in ("127.0.0.1", "localhost", "::1", "::ffff:127.0.0.1")
+            else auth_token
+        )
+        self.timeout = timeout
+
+    def _headers(self) -> dict[str, str]:
+        h = {"Content-Type": "application/json", "Accept": "application/json"}
+        if self.auth_token:
+            h["Authorization"] = f"Bearer {self.auth_token}"
+        return h
+
+    def _get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        url = f"{self.base_url}{path}"
+        if params:
+            qs = urllib.parse.urlencode(
+                {k: v for k, v in params.items() if v is not None}
+            )
+            url = f"{url}?{qs}"
+        req = urllib.request.Request(url, headers=self._headers(), method="GET")
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+
+    def _post(self, path: str, body: dict[str, Any]) -> tuple[int, Any]:
+        """POST JSON body; returns (status_code, parsed_response)."""
+        url = f"{self.base_url}{path}"
+        data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(url, data=data, headers=self._headers(), method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return resp.status, json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            body_bytes = e.read()
+            try:
+                parsed = json.loads(body_bytes.decode("utf-8"))
+            except Exception:
+                parsed = {"error": body_bytes.decode("utf-8", errors="replace")}
+            return e.code, parsed
+
+    # -- endpoints ------------------------------------------------------------
+
+    def health(self) -> dict[str, Any]:
+        return self._get("/health")
+
+    def search(
+        self,
+        query: str,
+        limit: int = 5,
+        project: Optional[str] = None,
+        privacy: Optional[str] = None,
+    ) -> list[dict]:
+        return self._get(
+            "/search",
+            {"query": query, "limit": limit, "project": project, "privacy": privacy},
+        ).get("results", [])
+
+    def context(
+        self,
+        project: Optional[str] = None,
+        limit: int = 10,
+        privacy: Optional[str] = None,
+    ) -> list[dict]:
+        return self._get(
+            "/context", {"project": project, "limit": limit, "privacy": privacy}
+        ).get("results", [])
+
+    def lessons(self) -> dict[str, Any]:
+        return self._get("/lessons")
+
+    def index(self) -> dict[str, Any]:
+        return self._get("/index")
+
+    def graph(
+        self,
+        op: str,
+        id: Optional[str] = None,
+        target_id: Optional[str] = None,
+        limit: Optional[int] = None,
+        domain: Optional[str] = None,
+        relationship: Optional[str] = None,
+    ) -> dict[str, Any]:
+        return self._get(
+            "/graph",
+            {
+                "op": op,
+                "id": id,
+                "target_id": target_id,
+                "limit": limit,
+                "domain": domain,
+                "relationship": relationship,
+            },
+        )
+
+    def ingest(
+        self,
+        content: str,
+        source_agent: Optional[str] = None,
+        project: Optional[str] = None,
+        memory_type: str = "episode",
+        privacy: str = "WORK",
+    ) -> tuple[int, dict[str, Any]]:
+        return self._post(
+            "/ingest",
+            {
+                "content": content,
+                "source_agent": source_agent or "hermes/manual",
+                "project": project,
+                "memory_type": memory_type,
+                "privacy": privacy,
+            },
+        )
+
+    def update(
+        self,
+        id: str,
+        content: Optional[str] = None,
+        project: Optional[str] = None,
+        memory_type: Optional[str] = None,
+        privacy: Optional[str] = None,
+    ) -> tuple[int, dict[str, Any]]:
+        body: dict[str, Any] = {"id": id}
+        if content is not None:
+            body["content"] = content
+        if project is not None:
+            body["project"] = project
+        if memory_type is not None:
+            body["memory_type"] = memory_type
+        if privacy is not None:
+            body["privacy"] = privacy
+        return self._post("/update", body)
+
+    def delete(self, id: str) -> tuple[int, dict[str, Any]]:
+        return self._post("/delete", {"id": id})

package/hermes-plugin/hicortex/config.py

@@ -0,0 +1,105 @@
+"""Config schema + load/save for the Hicortex Hermes plugin.
+
+Config lives at ``$HERMES_HOME/plugins/hicortex/config.json``. Environment
+variables (``HICORTEX_URL``, ``HICORTEX_AUTH_TOKEN``) override the file, so the
+plugin also works with env-only setup.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Dict, Optional
+
+# Declarative config schema — drives `hermes memory setup` (see MemoryProvider
+# .get_config_schema). Field shape per the Hermes MemoryProvider contract:
+# key, label, description, default, required, secret, env_var, choices, url.
+CONFIG_SCHEMA: list[dict[str, Any]] = [
+    {
+        "key": "hicortex_url",
+        "label": "Hicortex server URL",
+        "description": (
+            "URL of the Hicortex memory server. On the server host use "
+            "http://localhost:8787; on other machines use the server's "
+            "Tailscale hostname, e.g. http://memory-server:8787."
+        ),
+        "default": "http://localhost:8787",
+        "required": True,
+    },
+    {
+        "key": "hicortex_auth_token",
+        "label": "Auth token",
+        "description": (
+            "Bearer token for the server. Omit (leave blank) when targeting "
+            "localhost — the server bypasses auth there. Default token: "
+            "hctx-default-token."
+        ),
+        "secret": True,
+        "env_var": "HICORTEX_AUTH_TOKEN",
+    },
+    {
+        "key": "default_project",
+        "label": "Default project",
+        "description": "Optional project name to scope recall and capture.",
+        "required": False,
+    },
+    {
+        "key": "recall_limit",
+        "label": "Recall limit",
+        "description": "Max memories returned per recall (default 5).",
+        "default": "5",
+        "required": False,
+    },
+    {
+        "key": "privacy_filter",
+        "label": "Privacy filter",
+        "description": "Comma-separated privacy levels to include (e.g. WORK,PERSONAL).",
+        "default": "WORK,PERSONAL",
+        "required": False,
+    },
+    # NOTE: recall-only plugin — no capture config. Capture is handled by the
+    # nightly server-side reader of each agent's session store.
+]
+
+
+def _config_path(hermes_home: Optional[str] = None) -> str:
+    home = hermes_home or os.environ.get("HERMES_HOME") or os.path.expanduser("~/.hermes")
+    return os.path.join(home, "plugins", "hicortex", "config.json")
+
+
+def load_config() -> Dict[str, Any]:
+    """Load merged config: file <- env overrides <- defaults."""
+    path = _config_path()
+    cfg: Dict[str, Any] = {}
+    if os.path.exists(path):
+        try:
+            with open(path, encoding="utf-8") as f:
+                cfg = json.load(f) or {}
+        except Exception:
+            cfg = {}
+
+    # Env overrides
+    if os.environ.get("HICORTEX_URL"):
+        cfg["hicortex_url"] = os.environ["HICORTEX_URL"]
+    if os.environ.get("HICORTEX_AUTH_TOKEN"):
+        cfg["hicortex_auth_token"] = os.environ["HICORTEX_AUTH_TOKEN"]
+
+    # Defaults
+    cfg.setdefault("hicortex_url", "http://localhost:8787")
+    cfg.setdefault("recall_limit", 5)
+    cfg.setdefault("privacy_filter", "WORK,PERSONAL")
+    return cfg
+
+
+def save_config(values: Dict[str, Any], hermes_home: str) -> None:
+    """Write non-secret config values to the plugin's config file.
+
+    Called by `hermes memory setup` after collecting user inputs. Secret fields
+    (hicortex_auth_token) are routed to the env store by Hermes, not written here.
+    """
+    path = _config_path(hermes_home)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    # Don't persist secrets to the JSON file — Hermes stores them separately.
+    safe = {k: v for k, v in values.items() if k != "hicortex_auth_token"}
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(safe, f, indent=2)

package/hermes-plugin/hicortex/plugin.yaml

@@ -0,0 +1,12 @@
+name: hicortex
+version: 0.4.0
+description: "Self-learning memory for Hermes agents — every session is distilled into lessons overnight, and your agent wakes up wiser. Injects fresh lessons each turn and exposes the full 8-tool memory surface (search, context, ingest, lessons, index, graph, update, delete) via a shared Hicortex server. Stdlib-only."
+pip_dependencies: []
+hooks: []
+requires_env:
+  - name: HICORTEX_URL
+    description: "Hicortex server URL. Leave empty for a local server (http://127.0.0.1:8787)."
+    secret: false
+  - name: HICORTEX_AUTH_TOKEN
+    description: "Auth token from the Hicortex server — run `hicortex status` on the server to see it. Leave empty when the server runs on this machine (localhost bypasses auth)."
+    secret: true