---
title: Sessions & Checkpoints
description: >-
  Persistent chat sessions with checkpointing, time-travel debugging, and cloud
  sync.
tags:
  - sessions
  - checkpoints
  - chat
  - sync
  - persistence
---

  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](/docs/cli).

## 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:

```bash
# 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
```

- `--campaign` (string) —
Filter chats by campaign ID.

- `--limit` (int) —
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

```bash
# 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

```bash
ivybloom sessions list --limit 20
```

### Create a Session

```bash
ivybloom sessions create
```

### View Session Details

```bash
ivybloom sessions get SESSION_ID
```

### Append Messages

Add messages to a session programmatically:

```bash
# 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_ID` (string) —
Target session ID (positional argument).

- `--role` (string) —
Message role: `user`, `assistant`, or `system`.

- `--content` (string) —
Message content text.

- `--stdin` (bool) —
Read content from stdin instead of `--content`.

### Delete a Session

```bash
ivybloom sessions delete SESSION_ID
```

---

## Tool Call Recording

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

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

- `--tool` (string) —
Tool name (also `--name`).

- `--status` (string) —
Tool call status: `pending`, `running`, `complete`, or `error`.

- `--progress` (int) —
Progress percentage (0-100).

- `--job-id` (string) —
Associated job ID.

- `--tool-call-id` (string) —
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

```bash
ivybloom checkpoints create SESSION_ID
```

### List Checkpoints

```bash
ivybloom checkpoints list SESSION_ID
```

**Table (default)**

```
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
```

**JSON**

```
[
  {"id": "cp_abc123", "label": "pre-docking", "created_at": "2026-03-08T10:00:00Z", "message_count": 12},
  {"id": "cp_def456", "label": null, "created_at": "2026-03-08T11:15:00Z", "message_count": 18},
  {"id": "cp_ghi789", "label": "latest", "created_at": "2026-03-08T11:55:00Z", "message_count": 24}
]
```

### Rollback to a Checkpoint

```bash
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:

```bash
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:

```bash
# 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
```

- `--mode` (string) —
Sync strategy: `merge`, `force_local`, or `force_remote`.

### How Sync Works

1. Each device maintains a version vector tracking local changes
2. On sync, version vectors are compared to detect conflicts
3. **merge** — Combines both sides; concurrent edits are interleaved by timestamp
4. **force_local** — Overwrites remote with local state
5. **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.

---

## Read next

- [Interactive TUI](/docs/cli/tui) — Visual chat interface with session persistence
- [Orchestration](/docs/cli/orchestration) — AI-powered routing that creates sessions
- [MCP Integration](/docs/cli/mcp) — Session management via AI agents
- [Commands Reference](/docs/cli/commands) — Full command listing