Skip to content

Data on disk

In short

  • Sessions keep no database: everything is files under <data_root>/agents/, and published documents live under each workspace.
  • Back up <data_root> whole, with the backend stopped, and you have backed up every session.
  • Keep config/vault.json and .secret_key together: one without the other cannot be read.
  • A restart keeps every session, question and queued message. Working sessions show Process lost and resume from the banner.

Agent sessions keep no database: everything is files under the runtime's directory, <data_root>/agents, plus the published documents under each workspace. Back up <data_root> and you have backed up the sessions.

One session

runs/<root_id>/                 the orchestrator
  run.json                      current state (authoritative)
  events.jsonl                  journal and audit timeline, one per session
  transcript.jsonl              what the orchestrator said and did
  briefing.md                   the system prompt it was started with
  claude-mcp.json               Claude's MCP servers this attempt (variable names, no secrets)
  gemini-settings.json          the same for Gemini CLI; gemini-skill/ a copy of its skill
  cursor-skill/                 the copy of its skill a Cursor attempt reads (never the pack)
  template.json                 the flow-map snapshot taken at start
  host-assets/                  snapshot of the packs' rules and hooks
  uploads/<upload_id>/<name>    files people attached
  messages.json                 queued messages, and the latest 200 delivered
  archived.json                 present while archived
  halt.json                     who last stopped or cancelled it
  auto_resume.json              present while auto-resume is armed
  children/<run_id>/            one per step: run.json, transcript.jsonl, briefing.md
work/<root_id>/                 the agents' own files, shared by all steps

Run ids are UUIDv7, so a session's id sorts by its start time. People call a session by its number instead ("S-12", number in run.json and every run view): handed out in start order, never reused, and carried by each step and by the tombstone. A run.json without a number is refused by name. Every run view carries both absolute paths (control_path, workspace_path) for debugging.

Elsewhere:

Path What
session-number The last session number handed out.
tombstones/<root_id>.json A deleted session's summary (Recovery).
provenance/<token_id>.json Which session step a token was minted for (provenance).
workspace_profiles.json Each workspace's profile choice.
<data_root>/workspaces/<id>/documents/<doc_id>/ Published documents: document.json and v<n>/<file>.

What survives a restart

Everything above. A restart:

  • keeps every session, transcript, question and answer, queued message and auto-resume mark;
  • repairs a session whose last write was cut off (crash repair);
  • leaves working sessions as Process lost, to be resumed from the banner (nothing restarts by itself, except a run whose auto-resume time comes);
  • keeps open questions answerable, and resumes the agent when they are answered and Resume is pressed;
  • revokes nothing that matters: each attempt's ParleML token expires with the attempt's wall clock, and a resumed attempt gets a new one.

The CLIs' own conversation stores (for example ~/.claude, ~/.codex, ~/.gemini) live in the backend user's home directory, not in <data_root>. A session resumes in its saved conversation only while that store still has it; otherwise the run fails with conversation_missing and Resume starts a fresh conversation on the saved work directory.

The configuration lives apart from this state, in <data_root>/config/ (settings.yaml, connections.yaml, profiles/, packs/, skill-overrides/, vault.json), and is yours after the first boot. The backend rewrites only the shipped parleml-ml-lifecycle pack — at boot, whenever its content differs from the installed parleml-mcp package's (the digest in its .claude-plugin/plugin.json) — writes profiles/standard.yaml only when it is missing, and adds the built-in parleml connection to connections.yaml whenever it is missing.

Your edits to shipped skills live in config/skill-overrides/, with the effective folder and its original shipped base. Include this directory in a backup; the shipped pack alone does not contain your versions. New sessions use the effective skills, while existing sessions keep their snapshots.

Moving or backing up

Stop the backend first: it holds runs/.runtime.lock, and a copy taken while sessions run may catch a half-written transcript line (harmless) or miss the newest events. Copy <data_root> whole. Keep host-assets/ with its session: a resume refuses a missing or altered snapshot.

config/vault.json holds the secrets, encrypted with <data_root>/.secret_key: back the two up together, and keep them out of shared backups.

Starting over

To remove Do
One session Cancel it, then Delete transcript. Its tombstone stays; experiments, models and published documents stay.
Every session Stop the backend, delete runs/, work/ and tombstones/ (and provenance/ if object pages need not name sessions any more).
The agent configuration Stop the backend and delete config/profiles/ and config/packs/, and the tool servers in config/connections.yaml; the next boot seeds parleml, standard and the ML pack again. workspace_profiles.json then points at profiles that may be gone; those workspaces fall back to standard.
Everything about agents Stop the backend and delete <data_root>/agents, and the agent configuration as above.

Deleting a workspace deletes its sessions, as Delete transcript would, and forgets its profile choice. It is refused while any of its sessions is unfinished: cancel those first (Recovery & resume).

Next