Lineage · twin memory

Follow an item to everything it became - passages, facts, assertions, lines of what is known - or a fact back to the words it was read from.

POST /v1/memory/lineageAuth: read key

Lineage answers both ways. Give it an item id or an event id, and it returns what rests on that item. Give it a fact id from search, and it returns the events and passages the fact was read from. It walks the same edges forget deletes along, so what lineage says an item became is what forgetting it would remove. Makes no model call. See Lineage.

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

idstringrequired

An item id as you gave it to add, an event id (ev_…), or a fact id as search returns it (th_…#r…). 1 to 512 characters.

Response: of an item or event

ofstring

The id as sent.

eventsstring[]

The event ids it names.

passagesobject[]

The passages quoting it, each with id and path.

recordsobject[]

The facts resting on it, each with id, kind and text.

assertionsobject[]

The assertion lines resting on it, each with its path and the assertion's fields.

corestring[]

The lines of what is known that were made from those facts.

Response: of a fact

ofstring

The id as sent.

recordobject

The fact's kind and text.

eventsobject[]

The events it was read from, each with id and ledger path.

passagesobject[]

The passages holding those events, each with id and path.

Response: unknown id

ofstring

The id as sent.

errorstring

no event, item or record by this id in this account.

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 id.

503unavailable

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

Request

curl https://api.twinmemory.dev/v1/memory/lineage \
  -H "Authorization: Bearer $TWIN_MEMORY_API_KEY" \
  -H "X-Twin-Account: user_42" \
  -H "Content-Type: application/json" \
  -d '{ "id": "msg-001" }'

200 OK, of an item

{
  "of": "msg-001",
  "events": ["ev_620270db0bff9328"],
  "passages": [
    {
      "id": "th_8b5e5d4c8946d815/p_0001",
      "path": "passages/memory/messages/th_8b5e5d4c8946d815/p_0001.md"
    }
  ],
  "records": [
    { "id": "th_8b5e5d4c8946d815#r028d461216652fe5", "kind": "state", "text": "Alice lives in Lisbon" },
    { "id": "th_8b5e5d4c8946d815#rc052ae969cbe2551", "kind": "state", "text": "Alice works at Acme" }
  ],
  "assertions": [
    {
      "path": "assertions/alice-chen.jsonl",
      "subject": "alice chen",
      "attribute": "home_city",
      "value": "Lisbon",
      "valid_from": "2026-10-01",
      "polarity": 1,
      "source_turn_ids": ["ev_620270db0bff9328"]
    }
  ],
  "core": ["- Alice Chen · home_city: Lisbon [said 2026-10-01]; Berlin [said 2024-06-01]"]
}

200 OK, of a fact

{
  "of": "th_8b5e5d4c8946d815#r028d461216652fe5",
  "record": { "kind": "state", "text": "Alice lives in Lisbon" },
  "events": [
    {
      "id": "ev_620270db0bff9328",
      "path": "raw/memory/messages/2026-10-01/ev_620270db0bff9328.json"
    }
  ],
  "passages": [
    {
      "id": "th_8b5e5d4c8946d815/p_0001",
      "path": "passages/memory/messages/th_8b5e5d4c8946d815/p_0001.md"
    }
  ]
}