memwal 0.1.11.dev8__tar.gz → 0.1.11.dev10__tar.gz

{memwal-0.1.11.dev8 → memwal-0.1.11.dev10}/CHANGELOG.md

@@ -2,8 +2,13 @@
 
 ## Unreleased
 
+### Added
+
+- `get_remember_status(job_id)` on `MemWal` and `MemWalSync` returns `RememberJobStatus` from `GET /api/remember/{job_id}`, accepting 200 and 404 like the TypeScript SDK. (WALM-832, #1096)
+
 ### Fixed
 
+- `get_remember_status` and `wait_for_remember_job` reject a job id outside `[A-Za-z0-9_-]+` before the request. `.`, `..`, a backslash, and encoded dot-dot used to pass a denylist and be rewritten after signing. An empty id used to call `GET /api/remember/` and raise `json.JSONDecodeError`. An unparseable 404 is `not_found` / `MemWalRememberJobNotFound`, not a JSON error. `uuid.UUID` is coerced with `str()`. Valid UUID job ids are unchanged. (WALM-833, #1100, #1216)
 - `remember`, `remember_bulk`, `analyze`, and `embed` reject whitespace-only text before the request. A blank body used to be accepted and then sit until the caller timed out. (#1129)
 - A 401 `AUTH_REJECTED` now says a wallet address is not a MemWal account ID. (#1132)
 - `wait_for_remember_jobs` / `remember_bulk_and_wait` no longer return a batch they could not read as if it were still uploading. When every status poll is rate-limited, the wait makes one confirming read and raises `MemWalRateLimited` (`status` 429, `job_ids`, `retry_after`) if that is refused too. An item still unsettled at the deadline names its last known status, or says no read got through. (WALM-671, #967)

{memwal-0.1.11.dev8 → memwal-0.1.11.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memwal
-Version: 0.1.11.dev8
+Version: 0.1.11.dev10
 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
@@ -240,6 +240,7 @@ Create a new async client.
 | Method | Description |
 |--------|-------------|
 | `await remember(text, namespace?)` | Accept a background remember job and return `job_id` |
+| `await get_remember_status(job_id)` | Read one remember job without waiting |
 | `await wait_for_remember_job(job_id, ...)` | Poll one remember job until it is searchable |
 | `await remember_and_wait(text, namespace?, ...)` | Store a memory and wait until it is searchable |
 | `await remember_bulk(items)` | Accept several background remember jobs |

{memwal-0.1.11.dev8 → memwal-0.1.11.dev10}/README.md

@@ -201,6 +201,7 @@ Create a new async client.
 | Method | Description |
 |--------|-------------|
 | `await remember(text, namespace?)` | Accept a background remember job and return `job_id` |
+| `await get_remember_status(job_id)` | Read one remember job without waiting |
 | `await wait_for_remember_job(job_id, ...)` | Poll one remember job until it is searchable |
 | `await remember_and_wait(text, namespace?, ...)` | Store a memory and wait until it is searchable |
 | `await remember_bulk(items)` | Accept several background remember jobs |

{memwal-0.1.11.dev8 → memwal-0.1.11.dev10}/memwal/__init__.py

@@ -128,4 +128,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.1.11.dev8"
+__version__ = "0.1.11.dev10"

{memwal-0.1.11.dev8 → memwal-0.1.11.dev10}/memwal/client.py

@@ -27,6 +27,7 @@ from __future__ import annotations
 
 import asyncio
 import base64
+import hashlib
 import json
 import logging
 import math
@@ -68,6 +69,7 @@ from .types import (
     RememberBulkResult,
     RememberBulkStatusItem,
     RememberBulkStatusResult,
+    RememberJobStatus,
     RememberManualOptions,
     RememberManualResult,
     RememberResult,
@@ -136,6 +138,55 @@ def _reject_blank_text(text: object, message: str = "Text cannot be empty") -> N
         raise ValueError(message)
 
 
+IDEMPOTENCY_BUCKET_MS = 30 * 60 * 1000
+
+
+def _derived_idempotency_key(request_identity: str) -> str:
+    """Window over which the same (namespace, text) resolves to one key.
+
+    `_pending_remember_keys` only dedupes retries that reuse one client instance,
+    and callers such as sidecars or serverless functions build a fresh client
+    per session — so a random key lets a replay mint a second paid blob. The
+    bucket bounds the collapse: `remember_jobs` rows are never pruned, so an
+    unbucketed key would dedupe against a job from any point in history.
+
+    Matches TypeScript SDK derivedIdempotencyKey contract.
+    """
+    bucket = int(time.time() * 1000) // IDEMPOTENCY_BUCKET_MS
+    payload = f"{bucket}\0{request_identity}".encode("utf-8")
+    return f"r1-{hashlib.sha256(payload).hexdigest()}"
+
+
+def _require_remember_job_id(job_id: object) -> str:
+    """String form of a remember job id.
+
+    ``uuid.UUID`` used to interpolate into the path and still does. Any other
+    non-string is a type mistake: ``not_found`` would hide a job that exists.
+    """
+
+    if isinstance(job_id, uuid.UUID):
+        return str(job_id)
+    if not isinstance(job_id, str):
+        raise TypeError(
+            f"remember job id must be a string, got {type(job_id).__name__}"
+        )
+    return job_id
+
+
+def _remember_status_path(job_id: str) -> Optional[str]:
+    """``/api/remember/{job_id}`` when the id is one safe segment, else None.
+
+    httpx rewrites the path after it is signed. ``.`` requests
+    ``/api/remember``, ``..`` requests ``/api``, and a NUL raises
+    ``InvalidURL``. An allowlist keeps those from leaving the client. A
+    normal UUID is unchanged. (#1100, #1216)
+    """
+
+    if re.fullmatch(r"[A-Za-z0-9_-]+", job_id) is None:
+        return None
+    return f"/api/remember/{job_id}"
+
+
 def normalize_server_url(url: str) -> str:
     """Strip a trailing slash and warn on plaintext HTTP to a remote host.
 
@@ -466,9 +517,11 @@ class MemWal:
         resolved_namespace = namespace or self._namespace
         request_identity = f"{resolved_namespace}\0{text}"
         generated_key = idempotency_key is None
-        resolved_key = idempotency_key or self._pending_remember_keys.get(request_identity)
-        if resolved_key is None:
-            resolved_key = str(uuid.uuid4())
+        resolved_key = (
+            idempotency_key
+            or self._pending_remember_keys.get(request_identity)
+            or _derived_idempotency_key(request_identity)
+        )
         if generated_key:
             self._pending_remember_keys[request_identity] = resolved_key
 
@@ -502,6 +555,55 @@ class MemWal:
         remaining_s = (deadline_ms - _now_ms()) / 1000.0
         return max(0.001, min(60.0, remaining_s))
 
+    async def get_remember_status(self, job_id: str) -> RememberJobStatus:
+        """One-shot lookup of a remember job. Mirrors TS ``getRememberStatus``.
+
+        ``GET /api/remember/{job_id}``, accepting 200 and 404. A 404, or a
+        body with no ``status``, is ``not_found`` — not an exception. A job
+        id outside ``[A-Za-z0-9_-]+`` is ``not_found`` without a request.
+        """
+
+        job_id = _require_remember_job_id(job_id)
+        path = _remember_status_path(job_id)
+        if path is None:
+            return RememberJobStatus(
+                job_id=job_id,
+                status="not_found",
+                error=f"Job {job_id} not found",
+            )
+        try:
+            data = await self._signed_request(
+                "GET",
+                path,
+                {},
+                accepted_statuses=(200, 404),
+                # Status is metadata. No SEAL decrypt, so no session. Matches TS.
+                include_seal_session=False,
+            )
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            data = None
+        if not isinstance(data, dict):
+            return RememberJobStatus(
+                job_id=job_id,
+                status="not_found",
+                error=f"remember job not found: {job_id}",
+            )
+        status = data.get("status")
+        if not status:
+            return RememberJobStatus(
+                job_id=data.get("job_id") or job_id,
+                status="not_found",
+                error=data.get("error") or f"remember job not found: {job_id}",
+            )
+        return RememberJobStatus(
+            job_id=data.get("job_id", job_id),
+            status=status,
+            owner=data.get("owner"),
+            namespace=data.get("namespace"),
+            blob_id=data.get("blob_id"),
+            error=data.get("error"),
+        )
+
     async def wait_for_remember_job(
         self,
         job_id: str,
@@ -520,6 +622,11 @@ class MemWal:
         - First poll is immediate; later polls grow 1.5x toward 5s.
         """
 
+        job_id = _require_remember_job_id(job_id)
+        path = _remember_status_path(job_id)
+        if path is None:
+            raise MemWalRememberJobNotFound(job_id)
+
         deadline_ms = _now_ms() + timeout_ms
         attempt = 0
         saw_rate_limit = False
@@ -541,7 +648,7 @@ class MemWal:
                 try:
                     data = await self._signed_request(
                         "GET",
-                        f"/api/remember/{job_id}",
+                        path,
                         {},
                         accepted_statuses=(200, 404),
                         timeout=poll_timeout,
@@ -550,12 +657,14 @@ class MemWal:
                     if "unexpected keyword argument" in str(err) and "timeout" in str(err):
                         data = await self._signed_request(
                             "GET",
-                            f"/api/remember/{job_id}",
+                            path,
                             {},
                             accepted_statuses=(200, 404),
                         )
                     else:
                         raise
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                raise MemWalRememberJobNotFound(job_id) from None
             except _HttpStatusError as err:
                 if _is_transient_polling_status(err.status):
                     last_refusal = err.status
@@ -570,6 +679,8 @@ class MemWal:
                 last_refusal = 0
                 continue
 
+            if not isinstance(data, dict):
+                raise MemWalRememberJobNotFound(job_id)
             status_str = data.get("status")
             if status_str is None or status_str == "not_found":
                 raise MemWalRememberJobNotFound(job_id)
@@ -615,12 +726,15 @@ class MemWal:
         ``failed``). Mirrors TS ``rememberAndWait``.
         """
 
+        _reject_blank_text(text)
         resolved_namespace = namespace or self._namespace
         request_identity = f"{resolved_namespace}\0{text}"
         generated_key = idempotency_key is None
-        resolved_key = idempotency_key or self._pending_remember_keys.get(request_identity)
-        if resolved_key is None:
-            resolved_key = str(uuid.uuid4())
+        resolved_key = (
+            idempotency_key
+            or self._pending_remember_keys.get(request_identity)
+            or _derived_idempotency_key(request_identity)
+        )
         if generated_key:
             self._pending_remember_keys[request_identity] = resolved_key
 
@@ -1610,7 +1724,6 @@ class MemWal:
             - ``x-account-id``: Walrus Memory account object ID
             - ``Content-Type``: application/json
         """
-        import uuid
 
         await self._ensure_compatible_relayer()
 
@@ -1940,6 +2053,10 @@ class MemWalSync:
     ) -> RememberAcceptedResult:
         return self._run(self._inner.remember_async(text, namespace, idempotency_key))
 
+    def get_remember_status(self, job_id: str) -> RememberJobStatus:
+        """Synchronous version of :meth:`MemWal.get_remember_status`."""
+        return self._run(self._inner.get_remember_status(job_id))
+
     def wait_for_remember_job(
         self,
         job_id: str,

{memwal-0.1.11.dev8 → memwal-0.1.11.dev10}/pyproject.toml

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

{memwal-0.1.11.dev8 → memwal-0.1.11.dev10}/tests/test_client.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import base64
 import json
 import time
+import uuid
 from datetime import datetime, timedelta, timezone
 from typing import Any, Sequence
 
@@ -24,6 +25,7 @@ from memwal.client import (
     MemWalCompatibilityError,
     MemWalError,
     MemWalRateLimited,
+    MemWalRememberJobNotFound,
     MemWalRememberJobTimeout,
     MemWalSync,
     _HttpStatusError,
@@ -36,6 +38,7 @@ from memwal.types import (
     RememberBulkOptions,
     RememberBulkStatusItem,
     RememberBulkStatusResult,
+    RememberJobStatus,
     RememberManualOptions,
     ScoringWeights,
 )
@@ -642,6 +645,151 @@ class TestRememberJobTimeoutDetail:
         )
 
 
+# ============================================================
+# one-job remember status
+# ============================================================
+
+
+_NORMAL_JOB_ID = "550e8400-e29b-41d4-a716-446655440000"
+
+
+class TestRememberJobStatus:
+    @respx.mock
+    async def test_unsafe_job_id_is_not_requested(self, memwal_client: MemWal) -> None:
+        route = respx.route().mock(return_value=httpx.Response(500, text="nope"))
+        for job_id in ("", "abc/def?x=1", "job 1", "a\tb", "?", "/", ".", "..", "%2e%2e", "a\\b"):
+            status = await memwal_client.get_remember_status(job_id)
+            assert status == RememberJobStatus(
+                job_id=job_id,
+                status="not_found",
+                error=f"Job {job_id} not found",
+            )
+            with pytest.raises(MemWalRememberJobNotFound) as exc:
+                await memwal_client.wait_for_remember_job(
+                    job_id, poll_interval_ms=0, timeout_ms=5_000
+                )
+            assert exc.value.status == 404
+            assert exc.value.job_id == job_id
+            assert not isinstance(exc.value, json.JSONDecodeError)
+        assert route.call_count == 0
+
+    async def test_non_string_job_id_is_a_type_error(self, memwal_client: MemWal) -> None:
+        with pytest.raises(TypeError):
+            await memwal_client.get_remember_status(1)  # type: ignore[arg-type]
+        with pytest.raises(TypeError):
+            await memwal_client.wait_for_remember_job(1, poll_interval_ms=0, timeout_ms=5_000)  # type: ignore[arg-type]
+
+    @respx.mock
+    async def test_uuid_object_reads_the_string_path(self, memwal_client: MemWal) -> None:
+        _mock_version()
+        job = uuid.UUID(_NORMAL_JOB_ID)
+        route = respx.get(f"{_TEST_SERVER}/api/remember/{job}").mock(
+            return_value=httpx.Response(200, json={"job_id": str(job), "status": "running"})
+        )
+        status = await memwal_client.get_remember_status(job)  # type: ignore[arg-type]
+        assert status.status == "running"
+        assert status.job_id == str(job)
+        assert route.call_count == 1
+
+    @respx.mock
+    async def test_non_object_404_body_is_not_found(self, memwal_client: MemWal) -> None:
+        mock_seal_session_prereqs()
+        route = respx.get(f"{_TEST_SERVER}/api/remember/job-1")
+        for body in (b"null", b"[]", b'"Not Found"', b"<html>nope</html>"):
+            route.mock(return_value=httpx.Response(404, content=body))
+            status = await memwal_client.get_remember_status("job-1")
+            assert status.status == "not_found"
+            assert status.job_id == "job-1"
+            with pytest.raises(MemWalRememberJobNotFound) as exc:
+                await memwal_client.wait_for_remember_job(
+                    "job-1", poll_interval_ms=0, timeout_ms=5_000
+                )
+            assert exc.value.status == 404
+
+    @respx.mock
+    async def test_empty_404_body_is_not_found(self, memwal_client: MemWal) -> None:
+        mock_seal_session_prereqs()
+        respx.get(f"{_TEST_SERVER}/api/remember/job-1").mock(
+            return_value=httpx.Response(404, content=b"")
+        )
+        status = await memwal_client.get_remember_status("job-1")
+        assert status.status == "not_found"
+        assert status.job_id == "job-1"
+        with pytest.raises(MemWalRememberJobNotFound) as exc:
+            await memwal_client.wait_for_remember_job(
+                "job-1", poll_interval_ms=0, timeout_ms=5_000
+            )
+        assert exc.value.status == 404
+
+    @respx.mock
+    async def test_reads_a_normal_job_id(self, memwal_client: MemWal) -> None:
+        mock_seal_session_prereqs()
+        route = respx.get(f"{_TEST_SERVER}/api/remember/{_NORMAL_JOB_ID}").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "job_id": _NORMAL_JOB_ID,
+                    "status": "done",
+                    "blob_id": "blob-1",
+                    "owner": "0xowner",
+                    "namespace": "profile",
+                },
+            )
+        )
+
+        status = await memwal_client.get_remember_status(_NORMAL_JOB_ID)
+        assert status == RememberJobStatus(
+            job_id=_NORMAL_JOB_ID,
+            status="done",
+            owner="0xowner",
+            namespace="profile",
+            blob_id="blob-1",
+        )
+        assert "x-seal-session" not in route.calls[0].request.headers
+
+        result = await memwal_client.wait_for_remember_job(
+            _NORMAL_JOB_ID, poll_interval_ms=0, timeout_ms=5_000
+        )
+        assert result.blob_id == "blob-1"
+        assert result.namespace == "profile"
+        assert [str(call.request.url) for call in route.calls] == [
+            f"{_TEST_SERVER}/api/remember/{_NORMAL_JOB_ID}",
+            f"{_TEST_SERVER}/api/remember/{_NORMAL_JOB_ID}",
+        ]
+
+    @respx.mock
+    def test_sync_reads_a_normal_job_id(self) -> None:
+        _mock_version()
+        route = respx.get(f"{_TEST_SERVER}/api/remember/{_NORMAL_JOB_ID}").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "job_id": _NORMAL_JOB_ID,
+                    "status": "running",
+                    "namespace": "profile",
+                },
+            )
+        )
+        client = MemWalSync.create(
+            key=_TEST_KEY_HEX,
+            account_id=_TEST_ACCOUNT_ID,
+            server_url=_TEST_SERVER,
+        )
+        try:
+            missing = client.get_remember_status("")
+            assert missing.status == "not_found"
+            with pytest.raises(MemWalRememberJobNotFound):
+                client.wait_for_remember_job("abc/def?x=1", poll_interval_ms=0, timeout_ms=5_000)
+            status = client.get_remember_status(_NORMAL_JOB_ID)
+            assert status.status == "running"
+            assert status.namespace == "profile"
+            assert str(route.calls[0].request.url) == (
+                f"{_TEST_SERVER}/api/remember/{_NORMAL_JOB_ID}"
+            )
+        finally:
+            client.close()
+
+
 # ============================================================
 # recall() tests
 # ============================================================

memwal-0.1.11.dev10/tests/test_remember_derived_key.py

@@ -0,0 +1,250 @@
+"""
+Tests for derived idempotency keys in Python SDK (GH #1094, WALM-800).
+
+Validates parity with TypeScript SDK specification:
+- An omitted idempotency_key is derived from bucket + namespace + text:
+  r1-{sha256(bucket \0 namespace \0 text)}
+- Repeated identical writes reuse the same idempotency key across client instances
+- Different texts or namespaces produce distinct keys
+- Explicit idempotency keys are respected
+- MemWalSync synchronous wrapper inherits the same behavior
+"""
+
+import hashlib
+import json
+import time
+from unittest.mock import patch
+
+import httpx
+import pytest
+import respx
+
+from memwal.client import (
+    IDEMPOTENCY_BUCKET_MS,
+    MemWal,
+    MemWalRememberJobTimeout,
+    MemWalSync,
+    _derived_idempotency_key,
+)
+from memwal.utils import bytes_to_hex
+
+_TEST_KEY_HEX = bytes_to_hex(b"\x01" * 32)
+_TEST_ACCOUNT_ID = "0xabc123"
+_TEST_SERVER = "http://localhost:8000"
+
+
+def _make_client(namespace: str = "default") -> MemWal:
+    client = MemWal.create(
+        key=_TEST_KEY_HEX,
+        account_id=_TEST_ACCOUNT_ID,
+        server_url=_TEST_SERVER,
+        namespace=namespace,
+    )
+    # Cache a valid seal session (expiry in milliseconds) to avoid needing live Sui RPC
+    client._session_cache = ("fake-seal-session", int(time.time() * 1000) + 3_600_000)
+    return client
+
+
+def _mock_version_and_config():
+    respx.get(f"{_TEST_SERVER}/version").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "apiVersion": "1.0.0",
+                "relayerVersion": "1.0.0",
+                "minSupportedSdk": {"python": "0.1.0"},
+            },
+        )
+    )
+    respx.get(f"{_TEST_SERVER}/config").mock(
+        return_value=httpx.Response(
+            200,
+            json={"packageId": "0x1", "network": "testnet"},
+        )
+    )
+
+
+def test_derived_idempotency_key_format_and_cross_language_parity():
+    """Verify byte-for-byte SHA256 digest parity with TypeScript SDK."""
+    bucket = 123456
+    request_identity = "default\0I am allergic to peanuts"
+
+    # Pre-calculated reference matching TypeScript:
+    # r1-${sha256("123456\0default\0I am allergic to peanuts")}
+    expected_digest = hashlib.sha256(f"{bucket}\0{request_identity}".encode("utf-8")).hexdigest()
+    expected_key = f"r1-{expected_digest}"
+    assert expected_key == "r1-8690455a552eca1cc0d77d60b2a7c2a05a2dd836874f5106b1c9967dc5adc083"
+
+    with patch("time.time", return_value=(bucket * IDEMPOTENCY_BUCKET_MS) / 1000.0):
+        actual_key = _derived_idempotency_key(request_identity)
+        assert actual_key == expected_key
+        assert actual_key.startswith("r1-")
+        assert len(actual_key) == 3 + 64
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_same_fact_reuses_one_idempotency_key_across_client_instances():
+    """Two instances build what sidecars or serverless functions run on reconnect.
+
+    A per-instance random uuid4 made the replay look like a new write, so the
+    relayer minted a second paid Walrus blob. The content-based derived key
+    ensures both send the identical key.
+    """
+    _mock_version_and_config()
+    posted_bodies = []
+
+    def handle_remember(request: httpx.Request) -> httpx.Response:
+        posted_bodies.append(json.loads(request.content))
+        return httpx.Response(202, json={"job_id": "job-1", "status": "pending"})
+
+    respx.post(f"{_TEST_SERVER}/api/remember").mock(side_effect=handle_remember)
+    respx.get(f"{_TEST_SERVER}/api/remember/job-1").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "job_id": "job-1",
+                "status": "done",
+                "blob_id": "blob-1",
+                "owner": _TEST_ACCOUNT_ID,
+                "namespace": "default",
+            },
+        )
+    )
+
+    client1 = _make_client()
+    await client1.remember_and_wait("a durable fact")
+
+    client2 = _make_client()
+    await client2.remember_and_wait("a durable fact")
+
+    assert len(posted_bodies) == 2
+    assert posted_bodies[0]["idempotency_key"] == posted_bodies[1]["idempotency_key"]
+    assert posted_bodies[0]["idempotency_key"].startswith("r1-")
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_remember_async_reuses_derived_key():
+    """remember() (async accept) also derives the content key."""
+    _mock_version_and_config()
+    posted_bodies = []
+
+    def handle_remember(request: httpx.Request) -> httpx.Response:
+        posted_bodies.append(json.loads(request.content))
+        job_id = f"job-{len(posted_bodies)}"
+        return httpx.Response(202, json={"job_id": job_id, "status": "pending"})
+
+    respx.post(f"{_TEST_SERVER}/api/remember").mock(side_effect=handle_remember)
+
+    client = _make_client()
+    await client.remember("user likes pizza")
+    await client.remember("user likes pizza")
+
+    assert len(posted_bodies) == 2
+    assert posted_bodies[0]["idempotency_key"] == posted_bodies[1]["idempotency_key"]
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_different_text_and_namespaces_get_different_keys():
+    """Distinct writes must not collapse onto one job."""
+    _mock_version_and_config()
+    posted_bodies = []
+
+    def handle_remember(request: httpx.Request) -> httpx.Response:
+        posted_bodies.append(json.loads(request.content))
+        job_id = f"job-{len(posted_bodies)}"
+        return httpx.Response(202, json={"job_id": job_id, "status": "pending"})
+
+    respx.post(f"{_TEST_SERVER}/api/remember").mock(side_effect=handle_remember)
+
+    client = _make_client()
+    await client.remember("fact one")
+    await client.remember("fact two")
+    await client.remember("fact one", namespace="other-namespace")
+
+    keys = [b["idempotency_key"] for b in posted_bodies]
+    assert len(set(keys)) == 3, "distinct writes must produce distinct keys"
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_explicit_idempotency_key_still_wins():
+    """When the caller passes an explicit key, that key is sent directly."""
+    _mock_version_and_config()
+    posted_bodies = []
+
+    def handle_remember(request: httpx.Request) -> httpx.Response:
+        posted_bodies.append(json.loads(request.content))
+        return httpx.Response(202, json={"job_id": "job-explicit", "status": "pending"})
+
+    respx.post(f"{_TEST_SERVER}/api/remember").mock(side_effect=handle_remember)
+
+    client = _make_client()
+    await client.remember("a fact", idempotency_key="caller-owned-key")
+
+    assert len(posted_bodies) == 1
+    assert posted_bodies[0]["idempotency_key"] == "caller-owned-key"
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_remember_and_wait_preserves_key_on_polling_timeout():
+    """If polling times out, the pending key stays in the map for immediate retry."""
+    _mock_version_and_config()
+    posted_bodies = []
+
+    def handle_remember(request: httpx.Request) -> httpx.Response:
+        posted_bodies.append(json.loads(request.content))
+        return httpx.Response(202, json={"job_id": "slow-job", "status": "pending"})
+
+    respx.post(f"{_TEST_SERVER}/api/remember").mock(side_effect=handle_remember)
+    respx.get(f"{_TEST_SERVER}/api/remember/slow-job").mock(
+        return_value=httpx.Response(200, json={"job_id": "slow-job", "status": "running"})
+    )
+
+    client = _make_client()
+    with pytest.raises(MemWalRememberJobTimeout):
+        await client.remember_and_wait("timeout fact", poll_interval_ms=10, timeout_ms=50)
+
+    # Key must still be in pending map
+    request_identity = "default\0timeout fact"
+    assert request_identity in client._pending_remember_keys
+    pending_key = client._pending_remember_keys[request_identity]
+
+    # Retry uses the exact same pending key
+    with pytest.raises(MemWalRememberJobTimeout):
+        await client.remember_and_wait("timeout fact", poll_interval_ms=10, timeout_ms=50)
+
+    assert len(posted_bodies) == 2
+    assert posted_bodies[0]["idempotency_key"] == pending_key
+    assert posted_bodies[1]["idempotency_key"] == pending_key
+
+
+@respx.mock
+def test_sync_client_uses_derived_key():
+    """MemWalSync synchronous client derives and reuses content keys."""
+    _mock_version_and_config()
+    posted_bodies = []
+
+    def handle_remember(request: httpx.Request) -> httpx.Response:
+        posted_bodies.append(json.loads(request.content))
+        return httpx.Response(202, json={"job_id": "job-sync", "status": "pending"})
+
+    respx.post(f"{_TEST_SERVER}/api/remember").mock(side_effect=handle_remember)
+
+    sync_client = MemWalSync.create(
+        key=_TEST_KEY_HEX,
+        account_id=_TEST_ACCOUNT_ID,
+        server_url=_TEST_SERVER,
+        namespace="default",
+    )
+    sync_client._inner._session_cache = ("fake-seal-session", int(time.time() * 1000) + 3_600_000)
+
+    sync_client.remember("sync fact")
+    sync_client.remember("sync fact")
+
+    assert len(posted_bodies) == 2
+    assert posted_bodies[0]["idempotency_key"] == posted_bodies[1]["idempotency_key"]
+    assert posted_bodies[0]["idempotency_key"].startswith("r1-")