Session Configuration

Controls how agent sessions behave — automatic persistence, resume windows, and inactivity detection.

{
  "session": {
    "auto_end_threshold_calls": 0,
    "reconnect_window_secs": 300,
    "stale_threshold_mins": 30,
    "hibernate_window_secs": 14400
  }
}

Fields

Field	Type	Default	Description
`auto_end_threshold_calls`	`int`	`0`	Auto-persist memory after N tool calls. `0` = disabled.
`reconnect_window_secs`	`int`	`300`	Same-connection resume window (5 minutes)
`stale_threshold_mins`	`int`	`30`	Mark session stale after this many minutes of inactivity
`hibernate_window_secs`	`int`	`14400`	Cross-connection resume window (4 hours)

How Sessions Work

Start: Agent calls session_init — Synapses creates or resumes a session
Resume (same connection): If the same MCP connection calls session_init within reconnect_window_secs, the existing session is resumed
Resume (new connection): If a new connection matches agent_id + project_id within hibernate_window_secs, the session is resumed with full task context
Stale detection: After stale_threshold_mins of inactivity, the session is marked stale (but not ended)
Auto-end: If auto_end_threshold_calls > 0, session automatically persists knowledge after that many tool calls

Tuning Tips

Long-running agents: Set auto_end_threshold_calls to 80-100 to auto-persist checkpoints
Quick iterations: Lower reconnect_window_secs to 60 if you frequently restart agents
Team environments: Increase hibernate_window_secs to 28800 (8 hours) for day-long session continuity