memlayer-py 0.1.0__py3-none-any.whl

memlayer/__init__.py

@@ -0,0 +1,29 @@
+from sdk.memlayer.client import (
+    MemLayerClient,
+    AsyncMemLayerClient,
+    Memory,
+    StoreResult,
+    DeleteResult,
+    ContextResult,
+    MemLayerError,
+    AuthenticationError,
+    PlanLimitError,
+    MemoryNotFoundError,
+    DuplicateMemoryError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MemLayerClient",
+    "AsyncMemLayerClient",
+    "Memory",
+    "StoreResult",
+    "DeleteResult",
+    "ContextResult",
+    "MemLayerError",
+    "AuthenticationError",
+    "PlanLimitError",
+    "MemoryNotFoundError",
+    "DuplicateMemoryError",
+]

memlayer/client.py

@@ -0,0 +1,709 @@
+"""
+MemLayer Python SDK
+===================
+Persistent memory for AI agents.
+
+Install:
+    pip install memlayer-py
+
+Usage:
+    from memlayer import MemLayerClient
+
+    client = MemLayerClient(api_key="ml_live_xxx")
+
+    # Store a memory
+    mem_id = client.remember(
+        "User prefers dark mode",
+        user_id="user_123",
+        agent_id="support_bot",
+    )
+
+    # Recall relevant memories
+    memories = client.recall(
+        "what UI preferences does this user have?",
+        user_id="user_123",
+        agent_id="support_bot",
+    )
+
+    for m in memories:
+        print(m.content, m.score)
+
+    # Load context at session start
+    context = client.context(user_id="user_123", agent_id="support_bot")
+
+    # Forget everything for a user
+    client.forget_all(user_id="user_123", agent_id="support_bot")
+"""
+
+import httpx
+from dataclasses import dataclass, field
+from typing import Optional, Any
+
+
+# ── Data classes ──────────────────────────────────────────────────
+
+@dataclass
+class Memory:
+    id:            str
+    content:       str
+    user_id:       str
+    agent_id:      str
+    memory_type:   str
+    metadata:      dict
+    importance:    float
+    score:         Optional[float]
+    score_detail:  Optional[dict]
+    created_at:    str
+    last_accessed: Optional[str]
+    expires_at:    Optional[str]
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Memory":
+        return cls(
+            id=d["id"],
+            content=d["content"],
+            user_id=d["user_id"],
+            agent_id=d["agent_id"],
+            memory_type=d["memory_type"],
+            metadata=d.get("metadata") or {},
+            importance=d.get("importance", 0.5),
+            score=d.get("score"),
+            score_detail=d.get("score_detail"),
+            created_at=d["created_at"],
+            last_accessed=d.get("last_accessed"),
+            expires_at=d.get("expires_at"),
+        )
+
+    def __repr__(self) -> str:
+        score_str = f", score={self.score:.3f}" if self.score else ""
+        return f"Memory(id={self.id[:8]}..., content={self.content[:50]!r}{score_str})"
+
+
+@dataclass
+class StoreResult:
+    id:      str
+    message: str = "Memory stored successfully"
+
+    @property
+    def is_duplicate(self) -> bool:
+        return self.id == "duplicate"
+
+
+@dataclass
+class DeleteResult:
+    deleted: int
+    message: str
+
+
+@dataclass
+class ContextResult:
+    memories: list[Memory]
+    total:    int
+    limit:    int
+    offset:   int
+
+
+@dataclass
+class SearchResult:
+    memories: list[Memory]
+    query:    str
+    total:    int
+
+
+# ── Exceptions ────────────────────────────────────────────────────
+
+class MemLayerError(Exception):
+    """Base exception for all MemLayer SDK errors."""
+    def __init__(self, status_code: int, detail: str):
+        self.status_code = status_code
+        self.detail      = detail
+        super().__init__(f"MemLayer API error {status_code}: {detail}")
+
+
+class AuthenticationError(MemLayerError):
+    """Raised when the API key is invalid or missing."""
+    pass
+
+
+class PlanLimitError(MemLayerError):
+    """Raised when the tenant has hit their plan memory limit."""
+    pass
+
+
+class MemoryNotFoundError(MemLayerError):
+    """Raised when a memory ID does not exist."""
+    pass
+
+
+class DuplicateMemoryError(MemLayerError):
+    """Raised when a duplicate memory is detected."""
+    pass
+
+
+# ── Sync Client ───────────────────────────────────────────────────
+
+class MemLayerClient:
+    """
+    Synchronous MemLayer client.
+
+    Example:
+        client = MemLayerClient(api_key="ml_live_xxx")
+        mem_id = client.remember("User is in Lagos", user_id="u1", agent_id="bot")
+        memories = client.recall("where is the user?", user_id="u1", agent_id="bot")
+    """
+
+    def __init__(
+        self,
+        api_key:  str,
+        base_url: str = "https://memlayer.online",
+        timeout:  float = 30.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self._headers = {
+            "X-API-Key":    api_key,
+            "Content-Type": "application/json",
+        }
+        self._client = httpx.Client(
+            headers=self._headers,
+            timeout=timeout,
+        )
+
+    # ── Store ──────────────────────────────────────────────────────
+
+    def remember(
+        self,
+        content:     str,
+        user_id:     str,
+        agent_id:    str,
+        memory_type: str = "episodic",
+        metadata:    Optional[dict] = None,
+        importance:  float = 0.5,
+        ttl_days:    Optional[int] = None,
+    ) -> StoreResult:
+        """
+        Store a memory for a user+agent pair.
+        Returns a StoreResult with the memory ID.
+        Returns StoreResult with id='duplicate' if content already exists.
+
+        Args:
+            content:     The memory text to store.
+            user_id:     Identifier for the end user.
+            agent_id:    Identifier for the agent.
+            memory_type: 'episodic', 'semantic', or 'summary'.
+            metadata:    Optional dict of extra data to store with the memory.
+            importance:  Priority score 0.0 to 1.0 (default 0.5).
+            ttl_days:    Days until memory expires. None = permanent.
+        """
+        resp = self._client.post(
+            f"{self.base_url}/memories",
+            json={
+                "content":     content,
+                "user_id":     user_id,
+                "agent_id":    agent_id,
+                "memory_type": memory_type,
+                "metadata":    metadata or {},
+                "importance":  importance,
+                "ttl_days":    ttl_days,
+            },
+        )
+        self._raise_for_status(resp)
+        data = resp.json()
+        return StoreResult(id=data["id"], message=data.get("message", ""))
+
+    # ── Search ─────────────────────────────────────────────────────
+
+    def recall(
+        self,
+        query:       str,
+        user_id:     str,
+        agent_id:    str,
+        top_k:       int = 5,
+        min_score:   float = 0.70,
+        memory_type: Optional[str] = None,
+    ) -> list[Memory]:
+        """
+        Semantic search — returns top-k memories ranked by hybrid score.
+        Hybrid score = 70% cosine similarity + 20% recency + 10% importance.
+
+        Args:
+            query:       Natural language query.
+            user_id:     Identifier for the end user.
+            agent_id:    Identifier for the agent.
+            top_k:       Number of memories to return (1-20).
+            min_score:   Minimum hybrid score threshold (0.0-1.0).
+            memory_type: Filter by 'episodic', 'semantic', or 'summary'.
+        """
+        params: dict[str, Any] = {
+            "query":    query,
+            "user_id":  user_id,
+            "agent_id": agent_id,
+            "top_k":    top_k,
+            "min_score": min_score,
+        }
+        if memory_type:
+            params["memory_type"] = memory_type
+
+        resp = self._client.get(
+            f"{self.base_url}/memories/search",
+            params=params,
+        )
+        self._raise_for_status(resp)
+        data = resp.json()
+        return [Memory.from_dict(m) for m in data["memories"]]
+
+    # ── Context ────────────────────────────────────────────────────
+
+    def context(
+        self,
+        user_id:         str,
+        agent_id:        str,
+        top_k:           int = 10,
+        current_message: Optional[str] = None,
+    ) -> ContextResult:
+        """
+        Load memories at session start — before any query is made.
+        If current_message is provided, uses semantic search.
+        Otherwise returns memories ranked by importance + recency.
+
+        Args:
+            user_id:         Identifier for the end user.
+            agent_id:        Identifier for the agent.
+            top_k:           Number of memories to return (1-50).
+            current_message: First message in the session (optional).
+        """
+        params: dict[str, Any] = {
+            "user_id":  user_id,
+            "agent_id": agent_id,
+            "top_k":    top_k,
+        }
+        if current_message:
+            params["current_message"] = current_message
+
+        resp = self._client.get(
+            f"{self.base_url}/memories/context",
+            params=params,
+        )
+        self._raise_for_status(resp)
+        data = resp.json()
+        return ContextResult(
+            memories=[Memory.from_dict(m) for m in data["memories"]],
+            total=data["total"],
+            limit=data["limit"],
+            offset=data["offset"],
+        )
+
+    # ── List ───────────────────────────────────────────────────────
+
+    def list(
+        self,
+        user_id:     str,
+        agent_id:    str,
+        memory_type: Optional[str] = None,
+        limit:       int = 20,
+        offset:      int = 0,
+    ) -> ContextResult:
+        """
+        List all memories for a user+agent pair (paginated).
+
+        Args:
+            user_id:     Identifier for the end user.
+            agent_id:    Identifier for the agent.
+            memory_type: Filter by memory type.
+            limit:       Results per page (1-100).
+            offset:      Pagination offset.
+        """
+        params: dict[str, Any] = {
+            "user_id":  user_id,
+            "agent_id": agent_id,
+            "limit":    limit,
+            "offset":   offset,
+        }
+        if memory_type:
+            params["memory_type"] = memory_type
+
+        resp = self._client.get(
+            f"{self.base_url}/memories",
+            params=params,
+        )
+        self._raise_for_status(resp)
+        data = resp.json()
+        return ContextResult(
+            memories=[Memory.from_dict(m) for m in data["memories"]],
+            total=data["total"],
+            limit=data["limit"],
+            offset=data["offset"],
+        )
+
+    # ── Update ─────────────────────────────────────────────────────
+
+    def update(
+        self,
+        memory_id:   str,
+        user_id:     str,
+        agent_id:    str,
+        new_content: str,
+        importance:  Optional[float] = None,
+        metadata:    Optional[dict] = None,
+    ) -> Memory:
+        """
+        Update an existing memory with new content.
+        Re-embeds the new content. Same memory ID — just new content.
+
+        Args:
+            memory_id:   UUID of the memory to update.
+            user_id:     Identifier for the end user.
+            agent_id:    Identifier for the agent.
+            new_content: Replacement content.
+            importance:  New importance score (optional).
+            metadata:    New metadata (optional).
+        """
+        body: dict[str, Any] = {
+            "user_id":     user_id,
+            "agent_id":    agent_id,
+            "new_content": new_content,
+        }
+        if importance is not None:
+            body["importance"] = importance
+        if metadata is not None:
+            body["metadata"] = metadata
+
+        resp = self._client.patch(
+            f"{self.base_url}/memories/{memory_id}",
+            json=body,
+        )
+        self._raise_for_status(resp)
+        return Memory.from_dict(resp.json())
+
+    # ── Duplicate check ────────────────────────────────────────────
+
+    def is_duplicate(
+        self,
+        content:   str,
+        user_id:   str,
+        agent_id:  str,
+        threshold: float = 0.95,
+    ) -> bool:
+        """
+        Check if a memory already exists before storing.
+        Returns True if a near-identical memory is found.
+
+        Args:
+            content:   Memory text to check.
+            user_id:   Identifier for the end user.
+            agent_id:  Identifier for the agent.
+            threshold: Similarity threshold (0.0-1.0). Default 0.95.
+        """
+        resp = self._client.post(
+            f"{self.base_url}/memories/duplicate-check",
+            params={
+                "content":   content,
+                "user_id":   user_id,
+                "agent_id":  agent_id,
+                "threshold": threshold,
+            },
+        )
+        self._raise_for_status(resp)
+        return resp.json()["is_duplicate"]
+
+    # ── Delete one ─────────────────────────────────────────────────
+
+    def forget(
+        self,
+        memory_id: str,
+        user_id:   str,
+        agent_id:  str,
+    ) -> DeleteResult:
+        """
+        Delete a single memory by ID.
+
+        Args:
+            memory_id: UUID of the memory to delete.
+            user_id:   Identifier for the end user.
+            agent_id:  Identifier for the agent.
+        """
+        resp = self._client.delete(
+            f"{self.base_url}/memories/{memory_id}",
+            params={"user_id": user_id, "agent_id": agent_id},
+        )
+        self._raise_for_status(resp)
+        data = resp.json()
+        return DeleteResult(deleted=data["deleted"], message=data["message"])
+
+    # ── Wipe all ───────────────────────────────────────────────────
+
+    def forget_all(
+        self,
+        user_id:  str,
+        agent_id: str,
+    ) -> DeleteResult:
+        """
+        Wipe all memories for a user+agent pair.
+        Use for GDPR requests or account resets.
+
+        Args:
+            user_id:  Identifier for the end user.
+            agent_id: Identifier for the agent.
+        """
+        resp = self._client.delete(
+            f"{self.base_url}/memories",
+            params={
+                "user_id":  user_id,
+                "agent_id": agent_id,
+                "confirm":  True,
+            },
+        )
+        self._raise_for_status(resp)
+        data = resp.json()
+        return DeleteResult(deleted=data["deleted"], message=data["message"])
+
+    # ── Helpers ────────────────────────────────────────────────────
+
+    def _raise_for_status(self, resp: httpx.Response) -> None:
+        if resp.status_code < 400:
+            return
+        try:
+            detail = resp.json().get("detail", resp.text)
+        except Exception:
+            detail = resp.text
+
+        if resp.status_code == 401:
+            raise AuthenticationError(resp.status_code, detail)
+        if resp.status_code == 402:
+            raise PlanLimitError(resp.status_code, detail)
+        if resp.status_code == 404:
+            raise MemoryNotFoundError(resp.status_code, detail)
+        if resp.status_code == 409:
+            raise DuplicateMemoryError(resp.status_code, detail)
+        raise MemLayerError(resp.status_code, detail)
+
+    def close(self):
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+
+# ── Async Client ──────────────────────────────────────────────────
+
+class AsyncMemLayerClient:
+    """
+    Async MemLayer client for use with asyncio, LangGraph, and FastAPI.
+
+    Example:
+        async with AsyncMemLayerClient(api_key="ml_live_xxx") as client:
+            mem_id = await client.remember("user likes dark mode", user_id="u1", agent_id="bot")
+            memories = await client.recall("UI preferences", user_id="u1", agent_id="bot")
+    """
+
+    def __init__(
+        self,
+        api_key:  str,
+        base_url: str = "https://memlayer.online",
+        timeout:  float = 30.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self._headers = {
+            "X-API-Key":    api_key,
+            "Content-Type": "application/json",
+        }
+        self._timeout = timeout
+
+    def _get_client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(headers=self._headers, timeout=self._timeout)
+
+    async def remember(
+        self,
+        content:     str,
+        user_id:     str,
+        agent_id:    str,
+        memory_type: str = "episodic",
+        metadata:    Optional[dict] = None,
+        importance:  float = 0.5,
+        ttl_days:    Optional[int] = None,
+    ) -> StoreResult:
+        """Store a memory. Returns StoreResult with memory ID."""
+        async with self._get_client() as client:
+            resp = await client.post(
+                f"{self.base_url}/memories",
+                json={
+                    "content":     content,
+                    "user_id":     user_id,
+                    "agent_id":    agent_id,
+                    "memory_type": memory_type,
+                    "metadata":    metadata or {},
+                    "importance":  importance,
+                    "ttl_days":    ttl_days,
+                },
+            )
+            self._raise_for_status(resp)
+            data = resp.json()
+            return StoreResult(id=data["id"], message=data.get("message", ""))
+
+    async def recall(
+        self,
+        query:       str,
+        user_id:     str,
+        agent_id:    str,
+        top_k:       int = 5,
+        min_score:   float = 0.70,
+        memory_type: Optional[str] = None,
+    ) -> list[Memory]:
+        """Semantic search — returns top-k memories by hybrid score."""
+        params: dict[str, Any] = {
+            "query":     query,
+            "user_id":   user_id,
+            "agent_id":  agent_id,
+            "top_k":     top_k,
+            "min_score": min_score,
+        }
+        if memory_type:
+            params["memory_type"] = memory_type
+
+        async with self._get_client() as client:
+            resp = await client.get(
+                f"{self.base_url}/memories/search",
+                params=params,
+            )
+            self._raise_for_status(resp)
+            return [Memory.from_dict(m) for m in resp.json()["memories"]]
+
+    async def context(
+        self,
+        user_id:         str,
+        agent_id:        str,
+        top_k:           int = 10,
+        current_message: Optional[str] = None,
+    ) -> ContextResult:
+        """Load memories at session start."""
+        params: dict[str, Any] = {
+            "user_id":  user_id,
+            "agent_id": agent_id,
+            "top_k":    top_k,
+        }
+        if current_message:
+            params["current_message"] = current_message
+
+        async with self._get_client() as client:
+            resp = await client.get(
+                f"{self.base_url}/memories/context",
+                params=params,
+            )
+            self._raise_for_status(resp)
+            data = resp.json()
+            return ContextResult(
+                memories=[Memory.from_dict(m) for m in data["memories"]],
+                total=data["total"],
+                limit=data["limit"],
+                offset=data["offset"],
+            )
+
+    async def update(
+        self,
+        memory_id:   str,
+        user_id:     str,
+        agent_id:    str,
+        new_content: str,
+        importance:  Optional[float] = None,
+        metadata:    Optional[dict] = None,
+    ) -> Memory:
+        """Update an existing memory with new content."""
+        body: dict[str, Any] = {
+            "user_id":     user_id,
+            "agent_id":    agent_id,
+            "new_content": new_content,
+        }
+        if importance is not None:
+            body["importance"] = importance
+        if metadata is not None:
+            body["metadata"] = metadata
+
+        async with self._get_client() as client:
+            resp = await client.patch(
+                f"{self.base_url}/memories/{memory_id}",
+                json=body,
+            )
+            self._raise_for_status(resp)
+            return Memory.from_dict(resp.json())
+
+    async def forget(
+        self,
+        memory_id: str,
+        user_id:   str,
+        agent_id:  str,
+    ) -> DeleteResult:
+        """Delete a single memory by ID."""
+        async with self._get_client() as client:
+            resp = await client.delete(
+                f"{self.base_url}/memories/{memory_id}",
+                params={"user_id": user_id, "agent_id": agent_id},
+            )
+            self._raise_for_status(resp)
+            data = resp.json()
+            return DeleteResult(deleted=data["deleted"], message=data["message"])
+
+    async def forget_all(
+        self,
+        user_id:  str,
+        agent_id: str,
+    ) -> DeleteResult:
+        """Wipe all memories for a user+agent pair."""
+        async with self._get_client() as client:
+            resp = await client.delete(
+                f"{self.base_url}/memories",
+                params={
+                    "user_id":  user_id,
+                    "agent_id": agent_id,
+                    "confirm":  True,
+                },
+            )
+            self._raise_for_status(resp)
+            data = resp.json()
+            return DeleteResult(deleted=data["deleted"], message=data["message"])
+
+    async def is_duplicate(
+        self,
+        content:   str,
+        user_id:   str,
+        agent_id:  str,
+        threshold: float = 0.95,
+    ) -> bool:
+        """Check if a memory already exists before storing."""
+        async with self._get_client() as client:
+            resp = await client.post(
+                f"{self.base_url}/memories/duplicate-check",
+                params={
+                    "content":   content,
+                    "user_id":   user_id,
+                    "agent_id":  agent_id,
+                    "threshold": threshold,
+                },
+            )
+            self._raise_for_status(resp)
+            return resp.json()["is_duplicate"]
+
+    def _raise_for_status(self, resp: httpx.Response) -> None:
+        if resp.status_code < 400:
+            return
+        try:
+            detail = resp.json().get("detail", resp.text)
+        except Exception:
+            detail = resp.text
+
+        if resp.status_code == 401:
+            raise AuthenticationError(resp.status_code, detail)
+        if resp.status_code == 402:
+            raise PlanLimitError(resp.status_code, detail)
+        if resp.status_code == 404:
+            raise MemoryNotFoundError(resp.status_code, detail)
+        if resp.status_code == 409:
+            raise DuplicateMemoryError(resp.status_code, detail)
+        raise MemLayerError(resp.status_code, detail)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        pass

memlayer_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,430 @@
+Metadata-Version: 2.4
+Name: memlayer-py
+Version: 0.1.0
+Summary: Persistent memory for AI agents — one API key, your agent remembers everything.
+Home-page: https://github.com/yourusername/memlayer
+Author: Victor Sunday
+Author-email: sunvictor567@gmail.com
+License: MIT
+Project-URL: Documentation, https://memlayer.online/docs
+Project-URL: Bug Tracker, https://github.com/yourusername/memlayer/issues
+Project-URL: Homepage, https://memlayer.online
+Keywords: ai agent memory vector search langchain langgraph memlayer persistent memory
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Intended Audience :: Developers
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# memlayer-py
+
+> Persistent memory for AI agents. One API key. Your agent remembers everything.
+
+[![PyPI version](https://badge.fury.io/py/memlayer-py.svg)](https://badge.fury.io/py/memlayer-py)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## The Problem
+
+Every time a user starts a new conversation with your AI agent, it starts from zero. It doesn't remember their name, their preferences, what they complained about last week, or anything they've ever told it. You're either stuffing conversation history into the system prompt and hitting token limits, or your agent is asking the same questions over and over.
+
+**MemLayer fixes that.**
+
+---
+
+## Install
+
+```bash
+pip install memlayer-py
+```
+
+---
+
+## Quick Start
+
+```python
+from memlayer import MemLayerClient
+
+client = MemLayerClient(
+    api_key="ml_live_xxx",
+    base_url="https://memlayer.online",
+)
+
+# Store what your agent learns
+client.remember(
+    "User prefers concise bullet points over long paragraphs",
+    user_id="user_123",
+    agent_id="support_bot",
+    memory_type="semantic",
+    importance=0.8,
+)
+
+# Load context at the start of every session
+context = client.context(user_id="user_123", agent_id="support_bot")
+for m in context.memories:
+    print(m.content)
+
+# Search when the user asks something
+memories = client.recall(
+    "what are this user's communication preferences?",
+    user_id="user_123",
+    agent_id="support_bot",
+)
+for m in memories:
+    print(f"[{m.score:.3f}] {m.content}")
+```
+
+---
+
+## Get an API Key
+
+1. Visit [memlayer.online](https://memlayer.online)
+2. Sign up for a free account
+3. Copy your API key (`ml_live_xxx`)
+
+Free plan includes 500 memories and 100 requests per day — enough to build and test your agent fully.
+
+---
+
+## Core Methods
+
+### `remember()` — Store a memory
+
+```python
+result = client.remember(
+    content="User is based in Lagos, Nigeria",
+    user_id="user_123",
+    agent_id="support_bot",
+    memory_type="semantic",   # episodic | semantic | summary
+    importance=0.8,           # 0.0 (low) to 1.0 (high)
+    ttl_days=30,              # auto-expire after 30 days. None = permanent
+)
+
+print(result.id)             # memory UUID
+print(result.is_duplicate)   # True if already stored
+```
+
+### `recall()` — Semantic search
+
+```python
+memories = client.recall(
+    query="what does this user prefer?",
+    user_id="user_123",
+    agent_id="support_bot",
+    top_k=5,        # return top 5 results
+    min_score=0.70, # minimum relevance threshold
+)
+
+for m in memories:
+    print(m.content)      # memory text
+    print(m.score)        # hybrid relevance score
+    print(m.importance)   # importance weight
+    print(m.memory_type)  # episodic | semantic | summary
+```
+
+Retrieval uses hybrid scoring — **70% semantic similarity + 20% recency + 10% importance** — so the most relevant and recent memories always rank first.
+
+### `context()` — Load session context
+
+```python
+# Call this at the start of every conversation
+context = client.context(
+    user_id="user_123",
+    agent_id="support_bot",
+    top_k=10,
+
+    # Optional: pass the user's first message for smarter retrieval
+    current_message="I need help with my order",
+)
+
+# Inject into your system prompt
+system_prompt = "You are a helpful assistant.\n\nWhat you know about this user:\n"
+for m in context.memories:
+    system_prompt += f"- {m.content}\n"
+```
+
+### `update()` — Update a memory
+
+```python
+# User moved cities — update the old memory in place
+updated = client.update(
+    memory_id="775263ee-73af-4416-9804-1f274048ae08",
+    user_id="user_123",
+    agent_id="support_bot",
+    new_content="User moved from Lagos to Abuja, Nigeria",
+    importance=0.95,
+)
+
+print(updated.content)  # "User moved from Lagos to Abuja, Nigeria"
+```
+
+Same memory ID — just new content and a fresh embedding. No duplicate memories.
+
+### `forget()` — Delete one memory
+
+```python
+result = client.forget(
+    memory_id="775263ee-73af-4416-9804-1f274048ae08",
+    user_id="user_123",
+    agent_id="support_bot",
+)
+print(result.deleted)  # 1
+```
+
+### `forget_all()` — Wipe all memories
+
+```python
+# Use for GDPR requests or account resets
+result = client.forget_all(user_id="user_123", agent_id="support_bot")
+print(result.deleted)  # number of memories deleted
+```
+
+### `is_duplicate()` — Check before storing
+
+```python
+# Optional — remember() already checks internally
+# Use this when you want to check without committing to store
+already_known = client.is_duplicate(
+    content="User is based in Lagos",
+    user_id="user_123",
+    agent_id="support_bot",
+    threshold=0.95,
+)
+
+if not already_known:
+    client.remember("User is based in Lagos", user_id="user_123", agent_id="support_bot")
+```
+
+### `list()` — Browse all memories
+
+```python
+# Paginate through all stored memories
+page = client.list(
+    user_id="user_123",
+    agent_id="support_bot",
+    limit=20,
+    offset=0,
+)
+
+print(f"Total: {page.total}")
+for m in page.memories:
+    print(m.content, m.created_at)
+```
+
+---
+
+## Memory Types
+
+| Type | Use For | Example |
+|---|---|---|
+| `episodic` | Things that happened | "User complained about slow delivery" |
+| `semantic` | Facts about the user | "User is based in Lagos, Nigeria" |
+| `summary` | Compressed older memories | Auto-generated by MemLayer |
+
+---
+
+## Async Support
+
+For LangGraph, FastAPI, and any async application:
+
+```python
+from memlayer import AsyncMemLayerClient
+
+async def main():
+    async with AsyncMemLayerClient(api_key="ml_live_xxx") as client:
+
+        # Store
+        result = await client.remember(
+            "User prefers dark mode",
+            user_id="user_123",
+            agent_id="support_bot",
+        )
+
+        # Search
+        memories = await client.recall(
+            "UI preferences",
+            user_id="user_123",
+            agent_id="support_bot",
+        )
+```
+
+---
+
+## LangGraph Integration
+
+Drop MemLayer into any LangGraph graph as store and retrieve nodes:
+
+```python
+from memlayer import AsyncMemLayerClient
+from langgraph.graph import StateGraph, MessagesState
+
+maas = AsyncMemLayerClient(api_key="ml_live_xxx")
+
+
+async def load_memory(state: MessagesState):
+    """Load relevant memories before the agent responds."""
+    last_message = state["messages"][-1].content
+
+    memories = await maas.recall(
+        query=last_message,
+        user_id=state["user_id"],
+        agent_id="my_agent",
+        top_k=5,
+    )
+
+    memory_context = "\n".join(f"- {m.content}" for m in memories)
+    state["memory_context"] = memory_context
+    return state
+
+
+async def save_memory(state: MessagesState):
+    """Save what the agent learned after responding."""
+    last_message = state["messages"][-1].content
+
+    await maas.remember(
+        content=last_message,
+        user_id=state["user_id"],
+        agent_id="my_agent",
+        memory_type="episodic",
+    )
+    return state
+
+
+# Wire into your graph
+builder = StateGraph(MessagesState)
+builder.add_node("load_memory", load_memory)
+builder.add_node("agent", your_agent_node)
+builder.add_node("save_memory", save_memory)
+
+builder.add_edge("load_memory", "agent")
+builder.add_edge("agent", "save_memory")
+```
+
+---
+
+## Error Handling
+
+```python
+from memlayer import (
+    MemLayerClient,
+    AuthenticationError,
+    PlanLimitError,
+    MemoryNotFoundError,
+    DuplicateMemoryError,
+    MemLayerError,
+)
+
+client = MemLayerClient(api_key="ml_live_xxx")
+
+try:
+    result = client.remember(
+        "User prefers dark mode",
+        user_id="user_123",
+        agent_id="support_bot",
+    )
+
+except AuthenticationError:
+    print("Invalid API key — check your ml_live_xxx key")
+
+except PlanLimitError:
+    print("Memory limit reached — upgrade your plan at memlayer.online")
+
+except DuplicateMemoryError:
+    print("This memory already exists — skipped")
+
+except MemoryNotFoundError:
+    print("Memory ID not found")
+
+except MemLayerError as e:
+    print(f"API error {e.status_code}: {e.detail}")
+```
+
+---
+
+## Context Manager
+
+```python
+# Sync
+with MemLayerClient(api_key="ml_live_xxx") as client:
+    client.remember("something", user_id="u1", agent_id="bot")
+
+# Async
+async with AsyncMemLayerClient(api_key="ml_live_xxx") as client:
+    await client.remember("something", user_id="u1", agent_id="bot")
+```
+
+---
+
+## Pricing
+
+| Plan | Memories | Requests/day | Price |
+|---|---|---|---|
+| Free | 500 | 100 | $0/mo |
+| Pro | 50,000 | 10,000 | $19/mo |
+| Enterprise | Unlimited | Unlimited | $99+/mo |
+
+Enterprise includes BYOD (Bring Your Own Database) — your data never leaves your Supabase instance.
+
+---
+
+## REST API
+
+You don't need the SDK — every method maps to a REST endpoint:
+
+```bash
+# Store
+curl -X POST https://memlayer.online/memories \
+  -H "X-API-Key: ml_live_xxx" \
+  -H "Content-Type: application/json" \
+  -d '{"content": "User prefers dark mode", "user_id": "u1", "agent_id": "bot"}'
+
+# Search
+curl "https://memlayer.online/memories/search?query=preferences&user_id=u1&agent_id=bot" \
+  -H "X-API-Key: ml_live_xxx"
+
+# Context
+curl "https://memlayer.online/memories/context?user_id=u1&agent_id=bot" \
+  -H "X-API-Key: ml_live_xxx"
+```
+
+Full API reference at [memlayer.online/docs](https://memlayer.online/docs).
+
+---
+
+## Links
+
+- [Website](https://memlayer.online)
+- [API Docs](https://memlayer.online/docs)
+- [GitHub](https://github.com/yourusername/memlayer)
+- [Report a Bug](https://github.com/yourusername/memlayer/issues)
+- [Email](mailto:support@memlayer.online)
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

memlayer_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+memlayer/__init__.py,sha256=tyPl6AimPv8i3mf1Ma9HnFflmIqM6f1FP7SVoQBvE3Y,575
+memlayer/client.py,sha256=WW-f7Yk8OT_tXfbXYijpI4ZEzf4TaqNRcjZ4CdRleMw,23943
+memlayer_py-0.1.0.dist-info/licenses/LICENSE,sha256=B_XNTK2p3yc-FWqtdXjStFoudGNhLxXWrsW9CCiOKTU,1089
+memlayer_py-0.1.0.dist-info/METADATA,sha256=obQTKiimaxEQ67ilcXasLxHwSpfU-TjS08dP25k2Wqk,11535
+memlayer_py-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+memlayer_py-0.1.0.dist-info/top_level.txt,sha256=ET9kj1uGmnujtUVF0pEqmE4SgJgK25s3o7e8czqmPOU,9
+memlayer_py-0.1.0.dist-info/RECORD,,

memlayer_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
+

memlayer_py-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor Sunday
+
+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.

memlayer_py-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+memlayer