nucleus_sessions
Manage session lifecycles with save/resume, event logging, state persistence, and checkpoints to maintain continuity across AI conversations and hand off context between sessions.
Instructions
Manage session lifecycles with save/resume, structured event logging, key-value state persistence, and named checkpoints for rollback. Use this tool to maintain continuity across AI conversations, track what happened during a work session, and hand off context between sessions or agents. Do NOT use for persistent knowledge (use nucleus_engrams), task tracking (use nucleus_tasks), or multi-agent sync (use nucleus_sync). Actions: 'start' begins a new session with a stated goal and optional tags. 'save' persists current session state to .brain/sessions/. 'resume' restores a previous session with full context including events, state, and active tasks. 'end' closes the active session and records duration. 'emit_event' appends a structured event to the session log (side effect: writes to events.jsonl). 'read_events' retrieves event history with optional filters. 'get_state' reads the session's key-value state. 'update_state' sets a key-value pair. 'checkpoint' creates a named snapshot of current state for later rollback. 'resume_checkpoint' restores state from a checkpoint. 'handoff_summary' generates context for transitioning to a new session or agent. 'archive_resolved' removes completed sessions (destructive: deletes session files). 'garbage_collect' removes stale sessions older than threshold (destructive). Prerequisites: .brain directory. Returns JSON with {success: boolean, data: object}. Example: {action: 'start', params: {goal: 'Fix authentication bug', tags: ['backend', 'auth']}} returns {success: true, data: {session_id: 'sess_abc123', started: true}}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Select the session lifecycle action. 'start'/'end' control session boundaries. 'save'/'resume' persist and restore full session context. 'emit_event' appends to the event log (write). 'read_events'/'get_state'/'list'/'check_recent'/'handoff_summary' are read-only. 'update_state' modifies key-value session state. 'checkpoint'/'resume_checkpoint' create and restore named rollback points. 'archive_resolved'/'garbage_collect' are destructive cleanup operations that delete session data. | |
| params | No | Action-specific parameters as key-value pairs. start: {goal: string (required, session objective), tags: string[] (optional, categorization)}. save: {session_id: string (optional, auto-detected from active session), notes: string (optional)}. resume: {session_id: string (required, ID from 'list' output)}. emit_event: {event_type: string (required, e.g. 'decision'|'error'|'milestone'), data: object (required, event payload)}. read_events: {session_id: string (optional, defaults to active), limit: integer (optional, default 20), event_type: string (optional, filter by type)}. update_state: {key: string (required), value: any (required)}. checkpoint: {label: string (required, descriptive name like 'before-refactor')}. resume_checkpoint: {checkpoint_id: string (required)}. handoff_summary: {target_agent: string (optional, who receives the handoff)}. end/list/check_recent/get_state/archive_resolved/garbage_collect/propose_merges: no parameters needed. |