Sessions

A session is one BMO conversation: messages, session-local todos, file history, and optional session checkpoints. BMO keeps many sessions in the active data directory (default .bmo/bmo.db). You create or switch between them when you want separate threads of work; you branch when you need a fork without losing the original; you checkpoint when you need a named snapshot inside the same conversation.

This page is the concept hub for sessions and continuity. Deeper, feature-specific docs live on sibling pages — Session Modes, Session Compaction, Auto-Checkpoint (git micro-commits and session checkpoints), Agent Debugger (fork from a run step), and Run observability. For the full docs taxonomy, see Concept Map.

flowchart TD
    root["Root session\n(messages + todos + file history)"]
    branch["Branch session\n(source_session_id set)"]
    cp["Session checkpoint\n(snapshot inside one session)"]
    git["Git auto-checkpoint\n(repo commit after edits)"]

    root -->|"branch copy"| branch
    root -->|"ctrl+k / API create"| cp
    root -->|"restore truncates after checkpoint"| cp
    root -.->|"separate feature"| git

    note["Choose: new session vs branch vs checkpoint"]
    note --> root
    note --> branch
    note --> cp

When to use it

• Several conversations — different tasks, clients, or experiments; switch with /session or switch_session instead of one endless chat.
• Try an alternative path — branch from a session so messages, file history, read-file state, and checkpoints copy into a new session row with source_session_id set.
• Automation or integrators — create, list, and bind sessions from CLI, agent tools, HTTP, or MCP against the same SQLite store.
• Named in-conversation snapshots — session checkpoints (not a new session); see Sessions vs checkpoints vs branches below.

If you only need to rewind git history after edits, use Auto-Checkpoint undo — not session checkpoints. If you need to shrink context window pressure inside a long session, use Session Compaction.

Sessions vs checkpoints vs branches

Need	Use	Affects
Separate conversation thread	New root session	New session row; switch current session
Fork to explore without losing source	Branch (debugger fork or branch API)	New session row linked to source
Snapshot and restore inside one chat	Session checkpoint	Same session; truncates messages/todos and rewinds session file-history / read-file tracking after a successful restore. Does not change files on disk. Refuses when retained transcript identity no longer matches.
Undo last git commit after file edits	Git auto-checkpoint undo	Repository only; see Auto-Checkpoint

Session checkpoints do not change git history or workspace files on disk. Git auto-checkpoint does not replace session checkpoints. Branching creates a new session; restoring a checkpoint stays on the same session.

Operator surfaces

BMO exposes the same session family across surfaces. The TUI and agent keep one current session; you cannot delete the session you are on without switching first.

Surface	Typical entry	Notes
TUI	/session	Browse, create, switch, delete; ctrl+k / ctrl+e for session checkpoints from the Sessions dialog
CLI	bmo --session-id, bmo run --session-id, bmo session list, status, resume, diagnose	Fail-closed bind: ID must exist in the active data dir
Agent tools	create_session, list_sessions, switch_session, delete_session, …	List returns root sessions; paginate with limit / offset
HTTP	GET/POST/PATCH/DELETE /v1/sessions/...	When bmo service start http or autopilot is running
MCP	bmo_list_sessions, bmo_get_session_budget, …	Full-app serve-mcp; see MCP Server

List endpoints return sessions where parent_session_id is null — that includes independent conversations and branch forks (source_session_id set; titles often show [branch: …]). Task sub-sessions with a non-null parent_session_id are excluded from the default list; discover sibling branches with branch APIs or ListBranches(sourceSessionID).

Switching and resume

Interactive: open /session in the TUI and pick a session, or start with bmo --session-id <id> to bind an existing session on first send.

Non-interactive: append a turn with bmo run --session-id <id> "...".

Health-aware resume: bmo session resume --session <id> validates message integrity before opening the TUI; bmo session status reports budget even when resume would block on corrupt parts.

See FAQ — Sessions for the short operator path.

Persistence and recovery (operator view)

Conversation state for a data directory lives in SQLite (bmo.db). After a normal quit and restart, picking a session reloads messages and related state from disk. Abrupt process death can leave uncommitted work rolled back; in-memory coordinator, MCP, and LSP state is rebuilt on startup — not restored like messages.

Checkpoint restore reloads the chat from the store (truncating messages after the checkpoint and rewinding session-scoped file-history / read-file state when rewinders are configured). It validates retained transcript identity before mutating the session and refuses with no session change when that prefix is missing, changed, unsupported, or lacks required evidence. Files on disk stay unchanged. If load fails hard, BMO surfaces an error instead of a half-loaded thread.

Maintainers: reattachment matrix, WAL settings, and degraded sub-load behavior are documented in the Session maintainer topic.

Session-local todos

Session todos track in-chat progress for the current conversation. They restore with session checkpoints. They are not Markdown checklists in plan files, workspace todos/, or workstream findings — use the matching surface for each scope (session todo tools vs file edits vs workstream tooling).

Related features

Topic	Page
Per-session tool/mode posture	Session Modes
Context-window recovery	Session Compaction
Git micro-commits + session checkpoint ops	Auto-Checkpoint
Fork branch from a run step	Agent Debugger
Budget and cue readouts	Run observability
During-turn model comparison inside a session	Arena
MCP session operator tools	MCP Server

Maintainer and integrator depth

CLI command tables, MCP parity matrices, session historian, diagnostics, and lifecycle hook configuration live in the maintainer topic docs/topics/persistence/sessions.md on GitHub.