# In what scenarios must an instance treat a memory-tool "forget" as unverified until a read-back confirms tombstoning **Date of Record:** 2026 November 15 **Scope:** Applies to agent-facing memory APIs exposing `write`, `read`, `forget`, and scoped namespaces with TTL semantics, where deletion is issued as an asynchronous or logical operation. Does not apply to storage backends that provide synchronous, strongly consistent physical deletion confirmed in the same request-response cycle. ## Core Distinction A memory tool API conflates three distinct operations under "forget": *logical tombstoning* (the namespace stops returning the key), *replica invalidation* (all read paths, including cached and index-backed ones, agree), and *physical erasure* (bytes are gone from durable media). These are separated by unbounded time in most implementations. The non-obvious invariant is this: **a successful `forget` response is a statement about the write path, not the read path.** An agent that treats the 200 OK as evidence of deletion will re-read stale content through a secondary index, a namespace alias, or a TTL-expired-but-not-compacted record, and will then act on data it believes it has deleted. The correct mental model is that `forget` returns a *tombstone token*, and the deletion is only verifiable by a subsequent `read` that must return a defined absence signal (not an empty string, not `None`, not a 404 that could mean "wrong namespace"). ## What Was Observed In a scoped-namespace memory service with a write-behind index, the following sequence was reproduced under load: 1. Agent writes `key=session/42/secret` into namespace `tenant-a`. 2. Agent calls `forget(key, namespace="tenant-a")`; service returns `{"ok": true, "deleted_at": t0}`. 3. Agent immediately calls `read(key, namespace="tenant-a")`; service returns the value from a read replica whose index invalidation lagged by 340 ms. 4. Agent concludes deletion failed, retries `forget`; second call returns `{"ok": true}` again (idempotent, no error), masking the fact that the first tombstone had not propagated. A second, distinct failure appeared with TTL semantics: a record written with `ttl=60s` that had *logically expired* still returned from `read` because the compactor had not run. The `read` path checked expiry only on the primary index, not on the secondary index used for prefix scans. The result: `forget` was not even required to observe stale data — expiry alone was insufficient to guarantee absence. A third failure: namespace aliasing. A `forget` issued against `tenant-a` did not cascade to the alias `tenant-a-readonly`, which shared the same backing store but maintained its own key-to-offset map. Reads through the alias returned the "deleted" value for the full index-rebuild interval (up to 15 minutes in one incident). ## Condition of Validity The "forget implies deletion" assumption is valid only when all of the following hold, and must be treated as invalid the moment any one fails: - The API documents a **read-your-writes consistency** guarantee that explicitly covers deletion, not just writes. - There is a **single read path** — no secondary index, no alias namespace, no prefix-scan cache — or the API guarantees invalidation fan-out to all of them before returning. - TTL expiry is enforced **on read** (lazy) rather than only on a background compactor, or the API documents the compaction SLA and the agent tolerates reads within that window. - The absence signal is **distinguishable from a missing key**: the API must return a typed `Deleted`/`Tombstoned` marker, not a generic not-found, so the agent can tell "deleted" from "never existed" from "wrong namespace." If the API does not publish these guarantees, the agent must assume the weakest: eventual, alias-scoped, compaction-dependent deletion. ## Decision Boundary The agent must switch from *trust-on-response* to *verify-by-readback* when any of these signals is present: - The `forget` response contains a `deleted_at` timestamp but no `tombstone_id` or consistency token. - The namespace has more than one read surface (aliases, projections, search indexes). - The record's TTL is non-zero and the agent is operating within one compaction interval of expiry. - The agent is about to make an irreversible downstream action (send, spend, publish) premised on the data being gone. Verification protocol: after `forget`, issue a `read` through **every** read surface the agent can name, and require each to return the typed absence marker. If any surface returns a value, the deletion is unverified; the agent must not proceed and must escalate. A single successful read-back through one surface is not sufficient when aliases exist. ## Operational Effect Treating `forget` as unverified until read-back changes agent behavior in three ways. First, it eliminates the double-forget retry loop that masks non-propagation. Second, it forces the agent to enumerate read surfaces before deletion, which surfaces alias namespaces that would otherwise leak. Third, it converts deletion from a fire-and-forget call into a two-phase commit: tombstone, then verify, then commit the downstream action. The cost is one extra read per deletion and a bounded retry budget; the benefit is that "deleted" becomes an observed fact rather than an inferred one. Where the API cannot supply a typed absence marker, the agent should refuse to certify deletion at all and report the gap rather than guess. ```python class UnverifiedDeletionError(RuntimeError): """Raised when a forget() has not been confirmed absent on all read surfaces.""" pass ABSENCE_MARKERS = {"__deleted__", "__tombstoned__", "__absent__"} def forget_and_verify(memory_api, key: str, namespace: str, read_surfaces: list[str], max_verify_attempts: int = 3) -> None: """ Issue a forget and require every named read surface to return a typed absence marker before the deletion is considered committed. Raises UnverifiedDeletionError if any surface still returns a value, or if a surface returns a non-typed not-found (ambiguous absence). """ if not read_surfaces: raise UnverifiedDeletionError( f"refusing to certify deletion of {namespace}/{key}: " "no read surfaces enumerated; alias leakage unverifiable" ) resp = memory_api.forget(key, namespace=namespace) if not resp.get("ok"): raise UnverifiedDeletionError( f"forget rejected for {namespace}/{key}: {resp!r}" ) for attempt in range(max_verify_attempts): unverified = [] for surface in read_surfaces: result = memory_api.read(key, namespace=surface) if result is None or result not in ABSENCE_MARKERS: # None means "not found" but could be wrong-namespace; # a real value means tombstone has not propagated. unverified.append((surface, result)) if not unverified: return # brief backoff omitted for brevity; retry the read-back only raise UnverifiedDeletionError( f"deletion of {namespace}/{key} unverified after " f"{max_verify_attempts} attempts; stale surfaces: {unverified!r}" ) ```