mrmemory 0.1.0__tar.gz

mrmemory-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Rust
+target/
+**/*.rs.bk
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.venv/
+venv/
+
+# Node/TypeScript
+node_modules/
+dist/
+*.tsbuildinfo
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+docker-compose.override.yml

mrmemory-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: mrmemory
+Version: 0.1.0
+Summary: Agent Memory Relay — persistent long-term memory for AI agents
+Project-URL: Homepage, https://mrmemory.dev
+Project-URL: Documentation, https://docs.amr.dev
+Project-URL: Repository, https://github.com/amr-dev/amr-python
+Author-email: AMR <sdk@amr.dev>
+License-Expression: MIT
+Keywords: agents,ai,llm,memory,semantic-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# amr — Agent Memory Relay
+
+[![PyPI](https://img.shields.io/pypi/v/amr)](https://pypi.org/project/amr/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-mrmemory.dev-8b7aff)](https://mrmemory.dev/docs.html)
+
+Persistent long-term memory for AI agents. One line to install, three lines to integrate.
+
+**[Docs](https://mrmemory.dev/docs.html)** · **[API Reference](https://mrmemory.dev/docs.html#endpoints)** · **[Website](https://mrmemory.dev)**
+
+## Install
+
+```bash
+pip install amr
+```
+
+## Quickstart
+
+```python
+from amr import AMR
+
+amr = AMR("amr_sk_...")  # or set AMR_API_KEY env var
+
+# Store a memory
+amr.remember("User prefers dark mode and vim keybindings")
+
+# Semantic recall
+memories = amr.recall("What are the user's preferences?")
+for m in memories:
+    print(m.content, m.score)
+
+# Forget a memory
+amr.forget(memories[0].id)
+```
+
+## Async Support
+
+```python
+from amr import AsyncAMR
+
+async with AsyncAMR("amr_sk_...") as amr:
+    await amr.remember("User prefers dark mode")
+    memories = await amr.recall("What does the user prefer?")
+```
+
+## Configuration
+
+```python
+amr = AMR(
+    api_key="amr_sk_...",       # or set AMR_API_KEY env var
+    agent_id="my-assistant",    # default agent ID
+    namespace="default",        # default namespace
+    timeout=10.0,               # seconds
+    max_retries=3,              # retry on transient failures
+)
+```
+
+## API Endpoints
+
+All requests go to `https://amr-memory-api.fly.dev`.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/v1/remember` | Store a memory |
+| GET | `/v1/recall?q=...` | Semantic search |
+| DELETE | `/v1/forget/:id` | Delete a memory |
+| GET | `/v1/memories` | List all memories |
+
+Auth: `Authorization: Bearer amr_sk_...`
+
+## Pricing
+
+Starts at **$5/mo** — 10K memories, 50K API calls. [Sign up →](https://amr-memory-api.fly.dev/v1/billing/checkout)
+
+## Links
+
+- **Docs:** https://mrmemory.dev/docs.html
+- **Dashboard:** https://mrmemory.dev
+- **GitHub:** https://github.com/amr-dev/amr-python
+
+## License
+
+MIT

mrmemory-0.1.0/README.md

@@ -0,0 +1,83 @@
+# amr — Agent Memory Relay
+
+[![PyPI](https://img.shields.io/pypi/v/amr)](https://pypi.org/project/amr/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-mrmemory.dev-8b7aff)](https://mrmemory.dev/docs.html)
+
+Persistent long-term memory for AI agents. One line to install, three lines to integrate.
+
+**[Docs](https://mrmemory.dev/docs.html)** · **[API Reference](https://mrmemory.dev/docs.html#endpoints)** · **[Website](https://mrmemory.dev)**
+
+## Install
+
+```bash
+pip install amr
+```
+
+## Quickstart
+
+```python
+from amr import AMR
+
+amr = AMR("amr_sk_...")  # or set AMR_API_KEY env var
+
+# Store a memory
+amr.remember("User prefers dark mode and vim keybindings")
+
+# Semantic recall
+memories = amr.recall("What are the user's preferences?")
+for m in memories:
+    print(m.content, m.score)
+
+# Forget a memory
+amr.forget(memories[0].id)
+```
+
+## Async Support
+
+```python
+from amr import AsyncAMR
+
+async with AsyncAMR("amr_sk_...") as amr:
+    await amr.remember("User prefers dark mode")
+    memories = await amr.recall("What does the user prefer?")
+```
+
+## Configuration
+
+```python
+amr = AMR(
+    api_key="amr_sk_...",       # or set AMR_API_KEY env var
+    agent_id="my-assistant",    # default agent ID
+    namespace="default",        # default namespace
+    timeout=10.0,               # seconds
+    max_retries=3,              # retry on transient failures
+)
+```
+
+## API Endpoints
+
+All requests go to `https://amr-memory-api.fly.dev`.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/v1/remember` | Store a memory |
+| GET | `/v1/recall?q=...` | Semantic search |
+| DELETE | `/v1/forget/:id` | Delete a memory |
+| GET | `/v1/memories` | List all memories |
+
+Auth: `Authorization: Bearer amr_sk_...`
+
+## Pricing
+
+Starts at **$5/mo** — 10K memories, 50K API calls. [Sign up →](https://amr-memory-api.fly.dev/v1/billing/checkout)
+
+## Links
+
+- **Docs:** https://mrmemory.dev/docs.html
+- **Dashboard:** https://mrmemory.dev
+- **GitHub:** https://github.com/amr-dev/amr-python
+
+## License
+
+MIT

mrmemory-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mrmemory"
+version = "0.1.0"
+description = "Agent Memory Relay — persistent long-term memory for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "AMR", email = "sdk@amr.dev" }]
+keywords = ["ai", "agents", "memory", "llm", "semantic-search"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "respx>=0.22", "ruff>=0.8", "mypy>=1.13"]
+
+[project.urls]
+Homepage = "https://mrmemory.dev"
+Documentation = "https://docs.amr.dev"
+Repository = "https://github.com/amr-dev/amr-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/amr"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

mrmemory-0.1.0/src/amr/__init__.py

@@ -0,0 +1,28 @@
+"""AMR — Agent Memory Relay. Persistent long-term memory for AI agents."""
+
+from amr.client import AMR
+from amr.async_client import AsyncAMR
+from amr.types import Memory, MemoryEvent
+from amr.errors import (
+    AMRError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+)
+
+__all__ = [
+    "AMR",
+    "AsyncAMR",
+    "Memory",
+    "MemoryEvent",
+    "AMRError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "ServerError",
+]
+
+__version__ = "0.1.0"

mrmemory-0.1.0/src/amr/_config.py

@@ -0,0 +1,47 @@
+"""Configuration resolution for AMR clients."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "https://api.amr.dev/v1"
+DEFAULT_TIMEOUT = 10.0
+DEFAULT_MAX_RETRIES = 3
+
+
+@dataclass(slots=True)
+class Config:
+    """Resolved client configuration."""
+
+    api_key: str
+    base_url: str
+    agent_id: str | None
+    namespace: str | None
+    timeout: float
+    max_retries: int
+
+    @classmethod
+    def resolve(
+        cls,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        agent_id: str | None = None,
+        namespace: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> Config:
+        """Build config from explicit args → env vars → defaults."""
+        resolved_key = api_key or os.environ.get("AMR_API_KEY", "")
+        if not resolved_key:
+            raise ValueError(
+                "No API key provided. Pass api_key= or set AMR_API_KEY environment variable."
+            )
+        return cls(
+            api_key=resolved_key,
+            base_url=(base_url or os.environ.get("AMR_BASE_URL") or DEFAULT_BASE_URL).rstrip("/"),
+            agent_id=agent_id or os.environ.get("AMR_AGENT_ID"),
+            namespace=namespace or os.environ.get("AMR_NAMESPACE"),
+            timeout=timeout if timeout is not None else DEFAULT_TIMEOUT,
+            max_retries=max_retries if max_retries is not None else DEFAULT_MAX_RETRIES,
+        )

mrmemory-0.1.0/src/amr/_http.py

@@ -0,0 +1,137 @@
+"""HTTP transport with retry logic for AMR."""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import Any
+
+import httpx
+
+from amr._config import Config
+from amr.errors import (
+    AMRError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Raise an appropriate AMRError for non-2xx responses."""
+    code = response.status_code
+    if 200 <= code < 300:
+        return
+
+    try:
+        body = response.json()
+        message = body.get("error", body.get("message", response.text))
+    except Exception:
+        message = response.text or f"HTTP {code}"
+
+    if code == 401:
+        raise AuthenticationError(message, status_code=401)
+    if code == 404:
+        raise NotFoundError(message)
+    if code == 422:
+        raise ValidationError(message)
+    if code == 429:
+        retry_after = float(response.headers.get("retry-after", "1"))
+        raise RateLimitError(message, retry_after=retry_after)
+    if code >= 500:
+        raise ServerError(message, status_code=code)
+    raise AMRError(message, status_code=code)
+
+
+def _backoff(attempt: int) -> float:
+    """Exponential backoff with jitter."""
+    base = min(2**attempt, 30)
+    return base * (0.5 + random.random() * 0.5)
+
+
+class SyncTransport:
+    """Synchronous HTTP transport."""
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._client = httpx.Client(
+            base_url=config.base_url,
+            headers={
+                "Authorization": f"Bearer {config.api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "amr-python/0.1.0",
+            },
+            timeout=config.timeout,
+        )
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Make an HTTP request with automatic retries."""
+        last_exc: Exception | None = None
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = self._client.request(method, path, **kwargs)
+                if response.status_code in _RETRYABLE_STATUS and attempt < self._config.max_retries:
+                    wait = float(response.headers.get("retry-after", "0")) or _backoff(attempt)
+                    time.sleep(wait)
+                    continue
+                _raise_for_status(response)
+                if response.status_code == 204:
+                    return None
+                return response.json()
+            except (httpx.ConnectError, httpx.ReadTimeout) as exc:
+                last_exc = exc
+                if attempt < self._config.max_retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise AMRError(f"Connection failed: {exc}") from exc
+        raise last_exc or AMRError("Request failed after retries")  # type: ignore[misc]
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncTransport:
+    """Asynchronous HTTP transport."""
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._client = httpx.AsyncClient(
+            base_url=config.base_url,
+            headers={
+                "Authorization": f"Bearer {config.api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": "amr-python/0.1.0",
+            },
+            timeout=config.timeout,
+        )
+
+    async def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Make an async HTTP request with automatic retries."""
+        import asyncio
+
+        last_exc: Exception | None = None
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = await self._client.request(method, path, **kwargs)
+                if response.status_code in _RETRYABLE_STATUS and attempt < self._config.max_retries:
+                    wait = float(response.headers.get("retry-after", "0")) or _backoff(attempt)
+                    await asyncio.sleep(wait)
+                    continue
+                _raise_for_status(response)
+                if response.status_code == 204:
+                    return None
+                return response.json()
+            except (httpx.ConnectError, httpx.ReadTimeout) as exc:
+                last_exc = exc
+                if attempt < self._config.max_retries:
+                    await asyncio.sleep(_backoff(attempt))
+                    continue
+                raise AMRError(f"Connection failed: {exc}") from exc
+        raise last_exc or AMRError("Request failed after retries")  # type: ignore[misc]
+
+    async def close(self) -> None:
+        await self._client.aclose()

mrmemory-0.1.0/src/amr/async_client.py

@@ -0,0 +1,154 @@
+"""Asynchronous AMR client."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Any
+
+from amr._config import Config
+from amr._http import AsyncTransport
+from amr.types import Memory
+
+
+class AsyncAMR:
+    """Asynchronous client for Agent Memory Relay.
+
+    Usage::
+
+        from amr import AsyncAMR
+
+        async with AsyncAMR("amr_sk_...") as amr:
+            await amr.remember("User prefers dark mode", tags=["preferences"])
+            memories = await amr.recall("What does the user prefer?")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        agent_id: str | None = None,
+        namespace: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> None:
+        self._config = Config.resolve(
+            api_key=api_key,
+            base_url=base_url,
+            agent_id=agent_id,
+            namespace=namespace,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._transport = AsyncTransport(self._config)
+
+    # -- Context manager --
+
+    async def __aenter__(self) -> AsyncAMR:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._transport.close()
+
+    # -- Core API --
+
+    async def remember(
+        self,
+        content: str,
+        *,
+        tags: list[str] | None = None,
+        namespace: str | None = None,
+        agent_id: str | None = None,
+        ttl: timedelta | None = None,
+    ) -> Memory:
+        """Store a memory."""
+        body: dict[str, Any] = {"content": content}
+        if tags:
+            body["tags"] = tags
+        if namespace or self._config.namespace:
+            body["namespace"] = namespace or self._config.namespace
+        if agent_id or self._config.agent_id:
+            body["agent_id"] = agent_id or self._config.agent_id
+        if ttl is not None:
+            body["ttl"] = int(ttl.total_seconds())
+
+        data = await self._transport.request("POST", "/remember", json=body)
+        return Memory.from_dict(data)
+
+    async def recall(
+        self,
+        query: str,
+        *,
+        namespace: str | None = None,
+        agent_id: str | None = None,
+        tags: list[str] | None = None,
+        limit: int = 5,
+        threshold: float = 0.7,
+    ) -> list[Memory]:
+        """Retrieve relevant memories via semantic search."""
+        body: dict[str, Any] = {"query": query, "limit": limit, "threshold": threshold}
+        if tags:
+            body["tags"] = tags
+        if namespace or self._config.namespace:
+            body["namespace"] = namespace or self._config.namespace
+        if agent_id or self._config.agent_id:
+            body["agent_id"] = agent_id or self._config.agent_id
+
+        data = await self._transport.request("POST", "/recall", json=body)
+        return [Memory.from_dict(m) for m in data.get("memories", data if isinstance(data, list) else [])]
+
+    async def share(
+        self,
+        memory_ids: str | list[str],
+        *,
+        target_agent: str,
+        permissions: str = "read",
+    ) -> None:
+        """Share memories with another agent."""
+        ids = [memory_ids] if isinstance(memory_ids, str) else memory_ids
+        await self._transport.request(
+            "POST",
+            "/share",
+            json={
+                "memory_ids": ids,
+                "target_agent_id": target_agent,
+                "permissions": permissions,
+            },
+        )
+
+    async def forget(self, memory_ids: str | list[str]) -> None:
+        """Delete one or more memories."""
+        ids = [memory_ids] if isinstance(memory_ids, str) else memory_ids
+        await self._transport.request("DELETE", "/forget", json={"memory_ids": ids})
+
+    async def forget_all(self, *, namespace: str | None = None) -> None:
+        """Delete all memories, optionally scoped to a namespace."""
+        body: dict[str, Any] = {"forget_all": True}
+        if namespace:
+            body["namespace"] = namespace
+        await self._transport.request("DELETE", "/forget", json=body)
+
+    async def memories(
+        self,
+        *,
+        namespace: str | None = None,
+        agent_id: str | None = None,
+        tags: list[str] | None = None,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> list[Memory]:
+        """List memories with optional filters."""
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if namespace or self._config.namespace:
+            params["namespace"] = namespace or self._config.namespace
+        if agent_id or self._config.agent_id:
+            params["agent_id"] = agent_id or self._config.agent_id
+        if tags:
+            params["tags"] = ",".join(tags)
+
+        data = await self._transport.request("GET", "/memories", params=params)
+        return [Memory.from_dict(m) for m in data.get("memories", data if isinstance(data, list) else [])]

mrmemory-0.1.0/src/amr/client.py

@@ -0,0 +1,202 @@
+"""Synchronous AMR client."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import Any
+
+from amr._config import Config
+from amr._http import SyncTransport
+from amr.types import Memory
+
+
+class AMR:
+    """Synchronous client for Agent Memory Relay.
+
+    Usage::
+
+        from amr import AMR
+
+        amr = AMR("amr_sk_...")
+        amr.remember("User prefers dark mode", tags=["preferences"])
+        memories = amr.recall("What does the user prefer?")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        agent_id: str | None = None,
+        namespace: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+    ) -> None:
+        self._config = Config.resolve(
+            api_key=api_key,
+            base_url=base_url,
+            agent_id=agent_id,
+            namespace=namespace,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._transport = SyncTransport(self._config)
+
+    # -- Context manager --
+
+    def __enter__(self) -> AMR:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._transport.close()
+
+    # -- Core API --
+
+    def remember(
+        self,
+        content: str,
+        *,
+        tags: list[str] | None = None,
+        namespace: str | None = None,
+        agent_id: str | None = None,
+        ttl: timedelta | None = None,
+    ) -> Memory:
+        """Store a memory.
+
+        Args:
+            content: The memory text to store.
+            tags: Optional tags for filtering.
+            namespace: Override the client default namespace.
+            agent_id: Override the client default agent ID.
+            ttl: Auto-expire after this duration.
+
+        Returns:
+            The created Memory object.
+        """
+        body: dict[str, Any] = {"content": content}
+        if tags:
+            body["tags"] = tags
+        if namespace or self._config.namespace:
+            body["namespace"] = namespace or self._config.namespace
+        if agent_id or self._config.agent_id:
+            body["agent_id"] = agent_id or self._config.agent_id
+        if ttl is not None:
+            body["ttl"] = int(ttl.total_seconds())
+
+        data = self._transport.request("POST", "/remember", json=body)
+        return Memory.from_dict(data)
+
+    def recall(
+        self,
+        query: str,
+        *,
+        namespace: str | None = None,
+        agent_id: str | None = None,
+        tags: list[str] | None = None,
+        limit: int = 5,
+        threshold: float = 0.7,
+    ) -> list[Memory]:
+        """Retrieve relevant memories via semantic search.
+
+        Args:
+            query: Natural language query.
+            namespace: Filter by namespace.
+            agent_id: Filter by agent ID.
+            tags: Filter by tags (AND).
+            limit: Maximum results (default 5).
+            threshold: Minimum similarity score (default 0.7).
+
+        Returns:
+            List of Memory objects ranked by relevance.
+        """
+        body: dict[str, Any] = {"query": query, "limit": limit, "threshold": threshold}
+        if tags:
+            body["tags"] = tags
+        if namespace or self._config.namespace:
+            body["namespace"] = namespace or self._config.namespace
+        if agent_id or self._config.agent_id:
+            body["agent_id"] = agent_id or self._config.agent_id
+
+        data = self._transport.request("POST", "/recall", json=body)
+        return [Memory.from_dict(m) for m in data.get("memories", data if isinstance(data, list) else [])]
+
+    def share(
+        self,
+        memory_ids: str | list[str],
+        *,
+        target_agent: str,
+        permissions: str = "read",
+    ) -> None:
+        """Share memories with another agent.
+
+        Args:
+            memory_ids: Single ID or list of memory IDs to share.
+            target_agent: The target agent ID.
+            permissions: "read" (default) or "readwrite".
+        """
+        ids = [memory_ids] if isinstance(memory_ids, str) else memory_ids
+        self._transport.request(
+            "POST",
+            "/share",
+            json={
+                "memory_ids": ids,
+                "target_agent_id": target_agent,
+                "permissions": permissions,
+            },
+        )
+
+    def forget(self, memory_ids: str | list[str]) -> None:
+        """Delete one or more memories.
+
+        Args:
+            memory_ids: Single ID or list of memory IDs to delete.
+        """
+        ids = [memory_ids] if isinstance(memory_ids, str) else memory_ids
+        self._transport.request("DELETE", "/forget", json={"memory_ids": ids})
+
+    def forget_all(self, *, namespace: str | None = None) -> None:
+        """Delete all memories, optionally scoped to a namespace.
+
+        Args:
+            namespace: If provided, only delete memories in this namespace.
+        """
+        body: dict[str, Any] = {"forget_all": True}
+        if namespace:
+            body["namespace"] = namespace
+        self._transport.request("DELETE", "/forget", json=body)
+
+    def memories(
+        self,
+        *,
+        namespace: str | None = None,
+        agent_id: str | None = None,
+        tags: list[str] | None = None,
+        limit: int = 20,
+        offset: int = 0,
+    ) -> list[Memory]:
+        """List memories with optional filters.
+
+        Args:
+            namespace: Filter by namespace.
+            agent_id: Filter by agent ID.
+            tags: Filter by tags.
+            limit: Page size (default 20).
+            offset: Pagination offset.
+
+        Returns:
+            List of Memory objects.
+        """
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if namespace or self._config.namespace:
+            params["namespace"] = namespace or self._config.namespace
+        if agent_id or self._config.agent_id:
+            params["agent_id"] = agent_id or self._config.agent_id
+        if tags:
+            params["tags"] = ",".join(tags)
+
+        data = self._transport.request("GET", "/memories", params=params)
+        return [Memory.from_dict(m) for m in data.get("memories", data if isinstance(data, list) else [])]

mrmemory-0.1.0/src/amr/errors.py

@@ -0,0 +1,44 @@
+"""AMR exception hierarchy."""
+
+from __future__ import annotations
+
+
+class AMRError(Exception):
+    """Base exception for all AMR errors."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthenticationError(AMRError):
+    """Invalid or missing API key (401)."""
+
+
+class RateLimitError(AMRError):
+    """Too many requests (429)."""
+
+    def __init__(self, message: str, retry_after: float = 1.0) -> None:
+        super().__init__(message, status_code=429)
+        self.retry_after = retry_after
+
+
+class NotFoundError(AMRError):
+    """Resource not found (404)."""
+
+    def __init__(self, message: str = "Not found") -> None:
+        super().__init__(message, status_code=404)
+
+
+class ValidationError(AMRError):
+    """Invalid request parameters (422)."""
+
+    def __init__(self, message: str = "Validation error") -> None:
+        super().__init__(message, status_code=422)
+
+
+class ServerError(AMRError):
+    """AMR server error (5xx)."""
+
+    def __init__(self, message: str = "Server error", status_code: int = 500) -> None:
+        super().__init__(message, status_code=status_code)

mrmemory-0.1.0/src/amr/types.py

@@ -0,0 +1,69 @@
+"""AMR data types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from typing import Literal
+
+
+@dataclass(frozen=True, slots=True)
+class Memory:
+    """A stored memory."""
+
+    id: str
+    content: str
+    tags: list[str] = field(default_factory=list)
+    namespace: str = "default"
+    agent_id: str = ""
+    score: float | None = None
+    ttl: timedelta | None = None
+    expires_at: datetime | None = None
+    created_at: datetime = field(default_factory=datetime.now)
+    updated_at: datetime = field(default_factory=datetime.now)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Memory:  # type: ignore[type-arg]
+        """Parse a Memory from an API response dict."""
+        return cls(
+            id=data["id"],
+            content=data["content"],
+            tags=data.get("tags", []),
+            namespace=data.get("namespace", "default"),
+            agent_id=data.get("agent_id", ""),
+            score=data.get("score"),
+            ttl=timedelta(seconds=data["ttl"]) if data.get("ttl") else None,
+            expires_at=_parse_dt(data.get("expires_at")),
+            created_at=_parse_dt(data.get("created_at")) or datetime.now(),
+            updated_at=_parse_dt(data.get("updated_at")) or datetime.now(),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryEvent:
+    """A real-time memory event from the WebSocket stream."""
+
+    type: Literal["memory.created", "memory.shared", "memory.expired"]
+    memory_id: str
+    memory: Memory | None = None
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> MemoryEvent:  # type: ignore[type-arg]
+        """Parse a MemoryEvent from a WebSocket message."""
+        mem = Memory.from_dict(data["memory"]) if data.get("memory") else None
+        return cls(
+            type=data["type"],
+            memory_id=data.get("memory_id", mem.id if mem else ""),
+            memory=mem,
+            timestamp=_parse_dt(data.get("timestamp")) or datetime.now(),
+        )
+
+
+def _parse_dt(value: str | None) -> datetime | None:
+    """Parse an ISO 8601 datetime string."""
+    if value is None:
+        return None
+    # Handle trailing Z
+    s = value.replace("Z", "+00:00")
+    return datetime.fromisoformat(s)

mrmemory-0.1.0/tests/test_async_client.py

@@ -0,0 +1,74 @@
+"""Tests for the async AMR client."""
+
+import httpx
+import pytest
+import respx
+
+from amr import AsyncAMR, Memory
+
+
+API_KEY = "amr_sk_test_key_1234567890"
+BASE_URL = "https://api.amr.dev/v1"
+
+MOCK_MEMORY = {
+    "id": "mem_abc123",
+    "content": "User prefers dark mode",
+    "tags": ["preferences"],
+    "namespace": "default",
+    "agent_id": "test-agent",
+    "created_at": "2026-03-12T10:00:00Z",
+    "updated_at": "2026-03-12T10:00:00Z",
+}
+
+
+@respx.mock
+async def test_async_remember():
+    respx.post(f"{BASE_URL}/remember").mock(
+        return_value=httpx.Response(201, json=MOCK_MEMORY)
+    )
+    async with AsyncAMR(API_KEY) as amr:
+        memory = await amr.remember("User prefers dark mode", tags=["preferences"])
+
+    assert isinstance(memory, Memory)
+    assert memory.id == "mem_abc123"
+
+
+@respx.mock
+async def test_async_recall():
+    respx.post(f"{BASE_URL}/recall").mock(
+        return_value=httpx.Response(200, json={"memories": [{**MOCK_MEMORY, "score": 0.92}]})
+    )
+    async with AsyncAMR(API_KEY) as amr:
+        memories = await amr.recall("dark mode?")
+
+    assert len(memories) == 1
+    assert memories[0].score == 0.92
+
+
+@respx.mock
+async def test_async_share():
+    respx.post(f"{BASE_URL}/share").mock(
+        return_value=httpx.Response(200, json={"ok": True})
+    )
+    async with AsyncAMR(API_KEY) as amr:
+        await amr.share("mem_abc123", target_agent="agent-2")
+
+
+@respx.mock
+async def test_async_forget():
+    respx.delete(f"{BASE_URL}/forget").mock(
+        return_value=httpx.Response(204)
+    )
+    async with AsyncAMR(API_KEY) as amr:
+        await amr.forget("mem_abc123")
+
+
+@respx.mock
+async def test_async_memories():
+    respx.get(f"{BASE_URL}/memories").mock(
+        return_value=httpx.Response(200, json={"memories": [MOCK_MEMORY]})
+    )
+    async with AsyncAMR(API_KEY) as amr:
+        memories = await amr.memories()
+
+    assert len(memories) == 1

mrmemory-0.1.0/tests/test_client.py

@@ -0,0 +1,151 @@
+"""Tests for the synchronous AMR client."""
+
+import httpx
+import pytest
+import respx
+
+from amr import AMR, Memory
+from amr.errors import AuthenticationError, RateLimitError, NotFoundError, ValidationError
+
+
+API_KEY = "amr_sk_test_key_1234567890"
+BASE_URL = "https://api.amr.dev/v1"
+
+MOCK_MEMORY = {
+    "id": "mem_abc123",
+    "content": "User prefers dark mode",
+    "tags": ["preferences"],
+    "namespace": "default",
+    "agent_id": "test-agent",
+    "created_at": "2026-03-12T10:00:00Z",
+    "updated_at": "2026-03-12T10:00:00Z",
+}
+
+
+@respx.mock
+def test_remember():
+    respx.post(f"{BASE_URL}/remember").mock(
+        return_value=httpx.Response(201, json=MOCK_MEMORY)
+    )
+    with AMR(API_KEY) as amr:
+        memory = amr.remember("User prefers dark mode", tags=["preferences"])
+
+    assert isinstance(memory, Memory)
+    assert memory.id == "mem_abc123"
+    assert memory.content == "User prefers dark mode"
+    assert memory.tags == ["preferences"]
+
+
+@respx.mock
+def test_recall():
+    respx.post(f"{BASE_URL}/recall").mock(
+        return_value=httpx.Response(200, json={"memories": [{**MOCK_MEMORY, "score": 0.95}]})
+    )
+    with AMR(API_KEY) as amr:
+        memories = amr.recall("What does the user prefer?")
+
+    assert len(memories) == 1
+    assert memories[0].score == 0.95
+    assert memories[0].content == "User prefers dark mode"
+
+
+@respx.mock
+def test_share():
+    respx.post(f"{BASE_URL}/share").mock(
+        return_value=httpx.Response(200, json={"ok": True})
+    )
+    with AMR(API_KEY) as amr:
+        amr.share("mem_abc123", target_agent="agent-2")  # no exception = success
+
+
+@respx.mock
+def test_forget():
+    respx.delete(f"{BASE_URL}/forget").mock(
+        return_value=httpx.Response(204)
+    )
+    with AMR(API_KEY) as amr:
+        amr.forget("mem_abc123")  # no exception = success
+
+
+@respx.mock
+def test_forget_all():
+    respx.delete(f"{BASE_URL}/forget").mock(
+        return_value=httpx.Response(204)
+    )
+    with AMR(API_KEY) as amr:
+        amr.forget_all(namespace="test")
+
+
+@respx.mock
+def test_memories_list():
+    respx.get(f"{BASE_URL}/memories").mock(
+        return_value=httpx.Response(200, json={"memories": [MOCK_MEMORY]})
+    )
+    with AMR(API_KEY) as amr:
+        memories = amr.memories(limit=10)
+
+    assert len(memories) == 1
+    assert memories[0].id == "mem_abc123"
+
+
+@respx.mock
+def test_auth_error():
+    respx.post(f"{BASE_URL}/remember").mock(
+        return_value=httpx.Response(401, json={"error": "Invalid API key"})
+    )
+    with AMR(API_KEY, max_retries=0) as amr:
+        with pytest.raises(AuthenticationError):
+            amr.remember("test")
+
+
+@respx.mock
+def test_rate_limit_error():
+    respx.post(f"{BASE_URL}/remember").mock(
+        return_value=httpx.Response(429, json={"error": "Too many requests"}, headers={"retry-after": "5"})
+    )
+    with AMR(API_KEY, max_retries=0) as amr:
+        with pytest.raises(RateLimitError) as exc_info:
+            amr.remember("test")
+        assert exc_info.value.retry_after == 5.0
+
+
+@respx.mock
+def test_not_found_error():
+    respx.delete(f"{BASE_URL}/forget").mock(
+        return_value=httpx.Response(404, json={"error": "Memory not found"})
+    )
+    with AMR(API_KEY, max_retries=0) as amr:
+        with pytest.raises(NotFoundError):
+            amr.forget("mem_nonexistent")
+
+
+@respx.mock
+def test_validation_error():
+    respx.post(f"{BASE_URL}/remember").mock(
+        return_value=httpx.Response(422, json={"error": "content is required"})
+    )
+    with AMR(API_KEY, max_retries=0) as amr:
+        with pytest.raises(ValidationError):
+            amr.remember("")
+
+
+def test_no_api_key():
+    import os
+    env_backup = os.environ.pop("AMR_API_KEY", None)
+    try:
+        with pytest.raises(ValueError, match="No API key"):
+            AMR()
+    finally:
+        if env_backup:
+            os.environ["AMR_API_KEY"] = env_backup
+
+
+def test_env_api_key():
+    import os
+    os.environ["AMR_API_KEY"] = "amr_sk_from_env"
+    try:
+        amr = AMR()
+        assert amr._config.api_key == "amr_sk_from_env"
+        amr.close()
+    finally:
+        del os.environ["AMR_API_KEY"]