openai-agents-memorysync 1.0.0__py3-none-any.whl

openai_agents_memorysync/__init__.py

@@ -0,0 +1,45 @@
+"""openai-agents-memorysync — MemorySync memory for the OpenAI Agents SDK.
+
+Three layers, all optional and composable:
+
+- ``MemorySyncSession`` — a drop-in implementation of the SDK's Session
+  protocol: durable server-side conversation history that survives
+  restarts and deploys, shared across multi-agent handoffs, with
+  automatic long-term memory extraction.
+- ``memory_instructions`` — dynamic instructions that inject recalled
+  memory context per run.
+- ``create_memory_tools`` — five agentic memory tools (add, search,
+  list, update, delete) that never raise.
+- Helpers — ``get_memory_context``, ``search_memories``, ``save_turn``
+  for hand-wired setups.
+"""
+
+from ._api import (
+    FALLBACK_TENANT,
+    MemorySyncAPIError,
+    fnv1a64,
+    resolve_api_key,
+    resolve_base_url,
+)
+from ._version import __version__
+from .helpers import get_memory_context, save_turn, search_memories
+from .instructions import DEFAULT_TEMPLATE, PROFILE_PROMPT, memory_instructions
+from .session import MemorySyncSession
+from .tools import create_memory_tools
+
+__all__ = [
+    "MemorySyncSession",
+    "memory_instructions",
+    "create_memory_tools",
+    "get_memory_context",
+    "search_memories",
+    "save_turn",
+    "MemorySyncAPIError",
+    "DEFAULT_TEMPLATE",
+    "PROFILE_PROMPT",
+    "FALLBACK_TENANT",
+    "fnv1a64",
+    "resolve_api_key",
+    "resolve_base_url",
+    "__version__",
+]

openai_agents_memorysync/_api.py

@@ -0,0 +1,305 @@
+"""Async client for the MemorySync v1 data plane used by this integration.
+
+The session store persists items through the *episodic* ingestion path
+(``POST /v1/memory/add_turn``), which stores text verbatim — no fact
+extraction, no low-value-chatter gate, no rewriting. A conversation
+transcript that the Agents SDK will replay to the model must round-trip
+byte-for-byte; a plane that second-guessed it would corrupt the run.
+
+Everything here is async-native because the Agents SDK's ``Session``
+protocol is async and its runner drives every call from the event loop —
+a blocking HTTP client inside ``get_items`` would stall the whole run.
+"""
+
+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"openai-agents-memorysync/{__version__}"
+
+#: Namespace used when the key cannot list projects (see resolve_tenant_id).
+FALLBACK_TENANT = "default"
+
+
+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 the JavaScript adapters (`fnv1a64` in memorysync-ai-sdk
+    and memorysync-mastra hash over ``charCodeAt``) character for
+    character. Identical seeds across languages mean a turn persisted by a
+    Python surface and again by a JS surface 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 api_key(self) -> str:
+        return self._api_key
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def project_id(self) -> Optional[str]:
+        return self._project_id
+
+    @property
+    def timeout(self) -> float:
+        return self._timeout
+
+    @property
+    def transport(self) -> Optional[httpx.AsyncBaseTransport]:
+        return self._transport
+
+    # ── plumbing ─────────────────────────────────────────────────────
+
+    def _headers(self) -> 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
+        return h
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        try:
+            response = await self._http.request(
+                method, url, headers=self._headers(), 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; one extra GET per process, not per
+        turn. 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
+
+    @property
+    def tenant_is_fallback(self) -> bool:
+        """True when the namespace came from the 401/403 fallback.
+
+        Callers that mix this v1 plane with the header-scoped legacy plane
+        (the agent tools do) check this: under the fallback the two planes
+        resolve *different* internal users, so a v1 read would silently
+        miss legacy-plane writes. Better to say so than to answer wrongly.
+        """
+        return self._tenant_is_fallback
+
+    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,
+        occurred_at: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        source: str = "openai-agents",
+        sync_embed: bool = False,
+    ) -> Dict[str, Any]:
+        """Store one item verbatim (episodic ingestion).
+
+        ``speaker`` + ``occurred_at`` participate 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 occurred_at is not None:
+            body["occurred_at"] = occurred_at
+        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,
+        types: Optional[List[str]] = 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
+        if types is not None:
+            body["types"] = types
+        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 transcript read must never be
+        silently truncated, so that is the default here.
+
+        Both path segments are percent-encoded so an id containing ``/``,
+        ``%`` or ``?`` addresses the right row set — the server decodes
+        path parameters, so sending the raw string would corrupt the path.
+        """
+        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 []

openai_agents_memorysync/_version.py

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

openai_agents_memorysync/helpers.py

@@ -0,0 +1,134 @@
+"""Standalone async helpers for hand-wired setups.
+
+Same wire contracts as the session and instructions surfaces — same
+recall pipeline, same idempotent persistence seeds — so mixing styles
+never double-stores a turn.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from ._api import AsyncV1Api, fnv1a64, resolve_api_key, resolve_base_url
+
+
+def _api(
+    api_key: Optional[str],
+    base_url: Optional[str],
+    project_id: Optional[str],
+    tenant_id: Optional[str],
+    timeout: float,
+    transport: Optional[httpx.AsyncBaseTransport],
+) -> AsyncV1Api:
+    api = AsyncV1Api(
+        api_key=resolve_api_key(api_key),
+        base_url=resolve_base_url(base_url),
+        project_id=project_id,
+        timeout=timeout,
+        transport=transport,
+    )
+    if tenant_id:
+        api.set_tenant_id(str(tenant_id))
+    return api
+
+
+async def get_memory_context(
+    prompt: str,
+    *,
+    user_id: str,
+    k: Optional[int] = None,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    project_id: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    timeout: float = 30.0,
+    transport: Optional[httpx.AsyncBaseTransport] = None,
+) -> str:
+    """A prompt-ready context block for ``prompt``, or ``""`` when nothing
+    matches (a new user is not an error)."""
+    api = _api(api_key, base_url, project_id, tenant_id, timeout, transport)
+    try:
+        tenant = await api.resolve_tenant_id()
+        raw = await api.recall(tenant_id=tenant, user_id=user_id, prompt=prompt, k=k)
+        return str(raw.get("context") or "")
+    finally:
+        await api.aclose()
+
+
+async def search_memories(
+    query: str,
+    *,
+    user_id: str,
+    k: Optional[int] = None,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    project_id: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    timeout: float = 30.0,
+    transport: Optional[httpx.AsyncBaseTransport] = None,
+) -> List[Dict[str, Any]]:
+    """Scored memories relevant to ``query`` as ``{id, text, score}`` dicts."""
+    api = _api(api_key, base_url, project_id, tenant_id, timeout, transport)
+    try:
+        tenant = await api.resolve_tenant_id()
+        raw = await api.query(tenant_id=tenant, user_id=user_id, prompt=query, k=k)
+        memories: List[Dict[str, Any]] = []
+        for item in raw.get("memories") or []:
+            if not isinstance(item, dict):
+                continue
+            mem_id = str(item.get("memory_id") or item.get("id") or "")
+            text = str(item.get("raw_text") or item.get("value") or "").strip()
+            score = item.get("score")
+            if mem_id and text:
+                memories.append(
+                    {
+                        "id": mem_id,
+                        "text": text,
+                        "score": float(score) if isinstance(score, (int, float)) else None,
+                    }
+                )
+        return memories
+    finally:
+        await api.aclose()
+
+
+async def save_turn(
+    *,
+    user_id: str,
+    user: Optional[str] = None,
+    assistant: Optional[str] = None,
+    session_id: str = "default",
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    project_id: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    timeout: float = 30.0,
+    transport: Optional[httpx.AsyncBaseTransport] = None,
+) -> None:
+    """Persist one exchange to long-term memory explicitly. Idempotent:
+    retrying the same content for the same session stores nothing new
+    (same seeds as the session's ``long_term`` plane and every other
+    MemorySync adapter). RAISES on failure — an explicit persist call is
+    owed the truth about whether it worked."""
+    api = _api(api_key, base_url, project_id, tenant_id, timeout, transport)
+    try:
+        tenant = await api.resolve_tenant_id()
+        session = (session_id or "default").strip() or "default"
+        turns = []
+        if user and user.strip():
+            turns.append(("human", user.strip()))
+        if assistant and assistant.strip():
+            turns.append(("ai", assistant.strip()))
+        for role, text in turns:
+            await api.add_turn(
+                tenant_id=tenant,
+                user_id=user_id,
+                text=f"{role}: {text}",
+                speaker=f"{role}@{session}#h{fnv1a64(f'{role}:{text}')}",
+                metadata={"session_id": session},
+                source="openai-agents",
+            )
+    finally:
+        await api.aclose()

openai_agents_memorysync/instructions.py

@@ -0,0 +1,155 @@
+"""Long-term memory context for agent instructions.
+
+The Agents SDK's documented hook for dynamic system prompts is an
+``instructions`` callable: ``Callable[[RunContextWrapper, Agent], str |
+Awaitable[str]]``. ``memory_instructions`` builds that callable — base
+instructions plus a recalled-memory block for the user, fetched fresh on
+every run.
+
+Recall failure NEVER breaks the run: the callable falls back to the base
+instructions and reports through ``on_error``. A memory outage that took
+the agent down with it would be strictly worse than no memory.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Union
+
+import httpx
+
+from ._api import AsyncV1Api, resolve_api_key, resolve_base_url
+
+DEFAULT_TEMPLATE = (
+    "Relevant memories about this user from previous conversations:\n{context}"
+)
+
+#: The prompt used for profile recall — stable so results cache well.
+PROFILE_PROMPT = "profile overview: preferences, facts, context about this user"
+
+RecallMode = str  # "query" | "profile" | "full"
+
+OnError = Callable[[str, BaseException], None]
+
+
+def _default_on_error(stage: str, error: BaseException) -> None:
+    import logging
+
+    logging.getLogger("openai_agents_memorysync").warning("%s: %s", stage, error)
+
+
+def _latest_user_text(context: Any) -> str:
+    """Best-effort text of the newest user message on the run context.
+
+    The instructions callable receives the RunContextWrapper, not the
+    input items, so the user's message is only reachable when the caller
+    put it there. ``memory_instructions`` therefore accepts an explicit
+    ``prompt`` resolver for precise recall, and falls back to profile
+    recall otherwise — a wrong guess about the query would recall the
+    wrong memories.
+    """
+    return ""
+
+
+def memory_instructions(
+    base_instructions: str,
+    *,
+    user_id: Union[str, Callable[[Any], Optional[str]]],
+    mode: RecallMode = "profile",
+    k: Optional[int] = None,
+    template: str = DEFAULT_TEMPLATE,
+    prompt: Optional[Callable[[Any], Optional[str]]] = None,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    project_id: Optional[str] = None,
+    tenant_id: Optional[str] = None,
+    timeout: float = 30.0,
+    transport: Optional[httpx.AsyncBaseTransport] = None,
+    on_error: Optional[OnError] = None,
+) -> Callable[[Any, Any], Any]:
+    """Build a dynamic-instructions callable that injects recalled memory.
+
+    ```python
+    agent = Agent(
+        name="Assistant",
+        instructions=memory_instructions(
+            "You are a helpful assistant.",
+            user_id="customer-7",
+        ),
+    )
+    ```
+
+    Args:
+        user_id: The end user to recall for — a fixed string, or a
+            callable receiving the RunContextWrapper (multi-user servers
+            resolve identity per request). A resolver returning ``None``
+            skips recall for that run.
+        mode: ``"profile"`` (default — an overview of the user; the right
+            recall when the query text is not available), ``"query"``
+            (recall for the text returned by ``prompt``), or ``"full"``
+            (both).
+        prompt: Optional callable receiving the RunContextWrapper and
+            returning the text to recall against, for ``query``/``full``.
+    """
+    if mode not in ("query", "profile", "full"):
+        raise ValueError(f"mode must be 'query', 'profile' or 'full', got {mode!r}")
+    handle_error = on_error or _default_on_error
+    api = AsyncV1Api(
+        api_key=resolve_api_key(api_key),
+        base_url=resolve_base_url(base_url),
+        project_id=project_id,
+        timeout=timeout,
+        transport=transport,
+    )
+    if tenant_id:
+        api.set_tenant_id(str(tenant_id))
+
+    async def _context_for(user: str, question: str) -> str:
+        tenant = await api.resolve_tenant_id()
+        blocks: List[str] = []
+        if mode in ("profile", "full") or (mode == "query" and not question):
+            profile = await api.recall(
+                tenant_id=tenant, user_id=user, prompt=PROFILE_PROMPT, k=k
+            )
+            text = str(profile.get("context") or "").strip()
+            if text:
+                blocks.append(text)
+        if mode in ("query", "full") and question:
+            relevant = await api.recall(
+                tenant_id=tenant, user_id=user, prompt=question, k=k
+            )
+            text = str(relevant.get("context") or "").strip()
+            if text and text not in blocks:
+                blocks.append(text)
+        return "\n".join(blocks)
+
+    async def instructions(wrapper: Any, agent: Any) -> str:
+        user: Optional[str]
+        if callable(user_id):
+            try:
+                user = user_id(wrapper)
+            except Exception as exc:  # noqa: BLE001 — a broken resolver skips, never crashes
+                handle_error("identity", exc)
+                user = None
+        else:
+            user = user_id
+        if not user or not str(user).strip():
+            return base_instructions
+
+        question = ""
+        if prompt is not None:
+            try:
+                question = str(prompt(wrapper) or "").strip()
+            except Exception as exc:  # noqa: BLE001
+                handle_error("recall", exc)
+                question = ""
+
+        try:
+            context = await _context_for(str(user).strip(), question)
+        except Exception as exc:  # noqa: BLE001 — recall failure degrades, never breaks the run
+            handle_error("recall", exc)
+            return base_instructions
+        if not context.strip():
+            return base_instructions
+        return f"{base_instructions}\n\n{template.replace('{context}', context)}"
+
+    return instructions