agent-framework-memorysync 1.0.0__py3-none-any.whl

agent_framework_memorysync/__init__.py

@@ -0,0 +1,18 @@
+"""MemorySync for the Microsoft Agent Framework."""
+
+from ._api import MemorySyncAPIError, fnv1a64
+from ._version import __version__
+from .provider import (
+    DEFAULT_CONTEXT_TEMPLATE,
+    RUN_OPTION_USER_ID,
+    MemorySyncContextProvider,
+)
+
+__all__ = [
+    "MemorySyncContextProvider",
+    "MemorySyncAPIError",
+    "DEFAULT_CONTEXT_TEMPLATE",
+    "RUN_OPTION_USER_ID",
+    "fnv1a64",
+    "__version__",
+]

agent_framework_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: the Agent Framework's ContextProvider
+lifecycle is fully async, so the client rides the same event loop the
+agent runs on.
+"""
+
+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"agent-framework-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."""
+
+    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 = "agent-framework",
+        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 = "agent-framework",
+        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 {}
+        )

agent_framework_memorysync/_version.py

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

agent_framework_memorysync/provider.py

@@ -0,0 +1,330 @@
+"""MemorySync context provider for the Microsoft Agent Framework.
+
+Design rules, in priority order:
+
+1. **A run is never stalled and never broken.** ``before_run`` recalls
+   under a hard budget (default 1.2s) and injects nothing on a miss;
+   ``after_run`` persistence is entirely fail-open. The first-party Mem0
+   provider does the opposite on both counts: no timeout anywhere, and
+   an ``after_run`` failure PROPAGATES and crashes the agent.
+
+2. **Context belongs in the instructions layer.** Recalled memories are
+   injected via ``context.extend_instructions`` — the system layer —
+   never as a fabricated ``role="user"`` message (Mem0's approach, which
+   pollutes the conversation the model believes the user wrote).
+
+3. **One identity drives everything.** The same resolved user id scopes
+   recall AND capture. Mem0 splits storage (``user_id``) from retrieval
+   (``search_user_id``); forget the second and your agent is silently
+   memoryless. Here that bug cannot exist.
+
+4. **Per-run identity exists.** Both Mem0 and Zep bind identity at
+   construction and document it as a framework limitation. This provider
+   adds two escapes: pass ``memorysync_user_id=...`` straight through
+   ``agent.run(...)`` (it arrives in ``context.options``), or supply a
+   ``user_id_resolver`` callable. Construction-time ``user_id`` is the
+   fallback.
+
+5. **Capture is duplicate-proof and once-per-turn.**
+   ``after_run_once_per_turn = True`` so tool-loop agents persist a turn
+   exactly once, and every stored turn carries a deterministic
+   idempotency seed — retries converge on one row.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Callable, List, Optional
+
+import httpx
+
+from agent_framework import AgentSession, ContextProvider
+
+from ._api import (
+    MAX_TURN_CHARS,
+    AsyncV1Api,
+    MemorySyncAPIError,
+    fnv1a64,
+    resolve_api_key,
+    resolve_base_url,
+)
+
+logger = logging.getLogger("agent_framework_memorysync")
+
+DEFAULT_CONTEXT_TEMPLATE = (
+    "The following long-term memories about the user were retrieved from "
+    "MemorySync. Use them to inform your response.\n\n"
+    "<MEMORYSYNC_CONTEXT>\n{context}\n</MEMORYSYNC_CONTEXT>"
+)
+
+#: The agent.run() option key carrying a per-run user id.
+RUN_OPTION_USER_ID = "memorysync_user_id"
+
+
+def _text_of_message(message: Any) -> str:
+    """Best-effort plain text from an agent-framework Message."""
+    text = getattr(message, "text", None)
+    if isinstance(text, str) and text.strip():
+        return text.strip()
+    return ""
+
+
+def _role_of_message(message: Any) -> str:
+    role = getattr(message, "role", "")
+    value = getattr(role, "value", role)
+    return str(value or "").lower()
+
+
+class MemorySyncContextProvider(ContextProvider):
+    """Long-term memory for Agent Framework agents.
+
+    Wire it up::
+
+        from agent_framework import Agent
+        from agent_framework_memorysync import MemorySyncContextProvider
+
+        provider = MemorySyncContextProvider(
+            api_key="ms_...",          # or MEMORYSYNC_API_KEY
+            user_id="customer-42",
+            session_id="support",
+        )
+        agent = Agent(client=..., context_providers=[provider])
+
+    Every run recalls relevant memories into the instructions layer, and
+    both sides of the exchange persist automatically after the run.
+    """
+
+    # Tool-loop agents make several model round-trips per user turn; the
+    # capture must fire once per turn, not once per round-trip.
+    after_run_once_per_turn: bool = True
+
+    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,
+        source_id: str = "memorysync",
+        top_k: int = 5,
+        recall_timeout: float = 1.2,
+        min_prompt_chars: int = 8,
+        context_template: str = DEFAULT_CONTEXT_TEMPLATE,
+        capture: bool = True,
+        expose_search_tool: bool = False,
+        user_id_resolver: Optional[Callable[[AgentSession], Optional[str]]] = None,
+        source: str = "agent-framework",
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        super().__init__(source_id)
+        if not user_id or not str(user_id).strip():
+            raise ValueError("user_id is required and must be non-empty")
+        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.expose_search_tool = expose_search_tool
+        self.user_id_resolver = user_id_resolver
+        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._warmed = False
+        # Warm the connection off the hot path when a loop is already
+        # running: resolve the tenant and open the TLS/HTTP session now, so
+        # the FIRST run's bounded recall spends its budget on the recall
+        # itself — not connection setup.
+        try:
+            asyncio.get_running_loop().create_task(self._api.resolve_tenant_id())
+        except Exception:  # no running loop yet — the first-call grace covers it
+            pass
+
+    # ── identity ─────────────────────────────────────────────────────
+
+    def _resolve_user_id(
+        self, session: AgentSession, context: Any, state: dict
+    ) -> str:
+        """Per-run identity ladder: run options → resolver → constructor.
+
+        The resolved id is pinned in the provider's ``state`` slice so
+        ``after_run`` persists under exactly the identity ``before_run``
+        recalled for — the two can never diverge within a run.
+        """
+        candidate: Optional[str] = None
+        options = getattr(context, "options", None)
+        if isinstance(options, dict):
+            raw = options.get(RUN_OPTION_USER_ID)
+            if isinstance(raw, str) and raw.strip():
+                candidate = raw.strip()
+        if candidate is None and self.user_id_resolver is not None:
+            try:
+                raw = self.user_id_resolver(session)
+                if isinstance(raw, str) and raw.strip():
+                    candidate = raw.strip()
+            except Exception as exc:  # resolver bugs must not kill the run
+                logger.warning("MemorySync user_id_resolver failed (%s)", exc)
+        resolved = candidate or self.user_id
+        state["run_user_id"] = resolved
+        return resolved
+
+    @property
+    def _session_scope(self) -> str:
+        return f"agent-framework::{self.session_id}"
+
+    # ── before_run: budgeted recall into the instructions layer ──────
+
+    async def before_run(
+        self,
+        *,
+        agent: Any,
+        session: AgentSession,
+        context: Any,
+        state: dict,
+    ) -> None:
+        user_id = self._resolve_user_id(session, context, state)
+
+        if self.expose_search_tool:
+            try:
+                context.extend_tools(self.source_id, self._build_tools(user_id))
+            except Exception as exc:  # pragma: no cover - defensive
+                logger.warning("MemorySync tool registration failed (%s)", exc)
+
+        query = ""
+        for message in reversed(list(getattr(context, "input_messages", []) or [])):
+            if _role_of_message(message) == "user":
+                query = _text_of_message(message)
+                if query:
+                    break
+        if len(query.strip()) < self.min_prompt_chars:
+            return
+
+        try:
+            # One-time cold-start grace: the first recall of a fresh client
+            # may pay TLS + tenant resolution on top of the query itself.
+            # Give it room once; every later run keeps the strict budget.
+            budget = self.recall_timeout if self._warmed else max(self.recall_timeout, 3.0)
+            self._warmed = True
+            tenant_id = await asyncio.wait_for(
+                self._api.resolve_tenant_id(), timeout=budget
+            )
+            response = await asyncio.wait_for(
+                self._api.recall(
+                    tenant_id=tenant_id,
+                    user_id=user_id,
+                    prompt=query,
+                    k=self.top_k,
+                ),
+                timeout=budget,
+            )
+        except Exception as exc:
+            logger.warning(
+                "MemorySync recall unavailable this run (%s) — continuing without memories.",
+                exc,
+            )
+            return
+
+        block = response.get("context") if isinstance(response, dict) else ""
+        if not isinstance(block, str) or not block.strip():
+            return
+        # .replace, never .format: memory text may contain { } % legally.
+        rendered = self.context_template.replace("{context}", block)
+        context.extend_instructions(self.source_id, rendered)
+
+    # ── after_run: fail-open, duplicate-proof capture ────────────────
+
+    async def after_run(
+        self,
+        *,
+        agent: Any,
+        session: AgentSession,
+        context: Any,
+        state: dict,
+    ) -> None:
+        """Persist both sides of the exchange. NEVER raises — a memory
+        outage after a successful run must not turn it into a failure
+        (the first-party Mem0 provider crashes the agent here)."""
+        if not self.capture:
+            return
+        try:
+            user_id = state.get("run_user_id") or self.user_id
+            turns: List[tuple] = []
+            for message in list(getattr(context, "input_messages", []) or []):
+                if _role_of_message(message) == "user":
+                    text = _text_of_message(message)
+                    if text:
+                        turns.append(("human", text))
+            response = getattr(context, "response", None)
+            for message in list(getattr(response, "messages", []) or []):
+                if _role_of_message(message) == "assistant":
+                    text = _text_of_message(message)
+                    if text:
+                        turns.append(("ai", text))
+
+            if not turns:
+                return
+            tenant_id = await self._api.resolve_tenant_id()
+            for role, text in turns:
+                if len(text) > MAX_TURN_CHARS:
+                    text = text[:MAX_TURN_CHARS]
+                seed = f"{role}@{self._session_scope}#h{fnv1a64(f'{role}:{text}')}"
+                await self._api.add_turn(
+                    tenant_id=tenant_id,
+                    user_id=user_id,
+                    text=f"{role}: {text}",
+                    speaker=seed,
+                    metadata={"session_id": self._session_scope},
+                    source=self.source,
+                )
+        except Exception as exc:
+            logger.warning(
+                "MemorySync capture skipped for this run (%s) — the agent run itself succeeded.",
+                exc,
+            )
+
+    # ── tools ────────────────────────────────────────────────────────
+
+    def _build_tools(self, user_id: str) -> List[Any]:
+        api = self._api
+        source = self.source
+        top_k = self.top_k
+
+        async def search_memory(query: str, limit: int = top_k) -> str:
+            """Search the user's long-term memory for relevant context and preferences."""
+            tenant_id = await api.resolve_tenant_id()
+            response = await api.query(
+                tenant_id=tenant_id, user_id=user_id, prompt=query, k=limit
+            )
+            memories = response.get("memories") if isinstance(response, dict) else []
+            if not memories:
+                return "No relevant memories found."
+            lines = []
+            for i, entry in enumerate(memories, 1):
+                text = entry.get("value") or entry.get("text") or entry.get("raw_text") or ""
+                lines.append(f"{i}. {text}")
+            return "\n".join(lines)
+
+        async def save_memory(text: str) -> str:
+            """Save an important, durable fact about the user to long-term memory."""
+            response = await api.add_memory(user_id=user_id, text=text, source=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 [search_memory, save_memory]
+
+    # ── lifecycle ────────────────────────────────────────────────────
+
+    async def close(self) -> None:
+        """Release the HTTP client."""
+        await self._api.aclose()

agent_framework_memorysync-1.0.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: agent-framework-memorysync
+Version: 1.0.0
+Summary: MemorySync for Microsoft Agent Framework: a ContextProvider with budgeted instruction-layer recall, per-run identity, once-per-turn duplicate-proof capture, and fail-open everything.
+Project-URL: Homepage, https://docs.memorysync.io/guides/agent-framework
+Project-URL: Documentation, https://docs.memorysync.io/guides/agent-framework
+Project-URL: Repository, https://github.com/memorysyncio/memorysync-plugins
+Author-email: MemorySync <support@memorysync.io>
+License-Expression: MIT
+Keywords: agent-framework,agents,context-provider,long-term-memory,memory,memorysync,microsoft
+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: agent-framework-core<2,>=1.8
+Requires-Dist: httpx<1,>=0.25
+Description-Content-Type: text/markdown
+
+# agent-framework-memorysync
+
+[MemorySync](https://memorysync.io) for the
+[Microsoft Agent Framework](https://github.com/microsoft/agent-framework):
+agents that remember users across sessions — without ever stalling a run.
+
+```bash
+pip install agent-framework-memorysync
+```
+
+## Quick start
+
+```python
+from agent_framework import Agent
+from agent_framework_memorysync import MemorySyncContextProvider
+
+provider = MemorySyncContextProvider(
+    api_key="ms_...",          # or MEMORYSYNC_API_KEY
+    user_id="customer-42",     # required — who these memories belong to
+    session_id="support",      # scopes the transcript
+)
+
+agent = Agent(client=..., context_providers=[provider])
+result = await agent.run("which seat should I book?")
+```
+
+Every run recalls relevant memories into the **instructions layer** under
+a hard budget, and both sides of the exchange persist automatically after
+the run — no extra code per turn.
+
+## Why this one
+
+| | Mem0 (`agent-framework-mem0`, in-repo) | Zep (`zep-ms-agent-framework`) | **MemorySync** |
+| --- | --- | --- | --- |
+| Injection layer | ✗ fabricates a `role="user"` message | ✓ instructions | ✓ instructions |
+| Recall latency budget | ✗ none | ✗ none | ✓ hard 1.2s default — a slow backend means an unenriched run, never a late one |
+| Capture failure behaviour | ✗ **`after_run` errors crash the agent** | swallowed | ✓ entirely fail-open, logged |
+| Scope model | ✗ storage ≠ retrieval scopes — forget `search_user_id` and the agent is silently memoryless | single | ✓ one `user_id` drives both — the bug cannot exist |
+| Per-run identity | ✗ construction-only | ✗ construction-only (documented) | ✓ `agent.run(..., options={"memorysync_user_id": ...})` or a `user_id_resolver` |
+| Write dedup | ✗ re-adds every turn | ✗ | ✓ deterministic idempotency seeds |
+| Tool-loop double-capture | ✗ | — | ✓ `after_run_once_per_turn = True` |
+| Release status | beta (`1.0.0b…`) | 0.2.1 | ✓ stable 1.0.0 |
+| Python | ≥3.10 | ✗ ≥3.11 only | ✓ ≥3.10 (matches the framework) |
+
+## Semantics worth knowing
+
+- Turns store verbatim under the `agent-framework::<session>` transcript
+  scope — separate history, same shared user memories as every other
+  MemorySync surface.
+- The resolved run identity is pinned in the provider's session-state
+  slice, so recall and capture can never diverge within a run — and the
+  slice stays JSON-native, so `AgentSession` serialization keeps working.
+- `expose_search_tool=True` adds `search_memory` + `save_memory` tools
+  via `context.extend_tools`.
+- Free-tier quota exhaustion is silent by design (adds accepted-without-
+  storing, reads empty); evaluation keys surface strict `429`s.
+
+## Configuration
+
+| Parameter | Default | Meaning |
+| --- | --- | --- |
+| `user_id` | — (required) | End user the memories belong to |
+| `session_id` | `"default"` | Transcript scope |
+| `top_k` | `5` | Memories considered per run |
+| `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 |
+| `capture` | `True` | Persist the exchange after each run |
+| `expose_search_tool` | `False` | Register memory tools on every run |
+| `user_id_resolver` | `None` | `Callable[[AgentSession], str]` for dynamic identity |
+
+## Development
+
+```bash
+pip install -e . agent-framework-core pytest pytest-asyncio
+python -m pytest tests -q     # 21 tests incl. a REAL Agent run (stub chat client)
+```
+
+## License
+
+MIT

agent_framework_memorysync-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+agent_framework_memorysync/__init__.py,sha256=V0AmdssJbpMSqldiXn7Ubu4iS2yJAKQm3QOBaarxDe8,428
+agent_framework_memorysync/_api.py,sha256=yyvQa4F2Bl8ys1iwoeVfcNl9lc2O0inDcM3PeIbkOU8,10317
+agent_framework_memorysync/_version.py,sha256=ZhzQKWZ8RFrTIkj7z87B144DI95e8LMfA5w8NDWQDtg,23
+agent_framework_memorysync/provider.py,sha256=mj6BByKg-4Bug9f8NiQkhqRF6jzWeldx_M1Lu7mAvrk,13700
+agent_framework_memorysync-1.0.0.dist-info/METADATA,sha256=nc0mWkt0Im9HB_CT2gMxFuHLq_uR1W0F9aiWHBuaCWA,4808
+agent_framework_memorysync-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agent_framework_memorysync-1.0.0.dist-info/RECORD,,

agent_framework_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