History · twin memory

Every dated value recorded for one subject, attribute by attribute, each with the day it held from and the turns it was read from.

POST /v1/memory/historyAuth: read key

When a conversation is read in the background, statements of state become assertions: a subject, an attribute, a value and the day it held from. History returns every assertion for one subject. Nothing is overwritten, so an old value and the new one both appear. Makes no model call. See Values and history.

History is empty until the end user's items have been read.

Headers

Authorizationstringrequired

Bearer tm_…. A read key is enough.

X-Twin-Accountstringrequired

The end user whose memory to read. See End users.

X-Request-Idstring

Your id for this request, echoed on the response.

Body

subjectstringrequired

Who or what, by the name memory files it under, such as Alice Chen. Case and spacing do not matter. 1 to 512 characters. A name that misses returns the nearest recorded subjects.

attributestring

Only this attribute, such as home_city. Matched exactly.

Response

subjectstring

The subject as sent.

countinteger

How many assertions came back.

assertionsobject[]

Sorted by attribute, then by valid_from, oldest first. Each has subject, attribute, value, valid_from (the day it held from), polarity (1, or -1 when the statement says the value is not, never was, or stopped being true) and source_turn_ids, the event ids it was read from.

errorstring

nothing recorded, when the subject has no assertions.

subjectsstring[]

With error: up to 10 recorded subjects nearest the name sent.

recordedinteger

With error: how many subjects this memory has assertions for.

Errors

400bad request

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

401unauthorized

The bearer is not a key this service issued.

404not found

no memory for end user 'user_42' yet.

422invalid

An empty subject.

503unavailable

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

Request

curl https://api.twinmemory.dev/v1/memory/history \
  -H "Authorization: Bearer $TWIN_MEMORY_API_KEY" \
  -H "X-Twin-Account: user_42" \
  -H "Content-Type: application/json" \
  -d '{ "subject": "Alice Chen" }'

200 OK

{
  "subject": "Alice Chen",
  "count": 3,
  "assertions": [
    {
      "subject": "alice chen",
      "attribute": "employer",
      "value": "Acme",
      "valid_from": "2026-10-01",
      "polarity": 1,
      "source_turn_ids": ["ev_620270db0bff9328"]
    },
    {
      "subject": "alice chen",
      "attribute": "home_city",
      "value": "Berlin",
      "valid_from": "2024-03-01",
      "polarity": 1,
      "source_turn_ids": ["ev_c2cef398cd2bc8ac"]
    },
    {
      "subject": "alice chen",
      "attribute": "home_city",
      "value": "Lisbon",
      "valid_from": "2026-10-01",
      "polarity": 1,
      "source_turn_ids": ["ev_620270db0bff9328"]
    }
  ]
}

200 OK, a subject that misses

{
  "subject": "Alice",
  "error": "nothing recorded",
  "subjects": ["alice-chen"],
  "recorded": 1
}