1:1 mentoring with Big Tech AI engineers
System Design

The Run Ledger

The four kinds of agent state, the three tables that make a run resumable, billable and auditable, and the exit condition that tells you when one store is no longer enough.

Last updated

Production9 min readFirst readStateless vs StatefulWhere It Runs

After this section you can

  • Name the four kinds of agent state and what losing each one costs
  • Write the conversations, runs and steps tables with a reason for each column that carries one
  • State the trigger that would split the store, and why an invented row count is not one
29

The Run Ledger

Store an agent run so it can resume, be billed and be audited, and know when to split the store.

Key idea

An agent's state comes in four kinds, and most of it fits in one Postgres. The ledger is the set of tables that makes a run resumable, billable and auditable. Split the store only when a measured number says so, and write that number down before you split.

Four kinds of state, and one store until a measured number says otherwise
FOUR KINDS OF STATE WHERE EACH KIND LIVES Conversation history days to years · loss is amnesia Run checkpoints hours · loss means paying again Knowledge until re-indexed · loss: worse answers Coordination seconds to hours · loss degrades Postgres system of record steps, runs, conversations knowledge, if pgvector split only on a measured number Redis counters and caches: disposable

Purple: state. Teal: the store this lesson is about. Dashed: disposable.

Related

More in System Design

Get full access to all 74+ sections with code examples, diagrams, and interactive animations.

Unlock Premium