memwal 0.2.1.dev0__tar.gz → 0.2.2__tar.gz

{memwal-0.2.1.dev0 → memwal-0.2.2}/CHANGELOG.md

@@ -1,13 +1,30 @@
 # memwal
 
+## 0.2.2
+
+Unreleased.
+
+### Added
+
+- `forget(namespace=None)` (and alias `forget_namespace(namespace=None)`) on `MemWal` and `MemWalSync` wraps `POST /api/forget` and returns `ForgetResult` (`deleted`, `namespace`, `owner`). It deletes the owner's index rows for the namespace while leaving Walrus blobs in place. `MemWalMock` and `MemWalMockSync` retain synchronous per-blob `forget(blob_id) -> bool` and add `forget_namespace(namespace=None) -> ForgetResult` for namespace erasure. (#1061)
+- `MemWal.destroy()` and `MemWalSync.destroy()` (plus `close(clear_keys=True)`) zero the client's internal `bytearray` seed copy in place, clear `_private_key_hex`, drop `_signing_key` and cached SEAL session credentials, cancel in-flight initialization tasks, and reject any subsequent or in-flight operation with `MemWalError`. `MemWal.create()` and `MemWalSync.create()` also accept 32-byte `bytes` / `bytearray` keys and copy caller `bytearray` buffers so `destroy()` leaves the caller's buffer intact. (#975)
+
+### Fixed
+
+- `health()`, `compatibility()`, `_fetch_server_config()`, package-version preflight probes, and `_signed_request()` raise `MemWalJsonBodyError` (a `MemWalError` subclass carrying `.status`, `.endpoint`, and `.body`) instead of Python's raw `json.JSONDecodeError` when a 2xx response has an empty or non-JSON body. (#1219)
+- Shield shared `_build_seal_session` and `_resolve_owner` initialization tasks with `asyncio.shield`, clear the shared task slot via a completion callback that consumes exceptions on orphaned tasks, and cancel/drain in-flight initialization tasks in `close()` so cancelling one concurrent caller does not abort sibling callers or leave unretrieved task exceptions. (#1029)
+- `health`, `ask`, `restore`, `list_namespaces`, `remember_manual`, and `recall` raise `MemWalError` naming the endpoint and field when a 2xx response omits a required field. They used to raise a bare `KeyError` that callers catching `MemWalError` never saw. (#1250, #1256)
+- `ask()` rejects a blank `question` and a `limit` that is not a positive integer before it signs the request. A NaN `limit` used to serialize as an invalid-JSON `NaN` token, and negative or fractional values were sent as-is. (#1249, #1255)
+- `recall()` rejects a blank `query` and a `max_distance` that is NaN, infinite, negative, or not a number before it signs the request, and `MemWalMock.recall()` rejects the same `max_distance`. A NaN or negative threshold used to return an empty page that looked like an empty namespace. (#1248, #1254)
+
 ## 0.2.1
 
 Unreleased.
 
 ### 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)
+- `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. (#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.
 
 - Save confirmation preserves unconfirmed job IDs when an async wait is cancelled or a synchronous wait is interrupted, then propagates the cancellation or interrupt. (#1303)
 - Reject explicitly empty namespaces instead of silently writing to the default namespace. (#1265)
@@ -28,7 +45,7 @@ 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)
+- `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. (#1096)
 - `RecallMemory` and `RecallManualHit` include `created_at` and `score`. (#1178)
 - `RecallParams` accepts `scoring_weights` and `sort`. `recall()` forwards them on `POST /api/recall`. (#1062)
 
@@ -36,18 +53,18 @@ Unreleased.
 
 - The default `server_url` is `https://relayer.memory.walrus.xyz`, matching the TypeScript SDK. `env="local"` still selects `http://127.0.0.1:8000`. (#1064)
 - `remember` derives an idempotency key from the namespace and text inside a 30-minute bucket, matching the TypeScript SDK. A retry inside that window reuses the job. An explicit `idempotency_key` still wins. `remember_bulk_async` still sends no key. (#1094)
-- `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)
+- `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. (#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)
-- A job the bulk status response omits stays pending and is asked about again. It used to drop out and settle as `timeout`. (WALM-660)
+- `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. (#967)
+- A job the bulk status response omits stays pending and is asked about again. It used to drop out and settle as `timeout`.
 - `wait_for_remember_job` retries a transport error and stops at the caller's deadline. `Retry-After` may be a number of seconds or an HTTP date. (#1000, #1151)
-- `MemWalRememberJobTimeout` carries `last_status`, `server_error` and `last_refusal`, and its message names the relayer's last reported state. Under upload congestion a job stays `running` for up to ~25 minutes while the relayer retries, and the timeout used to hide that, so a job that was still retrying looked dead. (WALM-670, #966)
-- A `max_distance` filter keeps the relayer's matching `total` instead of replacing it with the number of rows left. (WALM-840)
+- `MemWalRememberJobTimeout` carries `last_status`, `server_error` and `last_refusal`, and its message names the relayer's last reported state. Under upload congestion a job stays `running` for up to ~25 minutes while the relayer retries, and the timeout used to hide that, so a job that was still retrying looked dead. (#966)
+- A `max_distance` filter keeps the relayer's matching `total` instead of replacing it with the number of rows left.
 - Middleware does not recall or auto-save on a tool-execution step. A later tool step reuses the cached recall. `flush()` raises when a background save failed, and `on_save_error` runs. The memory instruction is anchored at the start of the prompt. (#1107, #1117, #1159)
 - `normalize_private_key` accepts an uppercase `0X` prefix. Error text redacts IPv6, `0.0.0.0`, and `localhost` subdomains. (#1172, #1161)
-- Grow `wait_for_remember_job` / `wait_for_remember_jobs` poll delay 1.5× from the caller interval (floor 100ms) toward a 5s cap, with an immediate first poll. Backoff is disabled above the cap. (WALM-623)
-- A 429 during a remember-job wait is reported on the timeout. Retry-After is still clamped to the caller's remaining budget, and that remainder still buys one status read. (WALM-623)
+- Grow `wait_for_remember_job` / `wait_for_remember_jobs` poll delay 1.5× from the caller interval (floor 100ms) toward a 5s cap, with an immediate first poll. Backoff is disabled above the cap.
+- A 429 during a remember-job wait is reported on the timeout. Retry-After is still clamped to the caller's remaining budget, and that remainder still buys one status read.
 
 ## 0.1.11
 
@@ -67,7 +84,7 @@ Unreleased.
 
 - HTTP 503 with `x-auth-error: AUTH_UPSTREAM_UNAVAILABLE` is reported as a retryable credential-verification outage, not a sign-in failure. Other 503s keep the generic sanitized body.
 - `remember_bulk_async` rejects an empty `items` list before the request and raises when the relayer returns a `job_ids` length that does not match the batch.
-- restore `truncated` docs now match WALM-431 retryable semantics.
+- restore `truncated` docs now match the relayer’s retryable-incomplete semantics.
 - Warn when `server_url` uses plaintext `http://` against a non-localhost host, matching the TypeScript SDK `normalizeServerUrl` guard. Localhost, `127.0.0.1`, `::1`, and `*.localhost` are exempt; invalid URLs are left for the HTTP client to surface. The warning logs only scheme, host, and port so URL userinfo is not written to logs.
 
 ## 0.1.8

{memwal-0.2.1.dev0 → memwal-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memwal
-Version: 0.2.1.dev0
+Version: 0.2.2
 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
@@ -147,7 +147,7 @@ async def test_memory_flow():
     assert "dark mode" in result.results[0].text
 ```
 
-The mock supports remember/job polling, bulk remember, recall, analyze, embed, ask, health, restore, list_namespaces, `forget(blob_id)`, and `clear(namespace)`. For deterministic behavior, `analyze` stores its full input as one fact instead of invoking an LLM extractor. Its simple relevance score is for application tests, not production search-quality evaluation.
+The mock supports remember/job polling, bulk remember, recall, analyze, embed, ask, health, restore, list_namespaces, `forget(blob_id)` (synchronous per-blob deletion returning `bool`), `forget_namespace(namespace?)` (namespace erasure returning `ForgetResult`), and `clear(namespace?)`. For deterministic behavior, `analyze` stores its full input as one fact instead of invoking an LLM extractor. Its simple relevance score is for application tests, not production search-quality evaluation.
 
 ### Context Manager
 
@@ -181,7 +181,7 @@ memwal = MemWal.create(
 |-------|-------------|
 | `prod` | `https://relayer.memory.walrus.xyz` |
 | `dev` | `https://relayer.dev.memwal.ai` |
-| `staging` | `https://relayer-staging.memory.walrus.xyz` |
+| `staging` | `https://relayer.dev.memwal.ai` |
 
 Precedence: any explicit **`server_url` wins over `env`**, including the hosted
 default. `env` applies only when `server_url` is omitted (`None`). An unknown
@@ -254,11 +254,22 @@ Create a new async client.
 | `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 |
+| `await forget(namespace?)` | Delete index rows for the namespace. Walrus blobs stay. Returns `ForgetResult`. |
 | `await list_namespaces(cursor?, limit?)` | List namespaces that hold memories; paginate on `has_more` |
 | `await health()` | Check server health |
 | `await remember_manual(opts)` | Store encrypted payload + pre-computed vector |
 | `await recall_manual(opts)` | Search with pre-computed vector |
 | `await get_public_key_hex()` | Get Ed25519 public key |
+| `destroy()` | Zero internal key seed buffer, drop signing credentials/session cache, and permanently invalidate the client |
+| `await close(clear_keys=False)` | Close the underlying HTTP client (pass `clear_keys=True` to also run `destroy()`) |
+
+### Key Lifecycle & `destroy()`
+
+For parity with the TypeScript SDK's `destroy()`, `MemWal` and `MemWalSync` expose `destroy()` and `close(clear_keys=True)`:
+
+- `key` may be passed as a hex string, `suiprivkey1...` string, or a 32-byte `bytes` / `bytearray`. When passed as `bytearray`, the SDK copies the bytes into its own internal buffer so `destroy()` zeroes only the client's copy and leaves the caller's `bytearray` untouched.
+- Calling `destroy()` (or `await client.close(clear_keys=True)` / `sync_client.close(clear_keys=True)`) zero-fills the client's internal `bytearray` seed copy in place, clears `_private_key_hex`, drops the `_signing_key` and cached SEAL session references, cancels any in-flight initialization tasks, and causes subsequent or in-flight calls to raise `MemWalError`.
+- **CPython memory semantics**: Python `str` and `bytes` objects (and PyNaCl's internal C-level `SigningKey` buffers) are immutable in CPython and cannot be overwritten in place from pure Python. `destroy()` zeroes the mutable `bytearray` copy and drops all references to immutable key objects so they become eligible for garbage collection once the caller also releases its references. To minimize plaintext `str` copies in process memory, pass a 32-byte `bytearray` to `MemWal.create()` and zero your own buffer after creation.
 
 ## Authentication
 

{memwal-0.2.1.dev0 → memwal-0.2.2}/README.md

@@ -106,7 +106,7 @@ async def test_memory_flow():
     assert "dark mode" in result.results[0].text
 ```
 
-The mock supports remember/job polling, bulk remember, recall, analyze, embed, ask, health, restore, list_namespaces, `forget(blob_id)`, and `clear(namespace)`. For deterministic behavior, `analyze` stores its full input as one fact instead of invoking an LLM extractor. Its simple relevance score is for application tests, not production search-quality evaluation.
+The mock supports remember/job polling, bulk remember, recall, analyze, embed, ask, health, restore, list_namespaces, `forget(blob_id)` (synchronous per-blob deletion returning `bool`), `forget_namespace(namespace?)` (namespace erasure returning `ForgetResult`), and `clear(namespace?)`. For deterministic behavior, `analyze` stores its full input as one fact instead of invoking an LLM extractor. Its simple relevance score is for application tests, not production search-quality evaluation.
 
 ### Context Manager
 
@@ -140,7 +140,7 @@ memwal = MemWal.create(
 |-------|-------------|
 | `prod` | `https://relayer.memory.walrus.xyz` |
 | `dev` | `https://relayer.dev.memwal.ai` |
-| `staging` | `https://relayer-staging.memory.walrus.xyz` |
+| `staging` | `https://relayer.dev.memwal.ai` |
 
 Precedence: any explicit **`server_url` wins over `env`**, including the hosted
 default. `env` applies only when `server_url` is omitted (`None`). An unknown
@@ -213,11 +213,22 @@ Create a new async client.
 | `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 |
+| `await forget(namespace?)` | Delete index rows for the namespace. Walrus blobs stay. Returns `ForgetResult`. |
 | `await list_namespaces(cursor?, limit?)` | List namespaces that hold memories; paginate on `has_more` |
 | `await health()` | Check server health |
 | `await remember_manual(opts)` | Store encrypted payload + pre-computed vector |
 | `await recall_manual(opts)` | Search with pre-computed vector |
 | `await get_public_key_hex()` | Get Ed25519 public key |
+| `destroy()` | Zero internal key seed buffer, drop signing credentials/session cache, and permanently invalidate the client |
+| `await close(clear_keys=False)` | Close the underlying HTTP client (pass `clear_keys=True` to also run `destroy()`) |
+
+### Key Lifecycle & `destroy()`
+
+For parity with the TypeScript SDK's `destroy()`, `MemWal` and `MemWalSync` expose `destroy()` and `close(clear_keys=True)`:
+
+- `key` may be passed as a hex string, `suiprivkey1...` string, or a 32-byte `bytes` / `bytearray`. When passed as `bytearray`, the SDK copies the bytes into its own internal buffer so `destroy()` zeroes only the client's copy and leaves the caller's `bytearray` untouched.
+- Calling `destroy()` (or `await client.close(clear_keys=True)` / `sync_client.close(clear_keys=True)`) zero-fills the client's internal `bytearray` seed copy in place, clears `_private_key_hex`, drops the `_signing_key` and cached SEAL session references, cancels any in-flight initialization tasks, and causes subsequent or in-flight calls to raise `MemWalError`.
+- **CPython memory semantics**: Python `str` and `bytes` objects (and PyNaCl's internal C-level `SigningKey` buffers) are immutable in CPython and cannot be overwritten in place from pure Python. `destroy()` zeroes the mutable `bytearray` copy and drops all references to immutable key objects so they become eligible for garbage collection once the caller also releases its references. To minimize plaintext `str` copies in process memory, pass a 32-byte `bytearray` to `MemWal.create()` and zero your own buffer after creation.
 
 ## Authentication
 

{memwal-0.2.1.dev0 → memwal-0.2.2}/memwal/__init__.py

@@ -27,6 +27,7 @@ from .client import (
     MemWalClockDriftError,
     MemWalCompatibilityError,
     MemWalError,
+    MemWalJsonBodyError,
     MemWalRateLimited,
     MemWalRememberJobFailed,
     MemWalRememberJobNotFound,
@@ -43,6 +44,7 @@ from .types import (
     AskMemory,
     AskResult,
     EmbedResult,
+    ForgetResult,
     HealthResult,
     MemWalConfig,
     NamespacesResult,
@@ -83,6 +85,7 @@ __all__ = [
     "MemWalError",
     "MemWalCompatibilityError",
     "MemWalClockDriftError",
+    "MemWalJsonBodyError",
     "MemWalRateLimited",
     "MemWalRememberJobFailed",
     "MemWalRememberJobNotFound",
@@ -118,6 +121,7 @@ __all__ = [
     "AnalyzedFact",
     "HealthResult",
     "RestoreResult",
+    "ForgetResult",
     "NamespaceSummary",
     "NamespacesResult",
     "ScoringWeights",
@@ -128,4 +132,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.2.1.dev0"
+__version__ = "0.2.2"