Records & reading
How an added item becomes searchable at once, and dated facts later, and how to see how far each item has got.
Adding an item and understanding it are two steps. The first is quick and makes no model call. The second happens in the background.
What happens after an add
Accepted. The add request commits your items and answers 202. Nothing is lost from here on, but the items
are not searchable yet.
Landed. A moment later the items are filed: each conversation is cut into passages, and the passages are
indexed by their words and their meaning. From now on search, grep
and read find them. Send "wait": true with an add to hold the request until this step, up to
10 seconds.
Read. In the background, a model reads each new window of a conversation once and writes records: short, dated, typed statements of what was said, each citing the turns it came from. This is the one step that calls a model on the write side.
Folded. After records are filed, memory builds its pages from them, including what is known now about each
person and thing. Search returns those lines as known.
Until an item is read, search finds it as a passage under hits only. Once it is read, the same search also
returns facts and, once folded, known.
How long each step takes
| Step | When | What search returns from then |
|---|---|---|
| Landed | Within seconds of the add. | The words, as passages under hits. |
| Read | In the background. The earlier parts of a conversation within a minute or two; the newest part once the conversation has been quiet for about 10 minutes. | Dated facts. |
| Folded | When the end user's memory is next folded, at most about every 30 minutes. | known lines, and the values history lists. |
The newest part of a conversation waits for a quiet spell because it may still grow: reading it once the
conversation has paused reads each part once, not once per message. Until then, its words are in hits, and
when a passage shown is newer than every fact, the brief's notes say so.
Reading also waits when your organisation's daily budget is spent; see Reading and your budget.
What a record is
A record is one line a model read out of a conversation, such as:
(happened 2026-10-01) Alice lives in Lisbon (Alice · home_city: Lisbon) (state)Each record has:
- an id of the form
th_<thread>#r<name>, such asth_8b5e5d4c8946d815#r028d461216652fe5. This is the id you pass tocorrectandlineage. It does not change when other records around it change. - a kind, such as
stateorpreference. - the dates it happened and was said.
- the turns it was read from. Search returns the passage that holds them as
source.
Records that set a value for a subject, such as Alice's home city, also feed the values shown in known and in
history.
See how far an item has got
/v1/memory/status takes up to 500 item ids or event ids and returns the phase of each.
curl https://api.twinmemory.dev/v1/memory/status \
-H "Authorization: Bearer $TWIN_MEMORY_API_KEY" \
-H "X-Twin-Account: user_42" \
-H "Content-Type: application/json" \
-d '{ "ids": ["msg-001", "pref-diet", "nope-404"] }'{ "phases": { "msg-001": "folded", "pref-diet": "landed", "nope-404": "unknown" } }| Phase | Meaning |
|---|---|
accepted | Committed, not yet searchable. An item whose newer edit is still waiting is also accepted. |
landed | Searchable by its words and meaning. |
read | Records have been filed from a window that holds it. |
folded | Pages, including known, have been built since those records were filed. |
unknown | Memory holds no item or event by this id, or it was forgotten. |
Status makes no model call. Poll it at a modest rate if your app needs to know when facts are ready.
Reading and your budget
Reading is the step that calls a model, so it counts against your organisation's daily budget, which you set in the console. When the budget for the day is spent, reading waits until the next UTC day. Adding, landing, searching by words and every other route keep working. See Limits.
Related
- Search: what each response field holds.
- Values & history: what records say about one subject over time.
- Corrections: retract a record the model got wrong.