ag2-memorysync 1.0.0__py3-none-any.whl

ag2_memorysync/__init__.py

@@ -0,0 +1,15 @@
+"""MemorySync for AG2 (AutoGen classic ConversableAgent framework)."""
+
+from ._api import MemorySyncAPIError, fnv1a64
+from ._version import __version__
+from .capability import DEFAULT_CONTEXT_TEMPLATE, MemorySyncCapability
+from .tools import register_memory_tools
+
+__all__ = [
+    "MemorySyncCapability",
+    "MemorySyncAPIError",
+    "DEFAULT_CONTEXT_TEMPLATE",
+    "register_memory_tools",
+    "fnv1a64",
+    "__version__",
+]

ag2_memorysync/_api.py

@@ -0,0 +1,291 @@
+"""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: it lives on the bridge's dedicated
+event loop, and AG2's synchronous hooks submit work to it without ever
+touching the caller's loop.
+"""
+
+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"ag2-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 = "ag2",
+        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."""
+        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 add_memory(
+        self,
+        *,
+        user_id: str,
+        text: str,
+        source: str = "ag2",
+        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 {}
+        )

ag2_memorysync/_bridge.py

@@ -0,0 +1,96 @@
+"""One persistent background event loop bridging AG2's sync hooks to
+async MemorySync calls.
+
+AG2-classic's ``register_hook`` accepts only synchronous callables, so
+every memory integration must bridge to async I/O somehow. The naive
+bridge — spin up a fresh event loop per call — pays loop-startup latency
+on every turn and carries a documented deadlock caveat in Zep's adapter
+when the caller is already inside an async context.
+
+This bridge instead runs ONE daemon thread with ONE long-lived event
+loop per process. Callers submit coroutines with
+``run_coroutine_threadsafe``:
+
+- **The caller's own event loop is never touched.** Whether the hook
+  fires from plain ``initiate_chat`` or from inside somebody's
+  ``asyncio.run(...)``, the coroutine executes on the bridge's loop and
+  the hook thread blocks — bounded by an explicit timeout — on a plain
+  ``concurrent.futures`` future. No re-entrancy, no deadlock.
+- **Fire-and-forget writes stay off the hot path.** Persistence submits
+  and returns immediately; ``flush()`` awaits stragglers at shutdown or
+  in tests.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import logging
+import threading
+from typing import Any, Coroutine, Optional, Set
+
+logger = logging.getLogger("ag2_memorysync")
+
+
+class LoopBridge:
+    _shared: Optional["LoopBridge"] = None
+    _shared_lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._loop = asyncio.new_event_loop()
+        self._thread = threading.Thread(
+            target=self._run, name="memorysync-ag2-bridge", daemon=True
+        )
+        self._pending: Set[concurrent.futures.Future] = set()
+        self._pending_lock = threading.Lock()
+        self._thread.start()
+
+    @classmethod
+    def shared(cls) -> "LoopBridge":
+        with cls._shared_lock:
+            if cls._shared is None or not cls._shared._thread.is_alive():
+                cls._shared = cls()
+            return cls._shared
+
+    def _run(self) -> None:
+        asyncio.set_event_loop(self._loop)
+        self._loop.run_forever()
+
+    @property
+    def loop(self) -> asyncio.AbstractEventLoop:
+        return self._loop
+
+    def call(self, coro: Coroutine[Any, Any, Any], timeout: float) -> Any:
+        """Run a coroutine on the bridge loop; block at most ``timeout``.
+
+        On timeout the underlying task is cancelled so a slow backend
+        cannot pile up abandoned work.
+        """
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        try:
+            return future.result(timeout)
+        except concurrent.futures.TimeoutError:
+            future.cancel()
+            raise
+
+    def submit(self, coro: Coroutine[Any, Any, Any], label: str) -> None:
+        """Fire-and-forget: schedule, log failures, never block."""
+        future = asyncio.run_coroutine_threadsafe(coro, self._loop)
+        with self._pending_lock:
+            self._pending.add(future)
+
+        def _done(f: concurrent.futures.Future) -> None:
+            with self._pending_lock:
+                self._pending.discard(f)
+            exc = f.exception() if not f.cancelled() else None
+            if exc is not None:
+                logger.warning("MemorySync %s skipped (%s)", label, exc)
+
+        future.add_done_callback(_done)
+
+    def flush(self, timeout: float = 10.0) -> None:
+        """Wait for all in-flight fire-and-forget work to land."""
+        with self._pending_lock:
+            pending = list(self._pending)
+        if pending:
+            concurrent.futures.wait(pending, timeout=timeout)

ag2_memorysync/_version.py

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

ag2_memorysync/capability.py

@@ -0,0 +1,353 @@
+"""The automatic MemorySync memory loop for AG2-classic ConversableAgents.
+
+AG2-classic has no memory protocol; ``ConversableAgent.register_hook``
+is its only per-turn seam, and every hook must be a synchronous
+callable. This capability wires two hooks:
+
+- ``process_last_received_message`` (fires inside ``generate_reply``,
+  before the LLM): persists the ORIGINAL incoming text as a human turn
+  (fire-and-forget), recalls relevant context under a hard budget, and
+  returns the message with a context prefix. Verified AG2 behaviour: the
+  hook's return value feeds the LLM only — it is never written back to
+  ``_oai_messages`` — so the injected prefix can never re-persist.
+- ``process_message_before_send`` (fires on ``send``/``a_send``):
+  persists the outgoing reply as an ai turn (fire-and-forget) and
+  returns the message untouched.
+
+Design rules, in priority order:
+
+1. **The reply is never stalled and never broken.** Recall blocks the
+   hook for at most ``recall_timeout`` seconds (default 1.2); on
+   timeout, outage, or quota exhaustion the message passes through
+   unmodified. Persistence never blocks the hot path at all.
+2. **No duplicate rows — even in multi-agent chats.** Zep's zep-ag2
+   README documents this bug in their own adapter: when two attached
+   agents share a session, A's outgoing "X" (ai) is B's incoming "X"
+   (human), so every utterance stores twice with conflicting roles. A
+   process-wide registry of recently persisted content marks lets the
+   receiving side recognise and skip what the sending side just stored.
+   Same-role retries additionally converge server-side via
+   deterministic idempotency seeds.
+3. **No event-loop games.** All async work runs on one persistent
+   background loop (``_bridge.LoopBridge``); the caller's thread — and
+   the caller's event loop, if any — are never touched. Zep spins a new
+   loop per call and documents a deadlock caveat for async callers.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import Any, Dict, List, Optional, Set, Tuple, Union
+
+import httpx
+
+from ._api import (
+    MAX_TURN_CHARS,
+    AsyncV1Api,
+    MemorySyncAPIError,
+    fnv1a64,
+    resolve_api_key,
+    resolve_base_url,
+)
+from ._bridge import LoopBridge
+
+logger = logging.getLogger("ag2_memorysync")
+
+DEFAULT_CONTEXT_TEMPLATE = (
+    "Relevant user memories (MemorySync):\n{context}\n\n"
+)
+
+#: How long a cross-agent dedup mark stays fresh, in seconds.
+_MARK_TTL_S = 300.0
+
+
+class _DedupRegistry:
+    """Process-wide marks of recently persisted turns.
+
+    Key: ``(session_scope, content_hash)``. When agent A persists its
+    outgoing message, the mark lets agent B — receiving that same text a
+    microsecond later — recognise it and skip the double-store.
+    """
+
+    def __init__(self) -> None:
+        self._marks: Dict[Tuple[str, str], float] = {}
+        self._lock = threading.Lock()
+
+    def mark(self, session_scope: str, content_hash: str) -> None:
+        with self._lock:
+            self._prune()
+            self._marks[(session_scope, content_hash)] = time.monotonic()
+
+    def seen(self, session_scope: str, content_hash: str) -> bool:
+        with self._lock:
+            self._prune()
+            return (session_scope, content_hash) in self._marks
+
+    def _prune(self) -> None:
+        cutoff = time.monotonic() - _MARK_TTL_S
+        stale = [k for k, t in self._marks.items() if t < cutoff]
+        for k in stale:
+            del self._marks[k]
+
+
+_registry = _DedupRegistry()
+
+_MessageShape = Union[Dict[str, Any], str]
+_ContentShape = Union[str, List[Any]]
+
+
+def _content_of(message: Any) -> str:
+    if isinstance(message, str):
+        return message
+    if isinstance(message, list):
+        # Multimodal content: a list of {"type": "text", "text": ...} parts.
+        return "\n".join(
+            part.get("text", "")
+            for part in message
+            if isinstance(part, dict) and part.get("type") == "text"
+        ).strip()
+    if isinstance(message, dict):
+        return _content_of(message.get("content"))
+    return ""
+
+
+def _role_of(message: _MessageShape) -> str:
+    if isinstance(message, dict):
+        return str(message.get("role") or "")
+    return ""
+
+
+class MemorySyncCapability:
+    """Attachable long-term memory for one AG2-classic agent.
+
+    Usage::
+
+        from autogen import ConversableAgent
+        from ag2_memorysync import MemorySyncCapability
+
+        agent = ConversableAgent("assistant", llm_config=...)
+        memory = MemorySyncCapability(user_id="customer-42", session_id="support")
+        memory.add_to_agent(agent)
+
+    From then on every incoming user message is persisted and enriched
+    with recalled context, and every outgoing reply is persisted — with
+    no further code.
+    """
+
+    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,
+        capture: str = "both",
+        source: str = "ag2",
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        if not user_id or not str(user_id).strip():
+            raise ValueError("user_id is required and must be non-empty")
+        if capture not in ("both", "received", "sent"):
+            raise ValueError('capture must be "both", "received", or "sent"')
+        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.capture = capture
+        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,
+        )
+        self._bridge = LoopBridge.shared()
+        self._attached: Set[int] = set()
+
+    # ── scope helpers ────────────────────────────────────────────────
+
+    @property
+    def _session_scope(self) -> str:
+        return f"ag2::{self.session_id}"
+
+    # ── attachment ───────────────────────────────────────────────────
+
+    def add_to_agent(self, agent: Any) -> None:
+        """Register the memory hooks on a ConversableAgent.
+
+        Duck-typed: any object with AG2-classic's ``register_hook``
+        contract works, so this package needs no dependency on any
+        specific AutoGen distribution (and cannot version-conflict).
+        """
+        register = getattr(agent, "register_hook", None)
+        if not callable(register):
+            raise TypeError(
+                "add_to_agent expects an AG2-classic ConversableAgent "
+                "(an object with register_hook). Install the classic "
+                "framework with `pip install autogen` and construct a "
+                "ConversableAgent — the rewritten `pip install ag2` v1 "
+                "package has no hook system yet."
+            )
+        if id(agent) in self._attached:
+            return  # attaching twice must not double-register hooks
+        if self.capture in ("both", "received"):
+            register(
+                hookable_method="process_last_received_message",
+                hook=self._on_received,
+            )
+        if self.capture in ("both", "sent"):
+            register(
+                hookable_method="process_message_before_send",
+                hook=self._on_send,
+            )
+        self._attached.add(id(agent))
+
+    # ── hook 1: incoming ─────────────────────────────────────────────
+
+    def _on_received(self, content: _ContentShape) -> _ContentShape:
+        """Persist the ORIGINAL text, then return it context-prefixed.
+
+        AG2's dispatcher hands hooks the last message's CONTENT only —
+        a string, or a multimodal part list — and has already filtered
+        out function calls, context-carrying messages, and "exit". The
+        hook's return value replaces the content the LLM sees; it is
+        never written back to the stored conversation.
+        """
+        text = _content_of(content).strip()
+        if not text:
+            return content
+
+        if self.capture in ("both", "received"):
+            self._persist(role="human", text=text)
+
+        if len(text) < self.min_prompt_chars:
+            return content
+
+        recalled = self._recall_bounded(text)
+        if not recalled:
+            return content
+
+        # .replace, never .format: memory text may contain { } % legally.
+        prefix = self.context_template.replace("{context}", recalled)
+        if isinstance(content, str):
+            return prefix + content
+        if isinstance(content, list):
+            return [{"type": "text", "text": prefix}] + list(content)
+        return content
+
+    # ── hook 2: outgoing ─────────────────────────────────────────────
+
+    def _on_send(
+        self,
+        sender: Any,
+        message: _MessageShape,
+        recipient: Any,
+        silent: bool,
+    ) -> _MessageShape:
+        """Persist the outgoing reply; return the message untouched."""
+        if isinstance(message, dict) and (
+            _role_of(message) in ("tool", "function") or "function_call" in message or "tool_calls" in message
+        ):
+            return message  # never persist tool noise
+        text = _content_of(message).strip()
+        if text:
+            self._persist(role="ai", text=text)
+        return message
+
+    # ── persistence (fire-and-forget, duplicate-proof) ───────────────
+
+    def _persist(self, *, role: str, text: str) -> None:
+        if len(text) > MAX_TURN_CHARS:
+            text = text[:MAX_TURN_CHARS]
+        content_hash = fnv1a64(text)
+        if _registry.seen(self._session_scope, content_hash):
+            # The other side of this exchange just stored the same
+            # content in this session (Zep's documented double-store
+            # scenario) — one row is the truth, skip the second.
+            return
+        _registry.mark(self._session_scope, content_hash)
+        seed = f"{role}@{self._session_scope}#h{fnv1a64(f'{role}:{text}')}"
+
+        async def _store() -> None:
+            tenant_id = await self._api.resolve_tenant_id()
+            await self._api.add_turn(
+                tenant_id=tenant_id,
+                user_id=self.user_id,
+                text=f"{role}: {text}",
+                speaker=seed,
+                metadata={"session_id": self._session_scope},
+                source=self.source,
+            )
+
+        self._bridge.submit(_store(), label=f"{role}-turn store")
+
+    # ── recall (budgeted, fail-open) ─────────────────────────────────
+
+    def _recall_bounded(self, prompt: str) -> str:
+        async def _recall() -> str:
+            tenant_id = await self._api.resolve_tenant_id()
+            response = await self._api.recall(
+                tenant_id=tenant_id,
+                user_id=self.user_id,
+                prompt=prompt,
+                k=self.top_k,
+            )
+            block = response.get("context") if isinstance(response, dict) else ""
+            return block if isinstance(block, str) else ""
+
+        try:
+            context = self._bridge.call(_recall(), timeout=self.recall_timeout)
+        except Exception as exc:
+            logger.warning(
+                "MemorySync recall unavailable this turn (%s) — continuing without memories.",
+                exc,
+            )
+            return ""
+        return context.strip() if isinstance(context, str) else ""
+
+    # ── explicit operations ──────────────────────────────────────────
+
+    def search(self, query: str, *, limit: Optional[int] = None) -> List[Dict[str, Any]]:
+        """Synchronous semantic search (raises on definite failure)."""
+
+        async def _query() -> List[Dict[str, Any]]:
+            tenant_id = await self._api.resolve_tenant_id()
+            response = await self._api.query(
+                tenant_id=tenant_id,
+                user_id=self.user_id,
+                prompt=query,
+                k=limit or self.top_k,
+            )
+            raw = response.get("memories") if isinstance(response, dict) else []
+            return list(raw) if isinstance(raw, list) else []
+
+        return self._bridge.call(_query(), timeout=max(self.recall_timeout * 4, 8.0))
+
+    def save(self, text: str) -> Dict[str, Any]:
+        """Synchronously store a fact through the extraction path."""
+
+        async def _save() -> Dict[str, Any]:
+            return await self._api.add_memory(
+                user_id=self.user_id, text=text, source=self.source
+            )
+
+        return self._bridge.call(_save(), timeout=max(self.recall_timeout * 4, 8.0))
+
+    def flush(self, timeout: float = 10.0) -> None:
+        """Wait for all fire-and-forget writes to land (tests, shutdown)."""
+        self._bridge.flush(timeout=timeout)
+
+    def close(self) -> None:
+        """Flush pending writes and release the HTTP client."""
+        self.flush()
+        self._bridge.call(self._api.aclose(), timeout=10.0)

ag2_memorysync/tools.py

@@ -0,0 +1,67 @@
+"""Model-callable memory tools for AG2-classic agents.
+
+No ``from __future__ import annotations`` here on purpose: AG2's
+function-schema generator resolves tool annotations at registration
+time, and postponed annotations become unresolvable strings inside its
+TypeAdapter.
+"""
+
+from typing import Any
+
+from .capability import MemorySyncCapability
+
+
+def register_memory_tools(
+    memory: MemorySyncCapability,
+    *,
+    caller: Any,
+    executor: Any,
+) -> None:
+    """Register ``search_memory`` and ``save_memory`` on an agent pair.
+
+    ``caller`` is the LLM agent that decides to call the tool;
+    ``executor`` actually runs it (AG2-classic's standard split). Both
+    functions are synchronous — they ride the capability's bridge, so
+    they work in plain ``initiate_chat`` without event-loop concerns.
+    """
+    try:
+        from autogen import register_function
+    except ImportError as exc:  # pragma: no cover - guarded by tests
+        raise ImportError(
+            "register_memory_tools needs AG2-classic: `pip install autogen`."
+        ) from exc
+
+    def search_memory(query: str, limit: int = 5) -> str:
+        """Search the user's long-term memory for relevant context."""
+        hits = memory.search(query, limit=limit)
+        if not hits:
+            return "No relevant memories found."
+        lines = []
+        for i, hit in enumerate(hits, 1):
+            text = hit.get("value") or hit.get("text") or hit.get("raw_text") or ""
+            lines.append(f"{i}. {text}")
+        return "\n".join(lines)
+
+    def save_memory(text: str) -> str:
+        """Save an important, durable fact about the user to long-term memory."""
+        response = memory.save(text)
+        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."
+
+    register_function(
+        search_memory,
+        caller=caller,
+        executor=executor,
+        name="search_memory",
+        description="Search the user's long-term memory for relevant context and preferences.",
+    )
+    register_function(
+        save_memory,
+        caller=caller,
+        executor=executor,
+        name="save_memory",
+        description="Save an important, durable fact about the user to long-term memory.",
+    )

ag2_memorysync-1.0.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: ag2-memorysync
+Version: 1.0.0
+Summary: MemorySync for AG2 (AutoGen classic): an automatic memory loop on ConversableAgent's hook system — budgeted recall injection, duplicate-proof both-side capture, and a deadlock-free sync bridge.
+Project-URL: Homepage, https://docs.memorysync.io/guides/ag2
+Project-URL: Documentation, https://docs.memorysync.io/guides/ag2
+Project-URL: Repository, https://github.com/Rafay121/memorysync-plugins
+Author-email: MemorySync <support@memorysync.io>
+License-Expression: MIT
+Keywords: ag2,agents,autogen,conversableagent,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: httpx<1,>=0.25
+Description-Content-Type: text/markdown
+
+# ag2-memorysync
+
+[MemorySync](https://memorysync.io) for [AG2](https://github.com/ag2ai/ag2-classic)
+(the classic AutoGen `ConversableAgent` framework, `pip install autogen`):
+an automatic memory loop — recall injected before every reply, both sides
+persisted, zero extra code per turn.
+
+```bash
+pip install ag2-memorysync
+```
+
+## Quick start
+
+```python
+from autogen import ConversableAgent
+from ag2_memorysync import MemorySyncCapability
+
+assistant = ConversableAgent("assistant", llm_config=...)
+
+memory = MemorySyncCapability(
+    api_key="ms_...",              # or MEMORYSYNC_API_KEY
+    user_id="customer-42",         # required — who these memories belong to
+    session_id="support-chat",     # scopes the transcript
+)
+memory.add_to_agent(assistant)     # that's the whole integration
+```
+
+From then on every incoming user message is persisted and enriched with
+recalled context, and every outgoing reply is persisted — through AG2's
+own hook system (`process_last_received_message` +
+`process_message_before_send`).
+
+## Why this one
+
+| | Mem0 | Zep (`zep-ag2`) | **MemorySync** |
+| --- | --- | --- | --- |
+| AG2 adapter exists | ✗ docs show an AutoGen-0.2 recipe with placeholder model names | ✓ | ✓ |
+| Multi-agent duplication | — | ✗ **documented bug**: two attached agents store every utterance twice with conflicting roles | ✓ cross-hook dedup registry + idempotency seeds — one utterance, one row (by test) |
+| Sync→async bridge | — | per-call event-loop spin; documented deadlock caveat under asyncio | ✓ one persistent background loop; never touches the caller's loop (asyncio-driven chats pass, by test) |
+| Recall latency budget | — | ✗ none | ✓ hard 1.2s default — the reply is never late |
+| Framework pin | — | ✗ `ag2<1` — breaks on the v1 rewrite | ✓ **zero framework dependency** (duck-typed attach; works with whichever classic distribution you installed) |
+| Injected context re-stored? | — | system-message mutation, last-write-wins | ✓ hook output feeds the LLM only; the ORIGINAL text is what persists |
+
+## Semantics worth knowing
+
+- **The reply is never stalled and never broken.** Recall blocks at most
+  `recall_timeout` (default 1.2s); persistence is fire-and-forget off
+  the hot path. Outages and quota exhaustion degrade to "no memories
+  this turn".
+- Turns store verbatim under the `ag2::<session>` transcript scope with
+  deterministic idempotency seeds — retries and multi-agent echoes
+  converge on one stored row.
+- Tool/function messages are never persisted.
+- `register_memory_tools(memory, caller=..., executor=...)` adds
+  `search_memory` + `save_memory` tools (the caller needs an
+  `llm_config`, as usual for AG2 tools).
+- `memory.flush()` waits for in-flight writes (shutdown/tests);
+  `memory.close()` flushes and releases the HTTP client.
+
+## 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 messages |
+| `context_template` | built-in | `{context}` placeholder, brace-safe `.replace` rendering |
+| `capture` | `"both"` | `"received"` / `"sent"` to capture one side only |
+
+## Development
+
+```bash
+pip install -e . "autogen[openai]" pytest
+python -m pytest tests -q      # 22 tests through REAL ConversableAgent chats
+```
+
+The suite includes a reproduction of zep-ag2's documented multi-agent
+double-store scenario (we store once) and a chat driven from inside
+`asyncio.run()` (no deadlock).
+
+## License
+
+MIT

ag2_memorysync-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+ag2_memorysync/__init__.py,sha256=GiAIlC4rS7-sYNvUZ_ysYPFXgWYEx-Wrx4l9dffd93U,443
+ag2_memorysync/_api.py,sha256=1mpd0aZO1e_OFyo2CShklvorhuTCaoxItqd7C7hG5Vg,10300
+ag2_memorysync/_bridge.py,sha256=MMWfuaHf4586kAhtoxuEwBELObdDLottBoTBHDlOzhw,3640
+ag2_memorysync/_version.py,sha256=ZhzQKWZ8RFrTIkj7z87B144DI95e8LMfA5w8NDWQDtg,23
+ag2_memorysync/capability.py,sha256=I6LYCdOhShojHQvbXhDlI9LFq3W0kHvb9gSnRiFftYU,14265
+ag2_memorysync/tools.py,sha256=uPiqQBSX1MKen9MK5c26LD6xWU97cnXPWfXx9vzAdzY,2496
+ag2_memorysync-1.0.0.dist-info/METADATA,sha256=hQ6RMYa8JYwoFDxMSFbOOOSWiZakd1-CM4E2mQCuvNY,4838
+ag2_memorysync-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+ag2_memorysync-1.0.0.dist-info/RECORD,,

ag2_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