Storage & Data

Boatman Desktop stores all data locally on your machine. No cloud sync is used unless explicitly configured.

Storage Locations

Path	Contents
`~/.boatman/config.json`	User preferences and settings
`~/.boatman/sessions/`	Chat sessions, tasks, and metadata
`~/.boatman/checkpoints/`	Workflow checkpoints (used by CLI pipeline)
`~/.boatman/memory/`	Per-project learning data (used by CLI pipeline)
`~/.claude/claude_mcp_config.json`	MCP server configurations
`<project>/.boatman/runs/`	Provider-neutral runtime run records
`<project>/.boatman/memory/`	Inspectable runtime memory Markdown documents
`<project>/.boatman/routines/`	Markdown reports from repeatable routines

Session Storage

Each session is saved as a JSON file in ~/.boatman/sessions/.

What's Stored

Full conversation history (all messages)
Task list with status and metadata (plan, diff, feedback, log)
Session state (idle, running, stopped)
Mode and mode config (standard, firefighter, boatmanmode)
Tags and favorite status
Model and reasoning effort settings

Automatic Persistence

Sessions are saved automatically:

After each Claude command completes
After BoatmanMode execution finishes
When the app shuts down

Storage Management

View Usage

Go to Settings > Memory to see storage configuration.

Delete Sessions

Single session: Right-click in sidebar > Delete
Bulk cleanup: Configure auto-cleanup in Settings > Memory

Export / Import

Export: Right-click session > Export as JSON
Import: Settings > Import Sessions > Select JSON file

Useful for sharing sessions with team members or moving between machines.

Auto-Cleanup

Configure in Settings > Memory:

Setting	Default	Description
Max messages per session	1000	Older messages are trimmed
Archive old messages	Enabled	Trimmed messages are archived, not deleted
Auto-cleanup sessions	30 days	Sessions older than this are removed
Max total sessions	100	Oldest sessions pruned when exceeded

Runtime Store

When runtime recording is enabled, Boatman writes one directory per run:

<project>/.boatman/runs/<run-id>/
  metadata.json
  request.json
  events.ndjson
  artifacts.json

The Desktop Runtime tab reads these files directly. The CLI can inspect the same data:

boatman runs list
boatman runs show <run-id>
boatman runs request <run-id>
boatman runs artifacts <run-id>

Project-local recording is enabled for Desktop and provider-backed CLI runs by default. Set BOATMAN_RUNTIME_STORE_DIR to write runs somewhere else, or set BOATMAN_RUNTIME_STORE=0 to disable default recording.

Routine Reports

Desktop routines load optional project definitions from:

<project>/.boatman/routines.json
<project>/.boatman/routines/*.json

Routine runs write Markdown reports under:

<project>/.boatman/routines/<routine-id>/<run-id>.md

The Datadog GraphQL slow-query routine uses the same provider-neutral runtime recorder, so each report also has a corresponding run in .boatman/runs.

Runtime Memory Documents

Runtime memory documents are Markdown files with frontmatter:

<project>/.boatman/memory/
  project.md
  domains/payments.md

They are intended to be human-inspectable. Boatman loads non-expired documents as context for future provider runs, records a memory.loaded event, and the Runtime tab shows their scope, provenance, source run, expiration, path, and full body.

Data Privacy

All session data stays on your local machine
API keys are stored in ~/.boatman/config.json but never included in session exports
Sessions contain your prompts and Claude's responses
No telemetry or usage data is sent externally

CLI Storage

The CLI pipeline (used by BoatmanMode) stores additional data. See Harness Storage for details on:

Checkpoints (~/.boatman/checkpoints/) — workflow progress for crash recovery
Memory (~/.boatman/memory/) — learned patterns and preferences per project
Runtime runs (<project>/.boatman/runs/) — provider-neutral run events and artifacts
Runtime memory (<project>/.boatman/memory/) — inspectable Markdown context documents

Configuration Troubleshooting