memwal 0.1.0.dev1__tar.gz → 0.1.0.dev3__tar.gz

{memwal-0.1.0.dev1 → memwal-0.1.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memwal
-Version: 0.1.0.dev1
+Version: 0.1.0.dev3
 Summary: Python SDK for MemWal — Privacy-first AI memory with Ed25519 signing
 Project-URL: Homepage, https://memwal.ai
 Project-URL: Documentation, https://docs.memwal.ai
@@ -130,6 +130,32 @@ async with MemWal.create(
     await memwal.remember("I prefer dark mode")
 ```
 
+## Environment Presets
+
+Instead of hardcoding a relayer URL, pass `env` to target a hosted relayer.
+Same shorthand as the TypeScript SDK and MCP package.
+
+```python
+from memwal import MemWal
+
+memwal = MemWal.create(
+    key=os.environ["MEMWAL_KEY"],
+    account_id=os.environ["MEMWAL_ACCOUNT_ID"],
+    env="prod",   # prod | dev | staging | local
+)
+```
+
+| `env` | Relayer URL |
+|-------|-------------|
+| `prod` | `https://relayer.memwal.ai` |
+| `dev` | `https://relayer.dev.memwal.ai` |
+| `staging` | `https://relayer.staging.memwal.ai` |
+| `local` | `http://127.0.0.1:8000` |
+
+Precedence: an explicit non-default **`server_url` wins over `env`**, which wins
+over the default. An unknown preset raises `ValueError`. `env` is also accepted
+by `MemWalSync.create`, `with_memwal_langchain`, and `with_memwal_openai`.
+
 ## AI Middleware
 
 ### LangChain
@@ -201,10 +227,10 @@ Create a new async client.
 Every request is signed with Ed25519:
 
 ```
-message = f"{timestamp}.{method}.{path}.{sha256(body)}.{nonce}.{account_id}"
+message = f"{timestamp}.{method}.{path}.{sha256(body)}"
 ```
 
-Headers sent: `x-public-key`, `x-signature`, `x-timestamp`, `x-nonce`, `x-delegate-key`, `x-account-id`.
+Headers sent: `x-public-key`, `x-signature`, `x-timestamp`, `x-delegate-key`, `x-account-id`.
 
 ## License
 

{memwal-0.1.0.dev1 → memwal-0.1.0.dev3}/README.md

@@ -91,6 +91,32 @@ async with MemWal.create(
     await memwal.remember("I prefer dark mode")
 ```
 
+## Environment Presets
+
+Instead of hardcoding a relayer URL, pass `env` to target a hosted relayer.
+Same shorthand as the TypeScript SDK and MCP package.
+
+```python
+from memwal import MemWal
+
+memwal = MemWal.create(
+    key=os.environ["MEMWAL_KEY"],
+    account_id=os.environ["MEMWAL_ACCOUNT_ID"],
+    env="prod",   # prod | dev | staging | local
+)
+```
+
+| `env` | Relayer URL |
+|-------|-------------|
+| `prod` | `https://relayer.memwal.ai` |
+| `dev` | `https://relayer.dev.memwal.ai` |
+| `staging` | `https://relayer.staging.memwal.ai` |
+| `local` | `http://127.0.0.1:8000` |
+
+Precedence: an explicit non-default **`server_url` wins over `env`**, which wins
+over the default. An unknown preset raises `ValueError`. `env` is also accepted
+by `MemWalSync.create`, `with_memwal_langchain`, and `with_memwal_openai`.
+
 ## AI Middleware
 
 ### LangChain
@@ -162,10 +188,10 @@ Create a new async client.
 Every request is signed with Ed25519:
 
 ```
-message = f"{timestamp}.{method}.{path}.{sha256(body)}.{nonce}.{account_id}"
+message = f"{timestamp}.{method}.{path}.{sha256(body)}"
 ```
 
-Headers sent: `x-public-key`, `x-signature`, `x-timestamp`, `x-nonce`, `x-delegate-key`, `x-account-id`.
+Headers sent: `x-public-key`, `x-signature`, `x-timestamp`, `x-delegate-key`, `x-account-id`.
 
 ## License
 

{memwal-0.1.0.dev1 → memwal-0.1.0.dev3}/examples/async_remember_demo.py

@@ -25,6 +25,7 @@ import os
 import sys
 import time
 from pathlib import Path
+from typing import Optional
 
 
 def _load_env() -> None:
@@ -49,6 +50,7 @@ sys.path.insert(0, str(Path(__file__).parent.parent))
 
 from memwal import (  # noqa: E402
     MemWal,
+    MemWalRememberJobFailed,
     RememberBulkItem,
     RememberBulkOptions,
 )

{memwal-0.1.0.dev1 → memwal-0.1.0.dev3}/memwal/__init__.py

@@ -33,6 +33,7 @@ from .client import (
 from .middleware import with_memwal_langchain, with_memwal_openai
 from .utils import delegate_key_to_sui_address, delegate_key_to_public_key
 from .types import (
+    ENV_PRESETS,
     AnalyzedFact,
     AnalyzeResult,
     AnalyzeWaitResult,
@@ -81,6 +82,7 @@ __all__ = [
     "withMemWal",
     # Types
     "MemWalConfig",
+    "ENV_PRESETS",
     "AskMemory",
     "AskResult",
     "RememberResult",
@@ -108,4 +110,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.1.0.dev1"
+__version__ = "0.1.0.dev3"

{memwal-0.1.0.dev1 → memwal-0.1.0.dev3}/memwal/client.py

@@ -26,12 +26,14 @@ Example::
 from __future__ import annotations
 
 import asyncio
+import base64
 import json
 import random
 import time
-from typing import Any, Dict, List, Optional, Sequence, TypeVar
+from typing import Any, Dict, List, Optional, Sequence, Tuple, TypeVar
 
 import httpx
+import nacl.signing
 
 from .types import (
     AnalyzedFact,
@@ -55,20 +57,27 @@ from .types import (
     RememberBulkResult,
     RememberBulkStatusItem,
     RememberBulkStatusResult,
+    RememberJobStatus,
     RememberManualOptions,
     RememberManualResult,
     RememberResult,
     RestoreResult,
 )
 from .utils import (
+    build_seal_session_personal_message,
     build_signature_message,
     build_signing_key,
     bytes_to_hex,
+    delegate_key_to_sui_address,
+    encode_sui_private_key,
     sha256_hex,
     sign_message,
+    sign_sui_personal_message,
 )
 
 T = TypeVar("T")
+SEAL_SESSION_TTL_MIN = 5
+SEAL_SESSION_SAFETY_MARGIN_MS = 30_000
 
 
 # ============================================================
@@ -122,22 +131,30 @@ class MemWal:
         self._server_url = config.server_url.rstrip("/")
         self._namespace = config.namespace
         self._client: Optional[httpx.AsyncClient] = None
+        self._server_config: Optional[Dict[str, str]] = None
+        self._session_cache: Optional[Tuple[str, int]] = None
+        self._session_build_task: Optional[asyncio.Task[str]] = None
 
     @classmethod
     def create(
         cls,
         key: str,
         account_id: str,
-        server_url: str = "https://relayer.memwal.ai",
+        server_url: str = "http://localhost:8000",
         namespace: str = "default",
+        env: Optional[str] = None,
     ) -> "MemWal":
         """Create a new MemWal client instance.
 
         Args:
             key: Ed25519 private key hex string (the delegate key).
             account_id: MemWalAccount object ID on Sui.
-            server_url: Server URL (default: ``https://relayer.memwal.ai``).
+            server_url: Server URL (default: ``http://localhost:8000``).
             namespace: Default namespace for memory isolation (default: ``"default"``).
+            env: Optional relayer preset — ``"prod"``, ``"dev"``, ``"staging"``,
+                or ``"local"``. Resolves ``server_url`` to the matching hosted
+                relayer unless an explicit non-default ``server_url`` is given.
+                Precedence: explicit ``server_url`` > ``env`` > default.
 
         Returns:
             A configured :class:`MemWal` instance.
@@ -147,6 +164,7 @@ class MemWal:
             account_id=account_id,
             server_url=server_url,
             namespace=namespace,
+            env=env,
         )
         return cls(config)
 
@@ -652,11 +670,16 @@ class MemWal:
         Returns:
             :class:`RememberManualResult` with id, blob_id, owner, namespace.
         """
-        data = await self._signed_request("POST", "/api/remember/manual", {
-            "blob_id": opts.blob_id,
-            "vector": opts.vector,
-            "namespace": opts.namespace or self._namespace,
-        })
+        data = await self._signed_request(
+            "POST",
+            "/api/remember/manual",
+            {
+                "blob_id": opts.blob_id,
+                "vector": opts.vector,
+                "namespace": opts.namespace or self._namespace,
+            },
+            include_seal_session=False,
+        )
         return RememberManualResult(
             id=data["id"],
             blob_id=data["blob_id"],
@@ -676,11 +699,16 @@ class MemWal:
         Returns:
             :class:`RecallManualResult` with blob_id + distance pairs.
         """
-        data = await self._signed_request("POST", "/api/recall/manual", {
-            "vector": opts.vector,
-            "limit": opts.limit,
-            "namespace": opts.namespace or self._namespace,
-        })
+        data = await self._signed_request(
+            "POST",
+            "/api/recall/manual",
+            {
+                "vector": opts.vector,
+                "limit": opts.limit,
+                "namespace": opts.namespace or self._namespace,
+            },
+            include_seal_session=False,
+        )
         hits = [
             RecallManualHit(blob_id=h["blob_id"], distance=h["distance"])
             for h in data.get("results", [])
@@ -699,31 +727,141 @@ class MemWal:
     # Internal: Signed HTTP Requests
     # ============================================================
 
+    async def _fetch_server_config(self) -> Dict[str, str]:
+        if self._server_config is not None:
+            return self._server_config
+
+        response = await self._http.get(f"{self._server_url}/config")
+        if response.status_code != 200:
+            raise MemWalError(f"GET /config returned {response.status_code}")
+
+        data = response.json()
+        package_id = data.get("packageId")
+        network = data.get("network")
+        sui_rpc_url = data.get("suiRpcUrl")
+        if not package_id or not network or not sui_rpc_url:
+            raise MemWalError("GET /config response missing packageId / network / suiRpcUrl")
+
+        self._server_config = {
+            "packageId": package_id,
+            "network": network,
+            "suiRpcUrl": sui_rpc_url,
+        }
+        return self._server_config
+
+    async def _assert_first_package_version(self, sui_rpc_url: str, package_id: str) -> None:
+        response = await self._http.post(
+            sui_rpc_url,
+            json={
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "sui_getObject",
+                "params": [package_id, {"showBcs": False, "showContent": False, "showType": False}],
+            },
+        )
+        if response.status_code != 200:
+            raise MemWalError(f"sui_getObject returned {response.status_code}")
+
+        body = response.json()
+        result = body.get("result", {})
+        version = None
+        if isinstance(result, dict):
+            data = result.get("data")
+            if isinstance(data, dict):
+                version = data.get("version")
+            if version is None:
+                obj = result.get("object")
+                if isinstance(obj, dict):
+                    version = obj.get("version")
+        if str(version) != "1":
+            raise MemWalError(
+                f"SEAL package {package_id} must be at version 1 to build x-seal-session, got {version!r}"
+            )
+
+    async def _build_seal_session_inner(self) -> str:
+        cfg = await self._fetch_server_config()
+        await self._assert_first_package_version(cfg["suiRpcUrl"], cfg["packageId"])
+
+        session_signing_key = nacl.signing.SigningKey.generate()
+        session_public_key = bytes(session_signing_key.verify_key)
+        creation_time_ms = int(time.time() * 1000)
+        personal_message = build_seal_session_personal_message(
+            package_id=cfg["packageId"],
+            ttl_min=SEAL_SESSION_TTL_MIN,
+            creation_time_ms=creation_time_ms,
+            session_public_key_bytes=session_public_key,
+        )
+        personal_message_signature = sign_sui_personal_message(
+            personal_message,
+            self._signing_key,
+        )
+
+        json_str = json.dumps(
+            {
+                "address": delegate_key_to_sui_address(self._private_key_hex),
+                "packageId": cfg["packageId"],
+                "mvrName": None,
+                "creationTimeMs": creation_time_ms,
+                "ttlMin": SEAL_SESSION_TTL_MIN,
+                "personalMessageSignature": personal_message_signature,
+                "sessionKey": encode_sui_private_key(bytes(session_signing_key)),
+            },
+            separators=(",", ":"),
+        )
+        session_bytes = base64.b64encode(json_str.encode("utf-8")).decode("utf-8")
+        self._session_cache = (
+            session_bytes,
+            int(time.time() * 1000) + SEAL_SESSION_TTL_MIN * 60_000 - SEAL_SESSION_SAFETY_MARGIN_MS,
+        )
+        return session_bytes
+
+    async def _build_seal_session(self) -> str:
+        now_ms = int(time.time() * 1000)
+        if self._session_cache is not None:
+            cached_bytes, expires_at_ms = self._session_cache
+            if now_ms < expires_at_ms:
+                return cached_bytes
+
+        if self._session_build_task is not None:
+            return await self._session_build_task
+
+        self._session_build_task = asyncio.create_task(self._build_seal_session_inner())
+        try:
+            return await self._session_build_task
+        finally:
+            self._session_build_task = None
+
     async def _signed_request(
         self,
         method: str,
         path: str,
         body: Dict[str, Any],
         accepted_statuses: tuple = (200,),
+        include_seal_session: bool = True,
     ) -> Dict[str, Any]:
         """Make a signed request to the server.
 
         Signature format:
             ``{timestamp}.{method}.{path}.{body_sha256}.{nonce}.{account_id}``
 
+        For ``GET`` requests the canonical body string is the empty string,
+        and no HTTP request body is sent. This keeps the signed payload hash
+        byte-compatible with the TypeScript SDK and with intermediaries that
+        strip ``GET`` bodies on the wire.
+
         Headers sent:
             - ``x-public-key``: Ed25519 public key hex
             - ``x-signature``: Ed25519 signature hex
             - ``x-timestamp``: Unix seconds string
-            - ``x-nonce``: UUID v4 replay-protection nonce
-            - ``x-delegate-key``: Private key hex
+            - ``x-seal-session``: Base64-encoded exported session envelope
             - ``x-account-id``: MemWalAccount object ID
             - ``Content-Type``: application/json
         """
         import uuid
 
+        method_upper = method.upper()
         timestamp = str(int(time.time()))
-        body_str = json.dumps(body, separators=(",", ":"))
+        body_str = "" if method_upper == "GET" else json.dumps(body, separators=(",", ":"))
         body_hash = sha256_hex(body_str)
         # MED-1 / LOW-23: nonce + account_id are part of the canonical signed
         # message. Server rejects the request as "unsupported legacy SDK"
@@ -732,7 +870,7 @@ class MemWal:
 
         message = build_signature_message(
             timestamp,
-            method.upper(),
+            method_upper,
             path,
             body_hash,
             nonce=nonce,
@@ -747,15 +885,16 @@ class MemWal:
             "x-signature": signature_hex,
             "x-timestamp": timestamp,
             "x-nonce": nonce,
-            "x-delegate-key": self._private_key_hex,
             "x-account-id": self._account_id,
         }
+        if include_seal_session:
+            headers["x-seal-session"] = await self._build_seal_session()
 
         response = await self._http.request(
-            method=method.upper(),
+            method=method_upper,
             url=url,
             headers=headers,
-            content=body_str,
+            content=None if method_upper == "GET" else body_str,
         )
 
         if response.status_code not in accepted_statuses:
@@ -842,22 +981,27 @@ class MemWalSync:
         cls,
         key: str,
         account_id: str,
-        server_url: str = "https://relayer.memwal.ai",
+        server_url: str = "http://localhost:8000",
         namespace: str = "default",
+        env: Optional[str] = None,
     ) -> "MemWalSync":
         """Create a synchronous MemWal client.
 
-        Same parameters as :meth:`MemWal.create`.
+        Same parameters as :meth:`MemWal.create` (including the ``env``
+        relayer preset).
         """
         inner = MemWal.create(
             key=key,
             account_id=account_id,
             server_url=server_url,
             namespace=namespace,
+            env=env,
         )
         return cls(inner)
 
     def _run(self, coro: Any) -> Any:
+        import asyncio
+
         try:
             loop = asyncio.get_running_loop()
         except RuntimeError:

{memwal-0.1.0.dev1 → memwal-0.1.0.dev3}/memwal/middleware.py

@@ -137,12 +137,13 @@ def with_memwal_langchain(
     llm: "BaseChatModel",
     key: str,
     account_id: str,
-    server_url: str = "https://relayer.memwal.ai",
+    server_url: str = "http://localhost:8000",
     namespace: str = "default",
     max_memories: int = 5,
     auto_save: bool = True,
     min_relevance: float = 0.3,
     debug: bool = False,
+    env: Optional[str] = None,
 ) -> "BaseChatModel":
     """Wrap a LangChain ``BaseChatModel`` with MemWal memory management.
 
@@ -163,6 +164,8 @@ def with_memwal_langchain(
         auto_save: Auto-save new facts from conversation.
         min_relevance: Minimum similarity score (0-1) to include a memory.
         debug: Enable debug logging.
+        env: Optional relayer preset (``"prod"`` / ``"dev"`` / ``"staging"`` /
+            ``"local"``). Same precedence as :meth:`MemWal.create`.
 
     Returns:
         A wrapped ``BaseChatModel`` that automatically uses MemWal memory.
@@ -181,6 +184,7 @@ def with_memwal_langchain(
         account_id=account_id,
         server_url=server_url,
         namespace=namespace,
+        env=env,
     )
 
     log = logger.debug if not debug else logger.warning
@@ -254,6 +258,8 @@ def with_memwal_langchain(
         messages: List[List[BaseMessage]], *args: Any, **kwargs: Any
     ) -> ChatResult:
         # For sync generate, we inject memories synchronously via asyncio.run
+        import asyncio
+
         enriched = []
         for msg_list in messages:
             try:
@@ -290,12 +296,13 @@ def with_memwal_openai(
     client: Any,
     key: str,
     account_id: str,
-    server_url: str = "https://relayer.memwal.ai",
+    server_url: str = "http://localhost:8000",
     namespace: str = "default",
     max_memories: int = 5,
     auto_save: bool = True,
     min_relevance: float = 0.3,
     debug: bool = False,
+    env: Optional[str] = None,
 ) -> Any:
     """Wrap an OpenAI client with MemWal memory management.
 
@@ -318,6 +325,8 @@ def with_memwal_openai(
         auto_save: Auto-save new facts from conversation.
         min_relevance: Minimum similarity score (0-1) to include a memory.
         debug: Enable debug logging.
+        env: Optional relayer preset (``"prod"`` / ``"dev"`` / ``"staging"`` /
+            ``"local"``). Same precedence as :meth:`MemWal.create`.
 
     Returns:
         The same client, with ``chat.completions.create`` wrapped to use MemWal.
@@ -327,6 +336,7 @@ def with_memwal_openai(
         account_id=account_id,
         server_url=server_url,
         namespace=namespace,
+        env=env,
     )
 
     log = logger.debug if not debug else logger.warning
@@ -408,6 +418,8 @@ def _wrap_sync_openai(
     original_create = client.chat.completions.create
 
     def patched_create(*args: Any, **kwargs: Any) -> Any:
+        import asyncio
+
         messages = kwargs.get("messages") or (args[0] if args else None)
         if messages is None:
             return original_create(*args, **kwargs)

{memwal-0.1.0.dev1 → memwal-0.1.0.dev3}/memwal/types.py

@@ -15,6 +15,21 @@ from typing import List, Optional
 # Config
 # ============================================================
 
+#: Default ``server_url`` when neither an explicit URL nor an ``env`` preset
+#: is supplied. Kept as a module constant so ``__post_init__`` can tell an
+#: untouched default apart from an explicitly-passed custom URL.
+DEFAULT_SERVER_URL = "http://localhost:8000"
+
+#: Named relayer environments. Mirrors the TypeScript SDK / MCP package
+#: ``--prod`` / ``--dev`` / ``--staging`` / ``--local`` presets so the same
+#: shorthand works across every MemWal client.
+ENV_PRESETS = {
+    "prod": "https://relayer.memwal.ai",
+    "dev": "https://relayer.dev.memwal.ai",
+    "staging": "https://relayer.staging.memwal.ai",
+    "local": "http://127.0.0.1:8000",
+}
+
 
 @dataclass
 class MemWalConfig:
@@ -23,14 +38,33 @@ class MemWalConfig:
     Attributes:
         key: Ed25519 private key (hex string). This is the delegate key from app.memwal.com.
         account_id: MemWalAccount object ID on Sui.
-        server_url: Server URL (default: https://relayer.memwal.ai).
+        server_url: Server URL (default: http://localhost:8000). An explicit
+            non-default value always wins over ``env``.
         namespace: Default namespace for memory isolation (default: "default").
+        env: Optional relayer preset — one of ``"prod"``, ``"dev"``,
+            ``"staging"``, ``"local"``. Resolves ``server_url`` to the matching
+            hosted relayer when ``server_url`` is left at its default.
+            Precedence: explicit ``server_url`` > ``env`` > default.
     """
 
     key: str
     account_id: str
-    server_url: str = "https://relayer.memwal.ai"
+    server_url: str = DEFAULT_SERVER_URL
     namespace: str = "default"
+    env: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if self.env is not None:
+            preset = ENV_PRESETS.get(self.env)
+            if preset is None:
+                valid = ", ".join(sorted(ENV_PRESETS))
+                raise ValueError(
+                    f"Unknown env preset {self.env!r}. Valid presets: {valid}"
+                )
+            # Explicit, non-default server_url takes precedence over the
+            # preset; only fill from the preset when server_url is untouched.
+            if self.server_url == DEFAULT_SERVER_URL:
+                self.server_url = preset
 
 
 # ============================================================