Forget · twin memory

Hard-delete items, sessions, threads or events from one end user's memory, with every copy and everything learned from them, and get a receipt.

POST /v1/memory/forgetAuth: write key

Forget erases what you name from the end user's memory: the ledger entries, the passages cut from them, their words in the index and their vectors, the facts and assertions read from them, every version, and every page that quoted them. A thread with nothing left goes whole. Copies still waiting to land are removed too. Makes no model call. See Erasure and receipts.

Each erased event id is kept as a tombstone, so a copy still on its way in cannot bring it back. Adding the same item again on purpose lifts the tombstone.

The cost is linear in this end user's history: the rest of their memory is rebuilt from what remains.

Headers

Authorizationstringrequired

Bearer tm_…. The key must read and write.

X-Twin-Accountstringrequired

The end user to erase from. See End users.

X-Request-Idstring

Your id for this request, echoed on the response.

Body

itemsstring[]

Item ids as you gave them to add. Up to 500.

sessionsstring[]

Sessions, every day of each. Up to 500.

threadsstring[]

Thread ids (th_…), as results return them. Up to 500.

eventsstring[]

Event ids (ev_…). Up to 500.

At least one list must name something. Any mix is allowed.

Response

eventsinteger

How many events were erased. 0 when nothing matched.

threads_emptiedinteger

Threads with nothing left, removed whole.

ledgerinteger

Ledger entries deleted.

recordsinteger

Facts deleted: those citing an erased event, or read from a window that held one.

assertionsinteger

Assertion lines deleted.

correctionsinteger

Retractions resting on an erased event, deleted.

actionsinteger

Action lines deleted.

lessonsinteger

Lessons deleted.

unowned_vectorsinteger

Vectors no passage or fact owns any more, deleted.

log_emptiedboolean

Whether the database's write-ahead log was emptied after the delete.

tablesobject

Row counts for this end user, before and after, per table: events, threads, passages, mentions, facts, vectors, codes, parties, withdrawals, passages_fts, facts_fts, files. files can rise: the tombstone and the pages folded again are written.

inboxinteger

Items accepted and not yet landed, removed before they landed.

versionsinteger

Item versions erased.

queueinteger | null

Copies removed from the delivery queue. null when the queue could not be reached; the erasure from memory stands either way, and you can send the same request again.

When nothing matched, the receipt is {"events": 0, "inbox": 0, "versions": 0, "queue": 0}.

Errors

400bad request

X-Twin-Account is missing or not a usable id.

401unauthorized

The bearer is not a key this service issued.

403forbidden

this key reads; writing takes a key that writes.

413too large

body over 1000000 bytes.

422invalid

forget names nothing: give events, threads, items or sessions, or a list over 500.

503unavailable

At capacity, or this end user is being rebuilt. Retry after Retry-After seconds.

Request

curl https://api.twinmemory.dev/v1/memory/forget \
  -H "Authorization: Bearer $TWIN_MEMORY_API_KEY" \
  -H "X-Twin-Account: user_42" \
  -H "Content-Type: application/json" \
  -d '{ "items": ["pref-diet"] }'

200 OK

{
  "events": 1,
  "threads_emptied": 1,
  "lessons": 0,
  "ledger": 1,
  "records": 0,
  "corrections": 0,
  "actions": 0,
  "assertions": 0,
  "unowned_vectors": 0,
  "log_emptied": true,
  "tables": {
    "events": { "before": 4, "after": 3 },
    "threads": { "before": 3, "after": 2 },
    "passages": { "before": 3, "after": 2 },
    "mentions": { "before": 13, "after": 11 },
    "facts": { "before": 0, "after": 0 },
    "vectors": { "before": 0, "after": 0 },
    "codes": { "before": 0, "after": 0 },
    "parties": { "before": 2, "after": 2 },
    "withdrawals": { "before": 0, "after": 0 },
    "passages_fts": { "before": 3, "after": 2 },
    "facts_fts": { "before": 0, "after": 0 },
    "files": { "before": 18, "after": 19 }
  },
  "inbox": 0,
  "versions": 2,
  "queue": 0
}