Session continuity
Why a compacted or resumed session already knows what you were doing.
When your agent compacts its context or you close and reopen a session, the work you did does not vanish. context-mode records session events as they happen and rebuilds working state on the other side, so a fresh window already knows where you left off — without re-injecting the raw context that was just compacted away.
What gets captured
Hooks observe the session and write events into a per-project SQLite SessionDB. The events span many categories, including:
- Tool calls and their outcomes.
- Errors and blockers.
- Plans and decisions.
- User prompts.
- Rejected approaches, so a path you already ruled out is not retried.
Each event is small and structured, so capturing a whole session costs a fraction of what re-reading it would.
Built for concurrent writers
Several hook processes can fire at once, so the SessionDB is multi-writer safe by design.
- WAL journal mode lets readers and a writer proceed without blocking each other.
- A
busy_timeoutmakes a contending writer wait and retry instead of failing. - There is no external lockfile to leak or go stale.
The result is that concurrent hook processes can write at the same time without corrupting state or dropping events.
Across a compaction
Detect the emptied state
When the agent compacts, live working state is cleared. The SessionStart hook
detects that emptied state on the next turn.
Rebuild from the latest snapshot
Instead of re-injecting the raw transcript, the hook reconstructs working state from the most recent snapshot in the SessionDB. You keep the conclusions and lose the byte cost.
Across a resume
When you continue or resume a session, prior state rehydrates automatically from the same SessionDB. There is nothing to re-paste and no setup step — the next turn starts with the state the previous session ended on.
Practical guidance
After a resume, search memory before you ask. Run ctx_search with sort set to
timeline to recall prior decisions and errors in order, rather than asking the
user to repeat themselves.
ctx_search({
queries: ["summary of last session", "open decisions", "blockers"],
sort: "timeline",
})If that search returns nothing, treat it as a fresh session and proceed.