Lineage
Follow an item forward to what memory made of it, or a record back to the words it was read from.
/v1/memory/lineage answers two questions about provenance, with one id:
- Given an item or event, what did memory make of it?
- Given a record, which words was it read from?
Lineage makes no model call and reads memory as it is now. Nothing is written.
Forward: what an item became
Pass an item id or an event id.
For { "id": "msg-001" }, once the conversation has been read:
{
"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]"]
}| Field | What it lists |
|---|---|
events | The stored events the id names. |
passages | The passages that quote it. |
records | The records that rest on it, with their kind and text. |
assertions | The value lines built from those records, the ones history returns. |
core | The lines of what is known now, the known of search, that were made from those records. |
Before the item has been read, records, assertions and core are empty.
Backward: where a record came from
Pass a record id as search returns it under facts.
{
"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"
}
]
}Pass any path to read to see the words themselves.
Lineage and forget walk the same edges
"Rests on" means the same thing to lineage and to forget: a record rests on a message if it cites it, or if it was read from a window of the conversation that held it. Both use the same code to walk those edges. So what lineage says an item became is exactly what forgetting that item would remove. Use it to show a user what an erasure will take before you run it.
Unknown ids
An id memory does not hold answers 200 with an error field:
{ "of": "zzz", "error": "no event, item or record by this id in this account" }Related
- Lineage reference.
- Corrections: retract a record once you have found it wrong.