Feat: memory deletion — clearNamespace / forget / list (soft-delete) [WALM-115]

[hungtranphamminh]

Summary

Why

The SDK exposed remember/recall/restore but no way to delete a memory or clear a namespace. After an agent reset, stale memories keep surfacing in recall() — reported by two Walrus-Sessions-4 integrators (#258, +1 in-thread): a reset agent self-anchored on its own discarded outputs, and "day-one vs day-four" demo integrity broke on the same wallet. The only workaround (rotate the namespace string) orphans data forever.

What

Adds owner-scoped memory deletion across the stack. Deletion is soft — a deleted memory immediately stops surfacing in recall(), but the underlying Walrus blob persists (un-recallable, not erased).

• clearNamespace(ns) — soft-delete every memory in a namespace (the reset primitive).
• forget(id) — soft-delete a single memory by its per-row id.
• list(ns, { limit, cursor }) — enumerate a namespace (metadata only — id, blob_id, created_at, importance; no decrypted text), cursor-paginated via has_more / next_cursor.

Delivered in: the relayer (/api/clear-namespace, /api/list, /api/memories/forget) plus a deleted_at migration, the TS SDK (0.0.8), and the Python SDK (0.1.5) — with unit + e2e tests and public API-reference docs (relayer + both SDKs). MCP sidecar tools are included but dormant — see Related.

Solution

• Soft-delete via a deleted_at tombstone (migration 010): deletion stops a memory surfacing in recall() (and the analyze pre-extraction context) while retaining the row. The underlying Walrus blob is user-owned and persists — "delete" means un-recallable, not cryptographically erased (carried honestly in all docstrings). Fits the privacy floor: no new server-readable plaintext.
• The existing hard /api/forget is left untouched for benchmark-harness cleanup; clearNamespace is a separate soft path.
• list() keyset pagination on (created_at, id) (stable tie-break, no skip/dup under concurrent deletes); metadata-only so it's decrypt-free.
• Owner-scoped everywhere — every query binds the auth-derived owner; forget(id) of an id you don't own is a clean no-op (no cross-owner existence oracle).

Types of Changes

• Breaking change (existing functionality would change)
• New feature (non-breaking)
• Bug fix (non-breaking)
• Performance optimization
• Refactor (no behavior change)
• Dependency update
• Documentation
• Test
• Security / permission-scope change

Testing

• Tested locally
• Added/updated unit tests
• Added/updated integration tests
• cargo test / harness tests pass

Checklist

• Follows the project's commit + code conventions
• No ticket IDs / competitor names / local-doc paths in code comments
• Docs updated if needed
• Respects the privacy floor (no server-readable plaintext index)
• All new and existing tests pass

Related

• Closes No way to delete memories or clear a namespace — stale memories pollute recall after agent resets #258 (delete / clear namespace). Acknowledged in-thread by both reporting integrators.
• Linear: WALM-115.
• MCP is deferred to a separate go-live PR. The sidecar tools (memwal_clear_namespace / memwal_list / memwal_forget) are added but dormant: the sidecar's Docker build installs a pinned published SDK that predates these methods, so the tools resolve them only once the sidecar is built against the new SDK. No MCP version bump in this PR.
• Follow-ups (separate tickets): MCP go-live (sidecar build → pnpm/workspace); hard-purge/erasure job (must filter deleted_at IS NULL in restore's blob-discovery).