Persistent chat sessions with checkpointing, time-travel debugging, and cloud sync.

Difficulty

intermediate

The ivybloom CLI is the scriptable surface for the platform, and sessions give your scripted work durable, persistent conversations that survive CLI restarts — storing messages, tool call history, and context, synced between local storage and the cloud. Reach for sessions and checkpoints when a scripted pipeline needs to resume where it left off, snapshot state for rollback, or time-travel through prior steps for debugging. They keep long-running, reproducible work anchored across runs; for the full command surface, see the CLI overview.

Sessions & Checkpoints (since v0.8.10)

Persistent chat sessions with checkpointing, time-travel debugging, and cloud sync.

Overview

Sessions are persistent conversations that survive CLI restarts. They store messages, tool call history, and context — all synced between local storage and the cloud.

Key capabilities:

Persistence — Conversations survive restarts, stored locally and in the cloud
Checkpoints — Snapshot session state for rollback and time-travel
Sync — Version-vector-based synchronization between devices
Context — Attach files and memory notes to sessions (MCP)

Chat Commands

The chats command manages conversation threads within campaigns:

# List chats (optionally scoped to a campaign)
ivybloom chats list
ivybloom chats list --campaign CAMPAIGN_ID

# View chat message history
ivybloom chats history CHAT_ID --limit 50

--campaignstring

Filter chats by campaign ID.

--limitintdefault: 50

Maximum messages to return.

Chat creation, deletion, export, and resumption are MCP-only operations or available via root flags. They do not have dedicated chats subcommands.

Resuming Chats via Root Flags

# Resume a specific chat
ivybloom --resume CHAT_ID

# Resume the most recent chat
ivybloom -r last

# Send a single headless message (no TUI)
ivybloom -m "Fold BRCA1 and find binding sites"

MCP-Only Chat Operations

Available via ivybloom mcp serve:

MCP Tool	Description
`chats_create`	Create a new chat in a campaign
`chats_delete`	Delete a chat
`chats_export`	Export chat as JSON/markdown/text
`chats_messages`	Get all messages in a chat
`chats_recent`	Get most recent chats

Session Management

Sessions provide the persistence layer beneath chats.

List Sessions

ivybloom sessions list --limit 20

Create a Session

ivybloom sessions create

View Session Details

ivybloom sessions get SESSION_ID

Append Messages

Add messages to a session programmatically:

# Append a user message
ivybloom sessions append SESSION_ID --role user --content "Predict the structure of insulin"

# Append from stdin (pipe in content)
echo "Fold BRCA1" | ivybloom sessions append SESSION_ID --role user --stdin

SESSION_IDstringrequired

Target session ID (positional argument).

--rolestringrequired

Message role: user, assistant, or system.

--contentstring

Message content text.

--stdinbool

Read content from stdin instead of --content.

Delete a Session

ivybloom sessions delete SESSION_ID

Tool Call Recording

Record tool execution events in a session for tracking and replay:

ivybloom sessions tool-call SESSION_ID \
  --tool esmfold \
  --status running \
  --progress 50 \
  --job-id job_abc123

--toolstring

Tool name (also --name).

--statusstring

Tool call status: pending, running, complete, or error.

--progressint

Progress percentage (0-100).

--job-idstring

Associated job ID.

--tool-call-idstring

Existing tool call ID to update (for status transitions).

Checkpoints & Time-Travel (since v0.8.54)

Checkpoints are snapshots of session state. Use them to restore a session to a previous point — for example, rolling back after an undesired tool execution.

Create a Checkpoint

ivybloom checkpoints create SESSION_ID

List Checkpoints

ivybloom checkpoints list SESSION_ID

ID              LABEL          CREATED           MESSAGES
cp_abc123       pre-docking    2 hours ago       12
cp_def456       —              45 minutes ago    18
cp_ghi789       latest         5 minutes ago     24

Rollback to a Checkpoint

ivybloom checkpoints rollback SESSION_ID CHECKPOINT_ID

Rollback discards all messages and tool calls after the checkpoint. This cannot be undone.

Prune Old Checkpoints

Clean up old checkpoints to save storage:

ivybloom checkpoints prune SESSION_ID

By default, keeps the 5 most recent checkpoints.

Sync Protocol

Sessions use version vectors for conflict-free synchronization between devices:

# Default: merge local and remote changes
ivybloom sessions sync SESSION_ID

# Explicit merge mode
ivybloom sessions sync SESSION_ID --mode merge

# Force local state to remote (overwrite remote)
ivybloom sessions sync SESSION_ID --mode force_local

# Force remote state to local (overwrite local)
ivybloom sessions sync SESSION_ID --mode force_remote

--modestringdefault: merge

Sync strategy: merge, force_local, or force_remote.

How Sync Works

Each device maintains a version vector tracking local changes
On sync, version vectors are compared to detect conflicts
merge — Combines both sides; concurrent edits are interleaved by timestamp
force_local — Overwrites remote with local state
force_remote — Overwrites local with remote state

Use merge (default) for normal operation. Use force_local or force_remote only when resolving conflicts manually.

Context Management (MCP)

Context operations are available via the MCP server for AI agent integration:

MCP Tool	Description
`context_get`	Get files and memories attached to a chat
`context_add_file`	Attach a file reference to a chat's context
`context_remove_file`	Remove a file from context
`context_add_memory`	Add a persistent memory note
`context_clear_memories`	Clear all memories from a chat

These enable AI agents to maintain context across interactions — attaching PDB files, noting user preferences, and building up working knowledge.

Sessions & Checkpoints