twin memory

Expiry

Give an item an expiry and memory forgets it at that time, with everything learned from it, as a forget would.

Some things should be remembered for a while and then let go: a one-time code, a trip plan, a temporary preference. Set expires on the item when you add it.

{
  "items": [
    {
      "id": "trip-doc",
      "kind": "document",
      "title": "Porto trip plan",
      "expires": "2026-12-31",
      "text": "Day 1: train from Lisbon to Porto at 08:00. Day 2: Ribeira walk and port tasting."
    }
  ]
}

expires takes a date (2026-12-31, which is midnight UTC at the start of that day) or a full ISO time with an offset (2026-12-31T18:00:00+01:00). A time without an offset is taken as UTC.

What happens at the expiry

From the expiry time on:

  • No read returns it. Before memory answers any request for that end user, it erases every item whose expiry has passed. So no search, grep, read, history or MCP tool call shows the item, or anything learned from it, after its time.
  • It is erased as forget erases. The stored item, its passages and index entries, the records read from it, the values and pages built from those, and every version are deleted. A background sweep does this at the expiry time even if no request arrives.
  • One line stays. /v1/memory/versions answers state: "expired" with one line saying when it went, and nothing of what it said.

An item added with an expiry already in the past is erased before the next request is answered.

Move or lift an expiry

Send the item again with the same id:

  • with a new expires, to move it earlier or later;
  • with "expires": null, to lift it, so the item is kept until you forget it.

Sent again without expires, as when you fix a typo, the item keeps the expiry it had.

Each change is a new version. The item's text and its place in search do not change.

Send the change before the expiry passes. Once an item has expired it is gone; adding the same id again adds it as a new item.

Expiry and status

After an item expires, status reports it as unknown, as for a forgotten item.

Versions & edits

Sending an item again with the same id edits it, and every version memory took is kept for your backend until the item goes.

Erasure & receipts

Forget erases items, sessions or threads with every copy and everything learned from them, and returns a receipt counting what went.

On this page

What happens at the expiryMove or lift an expiryExpiry and statusRelated