memorysync 1.0.0__tar.gz

memorysync-1.0.0/.gitignore

@@ -0,0 +1,15 @@
+*.iml
+.gradle
+/local.properties
+/.idea/caches
+/.idea/libraries
+/.idea/modules.xml
+/.idea/workspace.xml
+/.idea/navEditor.xml
+/.idea/assetWizardSettings.xml
+.DS_Store
+/build
+/captures
+.externalNativeBuild
+.cxx
+local.properties

memorysync-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MemorySync
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memorysync-1.0.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: memorysync
+Version: 1.0.0
+Summary: Official Python client for the MemorySync API.
+Project-URL: Homepage, https://memorysync.dev
+Project-URL: Documentation, https://memorysync.dev/docs
+Author: MemorySync
+License: MIT
+License-File: LICENSE
+Keywords: client,memory,memorysync,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.25
+Requires-Dist: typing-extensions>=4.5; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# memorysync
+
+Official Python client for the MemorySync API. Sync and async, no surprises.
+
+```bash
+pip install memorysync
+```
+
+## Quick start
+
+```python
+from memorysync import MemorySyncClient
+
+ms = MemorySyncClient(
+    api_key="...",
+    base_url="https://api.memorysync.dev",
+    project_id="proj_xxxxxxxxxxxxxxxx",   # optional
+    end_user_id="user_42",                 # optional
+)
+
+ms.add("User prefers dark mode.")
+
+result = ms.query("ui preferences", k=5)
+for m in result.memories:
+    print(m.id, m.text)
+```
+
+## Async usage
+
+```python
+import asyncio
+from memorysync import AsyncMemorySyncClient
+
+async def main():
+    async with AsyncMemorySyncClient(api_key="...", base_url="...") as ms:
+        result = await ms.query("ui preferences", k=5)
+        print(result.memories)
+
+asyncio.run(main())
+```
+
+Use `MemorySyncClient` as a context manager when you want deterministic
+connection cleanup:
+
+```python
+with MemorySyncClient(api_key="...", base_url="...") as ms:
+    ms.add("...")
+```
+
+## Configuration
+
+| Argument        | Required | Description                                                                                  |
+| --------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `api_key`       | yes      | Sent as `X-API-Key`. Provision in your MemorySync dashboard.                                 |
+| `base_url`      | yes      | Deployment URL of your MemorySync instance.                                                  |
+| `project_id`    | no       | Pin every request to a project (`X-Project-ID`). Format: `proj_` + 16 hex chars.             |
+| `end_user_id`   | no       | Identify which of *your* users this client speaks for (`X-End-User-ID`).                     |
+| `timeout`       | no       | Per-request timeout in seconds. Default `30.0`.                                              |
+| `transport`     | no       | Inject a custom `httpx` transport (tests, retries, proxies).                                 |
+
+`end_user_id` can also be passed per-call on `add()` to override the client default.
+
+## Methods
+
+Every method maps 1:1 to a real HTTP route. The two clients share the same
+surface; only the call style differs (sync vs `await`).
+
+| Method                                       | Route                                  |
+| -------------------------------------------- | -------------------------------------- |
+| `add(text, **opts)`                          | `POST /memory/add`                     |
+| `bulk_add(items, *, deduplicate=True)`       | `POST /memory/bulk-add`                |
+| `query(query, *, k=None, ...)`               | `POST /memory/query`                   |
+| `get(memory_id)`                             | `GET /memory/{id}`                     |
+| `update(memory_id, **fields)`                | `PATCH /memory/{id}`                   |
+| `forget(memory_ids, *, reason=None)`         | `DELETE /memory/forget`                |
+| `summarize(memory_ids, *, lossless=False)`   | `POST /memory/summarize`               |
+| `compose(prompt_template, *, recall_k=None)` | `POST /memory/compose`                 |
+| `export_all()`                               | `GET /memory/export`                   |
+| `create_relation(from_id, **opts)`           | `POST /memory/{id}/relations`          |
+
+### `add` returns one of two shapes
+
+`add()` runs through MemorySync's extraction pipeline, so input that carries no
+high-value content is intentionally skipped. Branch on the type of the result:
+
+```python
+from memorysync import AddSkippedResponse, Memory
+
+result = ms.add("User prefers dark mode.")
+if isinstance(result, AddSkippedResponse):
+    print("skipped:", result.reason)
+else:
+    assert isinstance(result, Memory)
+    print(result.id, result.text)
+```
+
+## Errors
+
+Every non-2xx response raises a typed subclass of `MemorySyncError`:
+
+| Class             | When                                        |
+| ----------------- | ------------------------------------------- |
+| `AuthError`       | `401` / `403` — bad key, missing scope.     |
+| `ValidationError` | `400` / `409` / `422`.                      |
+| `NotFoundError`   | `404` — record not visible to the caller.   |
+| `RateLimitError`  | `429` — read `err.retry_after_seconds`.     |
+| `ServerError`     | `5xx`.                                      |
+| `MemorySyncError` | Network errors, timeouts, anything else.    |
+
+Every error carries `status_code`, `response`, and the server-issued
+`request_id` (when present) for support escalation.
+
+```python
+import time
+from memorysync import RateLimitError
+
+try:
+    ms.add("...")
+except RateLimitError as e:
+    time.sleep(e.retry_after_seconds)
+```
+
+## License
+
+MIT

memorysync-1.0.0/README.md

@@ -0,0 +1,125 @@
+# memorysync
+
+Official Python client for the MemorySync API. Sync and async, no surprises.
+
+```bash
+pip install memorysync
+```
+
+## Quick start
+
+```python
+from memorysync import MemorySyncClient
+
+ms = MemorySyncClient(
+    api_key="...",
+    base_url="https://api.memorysync.dev",
+    project_id="proj_xxxxxxxxxxxxxxxx",   # optional
+    end_user_id="user_42",                 # optional
+)
+
+ms.add("User prefers dark mode.")
+
+result = ms.query("ui preferences", k=5)
+for m in result.memories:
+    print(m.id, m.text)
+```
+
+## Async usage
+
+```python
+import asyncio
+from memorysync import AsyncMemorySyncClient
+
+async def main():
+    async with AsyncMemorySyncClient(api_key="...", base_url="...") as ms:
+        result = await ms.query("ui preferences", k=5)
+        print(result.memories)
+
+asyncio.run(main())
+```
+
+Use `MemorySyncClient` as a context manager when you want deterministic
+connection cleanup:
+
+```python
+with MemorySyncClient(api_key="...", base_url="...") as ms:
+    ms.add("...")
+```
+
+## Configuration
+
+| Argument        | Required | Description                                                                                  |
+| --------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `api_key`       | yes      | Sent as `X-API-Key`. Provision in your MemorySync dashboard.                                 |
+| `base_url`      | yes      | Deployment URL of your MemorySync instance.                                                  |
+| `project_id`    | no       | Pin every request to a project (`X-Project-ID`). Format: `proj_` + 16 hex chars.             |
+| `end_user_id`   | no       | Identify which of *your* users this client speaks for (`X-End-User-ID`).                     |
+| `timeout`       | no       | Per-request timeout in seconds. Default `30.0`.                                              |
+| `transport`     | no       | Inject a custom `httpx` transport (tests, retries, proxies).                                 |
+
+`end_user_id` can also be passed per-call on `add()` to override the client default.
+
+## Methods
+
+Every method maps 1:1 to a real HTTP route. The two clients share the same
+surface; only the call style differs (sync vs `await`).
+
+| Method                                       | Route                                  |
+| -------------------------------------------- | -------------------------------------- |
+| `add(text, **opts)`                          | `POST /memory/add`                     |
+| `bulk_add(items, *, deduplicate=True)`       | `POST /memory/bulk-add`                |
+| `query(query, *, k=None, ...)`               | `POST /memory/query`                   |
+| `get(memory_id)`                             | `GET /memory/{id}`                     |
+| `update(memory_id, **fields)`                | `PATCH /memory/{id}`                   |
+| `forget(memory_ids, *, reason=None)`         | `DELETE /memory/forget`                |
+| `summarize(memory_ids, *, lossless=False)`   | `POST /memory/summarize`               |
+| `compose(prompt_template, *, recall_k=None)` | `POST /memory/compose`                 |
+| `export_all()`                               | `GET /memory/export`                   |
+| `create_relation(from_id, **opts)`           | `POST /memory/{id}/relations`          |
+
+### `add` returns one of two shapes
+
+`add()` runs through MemorySync's extraction pipeline, so input that carries no
+high-value content is intentionally skipped. Branch on the type of the result:
+
+```python
+from memorysync import AddSkippedResponse, Memory
+
+result = ms.add("User prefers dark mode.")
+if isinstance(result, AddSkippedResponse):
+    print("skipped:", result.reason)
+else:
+    assert isinstance(result, Memory)
+    print(result.id, result.text)
+```
+
+## Errors
+
+Every non-2xx response raises a typed subclass of `MemorySyncError`:
+
+| Class             | When                                        |
+| ----------------- | ------------------------------------------- |
+| `AuthError`       | `401` / `403` — bad key, missing scope.     |
+| `ValidationError` | `400` / `409` / `422`.                      |
+| `NotFoundError`   | `404` — record not visible to the caller.   |
+| `RateLimitError`  | `429` — read `err.retry_after_seconds`.     |
+| `ServerError`     | `5xx`.                                      |
+| `MemorySyncError` | Network errors, timeouts, anything else.    |
+
+Every error carries `status_code`, `response`, and the server-issued
+`request_id` (when present) for support escalation.
+
+```python
+import time
+from memorysync import RateLimitError
+
+try:
+    ms.add("...")
+except RateLimitError as e:
+    time.sleep(e.retry_after_seconds)
+```
+
+## License
+
+MIT

memorysync-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "memorysync"
+version = "1.0.0"
+description = "Official Python client for the MemorySync API."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "MemorySync" }]
+keywords = ["memorysync", "memory", "sdk", "client"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.25,<1.0",
+  "typing-extensions>=4.5; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://memorysync.dev"
+Documentation = "https://memorysync.dev/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/memorysync"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/memorysync",
+  "README.md",
+  "LICENSE",
+  "pyproject.toml",
+]

memorysync-1.0.0/src/memorysync/__init__.py

@@ -0,0 +1,46 @@
+"""Public package surface for the MemorySync Python SDK."""
+
+from ._version import __version__
+from .errors import (
+    AuthError,
+    MemorySyncError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .types import (
+    AddSkippedResponse,
+    BulkAddItem,
+    BulkAddItemResult,
+    BulkAddResponse,
+    ComposeResponse,
+    ExportResponse,
+    Memory,
+    QueryResponse,
+    Relation,
+    RelationshipType,
+)
+from .client import AsyncMemorySyncClient, MemorySyncClient
+
+__all__ = [
+    "__version__",
+    "MemorySyncClient",
+    "AsyncMemorySyncClient",
+    "Memory",
+    "QueryResponse",
+    "BulkAddItem",
+    "BulkAddItemResult",
+    "BulkAddResponse",
+    "AddSkippedResponse",
+    "ComposeResponse",
+    "ExportResponse",
+    "Relation",
+    "RelationshipType",
+    "MemorySyncError",
+    "AuthError",
+    "ValidationError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+]

memorysync-1.0.0/src/memorysync/_version.py

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

memorysync-1.0.0/src/memorysync/client.py

@@ -0,0 +1,752 @@
+"""Sync and async HTTP clients for the MemorySync API.
+
+Both clients share an internal ``_RequestBuilder`` that constructs URLs,
+headers, and bodies, and an ``_ErrorMapper`` that converts HTTP failures
+into the typed exception hierarchy in ``errors.py``. Only the transport
+differs (``httpx.Client`` vs ``httpx.AsyncClient``).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Union
+
+import httpx
+
+from ._version import __version__
+from .errors import (
+    AuthError,
+    MemorySyncError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .types import (
+    AddResult,
+    AddSkippedResponse,
+    BulkAddItem,
+    BulkAddItemResult,
+    BulkAddResponse,
+    ComposeResponse,
+    ExportResponse,
+    Memory,
+    QueryResponse,
+    Relation,
+    RelationshipType,
+)
+
+
+_USER_AGENT = f"memorysync-sdk-py/{__version__}"
+_BULK_LIMIT = 50
+
+
+def _strip_none(d: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _camel_to_snake_filters(filters: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    if not filters:
+        return None
+    return _strip_none(
+        {
+            "memory_type": filters.get("memory_type"),
+            "source": filters.get("source"),
+            "tags": filters.get("tags"),
+            "since": filters.get("since"),
+            "until": filters.get("until"),
+            "include_summaries": filters.get("include_summaries"),
+            "tier": filters.get("tier"),
+        }
+    )
+
+
+def _extract_detail(body: Any) -> Optional[str]:
+    if not isinstance(body, dict):
+        return None
+    if isinstance(body.get("detail"), str):
+        return body["detail"]
+    err = body.get("error")
+    if isinstance(err, dict) and isinstance(err.get("message"), str):
+        return err["message"]
+    detail = body.get("detail")
+    if isinstance(detail, list) and detail:
+        first = detail[0]
+        if isinstance(first, dict) and isinstance(first.get("msg"), str):
+            return first["msg"]
+    return None
+
+
+def _extract_retry_after(body: Any) -> float:
+    if not isinstance(body, dict):
+        return 0.0
+    if isinstance(body.get("retry_after"), (int, float)):
+        return float(body["retry_after"])
+    err = body.get("error")
+    if isinstance(err, dict) and isinstance(err.get("retry_after"), (int, float)):
+        return float(err["retry_after"])
+    return 0.0
+
+
+def _raise_for_status(status: int, body: Any, request_id: Optional[str]) -> None:
+    detail = _extract_detail(body)
+    kwargs: Dict[str, Any] = {"status_code": status, "response": body, "request_id": request_id}
+    if status in (401, 403):
+        raise AuthError(detail or ("Unauthenticated" if status == 401 else "Forbidden"), **kwargs)
+    if status == 404:
+        raise NotFoundError(detail or "Not found", **kwargs)
+    if status in (400, 409, 422):
+        raise ValidationError(detail or "Validation error", **kwargs)
+    if status == 429:
+        raise RateLimitError(
+            detail or "Rate limited",
+            retry_after_seconds=_extract_retry_after(body),
+            **kwargs,
+        )
+    if status >= 500:
+        raise ServerError(detail or f"Server error ({status})", **kwargs)
+    raise MemorySyncError(detail or f"Unexpected status {status}", **kwargs)
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Request shaping (shared by sync & async clients)
+# ─────────────────────────────────────────────────────────────────────
+
+
+class _RequestBuilder:
+    """Pure functions that turn high-level method args into HTTP payloads."""
+
+    @staticmethod
+    def add(
+        text: str,
+        *,
+        source: Optional[str],
+        tags: Optional[Sequence[str]],
+        importance: Optional[float],
+        session_id: Optional[str],
+        metadata: Optional[Dict[str, Any]],
+        end_user_id: Optional[str],
+    ) -> Dict[str, Any]:
+        return _strip_none(
+            {
+                "text": text,
+                "source": source,
+                "tags": list(tags) if tags is not None else None,
+                "importance": importance,
+                "session_id": session_id,
+                "metadata": metadata,
+                "end_user_id": end_user_id,
+            }
+        )
+
+    @staticmethod
+    def bulk_add(items: Sequence[BulkAddItem], deduplicate: bool) -> Dict[str, Any]:
+        return {
+            "items": [i.to_dict() for i in items],
+            "deduplicate": deduplicate,
+        }
+
+    @staticmethod
+    def query(
+        query: str,
+        *,
+        k: Optional[int],
+        filters: Optional[Dict[str, Any]],
+        session_id: Optional[str],
+        traversal_depth: Optional[int],
+    ) -> Dict[str, Any]:
+        return _strip_none(
+            {
+                "query": query,
+                "k": k,
+                "filters": _camel_to_snake_filters(filters),
+                "session_id": session_id,
+                "traversal_depth": traversal_depth,
+            }
+        )
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Sync client
+# ─────────────────────────────────────────────────────────────────────
+
+
+class MemorySyncClient:
+    """Synchronous client. Use :class:`AsyncMemorySyncClient` for asyncio code."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        project_id: Optional[str] = None,
+        end_user_id: Optional[str] = None,
+        timeout: float = 30.0,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError("api_key is required")
+        if not base_url or not base_url.strip():
+            raise ValueError("base_url is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._project_id = project_id
+        self._end_user_id = end_user_id
+        self._http = httpx.Client(timeout=timeout, transport=transport)
+
+    def __enter__(self) -> "MemorySyncClient":
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # ── HTTP plumbing ────────────────────────────────────────────────
+
+    def _headers(self, end_user_override: Optional[str] = None) -> Dict[str, str]:
+        h: Dict[str, str] = {
+            "X-API-Key": self._api_key,
+            "Accept": "application/json",
+            "User-Agent": _USER_AGENT,
+        }
+        if self._project_id:
+            h["X-Project-ID"] = self._project_id
+        eu = end_user_override or self._end_user_id
+        if eu:
+            h["X-End-User-ID"] = eu
+        return h
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        end_user_override: Optional[str] = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        try:
+            response = self._http.request(
+                method,
+                url,
+                headers=self._headers(end_user_override),
+                json=json,
+            )
+        except httpx.TimeoutException as e:
+            raise MemorySyncError(f"Request timed out: {e}") from e
+        except httpx.HTTPError as e:
+            raise MemorySyncError(f"Network error: {e}") from e
+
+        request_id = response.headers.get("x-request-id")
+        if response.status_code == 204:
+            return None
+        try:
+            body: Any = response.json()
+        except ValueError:
+            body = response.text or None
+        if response.status_code >= 400:
+            _raise_for_status(response.status_code, body, request_id)
+        return body
+
+    # ── Memory ───────────────────────────────────────────────────────
+
+    def add(
+        self,
+        text: str,
+        *,
+        source: Optional[str] = None,
+        tags: Optional[Sequence[str]] = None,
+        importance: Optional[float] = None,
+        session_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        end_user_id: Optional[str] = None,
+    ) -> AddResult:
+        body = _RequestBuilder.add(
+            text,
+            source=source,
+            tags=tags,
+            importance=importance,
+            session_id=session_id,
+            metadata=metadata,
+            end_user_id=end_user_id,
+        )
+        raw = self._request("POST", "/memory/add", json=body, end_user_override=end_user_id)
+        if isinstance(raw, dict) and raw.get("status") == "skipped":
+            return AddSkippedResponse(
+                status="skipped",
+                reason=str(raw.get("reason", "no_high_value_content")),
+                memory_ids=list(raw.get("memory_ids", []) or []),
+                candidates_extracted=int(raw.get("candidates_extracted", 0) or 0),
+                candidates_stored=int(raw.get("candidates_stored", 0) or 0),
+            )
+        return Memory.from_dict(raw)
+
+    def bulk_add(
+        self,
+        items: Sequence[BulkAddItem],
+        *,
+        deduplicate: bool = True,
+    ) -> BulkAddResponse:
+        if not items:
+            raise ValidationError("items must contain at least one entry")
+        if len(items) > _BULK_LIMIT:
+            raise ValidationError(f"items may contain at most {_BULK_LIMIT} entries per request")
+        raw = self._request(
+            "POST",
+            "/memory/bulk-add",
+            json=_RequestBuilder.bulk_add(items, deduplicate),
+        )
+        return _parse_bulk(raw)
+
+    def query(
+        self,
+        query: str,
+        *,
+        k: Optional[int] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        session_id: Optional[str] = None,
+        traversal_depth: Optional[int] = None,
+    ) -> QueryResponse:
+        raw = self._request(
+            "POST",
+            "/memory/query",
+            json=_RequestBuilder.query(
+                query,
+                k=k,
+                filters=filters,
+                session_id=session_id,
+                traversal_depth=traversal_depth,
+            ),
+        )
+        return _parse_query(raw)
+
+    def get(self, memory_id: int) -> Memory:
+        _validate_id(memory_id, "memory_id")
+        raw = self._request("GET", f"/memory/{memory_id}")
+        return Memory.from_dict(raw)
+
+    def update(
+        self,
+        memory_id: int,
+        *,
+        tags: Optional[Sequence[str]] = None,
+        importance: Optional[float] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        source: Optional[str] = None,
+        event_type: Optional[str] = None,
+    ) -> Memory:
+        _validate_id(memory_id, "memory_id")
+        body = _strip_none(
+            {
+                "tags": list(tags) if tags is not None else None,
+                "importance": importance,
+                "metadata": metadata,
+                "source": source,
+                "event_type": event_type,
+            }
+        )
+        if not body:
+            raise ValidationError("update() requires at least one editable field")
+        raw = self._request("PATCH", f"/memory/{memory_id}", json=body)
+        return Memory.from_dict(raw)
+
+    def forget(self, memory_ids: Iterable[int], *, reason: Optional[str] = None) -> List[int]:
+        ids = list(memory_ids)
+        if not ids:
+            raise ValidationError("memory_ids must be a non-empty iterable")
+        body = _strip_none({"memory_ids": ids, "reason": reason})
+        raw = self._request("DELETE", "/memory/forget", json=body)
+        return list(raw or [])
+
+    def summarize(
+        self,
+        memory_ids: Iterable[int],
+        *,
+        lossless: bool = False,
+    ) -> Memory:
+        ids = list(memory_ids)
+        if not ids:
+            raise ValidationError("summarize() requires memory_ids")
+        raw = self._request(
+            "POST",
+            "/memory/summarize",
+            json={"memory_ids": ids, "lossless": lossless},
+        )
+        return Memory.from_dict(raw)
+
+    def compose(
+        self,
+        prompt_template: str,
+        *,
+        recall_k: Optional[int] = None,
+        max_tokens: Optional[int] = None,
+    ) -> ComposeResponse:
+        body = _strip_none(
+            {
+                "prompt_template": prompt_template,
+                "recall_k": recall_k,
+                "max_tokens": max_tokens,
+            }
+        )
+        raw = self._request("POST", "/memory/compose", json=body)
+        return _parse_compose(raw)
+
+    def export_all(self) -> ExportResponse:
+        raw = self._request("GET", "/memory/export")
+        return _parse_export(raw)
+
+    def create_relation(
+        self,
+        from_memory_id: int,
+        *,
+        to_memory_id: int,
+        relationship_type: RelationshipType,
+        confidence: Optional[float] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Relation:
+        _validate_id(from_memory_id, "from_memory_id")
+        _validate_id(to_memory_id, "to_memory_id")
+        if from_memory_id == to_memory_id:
+            raise ValidationError("from_memory_id must differ from to_memory_id (no self-loops)")
+        body = _strip_none(
+            {
+                "to_memory_id": to_memory_id,
+                "relationship_type": relationship_type,
+                "confidence": confidence,
+                "metadata": metadata,
+            }
+        )
+        raw = self._request("POST", f"/memory/{from_memory_id}/relations", json=body)
+        return _parse_relation(raw)
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Async client
+# ─────────────────────────────────────────────────────────────────────
+
+
+class AsyncMemorySyncClient:
+    """Async-native client for asyncio applications."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        *,
+        project_id: Optional[str] = None,
+        end_user_id: Optional[str] = None,
+        timeout: float = 30.0,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError("api_key is required")
+        if not base_url or not base_url.strip():
+            raise ValueError("base_url is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._project_id = project_id
+        self._end_user_id = end_user_id
+        self._http = httpx.AsyncClient(timeout=timeout, transport=transport)
+
+    async def __aenter__(self) -> "AsyncMemorySyncClient":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    def _headers(self, end_user_override: Optional[str] = None) -> Dict[str, str]:
+        h: Dict[str, str] = {
+            "X-API-Key": self._api_key,
+            "Accept": "application/json",
+            "User-Agent": _USER_AGENT,
+        }
+        if self._project_id:
+            h["X-Project-ID"] = self._project_id
+        eu = end_user_override or self._end_user_id
+        if eu:
+            h["X-End-User-ID"] = eu
+        return h
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        end_user_override: Optional[str] = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+        try:
+            response = await self._http.request(
+                method,
+                url,
+                headers=self._headers(end_user_override),
+                json=json,
+            )
+        except httpx.TimeoutException as e:
+            raise MemorySyncError(f"Request timed out: {e}") from e
+        except httpx.HTTPError as e:
+            raise MemorySyncError(f"Network error: {e}") from e
+
+        request_id = response.headers.get("x-request-id")
+        if response.status_code == 204:
+            return None
+        try:
+            body: Any = response.json()
+        except ValueError:
+            body = response.text or None
+        if response.status_code >= 400:
+            _raise_for_status(response.status_code, body, request_id)
+        return body
+
+    async def add(
+        self,
+        text: str,
+        *,
+        source: Optional[str] = None,
+        tags: Optional[Sequence[str]] = None,
+        importance: Optional[float] = None,
+        session_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        end_user_id: Optional[str] = None,
+    ) -> AddResult:
+        body = _RequestBuilder.add(
+            text,
+            source=source,
+            tags=tags,
+            importance=importance,
+            session_id=session_id,
+            metadata=metadata,
+            end_user_id=end_user_id,
+        )
+        raw = await self._request("POST", "/memory/add", json=body, end_user_override=end_user_id)
+        if isinstance(raw, dict) and raw.get("status") == "skipped":
+            return AddSkippedResponse(
+                status="skipped",
+                reason=str(raw.get("reason", "no_high_value_content")),
+                memory_ids=list(raw.get("memory_ids", []) or []),
+                candidates_extracted=int(raw.get("candidates_extracted", 0) or 0),
+                candidates_stored=int(raw.get("candidates_stored", 0) or 0),
+            )
+        return Memory.from_dict(raw)
+
+    async def bulk_add(
+        self,
+        items: Sequence[BulkAddItem],
+        *,
+        deduplicate: bool = True,
+    ) -> BulkAddResponse:
+        if not items:
+            raise ValidationError("items must contain at least one entry")
+        if len(items) > _BULK_LIMIT:
+            raise ValidationError(f"items may contain at most {_BULK_LIMIT} entries per request")
+        raw = await self._request(
+            "POST",
+            "/memory/bulk-add",
+            json=_RequestBuilder.bulk_add(items, deduplicate),
+        )
+        return _parse_bulk(raw)
+
+    async def query(
+        self,
+        query: str,
+        *,
+        k: Optional[int] = None,
+        filters: Optional[Dict[str, Any]] = None,
+        session_id: Optional[str] = None,
+        traversal_depth: Optional[int] = None,
+    ) -> QueryResponse:
+        raw = await self._request(
+            "POST",
+            "/memory/query",
+            json=_RequestBuilder.query(
+                query,
+                k=k,
+                filters=filters,
+                session_id=session_id,
+                traversal_depth=traversal_depth,
+            ),
+        )
+        return _parse_query(raw)
+
+    async def get(self, memory_id: int) -> Memory:
+        _validate_id(memory_id, "memory_id")
+        raw = await self._request("GET", f"/memory/{memory_id}")
+        return Memory.from_dict(raw)
+
+    async def update(
+        self,
+        memory_id: int,
+        *,
+        tags: Optional[Sequence[str]] = None,
+        importance: Optional[float] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        source: Optional[str] = None,
+        event_type: Optional[str] = None,
+    ) -> Memory:
+        _validate_id(memory_id, "memory_id")
+        body = _strip_none(
+            {
+                "tags": list(tags) if tags is not None else None,
+                "importance": importance,
+                "metadata": metadata,
+                "source": source,
+                "event_type": event_type,
+            }
+        )
+        if not body:
+            raise ValidationError("update() requires at least one editable field")
+        raw = await self._request("PATCH", f"/memory/{memory_id}", json=body)
+        return Memory.from_dict(raw)
+
+    async def forget(self, memory_ids: Iterable[int], *, reason: Optional[str] = None) -> List[int]:
+        ids = list(memory_ids)
+        if not ids:
+            raise ValidationError("memory_ids must be a non-empty iterable")
+        body = _strip_none({"memory_ids": ids, "reason": reason})
+        raw = await self._request("DELETE", "/memory/forget", json=body)
+        return list(raw or [])
+
+    async def summarize(
+        self,
+        memory_ids: Iterable[int],
+        *,
+        lossless: bool = False,
+    ) -> Memory:
+        ids = list(memory_ids)
+        if not ids:
+            raise ValidationError("summarize() requires memory_ids")
+        raw = await self._request(
+            "POST",
+            "/memory/summarize",
+            json={"memory_ids": ids, "lossless": lossless},
+        )
+        return Memory.from_dict(raw)
+
+    async def compose(
+        self,
+        prompt_template: str,
+        *,
+        recall_k: Optional[int] = None,
+        max_tokens: Optional[int] = None,
+    ) -> ComposeResponse:
+        body = _strip_none(
+            {
+                "prompt_template": prompt_template,
+                "recall_k": recall_k,
+                "max_tokens": max_tokens,
+            }
+        )
+        raw = await self._request("POST", "/memory/compose", json=body)
+        return _parse_compose(raw)
+
+    async def export_all(self) -> ExportResponse:
+        raw = await self._request("GET", "/memory/export")
+        return _parse_export(raw)
+
+    async def create_relation(
+        self,
+        from_memory_id: int,
+        *,
+        to_memory_id: int,
+        relationship_type: RelationshipType,
+        confidence: Optional[float] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Relation:
+        _validate_id(from_memory_id, "from_memory_id")
+        _validate_id(to_memory_id, "to_memory_id")
+        if from_memory_id == to_memory_id:
+            raise ValidationError("from_memory_id must differ from to_memory_id (no self-loops)")
+        body = _strip_none(
+            {
+                "to_memory_id": to_memory_id,
+                "relationship_type": relationship_type,
+                "confidence": confidence,
+                "metadata": metadata,
+            }
+        )
+        raw = await self._request("POST", f"/memory/{from_memory_id}/relations", json=body)
+        return _parse_relation(raw)
+
+
+# ─────────────────────────────────────────────────────────────────────
+# Shared response parsers
+# ─────────────────────────────────────────────────────────────────────
+
+
+def _validate_id(value: Any, name: str) -> None:
+    if not isinstance(value, int) or isinstance(value, bool) or value <= 0:
+        raise ValidationError(f"{name} must be a positive integer")
+
+
+def _parse_query(raw: Any) -> QueryResponse:
+    if not isinstance(raw, dict):
+        raise MemorySyncError("query response was not a JSON object")
+    memories = [Memory.from_dict(m) for m in (raw.get("memories") or [])]
+    return QueryResponse(
+        memories=memories,
+        context=raw.get("context"),
+        latency_ms=raw.get("latency_ms"),
+        session_id=raw.get("session_id"),
+        query_intent=raw.get("query_intent"),
+    )
+
+
+def _parse_bulk(raw: Any) -> BulkAddResponse:
+    if not isinstance(raw, dict):
+        raise MemorySyncError("bulk_add response was not a JSON object")
+    results = [
+        BulkAddItemResult(
+            index=int(r["index"]),
+            status=r["status"],
+            memory_ids=list(r.get("memory_ids", []) or []),
+            reason=r.get("reason"),
+        )
+        for r in (raw.get("results") or [])
+    ]
+    return BulkAddResponse(
+        total=int(raw.get("total", 0)),
+        created=int(raw.get("created", 0)),
+        skipped=int(raw.get("skipped", 0)),
+        rejected=int(raw.get("rejected", 0)),
+        results=results,
+    )
+
+
+def _parse_compose(raw: Any) -> ComposeResponse:
+    if not isinstance(raw, dict):
+        raise MemorySyncError("compose response was not a JSON object")
+    return ComposeResponse(
+        composed_prompt=str(raw.get("composed_prompt", "")),
+        memories_used=int(raw.get("memories_used", 0)),
+        token_count=int(raw.get("token_count", 0)),
+        truncated=bool(raw.get("truncated", False)),
+    )
+
+
+def _parse_export(raw: Any) -> ExportResponse:
+    if not isinstance(raw, dict):
+        raise MemorySyncError("export response was not a JSON object")
+    return ExportResponse(
+        user_id=int(raw.get("user_id", 0)),
+        memories=list(raw.get("memories") or []),
+        generated_at=str(raw.get("generated_at", "")),
+    )
+
+
+def _parse_relation(raw: Any) -> Relation:
+    if not isinstance(raw, dict):
+        raise MemorySyncError("relation response was not a JSON object")
+    return Relation(
+        id=int(raw["id"]),
+        from_memory_id=int(raw["from_memory_id"]),
+        to_memory_id=int(raw["to_memory_id"]),
+        relationship_type=raw["relationship_type"],
+        confidence=float(raw.get("confidence", 0.0)),
+        metadata=raw.get("metadata"),
+        created_at=raw.get("created_at"),
+    )

memorysync-1.0.0/src/memorysync/errors.py

@@ -0,0 +1,59 @@
+"""Typed exceptions raised by the MemorySync SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class MemorySyncError(Exception):
+    """Base class for every error raised by the SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        response: Any = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+        self.request_id = request_id
+
+
+class AuthError(MemorySyncError):
+    """401 / 403 — bad key, missing scope."""
+
+
+class ValidationError(MemorySyncError):
+    """400 / 409 / 422 — malformed or rejected request."""
+
+
+class NotFoundError(MemorySyncError):
+    """404 — record not visible to the caller."""
+
+
+class RateLimitError(MemorySyncError):
+    """429 — caller has exceeded a rate or quota limit."""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after_seconds: float,
+        *,
+        status_code: Optional[int] = None,
+        response: Any = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            response=response,
+            request_id=request_id,
+        )
+        self.retry_after_seconds = retry_after_seconds
+
+
+class ServerError(MemorySyncError):
+    """5xx — server failed to handle the request."""

memorysync-1.0.0/src/memorysync/types.py

@@ -0,0 +1,152 @@
+"""Public response and request dataclasses returned by the SDK.
+
+Every shape here mirrors a real on-the-wire payload. We use plain
+``@dataclass`` (stdlib, no extra dependency) so callers can pattern-match,
+serialize, and type-check without pulling Pydantic into their app.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional, Union
+
+RelationshipType = Literal[
+    "similar",
+    "derived_from",
+    "continuation",
+    "contradiction",
+    "summary_of",
+    "detail_of",
+    "caused_by",
+    "references",
+    "supports",
+    "extends",
+]
+
+
+@dataclass
+class Memory:
+    """A single memory record. Mirrors :class:`MemoryResponse` server-side."""
+
+    id: int
+    text: str
+    summary: Optional[str] = None
+    tags: Optional[List[str]] = None
+    source: Optional[str] = None
+    event_type: Optional[str] = None
+    importance: Optional[float] = None
+    metadata: Optional[Dict[str, Any]] = None
+    is_summary: bool = False
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    score: Optional[float] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Memory":
+        return cls(
+            id=int(data["id"]),
+            text=data.get("text", ""),
+            summary=data.get("summary"),
+            tags=data.get("tags"),
+            source=data.get("source"),
+            event_type=data.get("event_type"),
+            importance=data.get("importance"),
+            metadata=data.get("metadata"),
+            is_summary=bool(data.get("is_summary", False)),
+            created_at=data.get("created_at"),
+            updated_at=data.get("updated_at"),
+            score=data.get("score"),
+        )
+
+
+@dataclass
+class AddSkippedResponse:
+    """Returned by :meth:`MemorySyncClient.add` when extraction kept nothing."""
+
+    status: Literal["skipped"]
+    reason: str
+    memory_ids: List[int] = field(default_factory=list)
+    candidates_extracted: int = 0
+    candidates_stored: int = 0
+
+
+@dataclass
+class BulkAddItem:
+    text: str
+    source: Optional[str] = None
+    event_type: Optional[str] = None
+    tags: Optional[List[str]] = None
+    metadata: Optional[Dict[str, Any]] = None
+    importance: Optional[float] = None
+    end_user_id: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {"text": self.text}
+        if self.source is not None:
+            out["source"] = self.source
+        if self.event_type is not None:
+            out["event_type"] = self.event_type
+        if self.tags is not None:
+            out["tags"] = self.tags
+        if self.metadata is not None:
+            out["metadata"] = self.metadata
+        if self.importance is not None:
+            out["importance"] = self.importance
+        if self.end_user_id is not None:
+            out["end_user_id"] = self.end_user_id
+        return out
+
+
+@dataclass
+class BulkAddItemResult:
+    index: int
+    status: Literal["created", "skipped", "rejected"]
+    memory_ids: List[int] = field(default_factory=list)
+    reason: Optional[str] = None
+
+
+@dataclass
+class BulkAddResponse:
+    total: int
+    created: int
+    skipped: int
+    rejected: int
+    results: List[BulkAddItemResult]
+
+
+@dataclass
+class QueryResponse:
+    memories: List[Memory]
+    context: Optional[str] = None
+    latency_ms: Optional[float] = None
+    session_id: Optional[str] = None
+    query_intent: Optional[str] = None
+
+
+@dataclass
+class ComposeResponse:
+    composed_prompt: str
+    memories_used: int
+    token_count: int
+    truncated: bool
+
+
+@dataclass
+class ExportResponse:
+    user_id: int
+    memories: List[Dict[str, Any]]
+    generated_at: str
+
+
+@dataclass
+class Relation:
+    id: int
+    from_memory_id: int
+    to_memory_id: int
+    relationship_type: RelationshipType
+    confidence: float
+    metadata: Optional[Dict[str, Any]] = None
+    created_at: Optional[str] = None
+
+
+AddResult = Union[Memory, AddSkippedResponse]