memwal 0.1.2.dev3__tar.gz → 0.1.3.dev0__tar.gz

{memwal-0.1.2.dev3 → memwal-0.1.3.dev0}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # memwal
 
+## 0.1.3
+
+### Added
+
+- Added `RecallParams` for object-style `recall(...)` calls.
+
+### Changed
+
+- Changed the default `restore()` limit from `50` to `10` to match the relayer and TypeScript SDK.
+- Documented `restore()` response fields, default limit, pagination behavior, and performance expectations.
+
 ## 0.1.2
 
 ### Added

{memwal-0.1.2.dev3 → memwal-0.1.3.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: memwal
-Version: 0.1.2.dev3
+Version: 0.1.3.dev0
 Summary: Python SDK for Walrus Memory — Privacy-first AI memory with Ed25519 signing
 Project-URL: Homepage, https://memwal.ai
 Project-URL: Documentation, https://docs.memwal.ai
@@ -75,7 +75,7 @@ must stay server-side.
 ```python
 import asyncio
 import os
-from memwal import MemWal
+from memwal import MemWal, RecallParams
 
 async def main():
     memwal = MemWal.create(
@@ -89,7 +89,7 @@ async def main():
     print(result.blob_id)
 
     # Recall memories
-    matches = await memwal.recall("food allergies", limit=10, max_distance=0.7)
+    matches = await memwal.recall(RecallParams(query="food allergies", limit=10, max_distance=0.7))
     for memory in matches.results:
         print(f"{memory.text} (relevance: {1 - memory.distance:.2f})")
 
@@ -107,7 +107,7 @@ asyncio.run(main())
 
 ```python
 import os
-from memwal import MemWalSync
+from memwal import MemWalSync, RecallParams
 
 client = MemWalSync.create(
     key=os.environ["MEMWAL_PRIVATE_KEY"],
@@ -116,7 +116,7 @@ client = MemWalSync.create(
 )
 
 result = client.remember("I'm allergic to peanuts")
-matches = client.recall("food allergies")
+matches = client.recall(RecallParams(query="food allergies"))
 client.close()
 ```
 
@@ -216,7 +216,7 @@ Create a new async client.
 | Method | Description |
 |--------|-------------|
 | `await remember(text, namespace?)` | Store a memory |
-| `await recall(query, limit?, namespace?, max_distance?)` | Search memories, optionally filtering by distance |
+| `await recall(RecallParams(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.2.dev3 → memwal-0.1.3.dev0}/README.md

@@ -36,7 +36,7 @@ must stay server-side.
 ```python
 import asyncio
 import os
-from memwal import MemWal
+from memwal import MemWal, RecallParams
 
 async def main():
     memwal = MemWal.create(
@@ -50,7 +50,7 @@ async def main():
     print(result.blob_id)
 
     # Recall memories
-    matches = await memwal.recall("food allergies", limit=10, max_distance=0.7)
+    matches = await memwal.recall(RecallParams(query="food allergies", limit=10, max_distance=0.7))
     for memory in matches.results:
         print(f"{memory.text} (relevance: {1 - memory.distance:.2f})")
 
@@ -68,7 +68,7 @@ asyncio.run(main())
 
 ```python
 import os
-from memwal import MemWalSync
+from memwal import MemWalSync, RecallParams
 
 client = MemWalSync.create(
     key=os.environ["MEMWAL_PRIVATE_KEY"],
@@ -77,7 +77,7 @@ client = MemWalSync.create(
 )
 
 result = client.remember("I'm allergic to peanuts")
-matches = client.recall("food allergies")
+matches = client.recall(RecallParams(query="food allergies"))
 client.close()
 ```
 
@@ -177,7 +177,7 @@ Create a new async client.
 | Method | Description |
 |--------|-------------|
 | `await remember(text, namespace?)` | Store a memory |
-| `await recall(query, limit?, namespace?, max_distance?)` | Search memories, optionally filtering by distance |
+| `await recall(RecallParams(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.2.dev3 → memwal-0.1.3.dev0}/examples/async_remember_demo.py

@@ -51,6 +51,7 @@ sys.path.insert(0, str(Path(__file__).parent.parent))
 from memwal import (  # noqa: E402
     MemWal,
     MemWalRememberJobFailed,
+    RecallParams,
     RememberBulkItem,
     RememberBulkOptions,
 )
@@ -119,7 +120,7 @@ async def main() -> None:
 
         # 5. recall — confirm the memories are searchable
         _section("5. recall('coffee')")
-        rc = await memwal.recall("coffee", limit=3)
+        rc = await memwal.recall(RecallParams(query="coffee", limit=3))
         print(f"  found {len(rc.results)} / total={rc.total}")
         for m in rc.results[:3]:
             print(f"    [{m.distance:.3f}] {m.text[:80]}")

{memwal-0.1.2.dev3 → memwal-0.1.3.dev0}/examples/interactive_demo.py

@@ -39,7 +39,7 @@ def _load_env() -> None:
 _load_env()
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
-from memwal import MemWal, RememberBulkItem, RememberBulkOptions  # noqa: E402
+from memwal import MemWal, RecallParams, RememberBulkItem, RememberBulkOptions  # noqa: E402
 
 # Path to the running server's log so we can show what happens on the
 # server side as each SDK call is made.
@@ -164,7 +164,7 @@ async def main() -> None:
         print(f"  → query='{query}'")
         off = _log_offset()
         t = _now_ms()
-        rc = await memwal.recall(query, limit=3)
+        rc = await memwal.recall(RecallParams(query=query, limit=3))
         rec_ms = _now_ms() - t
         print(f"  ← {rec_ms} ms   {len(rc.results)} results")
         for m in rc.results:
@@ -199,7 +199,7 @@ async def main() -> None:
         # ───────────────────────────────────────────────────────────
         _hr("STEP 6   POST /api/recall   query='japan'")
         off = _log_offset()
-        rc2 = await memwal.recall("japan", limit=2)
+        rc2 = await memwal.recall(RecallParams(query="japan", limit=2))
         print(f"  ← {len(rc2.results)} results")
         for m in rc2.results:
             print(f"     [{m.distance:.3f}] {m.text}")

{memwal-0.1.2.dev3 → memwal-0.1.3.dev0}/memwal/__init__.py

@@ -14,7 +14,7 @@ Quick start::
 
     # Async
     result = await memwal.remember("I love coffee")
-    matches = await memwal.recall("beverage preferences")
+    matches = await memwal.recall(RecallParams(query="beverage preferences"))
 
     # Sync wrapper
     from memwal import MemWalSync
@@ -46,6 +46,7 @@ from .types import (
     RecallManualOptions,
     RecallManualResult,
     RecallMemory,
+    RecallParams,
     RecallResult,
     RememberAcceptedResult,
     RememberBulkAcceptedResult,
@@ -98,6 +99,7 @@ __all__ = [
     "RememberBulkStatusResult",
     "RememberBulkItemResult",
     "RememberBulkResult",
+    "RecallParams",
     "RecallResult",
     "RecallMemory",
     "EmbedResult",
@@ -114,4 +116,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.1.2.dev3"
+__version__ = "0.1.3.dev0"

{memwal-0.1.2.dev3 → memwal-0.1.3.dev0}/memwal/client.py

@@ -20,7 +20,7 @@ Example::
 
     # Async usage
     result = await memwal.remember("I'm allergic to peanuts")
-    matches = await memwal.recall("food allergies")
+    matches = await memwal.recall(RecallParams(query="food allergies"))
 """
 
 from __future__ import annotations
@@ -49,6 +49,7 @@ from .types import (
     RecallManualOptions,
     RecallManualResult,
     RecallMemory,
+    RecallParams,
     RecallResult,
     RememberAcceptedResult,
     RememberBulkAcceptedResult,
@@ -473,7 +474,7 @@ class MemWal:
 
     async def recall(
         self,
-        query: str,
+        query: "str | RecallParams",
         limit: int = 10,
         namespace: Optional[str] = None,
         max_distance: Optional[float] = None,
@@ -482,18 +483,40 @@ class MemWal:
 
         Server handles: verify -> embed query -> search -> Walrus download -> decrypt.
 
+        **Preferred call style** is to pass a :class:`RecallParams`
+        object so the call site reads self-describingly:
+
+            await client.recall(RecallParams(
+                query="food allergies", limit=5, namespace="profile"))
+
+        The legacy positional call ``client.recall(query, limit, namespace)``
+        is still supported but is easy to mis-read as
+        ``recall(query, namespace)``. Prefer kwargs at minimum.
+
         Args:
-            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.
+            query: Search query, or a :class:`RecallParams` carrying query +
+                limit + namespace + max_distance in one object.
+            limit: Max number of results (default: 10). Ignored when ``query``
+                is a :class:`RecallParams`.
+            namespace: Override the default namespace. Ignored when ``query``
+                is a :class:`RecallParams`.
+            max_distance: Optional client-side relevance threshold. Memories
+                with ``distance >= max_distance`` are dropped. Ignored when
+                ``query`` is a :class:`RecallParams`.
 
         Returns:
             :class:`RecallResult` with decrypted text results.
         """
+        if isinstance(query, RecallParams):
+            params = query
+            query_text = params.query
+            limit = params.limit
+            namespace = params.namespace
+            max_distance = params.max_distance
+        else:
+            query_text = query
         data = await self._signed_request("POST", "/api/recall", {
-            "query": query,
+            "query": query_text,
             "limit": limit,
             "namespace": namespace or self._namespace,
         })
@@ -630,18 +653,42 @@ class MemWal:
             memories=memories,
         )
 
-    async def restore(self, namespace: str, limit: int = 50) -> RestoreResult:
-        """Restore a namespace.
+    async def restore(self, namespace: str, limit: int = 10) -> RestoreResult:
+        """Rebuild missing local index entries for ``namespace`` from Walrus.
+
+        The relayer queries Walrus for blobs the caller owns in ``namespace``,
+        ignores blobs already indexed locally, downloads the missing ones,
+        SEAL-decrypts them with the delegate key, re-embeds the plaintext, and
+        inserts a fresh vector row per blob.
+
+        Response semantics:
 
-        Server downloads all blobs from Walrus, decrypts with delegate key,
-        re-embeds, and re-indexes.
+        * ``restored`` — blobs that completed the full
+          download → decrypt → embed → DB insert pipeline this call.
+        * ``skipped`` — on-chain blobs already present in the local index
+          (no work needed). Decrypt / embed failures are dropped silently and
+          do **not** count as either restored or skipped.
+        * ``total`` — count of on-chain blobs the relayer saw for
+          ``(owner, namespace)`` before the limit was applied.
 
         Args:
-            namespace: Namespace to restore.
-            limit: Max entries to restore (default: 50).
+            namespace: Namespace to restore. Exact match — no prefix or
+                hierarchy semantics (see SKILL.md "Namespace Semantics").
+            limit: Max blobs the relayer will *inspect* this call (default:
+                10, matches the server-side default and the TypeScript SDK).
+                The relayer fetches blobs newest-first and caps the work at
+                this number; it does **not** cap ``restored`` separately.
 
         Returns:
-            :class:`RestoreResult` with count of restored entries.
+            :class:`RestoreResult`.
+
+        Notes:
+            * **No pagination cursor** — restore is single-shot. To rebuild a
+              large namespace, call repeatedly with a growing ``limit`` or
+              prune the local index first.
+            * **Performance** scales linearly in ``limit``: up to 10 Walrus
+              downloads in parallel, then 3 SEAL decrypts in parallel, then
+              embeddings. Expect seconds-per-blob on cold caches.
         """
         data = await self._signed_request("POST", "/api/restore", {
             "namespace": namespace,
@@ -1053,11 +1100,11 @@ class MemWalSync:
 
     Example::
 
-        from memwal import MemWalSync
+        from memwal import MemWalSync, RecallParams
 
         client = MemWalSync.create(key="...", account_id="0x...")
         result = client.remember("I love coffee")
-        matches = client.recall("coffee preferences")
+        matches = client.recall(RecallParams(query="coffee preferences"))
     """
 
     def __init__(self, inner: MemWal) -> None:
@@ -1189,12 +1236,13 @@ class MemWalSync:
 
     def recall(
         self,
-        query: str,
+        query: "str | RecallParams",
         limit: int = 10,
         namespace: Optional[str] = None,
         max_distance: Optional[float] = None,
     ) -> RecallResult:
-        """Synchronous version of :meth:`MemWal.recall`."""
+        """Synchronous version of :meth:`MemWal.recall` (accepts
+        :class:`RecallParams` for the recommended object-style call)."""
         return self._run(self._inner.recall(query, limit, namespace, max_distance))
 
     def analyze(self, text: str, namespace: Optional[str] = None) -> AnalyzeResult:
@@ -1218,8 +1266,9 @@ class MemWalSync:
         """Synchronous version of :meth:`MemWal.ask`."""
         return self._run(self._inner.ask(question, limit, namespace))
 
-    def restore(self, namespace: str, limit: int = 50) -> RestoreResult:
-        """Synchronous version of :meth:`MemWal.restore`."""
+    def restore(self, namespace: str, limit: int = 10) -> RestoreResult:
+        """Synchronous version of :meth:`MemWal.restore`. Default limit is 10
+        (matches server + TypeScript SDK)."""
         return self._run(self._inner.restore(namespace, limit))
 
     def health(self) -> HealthResult:

{memwal-0.1.2.dev3 → memwal-0.1.3.dev0}/memwal/types.py

@@ -92,6 +92,24 @@ class RecallMemory:
     distance: float
 
 
+@dataclass
+class RecallParams:
+    """Object-style input for :meth:`MemWal.recall`.
+
+    Preferred over positional args because positional ``recall(query, limit,
+    namespace)`` is easy to mis-read as ``recall(query, namespace)`` at call
+    sites. Construct this dataclass and pass it as the sole argument:
+
+        client.recall(RecallParams(query="food allergies", limit=5,
+                                   namespace="profile"))
+    """
+
+    query: str
+    limit: int = 10
+    namespace: Optional[str] = None
+    max_distance: Optional[float] = None
+
+
 @dataclass
 class RecallResult:
     """Result from recall()."""

{memwal-0.1.2.dev3 → memwal-0.1.3.dev0}/pyproject.toml

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

{memwal-0.1.2.dev3 → memwal-0.1.3.dev0}/tests/test_client.py

@@ -17,7 +17,12 @@ import pytest
 import respx
 
 from memwal.client import MemWal, MemWalCompatibilityError, MemWalError
-from memwal.types import RecallManualOptions, RememberManualOptions, ScoringWeights
+from memwal.types import (
+    RecallManualOptions,
+    RecallParams,
+    RememberManualOptions,
+    ScoringWeights,
+)
 from memwal.utils import build_signature_message, bytes_to_hex, sha256_hex
 
 # ============================================================
@@ -270,6 +275,58 @@ class TestRecall:
         assert result.results[0].distance == 0.1
         assert result.results[1].blob_id == "b2"
 
+    @respx.mock
+    async def test_accepts_recall_params_object(
+        self, memwal_client: MemWal
+    ) -> None:
+        """recall(RecallParams(...)) sends the same request body as
+        the positional form, with query/limit/namespace pulled from the
+        dataclass instead of positional args."""
+        mock_seal_session_prereqs()
+        route = respx.post(f"{_TEST_SERVER}/api/recall").mock(
+            return_value=httpx.Response(
+                200,
+                json={"results": [], "total": 0},
+            )
+        )
+
+        await memwal_client.recall(
+            RecallParams(query="coffee", limit=7, namespace="profile"),
+        )
+
+        assert route.called
+        body = json.loads(route.calls[0].request.content)
+        assert body["query"] == "coffee"
+        assert body["limit"] == 7
+        assert body["namespace"] == "profile"
+
+    @respx.mock
+    async def test_recall_params_object_applies_max_distance_filter(
+        self, memwal_client: MemWal
+    ) -> None:
+        """max_distance on the RecallParams dataclass drops weak matches
+        client-side, matching the positional max_distance kwarg behavior."""
+        mock_seal_session_prereqs()
+        respx.post(f"{_TEST_SERVER}/api/recall").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "results": [
+                        {"blob_id": "b1", "text": "tight", "distance": 0.1},
+                        {"blob_id": "b2", "text": "noisy", "distance": 0.9},
+                    ],
+                    "total": 2,
+                },
+            )
+        )
+
+        result = await memwal_client.recall(
+            RecallParams(query="x", limit=10, max_distance=0.5),
+        )
+
+        assert len(result.results) == 1
+        assert result.results[0].blob_id == "b1"
+
     @respx.mock
     async def test_sends_correct_headers(self, memwal_client: MemWal) -> None:
         """recall() should include all required auth headers."""