memwal 0.1.1.dev0__tar.gz → 0.1.2.dev1__tar.gz

{memwal-0.1.1.dev0 → memwal-0.1.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memwal
-Version: 0.1.1.dev0
+Version: 0.1.2.dev1
 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
@@ -62,11 +62,14 @@ pip install memwal[all]         # Everything
 Set your environment variables first:
 
 ```bash
-export MEMWAL_KEY="your-ed25519-delegate-key-hex"
+export MEMWAL_PRIVATE_KEY="your-ed25519-delegate-private-key-hex"
 export MEMWAL_ACCOUNT_ID="0x-your-memwal-account-id"
 export MEMWAL_SERVER_URL="https://relayer.memwal.ai"
 ```
 
+`MEMWAL_PRIVATE_KEY` is the delegate private key from the MemWal dashboard and
+must stay server-side.
+
 ### Async (recommended)
 
 ```python
@@ -76,7 +79,7 @@ from memwal import MemWal
 
 async def main():
     memwal = MemWal.create(
-        key=os.environ["MEMWAL_KEY"],
+        key=os.environ["MEMWAL_PRIVATE_KEY"],
         account_id=os.environ["MEMWAL_ACCOUNT_ID"],
         server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
     )
@@ -86,7 +89,7 @@ async def main():
     print(result.blob_id)
 
     # Recall memories
-    matches = await memwal.recall("food allergies")
+    matches = await memwal.recall("food allergies", limit=10, max_distance=0.7)
     for memory in matches.results:
         print(f"{memory.text} (relevance: {1 - memory.distance:.2f})")
 
@@ -107,7 +110,7 @@ import os
 from memwal import MemWalSync
 
 client = MemWalSync.create(
-    key=os.environ["MEMWAL_KEY"],
+    key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
     server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
 )
@@ -124,7 +127,7 @@ import os
 from memwal import MemWal
 
 async with MemWal.create(
-    key=os.environ["MEMWAL_KEY"],
+    key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
 ) as memwal:
     await memwal.remember("I prefer dark mode")
@@ -139,7 +142,7 @@ Same shorthand as the TypeScript SDK and MCP package.
 from memwal import MemWal
 
 memwal = MemWal.create(
-    key=os.environ["MEMWAL_KEY"],
+    key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
     env="prod",   # prod | dev | staging | local
 )
@@ -169,7 +172,7 @@ from memwal import with_memwal_langchain
 llm = ChatOpenAI(model="gpt-4o")
 smart_llm = with_memwal_langchain(
     llm,
-    key=os.environ["MEMWAL_KEY"],
+    key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
     server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
     max_memories=5,
@@ -190,7 +193,7 @@ from memwal import with_memwal_openai
 client = AsyncOpenAI()
 smart_client = with_memwal_openai(
     client,
-    key=os.environ["MEMWAL_KEY"],
+    key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
     server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
 )
@@ -213,7 +216,7 @@ Create a new async client.
 | Method | Description |
 |--------|-------------|
 | `await remember(text, namespace?)` | Store a memory |
-| `await recall(query, limit?, namespace?)` | Search memories |
+| `await recall(query, limit?, namespace?, max_distance?)` | Search memories, optionally filtering by distance |
 | `await analyze(text, namespace?)` | Extract and store facts |
 | `await ask(question, limit?, namespace?)` | Ask a question answered using memories |
 | `await restore(namespace, limit?)` | Restore a namespace |

{memwal-0.1.1.dev0 → memwal-0.1.2.dev1}/README.md

@@ -23,11 +23,14 @@ pip install memwal[all]         # Everything
 Set your environment variables first:
 
 ```bash
-export MEMWAL_KEY="your-ed25519-delegate-key-hex"
+export MEMWAL_PRIVATE_KEY="your-ed25519-delegate-private-key-hex"
 export MEMWAL_ACCOUNT_ID="0x-your-memwal-account-id"
 export MEMWAL_SERVER_URL="https://relayer.memwal.ai"
 ```
 
+`MEMWAL_PRIVATE_KEY` is the delegate private key from the MemWal dashboard and
+must stay server-side.
+
 ### Async (recommended)
 
 ```python
@@ -37,7 +40,7 @@ from memwal import MemWal
 
 async def main():
     memwal = MemWal.create(
-        key=os.environ["MEMWAL_KEY"],
+        key=os.environ["MEMWAL_PRIVATE_KEY"],
         account_id=os.environ["MEMWAL_ACCOUNT_ID"],
         server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
     )
@@ -47,7 +50,7 @@ async def main():
     print(result.blob_id)
 
     # Recall memories
-    matches = await memwal.recall("food allergies")
+    matches = await memwal.recall("food allergies", limit=10, max_distance=0.7)
     for memory in matches.results:
         print(f"{memory.text} (relevance: {1 - memory.distance:.2f})")
 
@@ -68,7 +71,7 @@ import os
 from memwal import MemWalSync
 
 client = MemWalSync.create(
-    key=os.environ["MEMWAL_KEY"],
+    key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
     server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
 )
@@ -85,7 +88,7 @@ import os
 from memwal import MemWal
 
 async with MemWal.create(
-    key=os.environ["MEMWAL_KEY"],
+    key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
 ) as memwal:
     await memwal.remember("I prefer dark mode")
@@ -100,7 +103,7 @@ Same shorthand as the TypeScript SDK and MCP package.
 from memwal import MemWal
 
 memwal = MemWal.create(
-    key=os.environ["MEMWAL_KEY"],
+    key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
     env="prod",   # prod | dev | staging | local
 )
@@ -130,7 +133,7 @@ from memwal import with_memwal_langchain
 llm = ChatOpenAI(model="gpt-4o")
 smart_llm = with_memwal_langchain(
     llm,
-    key=os.environ["MEMWAL_KEY"],
+    key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
     server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
     max_memories=5,
@@ -151,7 +154,7 @@ from memwal import with_memwal_openai
 client = AsyncOpenAI()
 smart_client = with_memwal_openai(
     client,
-    key=os.environ["MEMWAL_KEY"],
+    key=os.environ["MEMWAL_PRIVATE_KEY"],
     account_id=os.environ["MEMWAL_ACCOUNT_ID"],
     server_url=os.environ.get("MEMWAL_SERVER_URL", "https://relayer.memwal.ai"),
 )
@@ -174,7 +177,7 @@ Create a new async client.
 | Method | Description |
 |--------|-------------|
 | `await remember(text, namespace?)` | Store a memory |
-| `await recall(query, limit?, namespace?)` | Search memories |
+| `await recall(query, limit?, namespace?, max_distance?)` | Search memories, optionally filtering by distance |
 | `await analyze(text, namespace?)` | Extract and store facts |
 | `await ask(question, limit?, namespace?)` | Ask a question answered using memories |
 | `await restore(namespace, limit?)` | Restore a namespace |

{memwal-0.1.1.dev0 → memwal-0.1.2.dev1}/examples/.env.example

@@ -1,7 +1,9 @@
 # Local server (default) or remote relayer
-MEMWAL_SERVER_URL=http://localhost:3001
+MEMWAL_SERVER_URL=http://localhost:8000
 # Ed25519 delegate private key (64-hex). Get from MemWal dashboard.
-MEMWAL_KEY=21b423e72282dcc47805de48ef9130331b642667b7b2a5cd621767928205e360
+MEMWAL_PRIVATE_KEY=21b423e72282dcc47805de48ef9130331b642667b7b2a5cd621767928205e360
+# Optional: paste the dashboard delegate public key so verification can catch mismatches.
+MEMWAL_DELEGATE_PUBLIC_KEY=
 # MemWalAccount object ID on Sui (the wallet's account)
 MEMWAL_ACCOUNT_ID=0x8a1121b8f95d79e68bd07efaf71689ce6fd832b369cdb1b2a943ec7beb822392
 # Namespace for these test memories

{memwal-0.1.1.dev0 → memwal-0.1.2.dev1}/examples/async_remember_demo.py

@@ -65,13 +65,13 @@ def _ms(start: float) -> int:
 
 
 async def main() -> None:
-    server_url = os.environ.get("MEMWAL_SERVER_URL", "http://localhost:3001")
-    key = os.environ.get("MEMWAL_KEY")
+    server_url = os.environ.get("MEMWAL_SERVER_URL", "http://localhost:8000")
+    key = os.environ.get("MEMWAL_PRIVATE_KEY")
     account_id = os.environ.get("MEMWAL_ACCOUNT_ID")
     namespace = os.environ.get("MEMWAL_NAMESPACE", "python-sdk-example")
 
     if not key or not account_id:
-        print("ERROR: set MEMWAL_KEY + MEMWAL_ACCOUNT_ID in examples/.env")
+        print("ERROR: set MEMWAL_PRIVATE_KEY + MEMWAL_ACCOUNT_ID in examples/.env")
         sys.exit(2)
 
     print(f"server      : {server_url}")

{memwal-0.1.1.dev0 → memwal-0.1.2.dev1}/examples/interactive_demo.py

@@ -94,13 +94,13 @@ def _log_offset() -> int:
 
 
 async def main() -> None:
-    server_url = os.environ.get("MEMWAL_SERVER_URL", "http://localhost:3001")
-    key = os.environ.get("MEMWAL_KEY")
+    server_url = os.environ.get("MEMWAL_SERVER_URL", "http://localhost:8000")
+    key = os.environ.get("MEMWAL_PRIVATE_KEY")
     account_id = os.environ.get("MEMWAL_ACCOUNT_ID")
     namespace = os.environ.get("MEMWAL_NAMESPACE", "python-sdk-example")
 
     if not key or not account_id:
-        print("ERROR: set MEMWAL_KEY + MEMWAL_ACCOUNT_ID in examples/.env")
+        print("ERROR: set MEMWAL_PRIVATE_KEY + MEMWAL_ACCOUNT_ID in examples/.env")
         sys.exit(2)
 
     print(f"server      : {server_url}")

memwal-0.1.2.dev1/examples/verify_credentials.py

@@ -0,0 +1,67 @@
+"""Verify MemWal example credentials before calling the relayer.
+
+Usage:
+    MEMWAL_PRIVATE_KEY=<hex> MEMWAL_ACCOUNT_ID=0x... python examples/verify_credentials.py
+
+Optional:
+    Set MEMWAL_DELEGATE_PUBLIC_KEY to the dashboard public key to fail on
+    public/private key mismatch.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+
+import nacl.signing
+
+HEX_32_BYTES = re.compile(r"^(0x)?[0-9a-fA-F]{64}$")
+ACCOUNT_ID = re.compile(r"^0x[0-9a-fA-F]{64}$")
+
+
+def normalize_hex(value: str) -> str:
+    value = value.strip()
+    return value[2:] if value.lower().startswith("0x") else value
+
+
+def main() -> None:
+    private_key = os.environ.get("MEMWAL_PRIVATE_KEY") or ""
+    account_id = os.environ.get("MEMWAL_ACCOUNT_ID") or ""
+    expected_public_key = os.environ.get("MEMWAL_DELEGATE_PUBLIC_KEY") or ""
+    server_url = os.environ.get("MEMWAL_SERVER_URL") or ""
+
+    if not private_key:
+        raise SystemExit("MEMWAL_PRIVATE_KEY is required")
+    if not HEX_32_BYTES.match(private_key):
+        raise SystemExit("MEMWAL_PRIVATE_KEY must be a 64-character Ed25519 private key hex string")
+    if account_id and not ACCOUNT_ID.match(account_id):
+        raise SystemExit("MEMWAL_ACCOUNT_ID must be a 0x-prefixed 32-byte Sui object ID")
+
+    signing_key = nacl.signing.SigningKey(bytes.fromhex(normalize_hex(private_key)))
+    derived_public_key = signing_key.verify_key.encode().hex()
+
+    if expected_public_key and derived_public_key != normalize_hex(expected_public_key).lower():
+        raise SystemExit(
+            "MEMWAL_PRIVATE_KEY does not derive MEMWAL_DELEGATE_PUBLIC_KEY. "
+            "You may have pasted a public key or a key from another account."
+        )
+
+    print("MemWal credentials look parseable.")
+    print(f"Derived delegate public key: {derived_public_key}")
+    if account_id:
+        print(f"Account ID: {account_id}")
+    if server_url:
+        print(f"Relayer URL: {server_url}")
+    if not expected_public_key:
+        print("Set MEMWAL_DELEGATE_PUBLIC_KEY to fail on public/private key mismatch.")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except SystemExit:
+        raise
+    except Exception as exc:
+        print(exc, file=sys.stderr)
+        raise SystemExit(1) from exc

{memwal-0.1.1.dev0 → memwal-0.1.2.dev1}/memwal/__init__.py

@@ -112,4 +112,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.1.1.dev0"
+__version__ = "0.1.2.dev1"

{memwal-0.1.1.dev0 → memwal-0.1.2.dev1}/memwal/client.py

@@ -79,6 +79,11 @@ from .utils import (
 T = TypeVar("T")
 SEAL_SESSION_TTL_MIN = 5
 SEAL_SESSION_SAFETY_MARGIN_MS = 30_000
+AUTH_REJECTED_MESSAGE = (
+    "401 from relayer: typically wrong private key, key not registered on this "
+    "account, account ID mismatch, or staging/mainnet mismatch. Check .env.local "
+    "and dashboard credentials."
+)
 
 
 # ============================================================
@@ -472,6 +477,7 @@ class MemWal:
         query: str,
         limit: int = 10,
         namespace: Optional[str] = None,
+        max_distance: Optional[float] = None,
     ) -> RecallResult:
         """Recall memories similar to a query.
 
@@ -481,6 +487,8 @@ class MemWal:
             query: Search query.
             limit: Max number of results (default: 10).
             namespace: Override the default namespace.
+            max_distance: Optional client-side relevance threshold. Memories with
+                ``distance >= max_distance`` are dropped.
 
         Returns:
             :class:`RecallResult` with decrypted text results.
@@ -498,6 +506,9 @@ class MemWal:
             )
             for m in data.get("results", [])
         ]
+        if max_distance is not None:
+            memories = [m for m in memories if m.distance < max_distance]
+            return RecallResult(results=memories, total=len(memories))
         return RecallResult(results=memories, total=data.get("total", len(memories)))
 
     async def analyze(self, text: str, namespace: Optional[str] = None) -> AnalyzeResult:
@@ -991,7 +1002,10 @@ class _HttpStatusError(MemWalError):
     """
 
     def __init__(self, status: int, body: str) -> None:
-        super().__init__(f"MemWal API error ({status}): {body}")
+        if status == 401:
+            super().__init__(AUTH_REJECTED_MESSAGE)
+        else:
+            super().__init__(f"MemWal API error ({status}): {body}")
         self.status = status
         self.body = body
 
@@ -1170,10 +1184,14 @@ class MemWalSync:
         return self._run(self._inner.remember_bulk_and_wait(items, opts))
 
     def recall(
-        self, query: str, limit: int = 10, namespace: Optional[str] = None
+        self,
+        query: str,
+        limit: int = 10,
+        namespace: Optional[str] = None,
+        max_distance: Optional[float] = None,
     ) -> RecallResult:
         """Synchronous version of :meth:`MemWal.recall`."""
-        return self._run(self._inner.recall(query, limit, namespace))
+        return self._run(self._inner.recall(query, limit, namespace, max_distance))
 
     def analyze(self, text: str, namespace: Optional[str] = None) -> AnalyzeResult:
         """Synchronous version of :meth:`MemWal.analyze`."""

{memwal-0.1.1.dev0 → memwal-0.1.2.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memwal"
-version = "0.1.1.dev0"
+version = "0.1.2.dev1"
 description = "Python SDK for MemWal — Privacy-first AI memory with Ed25519 signing"
 readme = "README.md"
 license = "MIT"

{memwal-0.1.1.dev0 → memwal-0.1.2.dev1}/run_tests.py

@@ -8,7 +8,7 @@ Usage:
     python3 run_tests.py
 
 With dev server (integration tests):
-    MEMWAL_KEY=<hex> MEMWAL_ACCOUNT_ID=0x... MEMWAL_SERVER_URL=https://... python3 run_tests.py
+    MEMWAL_PRIVATE_KEY=<hex> MEMWAL_ACCOUNT_ID=0x... MEMWAL_SERVER_URL=https://... python3 run_tests.py
 """
 
 from __future__ import annotations
@@ -27,7 +27,7 @@ DIM    = "\033[2m"
 RESET  = "\033[0m"
 
 SERVER_URL  = os.environ.get("MEMWAL_SERVER_URL", "https://relayer.dev.memwal.ai")
-PRIVATE_KEY = os.environ.get("MEMWAL_KEY", "")
+PRIVATE_KEY = os.environ.get("MEMWAL_PRIVATE_KEY", "")
 ACCOUNT_ID  = os.environ.get("MEMWAL_ACCOUNT_ID", "")
 HAS_KEY     = bool(PRIVATE_KEY and ACCOUNT_ID)
 
@@ -192,7 +192,7 @@ def main() -> None:
     print(f"  {'─' * 78}")
 
     if not HAS_KEY:
-        print(f"\n  {YELLOW}Integration tests skipped — set MEMWAL_KEY + MEMWAL_ACCOUNT_ID to run them{RESET}")
+        print(f"\n  {YELLOW}Integration tests skipped — set MEMWAL_PRIVATE_KEY + MEMWAL_ACCOUNT_ID to run them{RESET}")
         print_totals(total_passed, total_failed, all_failures)
         return
 

{memwal-0.1.1.dev0 → memwal-0.1.2.dev1}/tests/test_client.py

@@ -290,6 +290,31 @@ class TestRecall:
         assert "x-seal-session" in headers
         assert "x-delegate-key" not in headers
 
+    @respx.mock
+    async def test_max_distance_filters_results(self, memwal_client: MemWal) -> None:
+        """recall() should filter weak matches when max_distance is provided."""
+        mock_seal_session_prereqs()
+        route = respx.post(f"{_TEST_SERVER}/api/recall").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "results": [
+                        {"blob_id": "b1", "text": "I love coffee", "distance": 0.2},
+                        {"blob_id": "b2", "text": "I live in Tokyo", "distance": 0.7},
+                    ],
+                    "total": 2,
+                },
+            )
+        )
+
+        result = await memwal_client.recall("coffee", limit=10, max_distance=0.7)
+
+        body = json.loads(route.calls[0].request.content)
+        assert body["limit"] == 10
+        assert len(result.results) == 1
+        assert result.total == 1
+        assert result.results[0].blob_id == "b1"
+
     @respx.mock
     async def test_get_signed_request_uses_empty_body_hash_and_no_wire_body(
         self, memwal_client: MemWal
@@ -341,6 +366,22 @@ class TestErrorHandling:
         with pytest.raises(MemWalError, match="401"):
             await memwal_client.remember("test")
 
+    @respx.mock
+    async def test_empty_401_uses_workshop_friendly_message(
+        self, memwal_client: MemWal
+    ) -> None:
+        """Empty-body auth failures should still give actionable guidance."""
+        mock_seal_session_prereqs()
+        respx.post(f"{_TEST_SERVER}/api/recall").mock(
+            return_value=httpx.Response(401, text="")
+        )
+
+        with pytest.raises(
+            MemWalError,
+            match="wrong private key.*account ID mismatch.*staging/mainnet mismatch",
+        ):
+            await memwal_client.recall("test")
+
     @respx.mock
     async def test_500_raises_memwal_error(self, memwal_client: MemWal) -> None:
         """Server errors should raise MemWalError."""

{memwal-0.1.1.dev0 → memwal-0.1.2.dev1}/tests/test_integration.py

@@ -12,7 +12,7 @@ No-auth tests (always run, no env vars needed):
   - Future timestamp → 401
   - Unregistered key → SDK raises MemWalError
 
-Authenticated tests (require MEMWAL_KEY + MEMWAL_ACCOUNT_ID):
+Authenticated tests (require MEMWAL_PRIVATE_KEY + MEMWAL_ACCOUNT_ID):
   - remember() acceptance
   - remember_and_wait()
   - recall()
@@ -26,10 +26,10 @@ Usage:
   python -m pytest tests/test_integration.py -v -m "not requires_key"
 
   # Run full suite with real credentials
-  MEMWAL_KEY=<hex> MEMWAL_ACCOUNT_ID=0x... python -m pytest tests/test_integration.py -v
+  MEMWAL_PRIVATE_KEY=<hex> MEMWAL_ACCOUNT_ID=0x... python -m pytest tests/test_integration.py -v
 
   # Run against dev server using env vars
-  export MEMWAL_KEY="944aa24c09d8b6d6cc6a8fbedc6dc0942a46e49db7d36596e1b6af6061ec9261"
+  export MEMWAL_PRIVATE_KEY="944aa24c09d8b6d6cc6a8fbedc6dc0942a46e49db7d36596e1b6af6061ec9261"
   export MEMWAL_ACCOUNT_ID="0x70f9a6ff2df0ef6a9ecbfdc3f44c27c289ec3eb0cab5e10a5c07ca6165528565"
   export MEMWAL_SERVER_URL="https://relayer.dev.memwal.ai"
   python -m pytest tests/test_integration.py -v
@@ -53,14 +53,14 @@ from memwal.utils import build_signature_message, bytes_to_hex
 # ── Config ───────────────────────────────────────────────────────────────────
 
 SERVER_URL = os.environ.get("MEMWAL_SERVER_URL", "https://relayer.dev.memwal.ai")
-PRIVATE_KEY_HEX = os.environ.get("MEMWAL_KEY", "")
+PRIVATE_KEY_HEX = os.environ.get("MEMWAL_PRIVATE_KEY", "")
 ACCOUNT_ID = os.environ.get("MEMWAL_ACCOUNT_ID", "")
 
 HAS_KEY = bool(PRIVATE_KEY_HEX and ACCOUNT_ID)
 
 requires_key = pytest.mark.skipif(
     not HAS_KEY,
-    reason="MEMWAL_KEY and MEMWAL_ACCOUNT_ID not set",
+    reason="MEMWAL_PRIVATE_KEY and MEMWAL_ACCOUNT_ID not set",
 )
 
 # ── Helpers ───────────────────────────────────────────────────────────────────