Skip to main content

Sessions & State

A session is the unit of an agent's existence: the conversation, the accumulated state, and the metadata for one continuous run or relationship. Where context assembly decides what the model sees this turn, session state is what persists across turns, restarts, and reconnections.

Without a session layer, every interaction starts from zero — the Amnesiac Agent. With one, an agent can be paused, resumed on a new machine, audited after the fact, and carried across days of a long-running task.

Structure​

State is continuously persisted so a session can outlive the process that runs it — the foundation for durability and replay.

How It Works​

  1. Open a session — allocate an identity and an initial state record (history, scratch state, metadata, budget).
  2. Append per turn — each turn writes its messages, tool results, and any extracted state to the session record.
  3. Persist durably — write to a store, not just process memory, so a crash or redeploy doesn't lose the run.
  4. Separate transient from durable — the full message log is transient and compactible; extracted facts and decisions are durable and survive compaction.
  5. Resume or close — reload state to continue, or close and retain the record for audit and evaluation.

The durable tier is what actually carries a task across sessions. Anthropic's work on harnesses for long-running agents landed exactly here: compaction alone is insufficient for continuity, because a summary doesn't always pass clear instructions to the next session. What works is durable artifacts — a feature list, a progress log, git history — that the next session reads to pick up the thread, instead of reconstructing it from a lossy summary.

Key Characteristics​

  • The session is the source of truth — process memory is a cache of it. If it isn't persisted, it didn't happen.
  • Two tiers of state — transient conversation (large, summarizable) and durable facts (small, permanent). Conflating them means you either lose facts or never compact.
  • Identity enables everything downstream — a stable session id is what lets you trace, resume, replay, and bill a run.
  • State persistence underpins durability — pause/resume is impossible if state lives only in RAM.
  • Sessions have lifecycles — open, active, paused, resumed, closed, archived. Modeling them explicitly keeps cleanup and retention sane.

Pitfalls​

  • State only in memory — a redeploy or crash wipes the run and there's no resume and no audit trail.
  • One undifferentiated blob — mixing transient history and durable facts means compaction either can't run or silently drops things that mattered.
  • No retention policy — sessions accumulate forever, or get deleted before anyone can debug the incident they caused.