hermes-plugin-qdrant-memory 0.2.0__py3-none-any.whl

qdrant_memory/models.py

@@ -0,0 +1,130 @@
+"""Stable payload, identity, size and source-version contracts."""
+
+import hashlib
+import json
+import math
+import unicodedata
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+NAMESPACE = uuid.UUID("0e039c91-9509-57b6-877a-e878e1d61d93")
+UTC_OFFSET = "+00:00"
+
+
+def now():
+    """Return the current UTC instant as an RFC3339 string."""
+    return datetime.now(UTC).isoformat().replace(UTC_OFFSET, "Z")
+
+
+def digest(value):
+    """Hash canonical JSON for durable identity and verification."""
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, ensure_ascii=False, separators=(",", ":")).encode()
+    ).hexdigest()
+
+
+def normalize(text):
+    """Normalize Unicode and whitespace without changing stored display text."""
+    return " ".join(unicodedata.normalize("NFKC", text).split())
+
+
+def content_hash(text):
+    """Hash normalized text for exact scoped duplicate detection."""
+    return "sha256:" + hashlib.sha256(normalize(text).encode()).hexdigest()
+
+
+@dataclass(frozen=True)
+class Scope:
+    """Identify a memory partition by user and optional agent identity."""
+
+    user_id: str
+    agent_id: str | None
+
+    def as_dict(self):
+        """Return the payload fields used by every scope check."""
+        return {"user_id": self.user_id, "agent_id": self.agent_id}
+
+
+def point_id(scope, source, source_id):
+    """Derive a deterministic UUID from scope, source and source identity."""
+    return str(
+        uuid.uuid5(
+            NAMESPACE,
+            json.dumps([scope.user_id, scope.agent_id, source, source_id], ensure_ascii=False),
+        )
+    )
+
+
+def timestamp(value):
+    """Normalize a timestamp to UTC, treating naive values as UTC."""
+    if value is None:
+        return now()
+    parsed = datetime.fromisoformat(str(value).replace("Z", UTC_OFFSET))
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC).isoformat().replace(UTC_OFFSET, "Z")
+
+
+def payload(
+    text,
+    scope,
+    source,
+    session_id="",
+    category=None,
+    importance=0.5,
+    metadata=None,
+    cloud_origin=None,
+    created_at=None,
+    updated_at=None,
+):
+    """Build a validated schema-v1 payload with provenance and stable text hashing."""
+    if not isinstance(text, str) or not normalize(text):
+        raise ValueError("Memory text must be nonempty")
+    if (
+        not isinstance(importance, (float, int))
+        or not math.isfinite(importance)
+        or not 0 <= importance <= 1
+    ):
+        raise ValueError("Importance must be between zero and one")
+    category = category or []
+    if not isinstance(category, list) or not all(isinstance(x, str) for x in category):
+        raise ValueError("category must be an array of strings")
+    if metadata is not None and not isinstance(metadata, dict):
+        raise ValueError("metadata must be an object")
+    return {
+        "text": text,
+        **scope.as_dict(),
+        "source": source,
+        "session_id": session_id or None,
+        "category": category,
+        "importance": importance,
+        "metadata": metadata or {},
+        "cloud_origin": cloud_origin,
+        "created_at": timestamp(created_at),
+        "updated_at": timestamp(updated_at),
+        "content_hash": content_hash(text),
+        "schema_version": 1,
+    }
+
+
+def enforce_limits(value, limits):
+    """Enforce UTF-8 byte limits, rejecting oversize data unless truncation is explicit."""
+    value = dict(value)
+    if len(value["text"].encode()) > limits["max_text_bytes"]:
+        if limits["oversize_policy"] != "truncate":
+            raise ValueError("Memory exceeds max_text_bytes")
+        value["text"] = (
+            value["text"].encode()[: limits["max_text_bytes"]].decode("utf-8", errors="ignore")
+        )
+        if not normalize(value["text"]):
+            raise ValueError("Memory text must be nonempty after truncation")
+        value["content_hash"] = content_hash(value["text"])
+        value["metadata"] = {**value["metadata"], "truncated": True}
+    for key, bound in (("metadata", "max_metadata_bytes"), (None, "max_payload_bytes")):
+        if (
+            len(json.dumps(value[key] if key else value, ensure_ascii=False).encode())
+            > limits[bound]
+        ):
+            raise ValueError(f"Memory exceeds {bound}")
+    return value

qdrant_memory/ownership.py

@@ -0,0 +1,48 @@
+"""Exclusive profile/destination writer ownership across provider reloads."""
+
+import os
+from pathlib import Path
+
+from .models import digest
+
+
+class WriterBusyError(RuntimeError):
+    """Report exclusive writer ownership without disclosing destination details."""
+
+
+class WriterLease:
+    """Hold an OS lock until every owned service and worker has finished."""
+
+    @classmethod
+    def for_config(cls, home, cfg):
+        """Exclude writers to the same physical destination across mode/URL aliases."""
+        from .config import backend_destination
+
+        q = cfg["qdrant"]
+        destination = backend_destination(q)
+        if q["mode"] == "embedded":
+            # Keep the writer lock identity stable across plugin upgrades.
+            destination = (destination[0], destination[-1])
+        return cls(home, [destination, q["collection"]])
+
+    def __init__(self, home, namespace):
+        """Acquire without waiting so a replacement cannot overlap an old writer."""
+        # Imported lazily so provider discovery and registration stays free of
+        # runtime dependencies before Hermes has prepared them.
+        import portalocker
+
+        directory = Path(home) / "qdrant-memory"
+        directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        descriptor = os.open(
+            directory / (digest(namespace) + ".writer.lock"), os.O_CREAT | os.O_RDWR, 0o600
+        )
+        self.file = os.fdopen(descriptor, "a")
+        try:
+            portalocker.lock(self.file, portalocker.LOCK_EX | portalocker.LOCK_NB)
+        except portalocker.LockException as exc:
+            self.file.close()
+            raise WriterBusyError("Another writer still owns this profile destination") from exc
+
+    def close(self):
+        """Release ownership only after the owner's other cleanup callbacks."""
+        self.file.close()

qdrant_memory/plugin.yaml

@@ -0,0 +1,13 @@
+name: qdrant-memory
+version: 0.2.0
+description: Durable native memory with Qdrant and Hermes LLM extraction
+manifest_version: 2
+author: Kang Liu
+license: MIT
+homepage: https://github.com/cnkang/hermes-plugin-qdrant-memory
+tags: [memory, qdrant, vector-search]
+python_dependencies:
+  - "qdrant-client>=1.15,<2"
+  - "httpx>=0.28,<1"
+  - "portalocker>=3.2,<4"
+provides_hooks: []

qdrant_memory/progress.py

@@ -0,0 +1,89 @@
+"""Bounded, content-free migration diagnostics on stderr."""
+
+import sys
+import time
+from threading import Event, Lock, Thread
+
+
+def report(progress, stage, completed=None, total=None):
+    """Notify an optional observer without including source data or credentials."""
+    if progress is not None:
+        try:
+            progress(stage, completed, total)
+        except Exception:
+            # Diagnostics must not change the outcome of durable work.
+            pass
+
+
+class MigrationProgress:
+    """Show phase changes and periodic waiting messages even during blocked I/O."""
+
+    def __init__(self, quiet=False, interval=10.0):
+        """Configure a reporter; resolve stderr at construction for CLI capture."""
+        self.quiet = quiet
+        self.interval = interval
+        self.stream = sys.stderr
+        self.started = self.changed = time.monotonic()
+        self.printed = float("-inf")
+        self.stage = "Starting migration"
+        self.completed = self.total = None
+        self.lock = Lock()
+        self.stop = Event()
+        self.thread = None
+
+    def __enter__(self):
+        """Start the waiting reporter before configuration or external calls."""
+        self(self.stage)
+        if not self.quiet:
+            self.thread = Thread(target=self._heartbeat, daemon=True)
+            self.thread.start()
+        return self
+
+    def __exit__(self, exc_type, exc, traceback):
+        """Stop and join the reporter on success, failure, or interruption."""
+        self.stop.set()
+        if self.thread is not None:
+            self.thread.join()
+        if exc_type is not None:
+            try:
+                self("Migration stopped; see error output or rerun with --resume")
+            except Exception:
+                # Preserve the original migration failure after reporter shutdown.
+                pass
+
+    def __call__(self, stage, completed=None, total=None):
+        """Throttle record updates, but always show phase starts and completions."""
+        with self.lock:
+            changed = stage != self.stage
+            self.stage, self.completed, self.total = stage, completed, total
+            self.changed = time.monotonic()
+            if (
+                changed
+                or self.changed - self.printed >= 1
+                or (total is not None and completed == total)
+            ):
+                self._write()
+
+    def _write(self, waiting=False):
+        """Flush one safe line; a closed diagnostic stream must not abort writes."""
+        if self.quiet:
+            return
+        current = time.monotonic()
+        counts = "" if self.total is None else f" {self.completed}/{self.total}"
+        idle = f"; waiting, no progress for {current - self.changed:.0f}s" if waiting else ""
+        try:
+            print(
+                f"[qdrant-memory +{current - self.started:.0f}s] {self.stage}{counts}{idle}",
+                file=self.stream,
+                flush=True,
+            )
+        except (OSError, ValueError):
+            self.quiet = True
+        self.printed = current
+
+    def _heartbeat(self):
+        """Report inactivity without claiming that a stalled request is progressing."""
+        while not self.stop.wait(self.interval):
+            with self.lock:
+                if time.monotonic() - self.printed >= self.interval:
+                    self._write(waiting=True)