nat-memorysync 1.0.0__py3-none-any.whl

nat_memorysync/__init__.py

@@ -0,0 +1,15 @@
+"""MemorySync for the NVIDIA NeMo Agent Toolkit."""
+
+from ._api import MemorySyncAPIError, fnv1a64
+from ._version import __version__
+from .editor import MemorySyncEditor
+from .register import MemorySyncMemoryConfig, memorysync_memory_client
+
+__all__ = [
+    "MemorySyncEditor",
+    "MemorySyncMemoryConfig",
+    "memorysync_memory_client",
+    "MemorySyncAPIError",
+    "fnv1a64",
+    "__version__",
+]

nat_memorysync/_api.py

@@ -0,0 +1,286 @@
+"""Async client for the MemorySync v1 data plane used by this adapter.
+
+Conversation turns persist through the *episodic* ingestion path
+(``POST /v1/memory/add_turn``), which stores text verbatim — no fact
+extraction, no low-value-chatter gate, no rewriting. An agent transcript
+must round-trip byte-for-byte; a plane that second-guessed it would
+corrupt the user's history.
+
+Everything here is async-native: the toolkit's ``MemoryEditor`` methods
+are all coroutines running on the main asyncio loop, so the client rides
+along without any bridging.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.memorysync.io"
+_USER_AGENT = f"nat-memorysync/{__version__}"
+
+#: Namespace used when the key cannot list projects (see resolve_tenant_id).
+FALLBACK_TENANT = "default"
+
+#: One turn beyond this length is truncated before storage.
+MAX_TURN_CHARS = 16000
+
+
+class MemorySyncAPIError(Exception):
+    """A MemorySync call failed. Carries the status code and server detail."""
+
+    def __init__(self, message: str, *, status_code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+def resolve_api_key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get("MEMORYSYNC_API_KEY", "")
+    if not key or not key.strip():
+        raise ValueError(
+            "A MemorySync API key is required. Pass api_key=... or set the "
+            "MEMORYSYNC_API_KEY environment variable."
+        )
+    return key.strip()
+
+
+def resolve_base_url(base_url: Optional[str]) -> str:
+    url = base_url or os.environ.get("MEMORYSYNC_BASE_URL", "") or DEFAULT_BASE_URL
+    return url.rstrip("/")
+
+
+def fnv1a64(value: str) -> str:
+    """FNV-1a 64-bit over UTF-16 code units, as a fixed-width hex string.
+
+    Over UTF-16 code units — not code points, not UTF-8 bytes — so the
+    output matches every other MemorySync adapter (Python and JS)
+    character for character. Identical seeds across surfaces mean a turn
+    persisted here and again elsewhere converge on one stored row.
+    """
+    prime = 0x100000001B3
+    mask = 0xFFFFFFFFFFFFFFFF
+    h = 0xCBF29CE484222325
+    data = value.encode("utf-16-le")
+    for i in range(0, len(data), 2):
+        unit = data[i] | (data[i + 1] << 8)
+        h ^= unit
+        h = (h * prime) & mask
+    return format(h, "016x")
+
+
+class AsyncV1Api:
+    """Minimal asynchronous v1 client: add_turn, recall, query, list, forget."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        project_id: Optional[str] = None,
+        timeout: float = 30.0,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._project_id = project_id
+        self._timeout = timeout
+        self._transport = transport
+        self._http = httpx.AsyncClient(timeout=timeout, transport=transport)
+        self._tenant_id: Optional[str] = None
+        self._tenant_is_fallback = False
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    # ── plumbing ─────────────────────────────────────────────────────
+
+    def _headers(self, *, end_user_id: Optional[str] = None) -> Dict[str, str]:
+        h = {
+            "X-API-Key": self._api_key,
+            "Accept": "application/json",
+            "User-Agent": _USER_AGENT,
+        }
+        if self._project_id:
+            h["X-Project-ID"] = self._project_id
+        if end_user_id:
+            h["X-End-User-ID"] = end_user_id
+        return h
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        end_user_id: Optional[str] = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        try:
+            response = await self._http.request(
+                method,
+                url,
+                headers=self._headers(end_user_id=end_user_id),
+                json=json,
+                params=params,
+            )
+        except httpx.TimeoutException as e:
+            raise MemorySyncAPIError(f"Request timed out: {e}") from e
+        except httpx.HTTPError as e:
+            raise MemorySyncAPIError(f"Network error: {e}") from e
+
+        if response.status_code == 204:
+            return None
+        try:
+            body: Any = response.json()
+        except ValueError:
+            body = response.text or None
+        if response.status_code >= 400:
+            detail = body.get("detail") if isinstance(body, dict) else body
+            raise MemorySyncAPIError(
+                f"{method} {path} failed with HTTP {response.status_code}: {detail}",
+                status_code=response.status_code,
+            )
+        return body
+
+    # ── calls ────────────────────────────────────────────────────────
+
+    async def resolve_tenant_id(self) -> str:
+        """The tenant id, which the v1 routes need in path or body.
+
+        Derived from the project listing rather than asked for. Cached for
+        the lifetime of this client. Keys without the ``projects:read``
+        scope (evaluation keys) fall back to the fixed namespace
+        ``"default"`` — deterministic, so every read and write through
+        this client lands in one namespace. Only a definite 401/403
+        triggers the fallback; a transient server error re-raises rather
+        than silently switching namespaces.
+        """
+        if self._tenant_id:
+            return self._tenant_id
+        try:
+            projects = await self._request("GET", "/org/projects")
+        except MemorySyncAPIError as exc:
+            if exc.status_code in (401, 403):
+                self._tenant_id = FALLBACK_TENANT
+                self._tenant_is_fallback = True
+                return self._tenant_id
+            raise
+        first = projects[0] if isinstance(projects, list) and projects else None
+        tenant = first.get("tenant_id") if isinstance(first, dict) else None
+        if not tenant:
+            raise MemorySyncAPIError(
+                "Could not determine the tenant for this API key. Pass "
+                "tenant_id explicitly, or verify the key with `memorysync doctor`."
+            )
+        self._tenant_id = str(tenant)
+        return self._tenant_id
+
+    def set_tenant_id(self, tenant_id: str) -> None:
+        self._tenant_id = tenant_id
+
+    async def add_turn(
+        self,
+        *,
+        tenant_id: str,
+        user_id: str,
+        text: str,
+        speaker: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        source: str = "nat",
+        sync_embed: bool = False,
+    ) -> Dict[str, Any]:
+        """Store one item verbatim (episodic ingestion).
+
+        ``speaker`` participates in the server's idempotency seed, so
+        retrying an identical payload is recognised
+        (``already_exists: true``) instead of stored twice.
+        """
+        body: Dict[str, Any] = {
+            "tenant_id": tenant_id,
+            "user_id": user_id,
+            "source": source,
+            "text": text,
+            "sync_embed": sync_embed,
+        }
+        if speaker is not None:
+            body["speaker"] = speaker
+        if metadata is not None:
+            body["metadata"] = metadata
+        return await self._request("POST", "/v1/memory/add_turn", json=body) or {}
+
+    async def query(
+        self,
+        *,
+        tenant_id: str,
+        user_id: str,
+        prompt: str,
+        k: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Plain semantic search over the pair's memories (episodic included)."""
+        body: Dict[str, Any] = {
+            "tenant_id": tenant_id,
+            "user_id": user_id,
+            "prompt": prompt,
+        }
+        if k is not None:
+            body["k"] = k
+        return await self._request("POST", "/v1/memory/query", json=body) or {}
+
+    async def list_memories(
+        self,
+        *,
+        tenant_id: str,
+        user_id: str,
+        limit: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """Every memory for the tenant/user pair, newest first."""
+        from urllib.parse import quote
+
+        raw = await self._request(
+            "GET",
+            f"/v1/memory/{quote(tenant_id, safe='')}/{quote(user_id, safe='')}/list",
+            params={"limit": limit},
+        )
+        memories = raw.get("memories") if isinstance(raw, dict) else None
+        return list(memories) if isinstance(memories, list) else []
+
+    async def forget(self, *, user_id: str, memory_ids: List[int]) -> None:
+        """Delete specific memories by numeric id, scoped to one end user."""
+        if not memory_ids:
+            return
+        for start in range(0, len(memory_ids), 100):
+            batch = memory_ids[start : start + 100]
+            await self._request(
+                "DELETE",
+                "/memory/forget",
+                json={"memory_ids": batch},
+                end_user_id=user_id,
+            )
+
+    async def add_memory(
+        self,
+        *,
+        user_id: str,
+        text: str,
+        source: str = "nat",
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Store a fact through the extraction path (server-side gating)."""
+        body: Dict[str, Any] = {"text": text, "source": source}
+        if metadata is not None:
+            body["metadata"] = metadata
+        return (
+            await self._request(
+                "POST", "/memory/add", json=body, end_user_id=user_id
+            )
+            or {}
+        )

nat_memorysync/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

nat_memorysync/editor.py

@@ -0,0 +1,337 @@
+"""MemorySync MemoryEditor for the NVIDIA NeMo Agent Toolkit.
+
+Design rules, in priority order:
+
+1. **A workflow is never stalled and never broken.** ``search`` runs on
+   every response when wired through ``auto_memory_agent``, so it waits
+   at most ``recall_timeout`` seconds (default 1.2) and fails open to no
+   memories. ``add_items`` is fail-open too — a memory outage must not
+   turn a successful agent response into a failure. Deterministic
+   idempotency seeds make retries (including the toolkit's RetryMixin
+   patching) converge on one stored row instead of duplicating.
+
+2. **Multi-tenant bleed is impossible by construction.** Every stored
+   row is scoped by the item's ``user_id``; the session scope only adds
+   a per-user transcript label. The in-repo Zep editor routes everything
+   to one shared ``"default_zep_thread"`` when no conversation id is set
+   — two users' turns land in the same thread. Here that cannot happen.
+
+3. **Deletes cannot nuke a customer by accident.**
+   ``remove_items(user_id=...)`` deletes only this adapter's session
+   rows by default; wiping the user's entire memory requires the
+   explicit ``scope="user"`` opt-in. Calling with no kwargs raises — the
+   in-repo Mem0 editor silently does nothing.
+
+4. **Contracts are loud and typed.** ``search`` without ``user_id``
+   raises a ValueError naming the kwarg (Mem0 throws a bare KeyError);
+   caller items and metadata are never mutated (Mem0 pops keys out of
+   the dict you handed it); similarity scores are returned, not
+   discarded (Mem0 drops them); search returns one MemoryItem PER FACT
+   (Zep returns a single joined blob).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from nat.builder.context import Context
+from nat.memory.interfaces import MemoryEditor
+from nat.memory.models import MemoryItem
+
+from ._api import (
+    MAX_TURN_CHARS,
+    AsyncV1Api,
+    MemorySyncAPIError,
+    fnv1a64,
+    resolve_api_key,
+    resolve_base_url,
+)
+
+logger = logging.getLogger("nat_memorysync")
+
+_ROLE_MAP = {"user": "human", "human": "human", "assistant": "ai", "ai": "ai"}
+
+
+class MemorySyncEditor(MemoryEditor):
+    """The MemorySync-backed ``MemoryEditor``.
+
+    Works with both toolkit wiring modes: the ``add_memory`` /
+    ``get_memory`` tool functions, and the automatic
+    ``auto_memory_agent`` wrapper.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: Optional[str] = None,
+        project_id: Optional[str] = None,
+        top_k: int = 5,
+        recall_timeout: float = 1.2,
+        min_query_chars: int = 8,
+        source: str = "nat",
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        self.top_k = top_k
+        self.recall_timeout = recall_timeout
+        self.min_query_chars = min_query_chars
+        self.source = source
+        self._api = AsyncV1Api(
+            api_key=resolve_api_key(api_key),
+            base_url=resolve_base_url(base_url),
+            project_id=project_id,
+            timeout=max(recall_timeout * 4, 8.0),
+            transport=transport,
+        )
+
+    # ── scope ────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _session_scope() -> str:
+        """Per-run transcript label from the toolkit's async-safe Context.
+
+        The scope only labels the transcript INSIDE one user's memory —
+        rows are always additionally keyed by the item's own user_id, so
+        an unset conversation id can never mix two users' data (the
+        bleed the in-repo Zep editor has with its shared default thread).
+        """
+        conversation_id = None
+        try:
+            conversation_id = Context.get().conversation_id
+        except Exception:  # pragma: no cover - context outside a workflow
+            pass
+        return f"nat::{conversation_id or 'default'}"
+
+    # ── add_items: duplicate-proof, fail-open ────────────────────────
+
+    async def add_items(self, items: list[MemoryItem]) -> None:
+        """Persist items verbatim — per-item user scoping, never mutating
+        the caller's objects, never raising into the workflow."""
+        scope = self._session_scope()
+        stored = 0
+        skipped = 0
+        try:
+            tenant_id = await self._api.resolve_tenant_id()
+            coroutines = []
+            for item in items or []:
+                user_id = (item.user_id or "").strip()
+                if not user_id:
+                    skipped += 1
+                    continue
+                # Copies only — the in-repo Mem0 editor pops keys out of
+                # the metadata dict the caller handed it.
+                metadata = dict(item.metadata or {})
+                ignore_roles = {
+                    str(r).lower() for r in (metadata.pop("ignore_roles", []) or [])
+                }
+                conversation = list(item.conversation or [])
+                if not conversation and item.memory:
+                    # Single-fact shorthand goes through the extraction
+                    # path, where the server decides durability.
+                    coroutines.append(
+                        self._api.add_memory(
+                            user_id=user_id,
+                            text=str(item.memory),
+                            source=self.source,
+                            metadata=metadata or None,
+                        )
+                    )
+                    continue
+                for turn in conversation:
+                    if not isinstance(turn, dict):
+                        skipped += 1
+                        continue
+                    role = _ROLE_MAP.get(str(turn.get("role") or "").lower())
+                    text = str(turn.get("content") or "").strip()
+                    if role is None or not text:
+                        skipped += 1
+                        continue
+                    if str(turn.get("role") or "").lower() in ignore_roles:
+                        skipped += 1
+                        continue
+                    if len(text) > MAX_TURN_CHARS:
+                        text = text[:MAX_TURN_CHARS]
+                    seed = f"{role}@{scope}#h{fnv1a64(f'{role}:{text}')}"
+                    payload_metadata: Dict[str, Any] = {"session_id": scope}
+                    if metadata:
+                        payload_metadata.update(metadata)
+                    coroutines.append(
+                        self._api.add_turn(
+                            tenant_id=tenant_id,
+                            user_id=user_id,
+                            text=f"{role}: {text}",
+                            speaker=seed,
+                            metadata=payload_metadata,
+                            source=self.source,
+                        )
+                    )
+            if coroutines:
+                results = await asyncio.gather(*coroutines, return_exceptions=True)
+                for result in results:
+                    if isinstance(result, Exception):
+                        skipped += 1
+                        logger.warning("MemorySync add skipped one item (%s)", result)
+                    else:
+                        stored += 1
+        except Exception as exc:
+            logger.warning(
+                "MemorySync add_items degraded (%s) — stored %d, skipped %d; "
+                "idempotency seeds make a retry safe.",
+                exc,
+                stored,
+                skipped,
+            )
+
+    # ── search: budgeted, per-fact, fail-open ────────────────────────
+
+    async def search(self, query: str, top_k: int = 5, **kwargs) -> list[MemoryItem]:
+        """Semantic search returning one MemoryItem PER FACT, with
+        similarity scores populated.
+
+        ``user_id`` must be passed as a keyword argument — that is how
+        every built-in caller (the get_memory tool and
+        auto_memory_agent) invokes editors.
+        """
+        user_id = kwargs.get("user_id")
+        if not isinstance(user_id, str) or not user_id.strip():
+            # Mem0's editor does kwargs.pop("user_id") and throws a bare
+            # KeyError; a typed, descriptive error is kinder.
+            raise ValueError(
+                "search() requires a non-empty user_id keyword argument "
+                "(e.g. editor.search(query, top_k=5, user_id='customer-42'))."
+            )
+        user_id = user_id.strip()
+        text = (query or "").strip()
+        if len(text) < self.min_query_chars:
+            return []
+        limit = top_k or self.top_k
+
+        try:
+            tenant_id = await asyncio.wait_for(
+                self._api.resolve_tenant_id(), timeout=self.recall_timeout
+            )
+            response = await asyncio.wait_for(
+                self._api.query(
+                    tenant_id=tenant_id, user_id=user_id, prompt=text, k=limit
+                ),
+                timeout=self.recall_timeout,
+            )
+        except Exception as exc:
+            logger.warning(
+                "MemorySync recall unavailable this call (%s) — continuing without memories.",
+                exc,
+            )
+            return []
+
+        raw = response.get("memories") if isinstance(response, dict) else []
+        items: List[MemoryItem] = []
+        for entry in raw if isinstance(raw, list) else []:
+            if not isinstance(entry, dict):
+                continue
+            memory_text = (
+                entry.get("value") or entry.get("text") or entry.get("raw_text") or ""
+            )
+            if not isinstance(memory_text, str) or not memory_text:
+                continue
+            metadata: Dict[str, Any] = {}
+            if entry.get("memory_id") is not None:
+                metadata["memory_id"] = str(entry["memory_id"])
+            score = entry.get("score")
+            items.append(
+                MemoryItem(
+                    user_id=user_id,
+                    memory=memory_text,
+                    metadata=metadata,
+                    similarity_score=float(score)
+                    if isinstance(score, (int, float))
+                    else None,
+                )
+            )
+        return items
+
+    # ── remove_items: scoped by default, loud contracts ──────────────
+
+    async def remove_items(self, **kwargs) -> None:
+        """Delete memories — session-scoped by default.
+
+        - ``memory_id=...`` (with ``user_id``): delete one specific item.
+        - ``user_id=...``: delete only THIS adapter's session rows
+          (``nat::<conversation>`` scope) for that user.
+        - ``user_id=..., scope="user"``: explicit opt-in to wipe the
+          user's entire memory.
+        - No kwargs: raises ValueError (the in-repo Mem0 editor silently
+          does nothing — a latent data-management bug).
+        """
+        memory_id = kwargs.get("memory_id")
+        user_id = kwargs.get("user_id")
+        scope = kwargs.get("scope", "session")
+        if scope not in ("session", "user"):
+            raise ValueError('remove_items scope must be "session" or "user"')
+        if memory_id is None and (not isinstance(user_id, str) or not user_id.strip()):
+            raise ValueError(
+                "remove_items() needs memory_id=... and/or a non-empty user_id=... "
+                "keyword argument; refusing to guess what to delete."
+            )
+
+        if memory_id is not None:
+            if not isinstance(user_id, str) or not user_id.strip():
+                raise ValueError(
+                    "remove_items(memory_id=...) also needs user_id=... — "
+                    "deletion is always scoped to one end user."
+                )
+            parsed = self._parse_id(memory_id)
+            if parsed is None:
+                raise ValueError(f"Unparseable memory_id: {memory_id!r} (expected m_<n> or <n>)")
+            await self._api.forget(user_id=user_id.strip(), memory_ids=[parsed])
+            return
+
+        user_id = user_id.strip()
+        tenant_id = await self._api.resolve_tenant_id()
+        rows = await self._api.list_memories(tenant_id=tenant_id, user_id=user_id)
+        session_scope = self._session_scope()
+        ids: List[int] = []
+        for row in rows:
+            if scope == "session" and not self._in_session(row, session_scope):
+                continue
+            parsed = self._parse_id(row.get("memory_id"))
+            if parsed is not None:
+                ids.append(parsed)
+        await self._api.forget(user_id=user_id, memory_ids=ids)
+
+    @staticmethod
+    def _in_session(row: Dict[str, Any], session_scope: str) -> bool:
+        # Production nests client metadata one level deeper
+        # (metadata.metadata.session_id); older shapes were flat. Accept
+        # both — the same dual-envelope rule as every other adapter.
+        outer = row.get("metadata")
+        if not isinstance(outer, dict):
+            return False
+        inner = outer.get("metadata")
+        session = None
+        if isinstance(inner, dict):
+            session = inner.get("session_id")
+        if session is None:
+            session = outer.get("session_id")
+        return session == session_scope
+
+    @staticmethod
+    def _parse_id(raw: Any) -> Optional[int]:
+        if raw is None:
+            return None
+        value = str(raw)
+        if value.startswith("m_"):
+            value = value[2:]
+        try:
+            return int(value)
+        except ValueError:
+            return None
+
+    # ── lifecycle ────────────────────────────────────────────────────
+
+    async def aclose(self) -> None:
+        """Release the HTTP client (called by the registration factory)."""
+        await self._api.aclose()

nat_memorysync/register.py

@@ -0,0 +1,72 @@
+"""Config + registration: makes ``_type: memorysync_memory`` resolvable
+in workflow YAML and through the Builder API."""
+
+from __future__ import annotations
+
+import os
+
+from pydantic import Field
+
+from nat.builder.builder import Builder
+from nat.cli.register_workflow import register_memory
+from nat.data_models.memory import MemoryBaseConfig
+from nat.data_models.retry_mixin import RetryMixin
+
+
+class MemorySyncMemoryConfig(MemoryBaseConfig, RetryMixin, name="memorysync_memory"):
+    """MemorySync memory client configuration.
+
+    The API key is deliberately NOT a config field default: it comes
+    from the ``MEMORYSYNC_API_KEY`` environment variable unless
+    explicitly provided, so workflow YAML files never carry credentials.
+    RetryMixin adds the toolkit's standard retry knobs — safe here
+    because every write carries a deterministic idempotency seed, so a
+    retried add converges on one stored row.
+    """
+
+    base_url: str | None = Field(
+        default=None,
+        description="MemorySync API base URL (default https://api.memorysync.io).",
+    )
+    api_key: str | None = Field(
+        default=None,
+        description="MemorySync API key. Falls back to the MEMORYSYNC_API_KEY env var.",
+    )
+    project_id: str | None = Field(
+        default=None, description="Optional X-Project-ID header value."
+    )
+    top_k: int = Field(default=5, description="Default memories per search.")
+    recall_timeout: float = Field(
+        default=1.2,
+        description="Hard recall budget in seconds; a slow backend degrades to no memories.",
+    )
+    min_query_chars: int = Field(
+        default=8, description="Skip recall for queries shorter than this."
+    )
+    source: str = Field(default="nat", description="Source label on stored turns.")
+
+
+@register_memory(config_type=MemorySyncMemoryConfig)
+async def memorysync_memory_client(config: MemorySyncMemoryConfig, builder: Builder):
+    from .editor import MemorySyncEditor
+
+    api_key = config.api_key or os.environ.get("MEMORYSYNC_API_KEY")
+    if not api_key or not api_key.strip():
+        raise RuntimeError(
+            "MemorySync memory client needs an API key: set the "
+            "MEMORYSYNC_API_KEY environment variable or the api_key config "
+            "field (get one at https://app.memorysync.io)."
+        )
+    editor = MemorySyncEditor(
+        api_key=api_key,
+        base_url=config.base_url,
+        project_id=config.project_id,
+        top_k=config.top_k,
+        recall_timeout=config.recall_timeout,
+        min_query_chars=config.min_query_chars,
+        source=config.source,
+    )
+    try:
+        yield editor
+    finally:
+        await editor.aclose()

nat_memorysync-1.0.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: nat-memorysync
+Version: 1.0.0
+Summary: MemorySync for the NVIDIA NeMo Agent Toolkit: a MemoryEditor plugin with budgeted per-fact recall, duplicate-proof verbatim persistence, bleed-proof multi-tenant scoping, and session-scoped deletes.
+Project-URL: Homepage, https://docs.memorysync.io/guides/nemo-agent-toolkit
+Project-URL: Documentation, https://docs.memorysync.io/guides/nemo-agent-toolkit
+Project-URL: Repository, https://github.com/Rafay121/memorysync-plugins
+Author-email: MemorySync <support@memorysync.io>
+License-Expression: MIT
+Keywords: agents,aiqtoolkit,long-term-memory,memory,memorysync,nemo-agent-toolkit,nvidia,nvidia-nat
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.14,>=3.11
+Requires-Dist: httpx<1,>=0.25
+Requires-Dist: nvidia-nat-core<2,>=1.5
+Description-Content-Type: text/markdown
+
+# nat-memorysync
+
+MemorySync memory backend for the [NVIDIA NeMo Agent Toolkit](https://github.com/NVIDIA/NeMo-Agent-Toolkit) (`nvidia-nat`).
+
+Registers a `memorysync_memory` client that plugs into workflow YAML as a
+`memory:` section entry — usable from the toolkit's built-in `add_memory` /
+`get_memory` tools, from the automatic `auto_memory_agent` wrapper, and from
+any custom function that requests a memory client from the Builder.
+
+```bash
+pip install nat-memorysync
+```
+
+Requires Python 3.11+ (the toolkit's own floor). Installing this package pulls
+`nvidia-nat-core`; install `nvidia-nat` (or the plugin subpackages you need)
+for the full toolkit.
+
+## Why this instead of the in-repo editors?
+
+The toolkit ships example editors for Mem0 and Zep. Both have sharp edges we
+designed against:
+
+| Behavior | Mem0 (in-repo) | Zep (in-repo) | **nat-memorysync** |
+|---|---|---|---|
+| `search()` without `user_id` | bare `KeyError` | n/a (thread-scoped) | `ValueError` naming the kwarg |
+| Multi-user isolation with no conversation id | per-call `user_id` | **all users share `"default_zep_thread"`** | rows always keyed by item `user_id` — bleed impossible |
+| Your `metadata` dict after `add_items` | **mutated** (keys popped out) | untouched | untouched (copy-first, tested) |
+| Search result shape | items, **scores discarded** | **one joined text blob** | one `MemoryItem` per fact, `similarity_score` populated |
+| `remove_items()` with no kwargs | **silent no-op** | deletes current thread | raises — refuses to guess |
+| Delete blast radius | whole user | whole thread | session-scoped by default; whole user requires explicit `scope="user"` |
+| Slow/down memory backend | blocks the turn | blocks the turn | 1.2 s recall budget, fail-open both directions |
+| Retried writes | duplicated | duplicated | deterministic idempotency seeds — retries converge on one row |
+
+## Wiring mode 1 — explicit memory tools
+
+The agent decides when to store and when to recall:
+
+```yaml
+memory:
+  saas_memory:
+    _type: memorysync_memory        # key comes from MEMORYSYNC_API_KEY env var
+
+functions:
+  add_memory:
+    _type: add_memory
+    memory: saas_memory
+    description: Save any user preference or fact for later conversations.
+  get_memory:
+    _type: get_memory
+    memory: saas_memory
+    description: Recall previously saved user preferences and facts.
+
+workflow:
+  _type: react_agent
+  tool_names: [add_memory, get_memory]
+  llm_name: my_llm
+```
+
+## Wiring mode 2 — automatic memory (`auto_memory_agent`)
+
+No tools, no prompt changes — every turn is stored and every prompt is
+enriched automatically (requires `nvidia-nat-langchain`):
+
+```yaml
+memory:
+  saas_memory:
+    _type: memorysync_memory
+
+workflow:
+  _type: auto_memory_agent
+  augmented_fn: my_actual_workflow
+  memory: saas_memory
+```
+
+`search` runs inside a hard 1.2 s budget here, so automatic memory can never
+stall a turn.
+
+## Builder API (Python)
+
+```python
+from nat.builder.workflow_builder import WorkflowBuilder
+from nat_memorysync import MemorySyncMemoryConfig
+
+async with WorkflowBuilder() as builder:
+    await builder.add_memory_client("saas_memory", MemorySyncMemoryConfig())
+    editor = await builder.get_memory_client("saas_memory")
+
+    from nat.memory.models import MemoryItem
+    await editor.add_items([
+        MemoryItem(
+            conversation=[{"role": "user", "content": "I prefer teal dashboards"}],
+            user_id="customer-1",
+            metadata={"plan": "pro"},
+        )
+    ])
+    items = await editor.search("dashboard preferences", top_k=5, user_id="customer-1")
+    for it in items:
+        print(it.similarity_score, it.memory)
+```
+
+## Configuration
+
+All fields are optional except the API key (env var or config field):
+
+| YAML field | Default | Purpose |
+|---|---|---|
+| `api_key` | `MEMORYSYNC_API_KEY` env var | API key — keep it in the env var so YAML stays credential-free |
+| `base_url` | `https://api.memorysync.io` | Override for self-hosted / staging |
+| `project_id` | – | Optional `X-Project-ID` header |
+| `top_k` | `5` | Default memories per search |
+| `recall_timeout` | `1.2` | Hard recall budget (seconds); slow backend degrades to no memories |
+| `min_query_chars` | `8` | Skip recall for shorter queries |
+| `source` | `nat` | Source label on stored turns |
+
+`MemoryBaseConfig` + `RetryMixin` knobs (`num_retries`,
+`retry_on_status_codes`, …) work too — retries are safe because every write
+carries a deterministic idempotency seed.
+
+## Editor semantics
+
+- **`add_items(items)`** — each `MemoryItem.conversation` is stored through
+  MemorySync's extraction pipeline (facts, dedup, decay), scoped to that
+  item's `user_id`. `metadata` keys ride along; `metadata.ignore_roles`
+  filters roles out (e.g. `["assistant"]` stores only user turns). Items
+  whose extraction fails are logged and skipped — a partial batch never
+  raises mid-turn.
+- **`search(query, top_k=..., user_id=...)`** — semantic recall, one
+  `MemoryItem` per fact with `similarity_score`. `user_id` is required
+  (loud `ValueError`, not a `KeyError`).
+- **`remove_items(user_id=...)`** — deletes this adapter's session rows for
+  the user. Add `memory_id="..."` for one row, or `scope="user"` to wipe the
+  user's entire memory (explicit opt-in). No kwargs → `ValueError`.
+
+Session scope comes from the toolkit's `Context.get().conversation_id`
+ContextVar when set (`nat::<conversation_id>`), else `nat::default` — but
+rows are always additionally keyed by `user_id`, so an unset conversation id
+can never mix users.
+
+## Tests
+
+```bash
+pip install -e . nvidia-nat-core langchain-core pytest pytest-asyncio "httpx>=0.25,<1"
+pytest tests -q   # 26 tests
+```
+
+The suite exercises the real `WorkflowBuilder`, NVIDIA's real
+`add_memory`/`get_memory` tool functions driving this editor end to end, plus
+named regression tests for every competitor bug in the table above.
+
+## License
+
+MIT © MemorySync.

nat_memorysync-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+nat_memorysync/__init__.py,sha256=rwURV3clCc6XZXn3hdTa7javwhZGaZsrNK2tQroEjgg,417
+nat_memorysync/_api.py,sha256=zA47WuQLfoMS7PwXToDKqtVQoLWLncxhof-qE_NBeo0,10276
+nat_memorysync/_version.py,sha256=ZhzQKWZ8RFrTIkj7z87B144DI95e8LMfA5w8NDWQDtg,23
+nat_memorysync/editor.py,sha256=FTpI2W0H0-3Wgcb1yMEhAxMXC5_kpQfLFdj5Q_CEXEw,14365
+nat_memorysync/register.py,sha256=so9AtPbvy_3gQBn3F1iiwN1fi4WJe1zmQcRDvbDRT9E,2741
+nat_memorysync-1.0.0.dist-info/METADATA,sha256=KIssxtgxvqC1X45kAkKCZGuYAyw00sLhKhRLOK_Q8dk,7110
+nat_memorysync-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+nat_memorysync-1.0.0.dist-info/entry_points.txt,sha256=sXjYilcjCVtrzWxYGCOeccGD2ay34xJ7usIQXRwlThM,58
+nat_memorysync-1.0.0.dist-info/RECORD,,

nat_memorysync-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nat_memorysync-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[nat.components]
+nat_memorysync = nat_memorysync.register