History and records

Messages
user request
completed root answer

State blocks
validated updates
selected reader views

Turn records
parent + budget
usage + outcome

Next turn: select messages + render state ↓

opening context: assembled again
current-turn transcript: []
chain selection: first tier

Conversation history supplies context. Turn records explain execution. State holds application data.

A turn leaves several kinds of data behind. Conversation messages help the next request understand earlier discussion. State blocks hold application data. Turn records explain what executed and how it ended. They serve different purposes and are not interchangeable forms of memory.

Know what is stored

Data	Current runtime behavior
Root user message	Appended only for root turns opened with an envelope, after admission and before context assembly. A brief-only root appends nothing.
Root assistant message	Appended only when a root turn settles `completed`, with its text and payload parts.
Child conversation messages	Child turns do not append separate user or assistant conversation messages.
State updates	Applied through successful block updates during execution.
Turn record	Appended when a turn settles, including refused and non-completed turns.
Events	Kept by the runtime's event bus; available for inspection and export.

A user message can remain in history even if the subsequent turn fails its fit check or execution. Failed, cut, stopped, and truncated roots do not append a completed assistant message automatically. Their partial output remains available in emitted events, rather than being promoted to a successful conversation answer.

The default MemoryStore is in-process memory. Surviving process restarts requires an appropriate store implementation; see Storage and caching.

Inspect messages and execution separately

Every Store method is async — the same interface serves the in-memory store and a durable adapter, so always await it:

const recentMessages = await runtime.store.listMessages(ambient.threadId, 6);

const threadRecords = (await runtime.store.records()).filter(
  (record) => record.threadId === ambient.threadId,
);

for (const record of threadRecords) {
  console.log(record.turnId, record.parentTurnId, record.outcome);
}

Records contain the grant, steps used, selected model tier, fallback history, usage, timing, and outcome details. Child model usage stays on child records; it is not automatically added to the parent's token totals.

Turn IDs come from RuntimeConfig.turnIds. The default is a per-runtime counter (T1, T2, …) — deterministic, but colliding across process restarts if records are persisted. Inject a ULID or UUID generator (turnIds: () => ulid()) for durable, multi-instance runs. A record is also not a checkpoint containing enough execution state to resume an interrupted model loop.

Start the next turn with fresh execution

A later turn assembles context again using its agent's reads and historyWindow. That window selects stored messages, not user-assistant pairs. Its default is six; zero excludes stored conversation history.

The current implementation renders message roles and text into history. It does not automatically replay all stored structured parts as provider-native messages. Because an envelope's user message is stored before assembly, that message can appear in selected history as well as in the current brief.

The new turn starts with an empty current-turn transcript and a fresh chain selection at the first tier. It does not inherit every tool result from the previous turn automatically. See History and transcripts.

Do not confuse failure with rollback

A successful state update or external tool side effect can happen before a later failure. Settling the turn as failed does not automatically undo that work. Inspect state and execution records before deciding whether to retry.

The continuesFrom argument records a relationship to an earlier turn; it does not restore that turn's transcript, budget, or provider execution. Application restart and retry behavior must account for already-completed operations.

Inspect in Studio

Run a successful request, then a request that fails after a tool operation. Compare TURN RECORDS, STATE changes, and each turn's WIRE events. Start another request and inspect CONTEXT to see which messages and state views actually reached the model.

Next: The wire.