Conversations as event logs, not transcripts

The instinct is to model a conversation as a list of {role, text} messages. For an agent, that's not enough. An assistant turn isn't just text: it read three documents, generated a file, proposed five edits, and cited four sources. If you store only the final text, you lose all of that, and a reloaded conversation can't show the chips, cards, and citations the user saw live.

So model assistant messages as structured event logs: an ordered array of typed events (content, reasoning, document_read, document_generated, document_edited, citation, …), the same timeline you streamed (Chapter 8). Store it as a JSON column. On reload, replay the events to reconstruct the rich rendering exactly. The conversation table thus holds, per message: role, the event array (for assistant turns), the user's attachments and selections (for user turns), and any extracted annotations (citations, edits).

This single decision, events, not transcripts, is what makes faithful conversation replay possible.