memwal 0.2.0.dev0__tar.gz → 0.2.0.dev1__tar.gz

{memwal-0.2.0.dev0 → memwal-0.2.0.dev1}/CHANGELOG.md

@@ -12,6 +12,11 @@ Unreleased.
 
 - Require certifi 2026.10.19 or newer to remove trust in the compromised emSign certificate chain, and AnyIO 4.14.2 or newer for its TLS hostname fix. Update pip separately to 26.2.2 or newer; the SDK cannot replace pip's vendored trust store.
 
+### Fixed
+
+- `with_memwal_*` gains `save_mode` and confirmable saves: `memwal_wait_for_saves` (async and sync) polls every job the middleware enqueued, and restores the job ids if that poll raises so a retry can still confirm them. (WALM-307, #410, #411, #412)
+- `wait_for_remember_jobs` chunks its status reads to the relayer's 20-id `MAX_BULK_ITEMS` cap. Above it the relayer answers a non-transient 400, so a wait over 21+ jobs raised on every attempt and could never confirm — reachable from `save_mode="remember"` after 21 turns, or from two fat `analyze` extracts. (WALM-307)
+
 ## 0.1.12
 
 ### Added

{memwal-0.2.0.dev0 → memwal-0.2.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memwal
-Version: 0.2.0.dev0
+Version: 0.2.0.dev1
 Summary: Python SDK for Walrus Memory — Privacy-first AI memory with Ed25519 signing
 Project-URL: Homepage, https://memory.walrus.xyz
 Project-URL: Documentation, https://memory.walrus.xyz

{memwal-0.2.0.dev0 → memwal-0.2.0.dev1}/memwal/__init__.py

@@ -128,4 +128,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.2.0.dev0"
+__version__ = "0.2.0.dev1"

{memwal-0.2.0.dev0 → memwal-0.2.0.dev1}/memwal/client.py

@@ -98,6 +98,10 @@ PUBLIC_SUI_GRAPHQL_NETWORKS = ("mainnet", "testnet", "devnet")
 # Sui read endpoint is unresponsive.
 PACKAGE_VERSION_CHECK_TIMEOUT_S = 10.0
 SEAL_SESSION_SAFETY_MARGIN_MS = 30_000
+
+# The relayer's `MAX_BULK_ITEMS` (services/server/src/types.rs). A bulk read
+# above it is rejected with a non-transient 400, so callers must chunk.
+MAX_BULK_STATUS_IDS = 20
 AUTH_REJECTED_MESSAGE = (
     "401 from relayer: typically wrong private key, key not registered on this "
     "account, account ID mismatch (a wallet address is not a MemWal account ID), "
@@ -410,6 +414,29 @@ def _occurred_at_to_wire(
     )
 
 
+
+def _check_limit(limit: Any) -> None:
+    """Reject a limit that is not a positive integer before it is signed (#1218)."""
+    if isinstance(limit, bool) or not isinstance(limit, int) or limit <= 0:
+        raise ValueError(f"limit must be a positive integer, got {limit!r}")
+
+
+def _check_vector(vector: Any) -> None:
+    """Reject a vector that is not a non-empty list of finite numbers (#1218).
+
+    json.dumps would otherwise emit bare NaN/Infinity tokens, which are not
+    JSON, and the relayer would answer with an opaque parse error.
+    """
+    if (
+        not isinstance(vector, (list, tuple))
+        or len(vector) == 0
+        or not all(
+            isinstance(v, (int, float)) and not isinstance(v, bool) and math.isfinite(v)
+            for v in vector
+        )
+    ):
+        raise ValueError("vector must be a non-empty list of finite numbers")
+
 class MemWal:
     """Async-native Walrus Memory client.
 
@@ -907,60 +934,81 @@ class MemWal:
                 attempt += 1
             retry_after_ms = 0
 
-            try:
-                poll_timeout = self._poll_deadline_s(deadline_ms)
+            # The relayer rejects a bulk-status read of more than
+            # MAX_BULK_STATUS_IDS ids with a 400, which is NOT transient: an
+            # unchunked poll of 21+ jobs raises out of the whole wait and
+            # every retry hits the same 400. Chunk here so `memwal_wait_for_saves`
+            # and `remember_bulk_and_wait` are both fixed.
+            terminal_ids: Set[str] = set()
+            refused_ids: List[str] = []
+            for start in range(0, len(pending), MAX_BULK_STATUS_IDS):
+                chunk = pending[start : start + MAX_BULK_STATUS_IDS]
                 try:
-                    batch = await self.get_remember_bulk_status(pending, timeout=poll_timeout)
-                except TypeError as err:
-                    if "unexpected keyword argument" in str(err) and "timeout" in str(err):
-                        batch = await self.get_remember_bulk_status(pending)
-                    else:
-                        raise
-            except _HttpStatusError as err:
-                if _is_transient_polling_status(err.status):
-                    last_refusal = err.status
-                    if err.status == 429:
-                        saw_rate_limit = True
-                        retry_after_ms = _clamped_retry_after_ms(err, deadline_ms)
+                    poll_timeout = self._poll_deadline_s(deadline_ms)
+                    try:
+                        batch = await self.get_remember_bulk_status(chunk, timeout=poll_timeout)
+                    except TypeError as err:
+                        if "unexpected keyword argument" in str(err) and "timeout" in str(err):
+                            batch = await self.get_remember_bulk_status(chunk)
+                        else:
+                            raise
+                except _HttpStatusError as err:
+                    if _is_transient_polling_status(err.status):
+                        last_refusal = err.status
+                        if err.status == 429:
+                            saw_rate_limit = True
+                            retry_after_ms = _clamped_retry_after_ms(err, deadline_ms)
+                        # Refused, not answered: keep this chunk pending.
+                        refused_ids.extend(chunk)
+                        continue
+                    raise
+                except httpx.TransportError:
+                    # Network drops retry as status 0; continuing next loop iteration
+                    # increments `attempt` so exponential backoff delay continues to grow.
+                    last_refusal = 0
+                    refused_ids.extend(chunk)
                     continue
-                raise
-            except httpx.TransportError:
-                # Network drops retry as status 0; continuing next loop iteration
-                # increments `attempt` so exponential backoff delay continues to grow.
-                last_refusal = 0
-                continue
-            answered = True
+                answered = True
+                chunk_pending = set(chunk)
+                terminal_ids |= {
+                    item.job_id
+                    for item in batch.results
+                    if item.job_id in chunk_pending and settle(item)
+                }
 
-            terminal_ids: Set[str] = {
-                item.job_id
-                for item in batch.results
-                if item.job_id in pending and settle(item)
-            }
+            if not answered and refused_ids:
+                # Nothing got through this tick; back off and retry.
+                continue
             pending = [jid for jid in pending if jid not in terminal_ids]
 
         if opts.timeout_ms > 0 and len(pending) == len(job_ids) and not last_seen:
             # Nothing settled and nothing was seen: the polls may all have been
             # refused. Confirm with one direct read before reporting anything.
-            try:
-                probed = await self.get_remember_bulk_status(list(job_ids))
-            except _HttpStatusError as err:
-                if err.status == 429:
-                    # Header first, else the body's retry_after_seconds, so a
-                    # proxy that strips Retry-After does not lose the hint.
-                    wait_ms = _retry_after_ms(err)
-                    retry_after = f"{wait_ms / 1000:g}" if wait_ms else None
-                    raise MemWalRateLimited(job_ids, retry_after) from err
-                # Any other probe failure is not evidence about the jobs.
-            except httpx.TransportError:
-                pass
-            else:
+            settled: Set[str] = set()
+            all_ids = list(job_ids)
+            for start in range(0, len(all_ids), MAX_BULK_STATUS_IDS):
+                chunk = all_ids[start : start + MAX_BULK_STATUS_IDS]
+                try:
+                    probed = await self.get_remember_bulk_status(chunk)
+                except _HttpStatusError as err:
+                    if err.status == 429:
+                        # Header first, else the body's retry_after_seconds, so a
+                        # proxy that strips Retry-After does not lose the hint.
+                        wait_ms = _retry_after_ms(err)
+                        retry_after = f"{wait_ms / 1000:g}" if wait_ms else None
+                        raise MemWalRateLimited(job_ids, retry_after) from err
+                    # Any other probe failure is not evidence about the jobs.
+                    continue
+                except httpx.TransportError:
+                    continue
                 answered = True
-                settled = {
+                pending_now = set(pending)
+                settled |= {
                     item.job_id
                     for item in probed.results
-                    if item.job_id in pending and settle(item)
+                    if item.job_id in pending_now and settle(item)
                 }
-                pending = [jid for jid in pending if jid not in settled]
+            pending = [jid for jid in pending if jid not in settled]
 
         for job_id in pending:
             seen = last_seen.get(job_id)
@@ -1057,6 +1105,7 @@ class MemWal:
             sort = params.sort
         else:
             query_text = query
+        _check_limit(limit)
         body = {
             "query": query_text,
             "limit": limit,
@@ -1299,6 +1348,7 @@ class MemWal:
               downloads in parallel, then 3 SEAL decrypts in parallel, then
               embeddings. Expect seconds-per-blob on cold caches.
         """
+        _check_limit(limit)
         data = await self._signed_request("POST", "/api/restore", {
             "namespace": namespace,
             "limit": limit,
@@ -1354,6 +1404,10 @@ class MemWal:
         Returns:
             :class:`NamespacesResult`.
         """
+        # Validate before resolving the owner: on a fresh client that lookup is
+        # a signed POST /api/stats, so a bad limit must not reach it (#1218).
+        if limit is not None:
+            _check_limit(limit)
         owner = await self._resolve_owner()
 
         params: Dict[str, str] = {}
@@ -1428,6 +1482,7 @@ class MemWal:
         Returns:
             :class:`RememberManualResult` with id, blob_id, owner, namespace.
         """
+        _check_vector(opts.vector)
         data = await self._signed_request(
             "POST",
             "/api/remember/manual",
@@ -1457,6 +1512,8 @@ class MemWal:
         Returns:
             :class:`RecallManualResult` with blob_id + distance pairs.
         """
+        _check_vector(opts.vector)
+        _check_limit(opts.limit)
         body: Dict[str, Any] = {
             "vector": opts.vector,
             "limit": opts.limit,
@@ -1751,7 +1808,9 @@ class MemWal:
 
         method_upper = method.upper()
         timestamp = str(int(time.time()))
-        body_str = "" if method_upper == "GET" else json.dumps(body, separators=(",", ":"))
+        body_str = "" if method_upper == "GET" else json.dumps(
+            body, separators=(",", ":"), allow_nan=False
+        )
         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"

{memwal-0.2.0.dev0 → memwal-0.2.0.dev1}/memwal/middleware.py

@@ -55,7 +55,7 @@ from typing import (
 )
 
 from .client import MemWal, _with_fresh_http_client
-from .types import RecallMemory
+from .types import RecallMemory, RememberBulkOptions, RememberBulkResult
 
 if TYPE_CHECKING:
     from langchain_core.language_models.chat_models import BaseChatModel
@@ -178,6 +178,28 @@ def _format_memories(
     ])
 
 
+SAVE_MODES = ("analyze", "remember")
+"""Valid ``save_mode`` values for the auto-save path.
+
+``"analyze"`` extracts spoken-fact-style statements via the server LLM and
+stores one memory per fact — it is lossy by design, and non-sentence content
+(code snippets, structured data) yields zero facts. ``"remember"`` stores the
+user message verbatim as a single memory, which is what callers saving code or
+other non-conversational content want.
+"""
+
+
+def _validate_save_mode(save_mode: str) -> str:
+    if save_mode not in SAVE_MODES:
+        raise ValueError(
+            f"save_mode must be one of {SAVE_MODES}, got {save_mode!r}"
+        )
+    return save_mode
+
+
+_MAX_TRACKED_JOB_IDS = 1000
+
+
 class _PendingSaves:
     """Tracks in-flight fire-and-forget auto-save work (asyncio Tasks and
     background Threads) so a caller can drain it deterministically via
@@ -197,6 +219,7 @@ class _PendingSaves:
         self._failures: List[tuple[str, str]] = []
         self._dropped = 0
         self._on_save_error = on_save_error
+        self._job_ids: List[str] = []
         self._lock = threading.Lock()
         self._callback_threads: set[int] = set()
 
@@ -250,6 +273,23 @@ class _PendingSaves:
             f"Walrus Memory auto-save failed ({total} call(s)): {detail}"
         )
 
+    def track_job_ids(self, job_ids: List[str]) -> None:
+        """Record the background remember jobs an auto-save enqueued, so a
+        caller can later confirm they finished and read their blob IDs."""
+        if not job_ids:
+            return
+        with self._lock:
+            self._job_ids.extend(job_ids)
+            if len(self._job_ids) > _MAX_TRACKED_JOB_IDS:
+                del self._job_ids[:-_MAX_TRACKED_JOB_IDS]
+
+    def drain_job_ids(self) -> List[str]:
+        """Return every job ID recorded so far and forget them, so a second
+        wait does not re-poll jobs that already settled."""
+        with self._lock:
+            job_ids, self._job_ids = self._job_ids, []
+        return job_ids
+
     def track_task(self, task: "asyncio.Task[Any]") -> None:
         self._tasks.add(task)
         task.add_done_callback(self._tasks.discard)
@@ -333,6 +373,46 @@ class _PendingSaves:
             thread.join()
 
 
+async def _run_auto_save(
+    memwal: MemWal,
+    text: str,
+    namespace: str,
+    save_mode: str,
+    pending: _PendingSaves,
+    log: Callable[..., Any],
+) -> None:
+    """Persist `text` via the configured save mode and record its job IDs.
+
+    ``analyze()`` returns cleanly with zero facts for content it cannot read
+    as spoken facts (code, structured data), so a plain call there looks
+    identical to a successful save. Log in that case and point at
+    ``save_mode="remember"`` rather than dropping the write silently.
+    """
+    try:
+        if save_mode == "remember":
+            accepted = await memwal.remember(text, namespace)
+            if accepted is not None and getattr(accepted, "job_id", None):
+                pending.track_job_ids([accepted.job_id])
+            return
+
+        result = await memwal.analyze(text, namespace)
+        if result is None:
+            return
+        job_ids = list(getattr(result, "job_ids", None) or [])
+        facts = getattr(result, "facts", None)
+        pending.track_job_ids(job_ids)
+        if not facts and not job_ids:
+            log(
+                "[Walrus Memory] Auto-save extracted 0 facts from a "
+                f"{len(text)}-character message and stored nothing. analyze() "
+                "only extracts spoken-fact-style statements — pass "
+                'save_mode="remember" to store the message verbatim instead.'
+            )
+    except Exception as e:  # noqa: BLE001 -- auto-save must never break the LLM call
+        log(f"[Walrus Memory] Auto-save failed: {e}")
+        pending.note_error(e)
+
+
 def _expose_memwal_controls(obj: Any, memwal: MemWal, pending: _PendingSaves) -> None:
     """Attach the underlying client and a way to drain pending auto-saves —
     without this, a short-lived process has no way to avoid silently
@@ -349,9 +429,44 @@ def _expose_memwal_controls(obj: Any, memwal: MemWal, pending: _PendingSaves) ->
     (obj.memwal_flush) still finds it — OpenAI clients aren't Pydantic
     models and work the same way either way.
     """
+    async def memwal_wait_for_saves(
+        opts: Optional[RememberBulkOptions] = None,
+    ) -> RememberBulkResult:
+        """Drain pending auto-saves, then poll their remember jobs to a
+        terminal state and return per-job status + blob IDs."""
+        await pending.flush()
+        job_ids = pending.drain_job_ids()
+        try:
+            return await memwal.wait_for_remember_jobs(job_ids, opts)
+        except Exception:
+            pending.track_job_ids(job_ids)
+            raise
+
+    def memwal_wait_for_saves_sync(
+        opts: Optional[RememberBulkOptions] = None,
+    ) -> RememberBulkResult:
+        """Sync counterpart of ``memwal_wait_for_saves`` for callers on the
+        blocking entry points (``OpenAI``, ``llm.invoke``)."""
+        pending.flush_sync()
+        job_ids = pending.drain_job_ids()
+        try:
+            return _run_blocking(
+                lambda: _with_fresh_http_client(
+                    memwal, memwal.wait_for_remember_jobs(job_ids, opts)
+                )
+            )
+        except Exception:
+            pending.track_job_ids(job_ids)
+            raise
+
     object.__setattr__(obj, "_memwal", memwal)
+    # Public alias: reaching wait_for_remember_jobs() and the rest of the
+    # low-level client shouldn't require touching a private attribute.
+    object.__setattr__(obj, "memwal", memwal)
     object.__setattr__(obj, "memwal_flush", pending.flush)
     object.__setattr__(obj, "memwal_flush_sync", pending.flush_sync)
+    object.__setattr__(obj, "memwal_wait_for_saves", memwal_wait_for_saves)
+    object.__setattr__(obj, "memwal_wait_for_saves_sync", memwal_wait_for_saves_sync)
 
 
 async def _warn_if_cancelled(coro: Any, label: str) -> None:
@@ -416,6 +531,7 @@ def with_memwal_langchain(
     namespace: str = "default",
     max_memories: int = 5,
     auto_save: bool = True,
+    save_mode: str = "analyze",
     min_relevance: float = 0.3,
     debug: bool = False,
     env: Optional[str] = None,
@@ -438,6 +554,11 @@ def with_memwal_langchain(
         namespace: Default namespace.
         max_memories: Max memories to inject per request.
         auto_save: Auto-save new facts from conversation.
+        save_mode: How auto_save persists the user message. ``"analyze"``
+            (default) extracts spoken-fact-style statements and stores one
+            memory per fact — non-sentence content such as code yields zero
+            facts and stores nothing. ``"remember"`` stores the message
+            verbatim as a single memory.
         min_relevance: Minimum similarity score (0-1) to include a memory.
         debug: Enable debug logging.
         env: Optional relayer preset (``"prod"`` / ``"dev"`` / ``"staging"`` /
@@ -458,6 +579,8 @@ def with_memwal_langchain(
             "Install with: pip install memwal[langchain]"
         ) from e
 
+    _validate_save_mode(save_mode)
+
     memwal = MemWal.create(
         key=key,
         account_id=account_id,
@@ -552,16 +675,12 @@ def with_memwal_langchain(
             return messages
 
     async def _post_analyze(messages: List[BaseMessage]) -> None:
-        """Analyze user message for new facts."""
+        """Persist the user message via the configured save mode."""
         if not auto_save or not _is_last_message_user(messages):
             return
         user_text = _find_last_user_message(messages)
         if user_text:
-            try:
-                await memwal.analyze(user_text, namespace)
-            except Exception as e:
-                log(f"[Walrus Memory] Auto-save failed: {e}")
-                pending.note_error(e)
+            await _run_auto_save(memwal, user_text, namespace, save_mode, pending, log)
 
     async def patched_agenerate(
         messages: List[BaseMessage], *args: Any, **kwargs: Any
@@ -604,6 +723,7 @@ def with_memwal_openai(
     namespace: str = "default",
     max_memories: int = 5,
     auto_save: bool = True,
+    save_mode: str = "analyze",
     min_relevance: float = 0.3,
     debug: bool = False,
     env: Optional[str] = None,
@@ -628,6 +748,11 @@ def with_memwal_openai(
         namespace: Default namespace.
         max_memories: Max memories to inject per request.
         auto_save: Auto-save new facts from conversation.
+        save_mode: How auto_save persists the user message. ``"analyze"``
+            (default) extracts spoken-fact-style statements and stores one
+            memory per fact — non-sentence content such as code yields zero
+            facts and stores nothing. ``"remember"`` stores the message
+            verbatim as a single memory.
         min_relevance: Minimum similarity score (0-1) to include a memory.
         debug: Enable debug logging.
         env: Optional relayer preset (``"prod"`` / ``"dev"`` / ``"staging"`` /
@@ -639,6 +764,8 @@ def with_memwal_openai(
     Returns:
         The same client, with ``chat.completions.create`` wrapped to use Walrus Memory.
     """
+    _validate_save_mode(save_mode)
+
     memwal = MemWal.create(
         key=key,
         account_id=account_id,
@@ -654,11 +781,13 @@ def with_memwal_openai(
 
     if is_async:
         _wrap_async_openai(
-            client, memwal, namespace, max_memories, auto_save, min_relevance, log, pending
+            client, memwal, namespace, max_memories, auto_save, save_mode,
+            min_relevance, log, pending,
         )
     else:
         _wrap_sync_openai(
-            client, memwal, namespace, max_memories, auto_save, min_relevance, log, pending
+            client, memwal, namespace, max_memories, auto_save, save_mode,
+            min_relevance, log, pending,
         )
 
     _expose_memwal_controls(client, memwal, pending)
@@ -672,6 +801,7 @@ def _wrap_async_openai(
     namespace: str,
     max_memories: int,
     auto_save: bool,
+    save_mode: str,
     min_relevance: float,
     log: Callable[..., Any],
     pending: _PendingSaves,
@@ -725,18 +855,14 @@ def _wrap_async_openai(
 
         result = await original_create(*args, **kwargs)
 
-        # Fire-and-forget analyze
+        # Fire-and-forget auto-save
         if auto_save and _is_last_message_user(messages):
             user_text = _find_last_user_message(messages)
             if user_text:
-                async def _analyze() -> None:
-                    try:
-                        await memwal.analyze(user_text, namespace)
-                    except Exception as e:
-                        log(f"[Walrus Memory] Auto-save failed: {e}")
-                        pending.note_error(e)
-
-                _fire_and_forget(_analyze(), pending)
+                _fire_and_forget(
+                    _run_auto_save(memwal, user_text, namespace, save_mode, pending, log),
+                    pending,
+                )
 
         return result
 
@@ -749,6 +875,7 @@ def _wrap_sync_openai(
     namespace: str,
     max_memories: int,
     auto_save: bool,
+    save_mode: str,
     min_relevance: float,
     log: Callable[..., Any],
     pending: _PendingSaves,
@@ -807,18 +934,25 @@ def _wrap_sync_openai(
 
         result = original_create(*args, **kwargs)
 
-        # Fire-and-forget analyze
+        # Fire-and-forget auto-save
         if auto_save and _is_last_message_user(messages):
             user_text = _find_last_user_message(messages)
             if user_text:
-                def _analyze() -> None:
+                def _save() -> None:
+                    # _run_auto_save swallows request failures itself; this guards
+                    # the loop/http-client plumbing around it so a failure there
+                    # can't take down the background thread.
                     try:
-                        _run_memwal(lambda: memwal.analyze(user_text, namespace))
-                    except Exception as e:
+                        _run_memwal(
+                            lambda: _run_auto_save(
+                                memwal, user_text, namespace, save_mode, pending, log
+                            )
+                        )
+                    except Exception as e:  # noqa: BLE001
                         log(f"[Walrus Memory] Auto-save failed: {e}")
                         pending.note_error(e)
 
-                pending.spawn_thread(_analyze)
+                pending.spawn_thread(_save)
 
         return result
 

{memwal-0.2.0.dev0 → memwal-0.2.0.dev1}/memwal/mock.py

@@ -12,6 +12,7 @@ from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 from typing import Any, Dict, List, Optional, Sequence, Union
 
+from .client import _check_limit
 from .types import (
     AnalyzedFact,
     AnalyzeResult,
@@ -279,8 +280,7 @@ class MemWalMock:
             sort = None
             query_text = query
         _validate_text(query_text, "query")
-        if not isinstance(limit, int) or limit < 0:
-            raise ValueError("limit must be a non-negative integer")
+        _check_limit(limit)
         if sort not in (None, "relevance", "recent"):
             raise ValueError("sort must be 'relevance' or 'recent'")
         resolved_namespace = self._namespace if namespace is None else namespace
@@ -383,7 +383,7 @@ class MemWalMock:
         )
 
     async def restore(self, namespace: str, limit: int = 10) -> RestoreResult:
-        del limit
+        _check_limit(limit)
         return RestoreResult(
             restored=0,
             skipped=0,
@@ -399,6 +399,8 @@ class MemWalMock:
         cursor: Optional[str] = None,
         limit: Optional[int] = None,
     ) -> NamespacesResult:
+        if limit is not None:
+            _check_limit(limit)
         grouped: Dict[str, List[_Memory]] = {}
         for memory in self._memories:
             grouped.setdefault(memory.namespace, []).append(memory)

{memwal-0.2.0.dev0 → memwal-0.2.0.dev1}/pyproject.toml

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

{memwal-0.2.0.dev0 → memwal-0.2.0.dev1}/tests/test_middleware.py

@@ -26,14 +26,16 @@ import respx
 
 from memwal.client import MemWal
 from memwal.middleware import (
+    _MAX_TRACKED_JOB_IDS,
     _find_last_user_message,
     _format_memories,
     _inject_openai_memory,
     _PendingSaves,
+    _run_auto_save,
     with_memwal_langchain,
     with_memwal_openai,
 )
-from memwal.types import RecallMemory
+from memwal.types import RecallMemory, RememberBulkOptions
 from memwal.utils import bytes_to_hex
 
 # ============================================================
@@ -131,6 +133,27 @@ def _mock_analyze() -> httpx.Response:
     )
 
 
+_REMEMBER_URL = f"{_SERVER}/api/remember"
+_BULK_STATUS_URL = f"{_SERVER}/api/remember/bulk/status"
+
+
+def _mock_analyze_with_facts(*job_ids: str) -> httpx.Response:
+    return httpx.Response(
+        202,
+        json={
+            "facts": [{"text": f"fact {i}", "id": job_id} for i, job_id in enumerate(job_ids)],
+            "job_ids": list(job_ids),
+            "fact_count": len(job_ids),
+            "status": "pending",
+            "owner": "0xowner",
+        },
+    )
+
+
+def _mock_remember_accepted(job_id: str = "job-remember") -> httpx.Response:
+    return httpx.Response(202, json={"job_id": job_id, "status": "pending"})
+
+
 # ============================================================
 # Pure function tests (no mocking needed)
 # ============================================================
@@ -1363,3 +1386,246 @@ class TestPendingSaves:
         else:
             raise AssertionError("flush_sync did not raise")
 
+
+# ============================================================
+# WALM-307: auto_save save_mode + confirmable saves
+# ============================================================
+
+
+class TestAutoSaveMode:
+    """analyze() silently stores nothing for non-fact content (GH #411);
+    save_mode="remember" must store it verbatim instead."""
+
+    def _memwal(self) -> MemWal:
+        return MemWal.create(
+            key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, namespace="default"
+        )
+
+    @respx.mock
+    async def test_analyze_mode_reports_zero_facts_through_wrapper_log(self) -> None:
+        _mock_seal_session_prereqs()
+        respx.post(_ANALYZE_URL).mock(return_value=_mock_analyze())
+
+        pending = _PendingSaves()
+        messages: list = []
+        with patch("memwal.middleware.logger") as mock_logger:
+            await _run_auto_save(
+                self._memwal(), "def f():\n    return 1", "default", "analyze",
+                pending, messages.append,
+            )
+
+        assert not mock_logger.warning.called
+        assert len(messages) == 1
+        assert "save_mode" in messages[0]
+        assert pending.drain_job_ids() == []
+
+    @respx.mock
+    async def test_analyze_mode_tracks_job_ids_without_warning(self) -> None:
+        _mock_seal_session_prereqs()
+        respx.post(_ANALYZE_URL).mock(return_value=_mock_analyze_with_facts("j1", "j2"))
+
+        pending = _PendingSaves()
+        with patch("memwal.middleware.logger") as mock_logger:
+            await _run_auto_save(
+                self._memwal(), "I am allergic to peanuts", "default", "analyze",
+                pending, lambda *_: None,
+            )
+
+        assert not mock_logger.warning.called
+        assert pending.drain_job_ids() == ["j1", "j2"]
+
+    @respx.mock
+    async def test_remember_mode_stores_verbatim_and_skips_analyze(self) -> None:
+        _mock_seal_session_prereqs()
+        analyze_route = respx.post(_ANALYZE_URL).mock(return_value=_mock_analyze())
+        remember_route = respx.post(_REMEMBER_URL).mock(
+            return_value=_mock_remember_accepted("job-1")
+        )
+
+        pending = _PendingSaves()
+        await _run_auto_save(
+            self._memwal(), "def f():\n    return 1", "default", "remember",
+            pending, lambda *_: None,
+        )
+
+        assert remember_route.called
+        assert not analyze_route.called
+        assert pending.drain_job_ids() == ["job-1"]
+
+    def test_invalid_save_mode_rejected_at_wrap_time(self) -> None:
+        client = MagicMock()
+        try:
+            with_memwal_openai(
+                client, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER,
+                save_mode="verbatim",
+            )
+        except ValueError as e:
+            assert "save_mode" in str(e)
+        else:
+            raise AssertionError("expected ValueError for an unknown save_mode")
+
+    def test_drain_job_ids_is_one_shot(self) -> None:
+        pending = _PendingSaves()
+        pending.track_job_ids(["a", "b"])
+        assert pending.drain_job_ids() == ["a", "b"]
+        assert pending.drain_job_ids() == []
+
+    def test_tracked_job_ids_are_capped_keeping_the_newest(self) -> None:
+        pending = _PendingSaves()
+        for i in range(_MAX_TRACKED_JOB_IDS + 5):
+            pending.track_job_ids([f"job-{i}"])
+
+        job_ids = pending.drain_job_ids()
+        assert len(job_ids) == _MAX_TRACKED_JOB_IDS
+        assert job_ids[0] == "job-5"
+        assert job_ids[-1] == f"job-{_MAX_TRACKED_JOB_IDS + 4}"
+
+
+class TestConfirmableSaves:
+    """GH #410/#412: the easy-setup path had no way to confirm a save
+    landed or read its blob ID without dropping to the low-level client."""
+
+    def _make_async_client(self) -> MagicMock:
+        client = MagicMock()
+        client._async_client = MagicMock()
+        mock_response = MagicMock()
+        mock_response.choices = [MagicMock()]
+        mock_response.choices[0].message.content = "answer"
+        client.chat = MagicMock()
+        client.chat.completions = MagicMock()
+        client.chat.completions.create = AsyncMock(return_value=mock_response)
+        return client
+
+    @respx.mock
+    async def test_wait_for_saves_returns_blob_ids(self) -> None:
+        _mock_seal_session_prereqs()
+        respx.post(_RECALL_URL).mock(return_value=_mock_recall([]))
+        respx.post(_REMEMBER_URL).mock(return_value=_mock_remember_accepted("job-1"))
+        respx.post(_BULK_STATUS_URL).mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "results": [
+                        {"job_id": "job-1", "status": "done", "blob_id": "blob-abc"}
+                    ]
+                },
+            )
+        )
+
+        smart = with_memwal_openai(
+            self._make_async_client(), key=_KEY_HEX, account_id=_ACCOUNT_ID,
+            server_url=_SERVER, auto_save=True, save_mode="remember",
+        )
+        await smart.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "def f(): return 1"}],
+        )
+
+        result = await smart.memwal_wait_for_saves(
+            RememberBulkOptions(poll_interval_ms=1, timeout_ms=5000)
+        )
+
+        assert result.total == 1
+        assert result.succeeded == 1
+        assert result.results[0].blob_id == "blob-abc"
+
+    @respx.mock
+    async def test_wrapper_exposes_low_level_client_publicly(self) -> None:
+        _mock_seal_session_prereqs()
+        smart = with_memwal_openai(
+            self._make_async_client(), key=_KEY_HEX, account_id=_ACCOUNT_ID,
+            server_url=_SERVER, auto_save=False,
+        )
+
+        assert isinstance(smart.memwal, MemWal)
+        assert callable(smart.memwal.wait_for_remember_jobs)
+        assert callable(smart.memwal_wait_for_saves)
+        assert callable(smart.memwal_wait_for_saves_sync)
+
+    @respx.mock
+    async def test_failed_wait_leaves_job_ids_for_the_next_wait(self) -> None:
+        _mock_seal_session_prereqs()
+        respx.post(_RECALL_URL).mock(return_value=_mock_recall([]))
+        respx.post(_REMEMBER_URL).mock(return_value=_mock_remember_accepted("job-1"))
+        status_route = respx.post(_BULK_STATUS_URL).mock(
+            return_value=httpx.Response(403, json={"error": "forbidden"})
+        )
+
+        smart = with_memwal_openai(
+            self._make_async_client(), key=_KEY_HEX, account_id=_ACCOUNT_ID,
+            server_url=_SERVER, auto_save=True, save_mode="remember",
+        )
+        await smart.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "def f(): return 1"}],
+        )
+
+        opts = RememberBulkOptions(poll_interval_ms=1, timeout_ms=5000)
+        try:
+            await smart.memwal_wait_for_saves(opts)
+        except Exception:
+            pass
+        else:
+            raise AssertionError("expected the failing poll to raise")
+
+        status_route.mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "results": [
+                        {"job_id": "job-1", "status": "done", "blob_id": "blob-abc"}
+                    ]
+                },
+            )
+        )
+        result = await smart.memwal_wait_for_saves(opts)
+
+        assert result.total == 1
+        assert result.succeeded == 1
+        assert result.results[0].blob_id == "blob-abc"
+
+    @respx.mock
+    async def test_wait_confirms_more_jobs_than_the_relayer_bulk_cap(self) -> None:
+        """21 tracked jobs must confirm, not 400-loop.
+
+        `/api/remember/bulk/status` rejects more than `MAX_BULK_ITEMS` (20)
+        ids with a 400. 400 is not transient, so an unchunked poll raised,
+        the ids were restored for the retry, and every retry hit the same
+        400 — a wait that could never confirm. `save_mode="remember"` is one
+        job per turn, so 21 turns reach this.
+        """
+        _mock_seal_session_prereqs()
+        job_ids = [f"job-{i}" for i in range(21)]
+        seen_chunk_sizes: list[int] = []
+
+        def _status(request: httpx.Request) -> httpx.Response:
+            body = json.loads(request.content)
+            ids = body["job_ids"]
+            seen_chunk_sizes.append(len(ids))
+            if len(ids) > 20:
+                return httpx.Response(
+                    400, json={"error": "job_ids exceeds MAX_BULK_ITEMS"}
+                )
+            return httpx.Response(
+                200,
+                json={
+                    "results": [
+                        {"job_id": jid, "status": "done", "blob_id": f"blob-{jid}"}
+                        for jid in ids
+                    ]
+                },
+            )
+
+        respx.post(_BULK_STATUS_URL).mock(side_effect=_status)
+
+        client = MemWal.create(key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER)
+        result = await client.wait_for_remember_jobs(
+            job_ids, RememberBulkOptions(poll_interval_ms=1, timeout_ms=5000)
+        )
+
+        assert max(seen_chunk_sizes) <= 20, seen_chunk_sizes
+        assert result.total == 21
+        assert result.succeeded == 21
+        assert result.timed_out == 0
+        # Order still follows the caller's input, chunking notwithstanding.
+        assert [r.id for r in result.results] == job_ids

memwal-0.2.0.dev1/tests/test_nonfinite_validation.py

@@ -0,0 +1,238 @@
+"""#1218: non-finite vectors and bad limits must fail client-side.
+
+json.dumps emits bare NaN/Infinity tokens, which are not JSON, so the
+relayer rejected the body with an opaque parse error. Limits went out as
+NaN, -5 or ?limit=nan.
+"""
+
+from __future__ import annotations
+
+import math
+
+import httpx
+import pytest
+
+from memwal import (
+    MemWal,
+    MemWalError,
+    MemWalMock,
+    RecallManualOptions,
+    RecallParams,
+    RememberManualOptions,
+)
+
+
+class CaptureMemWal(MemWal):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.captured = []
+
+    async def _ensure_compatible_relayer(self):
+        return {
+            "apiVersion": "1.0.0",
+            "relayerVersion": "capture",
+            "minSupportedSdk": {"python": "0.0.0"},
+        }
+
+    async def _resolve_owner(self):
+        return "0xowner"
+
+    async def _signed_request(
+        self,
+        method,
+        path,
+        body,
+        accepted_statuses=(200,),
+        include_seal_session=True,
+        timeout=None,
+    ):
+        self.captured.append((method, path, body))
+        if path.startswith("/v1/owners"):
+            return {"namespaces": [], "has_more": False, "snapshot_version": 1}
+        if path == "/api/remember/manual":
+            return {"id": "1", "blob_id": "b", "owner": "0x1", "namespace": "default"}
+        if path == "/api/restore":
+            return {"restored": 0, "skipped": 0, "total": 0, "namespace": "ns", "owner": "0x1"}
+        return {"results": [], "total": 0}
+
+
+class FreshOwnerMemWal(MemWal):
+    """Keeps the real ``_resolve_owner``, so owner lookup goes through signing.
+
+    Every signed request is recorded and then fails, like a relayer outage:
+    a bad limit must surface as ValueError, not as this error.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.signed = []
+
+    async def _ensure_compatible_relayer(self):
+        return {
+            "apiVersion": "1.0.0",
+            "relayerVersion": "capture",
+            "minSupportedSdk": {"python": "0.0.0"},
+        }
+
+    async def _signed_request(
+        self,
+        method,
+        path,
+        body,
+        accepted_statuses=(200,),
+        include_seal_session=True,
+        timeout=None,
+    ):
+        self.signed.append((method, path))
+        raise MemWalError("relayer unavailable")
+
+
+def _client():
+    return CaptureMemWal.create(
+        key="11" * 32, account_id="0x" + "ab" * 32, server_url="https://relayer.example"
+    )
+
+
+BAD_VECTORS = [
+    [0.1, math.nan],
+    [math.inf],
+    [0.1, -math.inf],
+    [],
+    [0.1, "0.2"],
+    [0.1, None],
+    [True, 0.2],
+    "0.1,0.2",
+    None,
+]
+BAD_LIMITS = [math.nan, math.inf, -5, -1, 0, 2.5, "5", True]
+
+
+@pytest.mark.parametrize("vector", BAD_VECTORS, ids=repr)
+async def test_recall_manual_rejects_bad_vector(vector):
+    c = _client()
+    with pytest.raises(ValueError, match="vector"):
+        await c.recall_manual(RecallManualOptions(vector=vector))
+    assert c.captured == []
+
+
+@pytest.mark.parametrize("vector", BAD_VECTORS, ids=repr)
+async def test_remember_manual_rejects_bad_vector(vector):
+    c = _client()
+    with pytest.raises(ValueError, match="vector"):
+        await c.remember_manual(RememberManualOptions(encrypted_data="AAAA", vector=vector))
+    assert c.captured == []
+
+
+@pytest.mark.parametrize("limit", BAD_LIMITS, ids=repr)
+@pytest.mark.parametrize(
+    "call",
+    [
+        ("recall", lambda c, n: c.recall("q", limit=n)),
+        ("recall_params", lambda c, n: c.recall(RecallParams(query="q", limit=n))),
+        ("recall_manual", lambda c, n: c.recall_manual(RecallManualOptions(vector=[0.1], limit=n))),
+        ("restore", lambda c, n: c.restore("ns", limit=n)),
+        ("list_namespaces", lambda c, n: c.list_namespaces(limit=n)),
+    ],
+    ids=lambda x: x[0],
+)
+async def test_bad_limit_is_rejected_before_signing(call, limit):
+    c = _client()
+    with pytest.raises(ValueError, match="limit"):
+        await call[1](c, limit)
+    assert c.captured == []
+
+
+async def test_valid_inputs_still_go_out_unchanged():
+    c = _client()
+    await c.recall_manual(RecallManualOptions(vector=[0.1, -2, 0], limit=3))
+    await c.remember_manual(RememberManualOptions(encrypted_data="AAAA", vector=[1, 0.5]))
+    await c.recall("q", limit=1)
+    await c.restore("ns", limit=50)
+    await c.list_namespaces(limit=500)
+    await c.list_namespaces()
+    bodies = [b for _, _, b in c.captured]
+    assert bodies[0]["vector"] == [0.1, -2, 0] and bodies[0]["limit"] == 3
+    assert bodies[1]["vector"] == [1, 0.5]
+    assert bodies[2]["limit"] == 1
+    assert bodies[3]["limit"] == 50
+    assert c.captured[4][1].endswith("?limit=500")
+    assert "limit" not in c.captured[5][1]
+
+
+async def test_signed_request_never_emits_nan_tokens(monkeypatch):
+    """Backstop: even if a NaN reaches the signer, it must not be serialised."""
+    client = MemWal.create(
+        key="11" * 32, account_id="0x" + "ab" * 32, server_url="https://relayer.example"
+    )
+
+    async def compatible():
+        return {
+            "apiVersion": "1.0.0",
+            "relayerVersion": "t",
+            "minSupportedSdk": {"python": "0.0.0"},
+        }
+
+    sent = []
+
+    async def fake_post(*args, **kwargs):  # pragma: no cover - must not be reached
+        sent.append(kwargs)
+        raise AssertionError("request sent with a non-JSON body")
+
+    monkeypatch.setattr(client, "_ensure_compatible_relayer", compatible)
+    monkeypatch.setattr(httpx.AsyncClient, "send", fake_post)
+    with pytest.raises(ValueError):
+        await client._signed_request(
+            "POST", "/api/recall", {"limit": math.nan}, include_seal_session=False
+        )
+    assert sent == []
+    await client.close()
+
+
+@pytest.mark.parametrize("limit", BAD_LIMITS, ids=repr)
+async def test_list_namespaces_bad_limit_raises_before_owner_lookup(limit):
+    """The owner lookup is a signed POST /api/stats; a bad limit must not reach it."""
+    c = FreshOwnerMemWal.create(
+        key="11" * 32, account_id="0x" + "ab" * 32, server_url="https://relayer.example"
+    )
+    with pytest.raises(ValueError, match="limit"):
+        await c.list_namespaces(limit=limit)
+    assert c.signed == []
+    await c.close()
+
+
+async def test_list_namespaces_valid_limit_still_resolves_owner():
+    c = FreshOwnerMemWal.create(
+        key="11" * 32, account_id="0x" + "ab" * 32, server_url="https://relayer.example"
+    )
+    with pytest.raises(MemWalError, match="relayer unavailable"):
+        await c.list_namespaces(limit=5)
+    assert c.signed == [("POST", "/api/stats")]
+    await c.close()
+
+
+@pytest.mark.parametrize("limit", BAD_LIMITS, ids=repr)
+@pytest.mark.parametrize(
+    "call",
+    [
+        ("recall", lambda m, n: m.recall("q", limit=n)),
+        ("recall_params", lambda m, n: m.recall(RecallParams(query="q", limit=n))),
+        ("ask", lambda m, n: m.ask("q", limit=n)),
+        ("restore", lambda m, n: m.restore("ns", limit=n)),
+        ("list_namespaces", lambda m, n: m.list_namespaces(limit=n)),
+    ],
+    ids=lambda x: x[0],
+)
+async def test_mock_rejects_the_same_bad_limits_as_the_client(call, limit):
+    mock = MemWalMock.create()
+    await mock.remember("a fact")
+    with pytest.raises(ValueError, match="limit"):
+        await call[1](mock, limit)
+
+
+async def test_mock_accepts_positive_integer_limits():
+    mock = MemWalMock.create()
+    await mock.remember("a fact")
+    assert len((await mock.recall("fact", limit=1)).results) == 1
+    assert (await mock.restore("ns", limit=1)).restored == 0
+    assert len((await mock.list_namespaces(limit=1)).namespaces) == 1
+    assert len((await mock.list_namespaces()).namespaces) == 1