Core concepts

End usersCopy Anchor Link

An end user is one of your users. Each has a memory of their own, kept in a database of its own, and named by the X-Twin-Account header on every request. Your key decides the organisation and project; the header picks the user inside it. No request can reach another project's users, and no field in a body can name a user, so a model calling your tools cannot ask for somebody else's memory.

The first write to an end user creates their memory. Reading one that was never written to is a 404, which your code should treat as an empty memory. See End users & tenancy.

ItemsCopy Anchor Link

You add items, of three kinds:

• a message: one turn of a conversation, by a user or by your assistant;
• a document: a longer text with a title, such as a file or a page;
• a note: one statement to keep, such as a preference your app learned.

An item's id is its identity. Send the same id again with other text and it is an edit, not a second item. Edit only to fix the same statement; when something changes, add a new item, and memory keeps both, dated. Messages with the same session on the same day form one conversation. See Items.

PassagesCopy Anchor Link

When an item lands, its conversation or document is cut into passages: a few turns, or a section of text, with a header saying where and when it came from. Passages are what word search and meaning search find, and every one has an address such as passages/memory/messages/th_8b5e5d4c8946d815/p_0001.md that read opens.

Adding makes no model call, and an item is searchable by its words as soon as it lands.

RecordsCopy Anchor Link

In the background, each new window of a conversation is read once by a model into records: short dated facts such as Alice lives in Lisbon, each naming the passage it was read from. Records about a subject's attributes build what is known: every value a subject's attribute has had, as stated, newest first.

Reading happens after the add returns. status tells you how far each item has got: accepted, landed, read, then folded. See Records & reading.

Search and the briefCopy Anchor Link

search takes a question in plain words. It runs word match and meaning match over the end user's memory, then keeps what the question needs, and answers with a brief:

• known: what is true now, one line per subject and attribute;
• facts: the dated records behind it, each with its source;
• hits: the passages themselves, dated and addressed;
• notes: how to read the above, written for a model.

Hand the brief to your model as context. Because every line carries a date and an address, the model can say when something was said and cite where. Bound a search by a start date or a place and it answers with a plain ranked list instead. See Search and Using memory with an LLM.

Values, not overwritesCopy Anchor Link

When a value changes, such as a user moving city, memory keeps every value with the day it was said. It does not decide that one replaced another; the newest is listed first, and your model sees the whole story. See Values & history.

Taking things backCopy Anchor Link

• forget hard-deletes items, sessions or threads with every copy and everything learned from them, and returns a receipt that counts each table before and after. See Erasure & receipts.
• An item's expires time forgets it the same way, on its own. See Expiry.
• correct retracts one record that was read wrong, for good. See Corrections.

Two kinds of keyCopy Anchor Link

A read key searches and reads. A read and write key also adds, forgets and corrects. Give an agent that only reads a read key, and an agent that saves what it learns a read and write key. Your backend holds a read and write key. See Authentication & keys.