memorylayer-py 0.1.0__py3-none-any.whl

memorylayer_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: memorylayer-py
+Version: 0.1.0
+Summary: Privacy-first memory API for LLMs
+Author-email: "rec0.ai" <hello@rec0.ai>
+License: MIT
+Project-URL: Homepage, https://rec0.ai
+Project-URL: Documentation, https://docs.rec0.ai
+Project-URL: Repository, https://github.com/rec0ai/rec0-python
+Project-URL: Bug Tracker, https://github.com/rec0ai/rec0-python/issues
+Keywords: llm,memory,ai,privacy,rag
+Classifier: Development Status :: 4 - Beta
+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
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: responses>=0.25.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+
+# rec0 — memory for any LLM
+
+> Give your AI a permanent memory in 3 lines of code.
+
+[![PyPI version](https://img.shields.io/pypi/v/rec0.svg)](https://pypi.org/project/rec0/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## Install
+
+```bash
+pip install rec0
+```
+
+## Quickstart
+
+```python
+from rec0 import Memory
+
+mem = Memory(api_key="r0_xxx", user_id="user_123")
+mem.store("User prefers Python and dark mode")
+context = mem.context("user preferences")
+# inject context into your LLM prompt — done
+```
+
+That's it. `context` returns a bullet-list string ready to prepend to any system prompt.
+
+---
+
+## Why rec0
+
+| | rec0 | Mem0 |
+|---|---|---|
+| **Privacy** | Data never leaves your servers | Processed externally |
+| **Cost** | $0.002 / 1K ops | ~$0.10 / 1K ops |
+| **Setup** | 3 lines | OAuth + config |
+| **LLM support** | Any model | OpenAI-first |
+| **GDPR** | 1 API call | Manual |
+
+- **Privacy-first:** embeddings and summaries run on YOUR infrastructure — no user data touches third-party APIs
+- **LLM-agnostic:** works with OpenAI, Anthropic, Gemini, Llama, Mistral — anything that takes a string
+- **Memory lifecycle:** automatic importance scoring, recall-count boosting, and time-based decay
+- **GDPR compliant:** right-to-erasure in one call (`mem.delete_user()`)
+
+---
+
+## Full API reference
+
+### `Memory(user_id, api_key, app_id, base_url)`
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `user_id` | `str` | required | Your end-user identifier |
+| `api_key` | `str` | `$REC0_API_KEY` | Your rec0 API key |
+| `app_id` | `str` | `"default"` | Namespace for multi-app isolation |
+| `base_url` | `str` | prod URL | Override for self-hosting |
+
+### Methods
+
+#### `mem.store(content)` → `MemoryObject`
+Store a new memory. Auto-generates embedding and summary server-side.
+
+```python
+m = mem.store("User is building a SaaS product in Python")
+print(m.id)          # UUID
+print(m.importance)  # starts at 1.0, increases with each recall
+```
+
+#### `mem.context(query, limit=5)` → `str`
+**The most-used method.** Returns a bullet-list string to inject into your LLM prompt.
+
+```python
+context = mem.context("what does the user like", limit=5)
+# "- User prefers Python and dark mode\n- User is building a SaaS product"
+
+# Typical usage with OpenAI:
+messages = [
+    {"role": "system", "content": f"User context:\n{context}"},
+    {"role": "user", "content": user_message},
+]
+```
+
+#### `mem.recall(query, limit=5)` → `List[MemoryObject]`
+Returns memories ranked by semantic similarity. Use when you need scores or metadata.
+
+```python
+memories = mem.recall("programming preferences", limit=3)
+for m in memories:
+    print(f"{m.content}  (score: {m.relevance_score})")
+```
+
+#### `mem.list()` → `List[MemoryObject]`
+All active memories for this user, ordered by creation time.
+
+#### `mem.delete(memory_id)` → `None`
+Soft-delete a specific memory (retained for audit trail).
+
+#### `mem.delete_user()` → `dict`
+GDPR right-to-erasure. Removes all memories for this user.
+
+#### `mem.export()` → `dict`
+GDPR data export. Returns all memory data as a dictionary.
+
+#### `mem.ping()` → `bool`
+Connectivity check. Returns `True` if the API is reachable.
+
+```python
+if not mem.ping():
+    print("rec0 API unreachable — check your key")
+```
+
+---
+
+## Error handling
+
+```python
+from rec0 import Memory, Rec0Error, AuthError, RateLimitError, NotFoundError
+
+mem = Memory(api_key="r0_xxx", user_id="user_123")
+
+try:
+    mem.store("User loves rec0")
+except AuthError:
+    print("Invalid API key — check REC0_API_KEY")
+except RateLimitError as e:
+    print(f"Rate limited — retry in {e.retry_after}s")
+except NotFoundError:
+    print("Memory not found")
+except Rec0Error as e:
+    print(f"Unexpected error: {e}")
+```
+
+Rate limits are handled automatically: rec0 will wait `retry_after` seconds and retry once before raising.
+
+---
+
+## Async usage
+
+Every method has an async equivalent via `AsyncMemory`:
+
+```python
+import asyncio
+from rec0 import AsyncMemory
+
+async def main():
+    mem = AsyncMemory(api_key="r0_xxx", user_id="user_123")
+    await mem.store("User is a night-owl developer")
+    context = await mem.context("when does the user work")
+    print(context)
+
+asyncio.run(main())
+```
+
+`AsyncMemory` uses `httpx` under the hood and is safe to use in FastAPI, Django async views, and any `asyncio` application.
+
+---
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `REC0_API_KEY` | Your rec0 API key (used automatically if `api_key=` not passed) |
+| `REC0_BASE_URL` | Override the API base URL (optional, for self-hosting) |
+
+```bash
+export REC0_API_KEY=r0_your_key_here
+```
+
+```python
+# api_key is now auto-loaded — no need to hardcode it
+mem = Memory(user_id="user_123")
+```
+
+---
+
+## MemoryObject fields
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `str` | UUID |
+| `content` | `str` | The original memory text |
+| `summary` | `str \| None` | Auto-generated summary |
+| `importance` | `float` | 1.0–10.0; increases with recall |
+| `recall_count` | `int` | Times this memory was recalled |
+| `relevance_score` | `float \| None` | Similarity score (recall only) |
+| `created_at` | `datetime` | When stored |
+| `is_active` | `bool` | False if deleted |
+
+---
+
+## Self-hosting
+
+rec0 is open-source. Deploy your own instance on Railway, Fly, or any server:
+
+```bash
+git clone https://github.com/patelyash2511/memorylayer
+# See README for Railway deployment instructions
+```
+
+Then point the SDK at your instance:
+
+```python
+mem = Memory(
+    api_key="your_key",
+    user_id="user_123",
+    base_url="https://your-instance.up.railway.app",
+)
+```
+
+---
+
+[rec0.ai](https://rec0.ai) · [docs](https://docs.rec0.ai) · [discord](https://discord.gg/rec0) · [twitter](https://twitter.com/rec0ai)

memorylayer_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+rec0/__init__.py,sha256=NReh7VjGkvbR76XKFFvymatPGHFWThhlLxGAJT3lCgA,742
+rec0/async_client.py,sha256=B-GpMT0BpxscOT_kXwxf1LiGktQXyHBPJFL5ykuTHk4,7445
+rec0/client.py,sha256=C_fGgd503bJTDD6Gs1qDJrGLoc0BZ6ztKk2mCyHxjoY,7970
+rec0/exceptions.py,sha256=u7b3DgO0A7Ecs2pOOWTX1i-ihoKpQqBLw8LQvwgoqBw,740
+rec0/models.py,sha256=nh4jDfOeenZMdu2daDbvVd9XDd3sOmr6F15K0JXJWvs,1826
+rec0/version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+memorylayer_py-0.1.0.dist-info/METADATA,sha256=PdtGY0LaEXCkI5IvPKPrQrt2qLMDiBwtv3E7fmP2A44,7038
+memorylayer_py-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+memorylayer_py-0.1.0.dist-info/top_level.txt,sha256=8N2dtJTBzcUZEXxkphDTo3LB6vKzMcbiag7DWe4iQQU,5
+memorylayer_py-0.1.0.dist-info/RECORD,,

memorylayer_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

memorylayer_py-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rec0

rec0/__init__.py

@@ -0,0 +1,30 @@
+"""rec0 — privacy-first memory API for LLMs.
+
+Quick start::
+
+    from rec0 import Memory
+
+    mem = Memory(api_key="r0_xxx", user_id="user_123")
+    mem.store("User prefers dark mode and uses VSCode")
+    context = mem.context("user preferences")
+    # inject context into your LLM prompt — done
+"""
+
+from .async_client import AsyncMemory
+from .client import Memory
+from .exceptions import AuthError, NotFoundError, RateLimitError, Rec0Error, ServerError
+from .models import MemoryObject, RecallResult
+from .version import __version__
+
+__all__ = [
+    "Memory",
+    "AsyncMemory",
+    "MemoryObject",
+    "RecallResult",
+    "Rec0Error",
+    "AuthError",
+    "RateLimitError",
+    "NotFoundError",
+    "ServerError",
+    "__version__",
+]

rec0/async_client.py

@@ -0,0 +1,201 @@
+"""rec0 async client — AsyncMemory class backed by httpx."""
+
+from __future__ import annotations
+
+import logging
+import asyncio
+import os
+from typing import List, Optional
+
+import httpx
+
+from .exceptions import AuthError, NotFoundError, RateLimitError, Rec0Error, ServerError
+from .models import MemoryObject, RecallResult
+from .version import __version__
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_BASE_URL = "https://memorylayer-production.up.railway.app"
+_DEFAULT_TIMEOUT = 10  # seconds
+
+
+def _raise_for_response(resp: httpx.Response) -> None:
+    """Map HTTP error codes to typed exceptions."""
+    if resp.status_code < 400:
+        return
+    try:
+        body = resp.json()
+        detail = body.get("detail", body)
+        if isinstance(detail, dict):
+            message = detail.get("message", str(detail))
+        else:
+            message = str(detail)
+    except Exception:
+        message = resp.text or f"HTTP {resp.status_code}"
+
+    if resp.status_code == 401:
+        raise AuthError(message)
+    if resp.status_code == 404:
+        raise NotFoundError(message)
+    if resp.status_code == 429:
+        retry_after = 60
+        try:
+            detail = resp.json().get("detail", {})
+            if isinstance(detail, dict):
+                retry_after = int(detail.get("retry_after_seconds", 60))
+        except Exception:
+            pass
+        raise RateLimitError(message, retry_after=retry_after)
+    if resp.status_code >= 500:
+        raise ServerError(message)
+    raise Rec0Error(f"HTTP {resp.status_code}: {message}")
+
+
+class AsyncMemory:
+    """Asynchronous rec0 client.
+
+    Example::
+
+        from rec0 import AsyncMemory
+
+        async def main():
+            mem = AsyncMemory(api_key="r0_xxx", user_id="user_123")
+            await mem.store("User is a Python developer")
+            context = await mem.context("user preferences")
+    """
+
+    def __init__(
+        self,
+        user_id: str,
+        api_key: Optional[str] = None,
+        app_id: str = "default",
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: int = _DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("REC0_API_KEY", "")
+        if not resolved_key:
+            raise AuthError(
+                "No API key provided. Pass api_key= or set REC0_API_KEY env var."
+            )
+        self._api_key = resolved_key
+        self.user_id = user_id
+        self.app_id = app_id
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._headers = {
+            "X-API-Key": self._api_key,
+            "Content-Type": "application/json",
+            "User-Agent": f"rec0-python/{__version__}",
+        }
+
+    # ── Internal helpers ───────────────────────────────────────────────────────
+
+    async def _post(self, path: str, json: dict) -> httpx.Response:
+        try:
+            async with httpx.AsyncClient(
+                headers=self._headers, timeout=self._timeout
+            ) as client:
+                resp = await client.post(f"{self._base_url}{path}", json=json)
+        except httpx.TimeoutException:
+            raise Rec0Error("Request timed out")
+        except httpx.ConnectError as exc:
+            raise Rec0Error(f"Connection error: {exc}")
+        _raise_for_response(resp)
+        return resp
+
+    async def _get(self, path: str, params: Optional[dict] = None) -> httpx.Response:
+        try:
+            async with httpx.AsyncClient(
+                headers=self._headers, timeout=self._timeout
+            ) as client:
+                resp = await client.get(f"{self._base_url}{path}", params=params)
+        except httpx.TimeoutException:
+            raise Rec0Error("Request timed out")
+        except httpx.ConnectError as exc:
+            raise Rec0Error(f"Connection error: {exc}")
+        _raise_for_response(resp)
+        return resp
+
+    async def _delete(self, path: str) -> httpx.Response:
+        try:
+            async with httpx.AsyncClient(
+                headers=self._headers, timeout=self._timeout
+            ) as client:
+                resp = await client.delete(f"{self._base_url}{path}")
+        except httpx.TimeoutException:
+            raise Rec0Error("Request timed out")
+        except httpx.ConnectError as exc:
+            raise Rec0Error(f"Connection error: {exc}")
+        _raise_for_response(resp)
+        return resp
+
+    async def _post_with_retry(self, path: str, json: dict) -> httpx.Response:
+        """POST with one automatic retry on RateLimitError."""
+        try:
+            return await self._post(path, json)
+        except RateLimitError as exc:
+            logger.warning("rec0: rate limited, retrying in %ds...", exc.retry_after)
+            await asyncio.sleep(exc.retry_after)
+            return await self._post(path, json)
+
+    # ── Public API ─────────────────────────────────────────────────────────────
+
+    async def store(self, content: str) -> MemoryObject:
+        """Store a new memory."""
+        resp = await self._post_with_retry(
+            "/v1/memory/store",
+            {"user_id": self.user_id, "app_id": self.app_id, "content": content},
+        )
+        return MemoryObject._from_dict(resp.json())
+
+    async def recall(self, query: str, limit: int = 5) -> List[MemoryObject]:
+        """Recall memories most relevant to *query*."""
+        resp = await self._post_with_retry(
+            "/v1/memory/recall",
+            {
+                "user_id": self.user_id,
+                "app_id": self.app_id,
+                "query": query,
+                "limit": limit,
+            },
+        )
+        data = resp.json()
+        return [MemoryObject._from_dict(m) for m in data.get("memories", [])]
+
+    async def context(self, query: str, limit: int = 5) -> str:
+        """Build a context string ready to inject into any LLM prompt."""
+        memories = await self.recall(query, limit=limit)
+        return "\n".join(f"- {m.content}" for m in memories)
+
+    async def list(self) -> List[MemoryObject]:
+        """List all active memories for this user."""
+        resp = await self._get(
+            "/v1/memory/list",
+            params={"user_id": self.user_id, "app_id": self.app_id},
+        )
+        data = resp.json()
+        return [MemoryObject._from_dict(m) for m in data.get("memories", [])]
+
+    async def delete(self, memory_id: str) -> None:
+        """Soft-delete a specific memory by ID."""
+        await self._delete(f"/v1/memory/{memory_id}")
+
+    async def delete_user(self) -> dict:
+        """GDPR right-to-erasure: delete all memories for this user."""
+        resp = await self._delete(f"/v1/users/{self.user_id}")
+        if resp.status_code == 204 or not resp.content:
+            return {"deleted": True, "memories_removed": 0}
+        return resp.json()
+
+    async def export(self) -> dict:
+        """GDPR data export: return all memories for this user as a dict."""
+        resp = await self._get(f"/v1/users/{self.user_id}/export")
+        return resp.json()
+
+    async def ping(self) -> bool:
+        """Check connectivity. Returns True if server is reachable."""
+        try:
+            await self._get("/health")
+            return True
+        except Exception:
+            return False

rec0/client.py

@@ -0,0 +1,232 @@
+"""rec0 sync client — Memory class backed by requests."""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import List, Optional
+
+import requests
+
+from .exceptions import AuthError, NotFoundError, RateLimitError, Rec0Error, ServerError
+from .models import MemoryObject, RecallResult
+from .version import __version__
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_BASE_URL = "https://memorylayer-production.up.railway.app"
+_DEFAULT_TIMEOUT = 10  # seconds
+
+
+def _raise_for_response(resp: requests.Response) -> None:
+    """Map HTTP error codes to typed exceptions."""
+    if resp.status_code < 400:
+        return
+    try:
+        body = resp.json()
+        detail = body.get("detail", body)
+        if isinstance(detail, dict):
+            message = detail.get("message", str(detail))
+        else:
+            message = str(detail)
+    except Exception:
+        message = resp.text or f"HTTP {resp.status_code}"
+
+    if resp.status_code == 401:
+        raise AuthError(message)
+    if resp.status_code == 404:
+        raise NotFoundError(message)
+    if resp.status_code == 429:
+        retry_after = 60
+        try:
+            detail = resp.json().get("detail", {})
+            if isinstance(detail, dict):
+                retry_after = int(detail.get("retry_after_seconds", 60))
+        except Exception:
+            pass
+        raise RateLimitError(message, retry_after=retry_after)
+    if resp.status_code >= 500:
+        raise ServerError(message)
+    raise Rec0Error(f"HTTP {resp.status_code}: {message}")
+
+
+class Memory:
+    """Synchronous rec0 client.
+
+    Example::
+
+        from rec0 import Memory
+
+        mem = Memory(api_key="r0_xxx", user_id="user_123")
+        mem.store("User prefers dark mode")
+        context = mem.context("user preferences")
+    """
+
+    def __init__(
+        self,
+        user_id: str,
+        api_key: Optional[str] = None,
+        app_id: str = "default",
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: int = _DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("REC0_API_KEY", "")
+        if not resolved_key:
+            raise AuthError(
+                "No API key provided. Pass api_key= or set REC0_API_KEY env var."
+            )
+        self._api_key = resolved_key
+        self.user_id = user_id
+        self.app_id = app_id
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "X-API-Key": self._api_key,
+                "Content-Type": "application/json",
+                "User-Agent": f"rec0-python/{__version__}",
+            }
+        )
+
+    # ── Internal helpers ───────────────────────────────────────────────────────
+
+    def _post(self, path: str, json: dict) -> requests.Response:
+        try:
+            resp = self._session.post(
+                f"{self._base_url}{path}", json=json, timeout=self._timeout
+            )
+        except requests.Timeout:
+            raise Rec0Error("Request timed out")
+        except requests.ConnectionError as exc:
+            raise Rec0Error(f"Connection error: {exc}")
+        _raise_for_response(resp)
+        return resp
+
+    def _get(self, path: str, params: Optional[dict] = None) -> requests.Response:
+        try:
+            resp = self._session.get(
+                f"{self._base_url}{path}", params=params, timeout=self._timeout
+            )
+        except requests.Timeout:
+            raise Rec0Error("Request timed out")
+        except requests.ConnectionError as exc:
+            raise Rec0Error(f"Connection error: {exc}")
+        _raise_for_response(resp)
+        return resp
+
+    def _delete(self, path: str) -> requests.Response:
+        try:
+            resp = self._session.delete(
+                f"{self._base_url}{path}", timeout=self._timeout
+            )
+        except requests.Timeout:
+            raise Rec0Error("Request timed out")
+        except requests.ConnectionError as exc:
+            raise Rec0Error(f"Connection error: {exc}")
+        _raise_for_response(resp)
+        return resp
+
+    def _post_with_retry(self, path: str, json: dict) -> requests.Response:
+        """POST with one automatic retry on RateLimitError."""
+        try:
+            return self._post(path, json)
+        except RateLimitError as exc:
+            logger.warning("rec0: rate limited, retrying in %ds...", exc.retry_after)
+            time.sleep(exc.retry_after)
+            return self._post(path, json)
+
+    # ── Public API ─────────────────────────────────────────────────────────────
+
+    def store(self, content: str) -> MemoryObject:
+        """Store a new memory.
+
+        Args:
+            content: The text to remember.
+
+        Returns:
+            The stored :class:`MemoryObject`.
+        """
+        resp = self._post_with_retry(
+            "/v1/memory/store",
+            {"user_id": self.user_id, "app_id": self.app_id, "content": content},
+        )
+        return MemoryObject._from_dict(resp.json())
+
+    def recall(self, query: str, limit: int = 5) -> List[MemoryObject]:
+        """Recall memories most relevant to *query*.
+
+        Args:
+            query: Natural language query.
+            limit: Maximum number of results to return (default 5).
+
+        Returns:
+            List of :class:`MemoryObject` sorted by relevance (highest first).
+        """
+        resp = self._post_with_retry(
+            "/v1/memory/recall",
+            {
+                "user_id": self.user_id,
+                "app_id": self.app_id,
+                "query": query,
+                "limit": limit,
+            },
+        )
+        data = resp.json()
+        return [MemoryObject._from_dict(m) for m in data.get("memories", [])]
+
+    def context(self, query: str, limit: int = 5) -> str:
+        """Build a context string ready to inject into any LLM prompt.
+
+        Args:
+            query: What you want to remember about the user.
+            limit: Maximum memories to include (default 5).
+
+        Returns:
+            Newline-separated bullet list: ``"- memory1\\n- memory2\\n..."``
+            Returns an empty string when no memories exist.
+        """
+        memories = self.recall(query, limit=limit)
+        return "\n".join(f"- {m.content}" for m in memories)
+
+    def list(self) -> List[MemoryObject]:
+        """List all active memories for this user, ordered by creation time."""
+        resp = self._get(
+            "/v1/memory/list",
+            params={"user_id": self.user_id, "app_id": self.app_id},
+        )
+        data = resp.json()
+        return [MemoryObject._from_dict(m) for m in data.get("memories", [])]
+
+    def delete(self, memory_id: str) -> None:
+        """Soft-delete a specific memory by ID."""
+        self._delete(f"/v1/memory/{memory_id}")
+
+    def delete_user(self) -> dict:
+        """GDPR right-to-erasure: delete all memories for this user.
+
+        Returns:
+            ``{"deleted": True, "memories_removed": N}``
+        """
+        resp = self._delete(f"/v1/users/{self.user_id}")
+        if resp.status_code == 204 or not resp.content:
+            return {"deleted": True, "memories_removed": 0}
+        return resp.json()
+
+    def export(self) -> dict:
+        """GDPR data export: return all memories for this user as a dict."""
+        resp = self._get(f"/v1/users/{self.user_id}/export")
+        return resp.json()
+
+    def ping(self) -> bool:
+        """Check connectivity and confirm the API key works.
+
+        Returns:
+            ``True`` if the server is reachable, ``False`` otherwise.
+        """
+        try:
+            self._get("/health")
+            return True
+        except Exception:
+            return False

rec0/exceptions.py

@@ -0,0 +1,31 @@
+"""rec0 exceptions — every error maps to a meaningful Python type."""
+
+from __future__ import annotations
+
+
+class Rec0Error(Exception):
+    """Base exception for all rec0 errors."""
+
+
+class AuthError(Rec0Error):
+    """Raised on 401 — invalid or missing API key."""
+
+
+class RateLimitError(Rec0Error):
+    """Raised on 429 — rate limit exceeded.
+
+    Attributes:
+        retry_after: seconds to wait before retrying.
+    """
+
+    def __init__(self, message: str, retry_after: int = 60) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class NotFoundError(Rec0Error):
+    """Raised on 404 — resource not found."""
+
+
+class ServerError(Rec0Error):
+    """Raised on 5xx — unexpected server error."""

rec0/models.py

@@ -0,0 +1,61 @@
+"""rec0 data models — clean dataclasses for API responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import List, Optional
+
+
+@dataclass
+class MemoryObject:
+    id: str
+    user_id: str
+    app_id: str
+    content: str
+    summary: Optional[str]
+    importance: float
+    recall_count: int
+    created_at: datetime
+    updated_at: datetime
+    is_active: bool
+    rec0_version: str
+    relevance_score: Optional[float] = None  # only present on recall results
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "MemoryObject":
+        return cls(
+            id=data["id"],
+            user_id=data["user_id"],
+            app_id=data["app_id"],
+            content=data["content"],
+            summary=data.get("summary"),
+            importance=float(data.get("importance", 1.0)),
+            recall_count=int(data.get("recall_count", 0)),
+            created_at=_parse_dt(data["created_at"]),
+            updated_at=_parse_dt(data["updated_at"]),
+            is_active=bool(data.get("is_active", True)),
+            rec0_version=data.get("rec0_version", "1.0.0"),
+            relevance_score=float(data["relevance_score"]) if "relevance_score" in data else None,
+        )
+
+
+@dataclass
+class RecallResult:
+    memories: List[MemoryObject]
+    total_memories: int
+    recall_time_ms: int
+    rec0_version: str
+
+
+def _parse_dt(value: str | datetime) -> datetime:
+    if isinstance(value, datetime):
+        return value
+    # Handle ISO strings with or without timezone suffix
+    value = value.rstrip("Z")
+    for fmt in ("%Y-%m-%dT%H:%M:%S.%f", "%Y-%m-%dT%H:%M:%S"):
+        try:
+            return datetime.strptime(value, fmt)
+        except ValueError:
+            continue
+    raise ValueError(f"Cannot parse datetime: {value!r}")

rec0/version.py

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