autogen-memorysync 1.0.0__py3-none-any.whl

autogen_memorysync/__init__.py

@@ -0,0 +1,20 @@
+"""MemorySync for Microsoft AutoGen (autogen-agentchat 0.4+)."""
+
+from ._api import MemorySyncAPIError, fnv1a64
+from ._version import __version__
+from .memory import (
+    DEFAULT_CONTEXT_TEMPLATE,
+    MemorySyncMemory,
+    MemorySyncMemoryConfig,
+)
+from .tools import create_memory_tools
+
+__all__ = [
+    "MemorySyncMemory",
+    "MemorySyncMemoryConfig",
+    "MemorySyncAPIError",
+    "DEFAULT_CONTEXT_TEMPLATE",
+    "create_memory_tools",
+    "fnv1a64",
+    "__version__",
+]

autogen_memorysync/_api.py

@@ -0,0 +1,311 @@
+"""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 because AutoGen's ``Memory`` protocol is
+fully async — a blocking HTTP client inside ``update_context`` would
+stall the event loop for every agent in the process (the exact bug in
+the Mem0 adapter that ships inside autogen-ext).
+"""
+
+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"autogen-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 = "autogen",
+        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 recall(
+        self,
+        *,
+        tenant_id: str,
+        user_id: str,
+        prompt: str,
+        k: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Hierarchical recall: grouped, prompt-ready context block."""
+        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/recall", 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.
+
+        ``limit=0`` means no limit — a scoped clear must see every row,
+        so that is the default here.
+        """
+        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
+        # Deletion in bounded batches so one enormous clear cannot build
+        # an unbounded request body.
+        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 = "autogen",
+        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 {}
+        )

autogen_memorysync/_version.py

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

autogen_memorysync/memory.py

@@ -0,0 +1,457 @@
+"""MemorySync memory for Microsoft AutoGen (``autogen-agentchat`` 0.4+).
+
+Design rules, in priority order:
+
+1. **The turn is never stalled and never broken.** ``update_context`` runs
+   on the hot path before every LLM call, so recall waits at most
+   ``recall_timeout`` seconds (default 1.2). On timeout, outage, or quota
+   exhaustion it injects nothing and returns an empty result — the agent
+   answers without memories rather than late or not at all. (The Mem0
+   adapter that ships inside autogen-ext has no budget at all — and calls
+   a *synchronous* client inside these async methods, blocking the entire
+   event loop.)
+
+2. **Retrieval is role-aware.** The query is the last *user* message,
+   found by walking the context backwards — not blindly ``messages[-1]``,
+   which after a tool result is assistant text (a real retrieval-quality
+   bug in the Mem0 adapter).
+
+3. **Writes are duplicate-proof.** ``add`` stores verbatim with a
+   deterministic idempotency seed derived from role, session, and
+   content; a retried call converges on one stored row.
+
+4. **``clear()`` cannot nuke a customer.** By default it deletes only
+   this adapter's session transcript (the ``autogen::<session>`` scope).
+   Wiping the user's entire memory requires the explicit
+   ``clear_scope="user"`` opt-in. Both Mem0 and Zep delete everything.
+
+5. **Hot path fails open, explicit calls fail loud.** ``update_context``
+   catches everything and logs; ``add``/``query``/``clear`` raise on
+   definite failure because the application called them deliberately.
+   (Mem0 does the reverse for query — it silently returns empty, so a
+   broken connection looks like an empty memory.)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+import httpx
+from pydantic import BaseModel
+
+from autogen_core import CancellationToken, Component
+from autogen_core.memory import (
+    Memory,
+    MemoryContent,
+    MemoryMimeType,
+    MemoryQueryResult,
+    UpdateContextResult,
+)
+from autogen_core.model_context import ChatCompletionContext
+from autogen_core.models import SystemMessage, UserMessage
+
+from ._api import (
+    MAX_TURN_CHARS,
+    AsyncV1Api,
+    MemorySyncAPIError,
+    fnv1a64,
+    resolve_api_key,
+    resolve_base_url,
+)
+
+logger = logging.getLogger("autogen_memorysync")
+
+DEFAULT_CONTEXT_TEMPLATE = (
+    "\nRelevant user memories (MemorySync):\n{context}\n"
+)
+
+
+class MemorySyncMemoryConfig(BaseModel):
+    """Declarative config for component serialization.
+
+    ``api_key`` is deliberately excluded from serialized output: a dumped
+    component must never carry a credential. On load the key comes from
+    the ``MEMORYSYNC_API_KEY`` environment variable (or pass ``api_key``
+    when constructing directly).
+    """
+
+    user_id: str
+    session_id: str = "default"
+    base_url: Optional[str] = None
+    project_id: Optional[str] = None
+    top_k: int = 5
+    recall_timeout: float = 1.2
+    min_prompt_chars: int = 8
+    context_template: str = DEFAULT_CONTEXT_TEMPLATE
+    clear_scope: str = "session"
+
+
+def _is_cancelled(token: Optional[CancellationToken]) -> bool:
+    if token is None:
+        return False
+    checker = getattr(token, "is_cancelled", None)
+    return bool(checker()) if callable(checker) else False
+
+
+def _text_of(content: Any) -> str:
+    """Best-effort plain text from an AutoGen message content value."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "\n".join(part for part in content if isinstance(part, str)).strip()
+    return ""
+
+
+class MemorySyncMemory(Memory, Component[MemorySyncMemoryConfig]):
+    """AutoGen ``Memory`` backed by MemorySync.
+
+    Wire it into an agent::
+
+        from autogen_agentchat.agents import AssistantAgent
+        from autogen_memorysync import MemorySyncMemory
+
+        memory = MemorySyncMemory(user_id="customer-42", session_id="support")
+        agent = AssistantAgent("assistant", model_client=..., memory=[memory])
+
+    AutoGen calls ``update_context`` automatically before every model
+    call. It never calls ``add`` — persist turns yourself, most simply::
+
+        result = await agent.run(task=user_text)
+        await memory.add_turn_pair(user_text, result.messages[-1].content)
+    """
+
+    component_type = "memory"
+    component_config_schema = MemorySyncMemoryConfig
+    component_provider_override = "autogen_memorysync.MemorySyncMemory"
+
+    def __init__(
+        self,
+        *,
+        user_id: str,
+        session_id: str = "default",
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        project_id: Optional[str] = None,
+        top_k: int = 5,
+        recall_timeout: float = 1.2,
+        min_prompt_chars: int = 8,
+        context_template: str = DEFAULT_CONTEXT_TEMPLATE,
+        clear_scope: str = "session",
+        source: str = "autogen",
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        # user_id is required, never auto-generated: the Mem0 adapter
+        # invents a random UUID per process when omitted, which silently
+        # strands every stored memory in a namespace nobody will ever
+        # query again. Refusing is kinder than losing data.
+        if not user_id or not str(user_id).strip():
+            raise ValueError("user_id is required and must be non-empty")
+        if clear_scope not in ("session", "user"):
+            raise ValueError('clear_scope must be "session" or "user"')
+        self.user_id = str(user_id).strip()
+        self.session_id = str(session_id or "default").strip() or "default"
+        self.top_k = top_k
+        self.recall_timeout = recall_timeout
+        self.min_prompt_chars = min_prompt_chars
+        self.context_template = context_template
+        self.clear_scope = clear_scope
+        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,
+        )
+
+    # ── component serialization ──────────────────────────────────────
+
+    def _to_config(self) -> MemorySyncMemoryConfig:
+        return MemorySyncMemoryConfig(
+            user_id=self.user_id,
+            session_id=self.session_id,
+            base_url=self._api.base_url,
+            top_k=self.top_k,
+            recall_timeout=self.recall_timeout,
+            min_prompt_chars=self.min_prompt_chars,
+            context_template=self.context_template,
+            clear_scope=self.clear_scope,
+        )
+
+    @classmethod
+    def _from_config(cls, config: MemorySyncMemoryConfig) -> "MemorySyncMemory":
+        return cls(
+            user_id=config.user_id,
+            session_id=config.session_id,
+            base_url=config.base_url,
+            project_id=config.project_id,
+            top_k=config.top_k,
+            recall_timeout=config.recall_timeout,
+            min_prompt_chars=config.min_prompt_chars,
+            context_template=config.context_template,
+            clear_scope=config.clear_scope,
+        )
+
+    # ── scope helpers ────────────────────────────────────────────────
+
+    @property
+    def _session_scope(self) -> str:
+        return f"autogen::{self.session_id}"
+
+    # ── the hot path ─────────────────────────────────────────────────
+
+    async def update_context(
+        self, model_context: ChatCompletionContext
+    ) -> UpdateContextResult:
+        """Inject relevant memories before the model call — budgeted.
+
+        Called automatically by ``AssistantAgent`` before every LLM
+        inference. Any failure here degrades to "no memories this turn";
+        it never raises into the agent.
+        """
+        empty = UpdateContextResult(memories=MemoryQueryResult(results=[]))
+        try:
+            messages = await model_context.get_messages()
+        except Exception:  # pragma: no cover - defensive
+            return empty
+        if not messages:
+            return empty
+
+        # Role-aware query: the last *user* message, not messages[-1].
+        query_text = ""
+        for message in reversed(messages):
+            if isinstance(message, UserMessage):
+                query_text = _text_of(message.content)
+                if query_text:
+                    break
+        if len(query_text.strip()) < self.min_prompt_chars:
+            return empty
+
+        try:
+            tenant_id = await asyncio.wait_for(
+                self._api.resolve_tenant_id(), timeout=self.recall_timeout
+            )
+            response = await asyncio.wait_for(
+                self._api.recall(
+                    tenant_id=tenant_id,
+                    user_id=self.user_id,
+                    prompt=query_text,
+                    k=self.top_k,
+                ),
+                timeout=self.recall_timeout,
+            )
+        except (asyncio.TimeoutError, MemorySyncAPIError, Exception) as exc:
+            logger.warning(
+                "MemorySync recall unavailable this turn (%s) — continuing without memories.",
+                exc,
+            )
+            return empty
+
+        context_block = response.get("context") if isinstance(response, dict) else ""
+        if not isinstance(context_block, str) or not context_block.strip():
+            return empty
+
+        results = self._memories_to_content(response.get("memories"))
+        if not results:
+            # Surface the injected block itself so MemoryQueryEvent still
+            # tells observers what the model saw.
+            results = [
+                MemoryContent(
+                    content=context_block,
+                    mime_type=MemoryMimeType.MARKDOWN,
+                    metadata={"kind": "context_block"},
+                )
+            ]
+
+        # .replace, never .format: memory text may contain { } % legally.
+        block = self.context_template.replace("{context}", context_block)
+        await model_context.add_message(SystemMessage(content=block))
+        return UpdateContextResult(memories=MemoryQueryResult(results=results))
+
+    @staticmethod
+    def _memories_to_content(raw: Any) -> List[MemoryContent]:
+        items: List[MemoryContent] = []
+        if not isinstance(raw, list):
+            return items
+        for entry in raw:
+            if not isinstance(entry, dict):
+                continue
+            text = (
+                entry.get("value")
+                or entry.get("text")
+                or entry.get("raw_text")
+                or ""
+            )
+            if not isinstance(text, str) or not text:
+                continue
+            metadata: Dict[str, Any] = {}
+            if entry.get("memory_id") is not None:
+                metadata["memory_id"] = str(entry["memory_id"])
+            elif entry.get("id") is not None:
+                metadata["memory_id"] = str(entry["id"])
+            if isinstance(entry.get("score"), (int, float)):
+                metadata["score"] = float(entry["score"])
+            items.append(
+                MemoryContent(
+                    content=text,
+                    mime_type=MemoryMimeType.TEXT,
+                    metadata=metadata or None,
+                )
+            )
+        return items
+
+    # ── explicit calls: fail loud ────────────────────────────────────
+
+    async def add(
+        self,
+        content: MemoryContent,
+        cancellation_token: Optional[CancellationToken] = None,
+    ) -> None:
+        """Persist one turn verbatim with a deterministic idempotency seed.
+
+        Role comes from ``content.metadata["role"]`` (``"user"`` or
+        ``"assistant"``; anything else counts as user). The caller's
+        metadata dict is **copied, never mutated** — the Mem0 adapter
+        pops keys out of the dict you handed it.
+        """
+        if _is_cancelled(cancellation_token):
+            return
+        text = self._render_text(content)
+        text = text.strip()
+        if not text:
+            return
+        if len(text) > MAX_TURN_CHARS:
+            text = text[:MAX_TURN_CHARS]
+
+        metadata = dict(content.metadata or {})  # copy: never mutate caller's dict
+        raw_role = str(metadata.pop("role", "user")).lower()
+        role = "ai" if raw_role in ("assistant", "ai") else "human"
+        metadata.pop("user_id", None)  # scoping is this adapter's job
+
+        seed = f"{role}@{self._session_scope}#h{fnv1a64(f'{role}:{text}')}"
+        tenant_id = await self._api.resolve_tenant_id()
+        payload_metadata: Dict[str, Any] = {"session_id": self._session_scope}
+        if metadata:
+            payload_metadata.update(metadata)
+        # Silent-quota responses ({"status": "ok"} with no id) are
+        # accepted-by-contract, not errors; definite failures raise.
+        await self._api.add_turn(
+            tenant_id=tenant_id,
+            user_id=self.user_id,
+            text=f"{role}: {text}",
+            speaker=seed,
+            metadata=payload_metadata,
+            source=self.source,
+        )
+
+    @staticmethod
+    def _render_text(content: MemoryContent) -> str:
+        mime = content.mime_type
+        mime_value = mime.value if isinstance(mime, MemoryMimeType) else str(mime)
+        value = content.content
+        if mime_value == "application/json" and not isinstance(value, str):
+            try:
+                return json.dumps(value, ensure_ascii=False)
+            except (TypeError, ValueError):
+                return str(value)
+        return value if isinstance(value, str) else str(value)
+
+    async def add_turn_pair(self, user_text: str, assistant_text: str) -> None:
+        """Persist one user/assistant exchange — the capture loop AutoGen
+        deliberately leaves to the application, reduced to one call."""
+        if user_text and user_text.strip():
+            await self.add(
+                MemoryContent(
+                    content=user_text,
+                    mime_type=MemoryMimeType.TEXT,
+                    metadata={"role": "user"},
+                )
+            )
+        if assistant_text and assistant_text.strip():
+            await self.add(
+                MemoryContent(
+                    content=assistant_text,
+                    mime_type=MemoryMimeType.TEXT,
+                    metadata={"role": "assistant"},
+                )
+            )
+
+    async def query(
+        self,
+        query: str | MemoryContent = "",
+        cancellation_token: Optional[CancellationToken] = None,
+        **kwargs: Any,
+    ) -> MemoryQueryResult:
+        """Semantic search. Raises on failure — an explicit query that
+        silently returns empty would make an outage look like amnesia."""
+        if _is_cancelled(cancellation_token):
+            return MemoryQueryResult(results=[])
+        query_text = (
+            query if isinstance(query, str) else _text_of(query.content) or str(query.content)
+        )
+        limit = kwargs.pop("limit", None) or kwargs.pop("k", None) or self.top_k
+        tenant_id = await self._api.resolve_tenant_id()
+        response = await self._api.query(
+            tenant_id=tenant_id,
+            user_id=self.user_id,
+            prompt=query_text,
+            k=int(limit),
+        )
+        raw = response.get("memories") if isinstance(response, dict) else []
+        return MemoryQueryResult(results=self._memories_to_content(raw))
+
+    async def clear(self) -> None:
+        """Delete stored memories — scoped to this session by default.
+
+        ``clear_scope="session"`` (default): only rows this adapter wrote
+        under ``autogen::<session>``. ``clear_scope="user"``: every memory
+        for the user — an explicit, documented opt-in, because an agent
+        framework calling ``clear()`` must never be able to erase a
+        customer's whole history by accident.
+        """
+        tenant_id = await self._api.resolve_tenant_id()
+        items = await self._api.list_memories(
+            tenant_id=tenant_id, user_id=self.user_id
+        )
+        ids: List[int] = []
+        for item in items:
+            if self.clear_scope == "session" and not self._in_session(item):
+                continue
+            parsed = self._parse_id(item.get("memory_id"))
+            if parsed is not None:
+                ids.append(parsed)
+        await self._api.forget(user_id=self.user_id, memory_ids=ids)
+
+    def _in_session(self, item: Dict[str, Any]) -> 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 = item.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 == self._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
+
+    async def close(self) -> None:
+        """Release the HTTP client (Mem0's close() is a no-op ``pass``)."""
+        await self._api.aclose()

autogen_memorysync/tools.py

@@ -0,0 +1,53 @@
+"""Model-callable memory tools for tool-equipped AutoGen agents."""
+
+from __future__ import annotations
+
+from typing import List
+
+from autogen_core.tools import FunctionTool
+
+from .memory import MemorySyncMemory
+
+
+def create_memory_tools(memory: MemorySyncMemory) -> List[FunctionTool]:
+    """Two ``FunctionTool``s bound to one adapter: search and save.
+
+    ``search_memory`` reads through the same budgetless explicit path as
+    ``Memory.query`` (the model chose to wait). ``save_memory`` goes
+    through the server's extraction path, so the server — not the model —
+    decides whether the text is durable enough to keep.
+    """
+
+    async def search_memory(query: str, limit: int = 5) -> str:
+        """Search the user's long-term memory for relevant context."""
+        result = await memory.query(query, limit=limit)
+        if not result.results:
+            return "No relevant memories found."
+        lines = []
+        for i, item in enumerate(result.results, 1):
+            lines.append(f"{i}. {item.content}")
+        return "\n".join(lines)
+
+    async def save_memory(text: str) -> str:
+        """Save an important fact about the user to long-term memory."""
+        response = await memory._api.add_memory(
+            user_id=memory.user_id, text=text, source=memory.source
+        )
+        if isinstance(response, dict) and response.get("id") is not None:
+            return f"Saved (id m_{response['id']})."
+        if isinstance(response, dict) and response.get("status") == "skipped":
+            return "Not saved: no durable content."
+        return "Accepted."
+
+    return [
+        FunctionTool(
+            search_memory,
+            name="search_memory",
+            description="Search the user's long-term memory for relevant context and preferences.",
+        ),
+        FunctionTool(
+            save_memory,
+            name="save_memory",
+            description="Save an important, durable fact about the user to long-term memory.",
+        ),
+    ]

autogen_memorysync-1.0.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: autogen-memorysync
+Version: 1.0.0
+Summary: MemorySync for Microsoft AutoGen: an async-native Memory implementation with a hard recall budget, role-aware retrieval, duplicate-proof persistence, and session-scoped clear.
+Project-URL: Homepage, https://docs.memorysync.io/guides/autogen
+Project-URL: Documentation, https://docs.memorysync.io/guides/autogen
+Project-URL: Repository, https://github.com/Rafay121/memorysync-plugins
+Author-email: MemorySync <support@memorysync.io>
+License-Expression: MIT
+Keywords: agents,autogen,autogen-agentchat,long-term-memory,memory,memorysync
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+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.10
+Requires-Dist: autogen-core<0.8,>=0.4.0
+Requires-Dist: httpx<1,>=0.25
+Description-Content-Type: text/markdown
+
+# autogen-memorysync
+
+[MemorySync](https://memorysync.io) for [Microsoft AutoGen](https://github.com/microsoft/autogen)
+(`autogen-agentchat` 0.4+): agents that remember users across sessions —
+without ever stalling a turn.
+
+```bash
+pip install autogen-memorysync
+```
+
+## Quick start
+
+```python
+from autogen_agentchat.agents import AssistantAgent
+from autogen_memorysync import MemorySyncMemory
+
+memory = MemorySyncMemory(
+    api_key="ms_...",              # or MEMORYSYNC_API_KEY
+    user_id="customer-42",         # required — who these memories belong to
+    session_id="support-chat",     # scopes the transcript
+)
+
+agent = AssistantAgent("assistant", model_client=..., memory=[memory])
+
+result = await agent.run(task=user_text)
+# AutoGen never persists automatically — capture the exchange in one call:
+await memory.add_turn_pair(user_text, result.messages[-1].content)
+```
+
+`update_context` runs automatically before every model call: relevant
+memories are recalled and injected as a `SystemMessage`, and the
+retrieval surfaces to observers as a `MemoryQueryEvent`.
+
+## Why this one
+
+| | Mem0 (`autogen-ext[mem0]`) | Zep (`zep-autogen`) | **MemorySync** |
+| --- | --- | --- | --- |
+| Async correctness | ✗ sync client inside `async def` — blocks the event loop | ✓ | ✓ `httpx.AsyncClient` throughout |
+| Recall latency budget | ✗ none | ✗ none | ✓ hard 1.2s default — a slow backend means an unenriched turn, never a late one |
+| Retrieval query | ✗ `messages[-1]` even when it's assistant/tool text | last context message | ✓ last **user** message, role-aware |
+| Query errors | ✗ swallowed — outage looks like amnesia | logged | ✓ explicit `query()` raises; only the hot path fails open |
+| `clear()` blast radius | ✗ entire user | ✗ entire user | ✓ **session-scoped by default**; whole-user wipe is an explicit opt-in |
+| Retry safety | ✗ | ✗ | ✓ deterministic idempotency seeds — retries converge on one row |
+| Caller's metadata dict | ✗ mutated (`pop`) | — | ✓ copied, never touched |
+| `close()` | `pass` | ✓ | ✓ releases the HTTP client |
+
+## Semantics worth knowing
+
+- **The turn is never stalled and never broken.** Recall waits at most
+  `recall_timeout` (default 1.2s); on timeout, outage, or quota
+  exhaustion the agent simply answers without memories.
+- **`user_id` is required.** No silent auto-generated UUID namespaces
+  where stored memories can never be found again.
+- Turns store verbatim under the `autogen::<session>` transcript scope —
+  separate history, same shared user memories as every other MemorySync
+  surface.
+- Free-tier quota exhaustion is silent by design (adds accepted-without-
+  storing, reads empty); evaluation keys surface strict `429`s.
+- `create_memory_tools(memory)` returns `search_memory` + `save_memory`
+  `FunctionTool`s for tool-equipped agents.
+
+## Configuration
+
+| Parameter | Default | Meaning |
+| --- | --- | --- |
+| `user_id` | — (required) | End user the memories belong to |
+| `session_id` | `"default"` | Transcript scope |
+| `top_k` | `5` | Memories considered per turn |
+| `recall_timeout` | `1.2` | Hard recall budget, seconds |
+| `min_prompt_chars` | `8` | Skip recall for trivial prompts |
+| `context_template` | built-in | `{context}` placeholder, brace-safe `.replace` rendering |
+| `clear_scope` | `"session"` | `clear()` blast radius; `"user"` opt-in wipes everything |
+
+## Development
+
+```bash
+pip install -e . autogen-agentchat autogen-ext pytest pytest-asyncio
+python -m pytest tests -q      # 33 tests incl. a REAL AssistantAgent drive
+```
+
+Note: `autogen-agentchat` is in maintenance mode (Microsoft's successor
+is the Microsoft Agent Framework — a separate MemorySync adapter target).
+Maintenance mode means the `Memory` protocol this package implements is
+frozen and stable.
+
+## License
+
+MIT

autogen_memorysync-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+autogen_memorysync/__init__.py,sha256=PiFu40CqP-kZOvQTZuWZbBmPO_W4_LHCgODOQWB0RX4,497
+autogen_memorysync/_api.py,sha256=B2NsPJRRoHPCNv86yA6XrDdDxudVu-EBKm_sfWfpb7w,11153
+autogen_memorysync/_version.py,sha256=ZhzQKWZ8RFrTIkj7z87B144DI95e8LMfA5w8NDWQDtg,23
+autogen_memorysync/memory.py,sha256=96U2XS4Y763PLL7Q_whlv0YB971gZxwASLzNbseUAwk,18230
+autogen_memorysync/tools.py,sha256=1qJncGUnaGdWCy9wjocHK51SX-I6TsHvOzv71MU4jGs,2048
+autogen_memorysync-1.0.0.dist-info/METADATA,sha256=R7MCtmXzext1rWTwAeOz4SeW-tLtmsQVRcVr0D3VivA,4997
+autogen_memorysync-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+autogen_memorysync-1.0.0.dist-info/RECORD,,

autogen_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