Session State, Resumption & Forking
Managing session state across long-running and multi-session investigations. Named session resumption with --resume, fork_session for parallel exploration branches, and strategies for deciding between resuming stale sessions and starting fresh with structured summaries.
Quick Reference
- →Named sessions: use --resume <session-name> to continue a previous investigation
- →fork_session creates a divergent copy of the current session for parallel exploration
- →Resumed sessions retain full conversation history -- but tool results may be stale
- →When tool results are stale, starting a new session with a structured summary is often better
- →Inform resumed sessions about specific file changes: 'Since our last session, these files changed: ...'
- →Fork sessions share the starting state but diverge independently from the fork point
- →Named sessions enable multi-day investigations that build on prior work
- →Session state includes: conversation history, tool results, working assumptions, and open questions
- →Fresh sessions with summaries avoid stale context but lose nuanced working state
- →Decision framework: resume if context is still valid, start fresh if tool results are likely outdated
Session State Fundamentals
Session state is the accumulated context of an agent conversation: the message history, tool call results, working hypotheses, discovered information, and decisions made. Session management determines how this state persists across multiple interactions and how it can be reused, forked, or replaced.
In short-lived interactions, session state is trivial -- the conversation starts and ends in a single run. But real-world agent tasks often span hours, days, or even weeks. A complex investigation might require multiple sessions: an initial exploration, a deep-dive into a specific area, a follow-up after code changes, and a final verification. Session management is about maintaining continuity across these interactions without losing context or accumulating stale information.
The challenge is that session state has a shelf life. Tool results go stale: files change, databases are updated, APIs return different results. Working assumptions may be invalidated by external events. The art of session management is knowing when state is still valuable and when it has become a liability.