Long-Running Agents

Session Is Not the Same as Context Window

The two most commonly confused concepts: what Claude can currently see, versus everything that has happened. They must be kept separate.

Two easily confused concepts

Temporary / Limited

Context Window

The Tokens Claude can currently see. Like human working memory: limited capacity, forgotten when full. Built at the start of each turn, discarded when done.

Curated content for the current inference

Permanent / Replayable

Session

A persistent log of everything that has ever happened. Like a full recording: every moment captured, always rewindable. Append-only — events only ever accumulate.

Complete record of all raw events

Why they must be kept separate

Context management is irreversible

1 Both Compaction and Trimming are irreversible operations — once compressed, the original details are gone forever
2 At compression time, it's impossible to know which Tokens will matter later — today's seemingly irrelevant detail may be the basis for tomorrow's critical decision
3 If the original information is lost after compression, it can never be recovered — this is a fundamental constraint of information theory

The correct approach: raw events are stored permanently in the Session, while the Context Window is just a temporary viewport into the Session. Losing the Context is fine — the Session persists, and you can always rebuild from it.

Session as a persistent context object

The getEvents() interface

Session provides a database-like query interface: the Brain can read any range of events on demand, breaking free from the constraints of a fixed context window.

// Brain can flexibly query the Session
const recentEvents = session.getEvents({
  from: position - 100,   // start reading from a position
  to: position             // read up to current position
});

// Rewind to a specific point in time
const beforeDecision = session.getEvents({
  from: decisionPoint - 20,
  to: decisionPoint + 5
});

// Filter for specific event types
const toolCalls = session.getEvents({
  filter: "tool_use"
});
    

Just like an object in a REPL, the LLM can write code to query and filter events from the Session. The Brain can start reading from any position, rewind to a specific point in time, or re-read the context surrounding a past decision.

The flexibility of the Harness

Events pulled from the Session can be transformed arbitrarily

Optimize Prompt Cache hit rate: keep prefixes stable to reduce redundant Token computation costs
Context engineering: selectively include the most relevant historical events based on the current task type
The Harness is swappable: different models may need different context strategies; swapping the Harness doesn't affect the Session

Core comparison

Dimension	Context Window	Session
Persistence	Temporary, discarded after use	Permanent, durably stored
Contents	Curated Tokens	All raw events
Operation	Read-only (from Claude's perspective)	Append-only
Size	Limited (model's max window)	Unbounded
Purpose	Current inference	History replay, state recovery

Hardware analogy

RAM (Memory)

Context Window

Fast, small, lost on power-off. Data the CPU needs must be in RAM, but RAM is not for long-term storage.

Disk (Storage)

Session

Slow, large, survives power-off. All data ultimately lives on disk; load into RAM only when needed.

You wouldn't load all your files into RAM at once — that would overflow it. By the same logic, you shouldn't stuff all historical events into the Context Window — that would overflow your Tokens. The correct approach is load on demand: store everything in the Session, pull a subset into Context.

Session is the Agent's hard drive; Context Window is RAM. Don't use RAM as a hard drive. Store all raw events in the Session and let the Harness assemble the Context on demand. That way, even if the context is compressed or the model is swapped out, history is never lost.