Archive Retention

Archived sessions include full git worktrees with installed dependencies, which can consume significant disk space over time. Archive retention lets you automatically remove old archived sessions on a per-project basis, while protecting specific sessions you want to keep.

How It Works

When archive retention is enabled for a project, Braide runs a background pruning sweep every hour across all projects. For each project with retention configured, it checks every archived session:

  1. If the session was created more than the configured number of days ago, it is eligible for pruning
  2. If the session has retention protection enabled, it is skipped regardless of age
  3. Eligible sessions are fully removed — the worktree is deleted, the session directory is cleaned up, and connected clients are notified

Configuring Retention

Archive retention is a per-project setting, allowing different retention policies for each project.

  1. Open the Settings modal by clicking the gear icon
  2. Switch to the Project tab
  3. Select Archive Retention in the sidebar under System

Settings

  • Auto-prune archived sessions — Toggle to enable or disable automatic pruning for this project. When disabled, no sessions are pruned automatically.
  • Remove after N days — The number of days after which an archived session becomes eligible for pruning. Minimum is 1 day. Default is 7 days.

Prune Now

Click the Prune now button to immediately run the pruning logic for the current project, rather than waiting for the next hourly sweep. While running, the button shows Pruning… alongside a progress bar and a checked/total counter (plus a running count of sessions pruned). When complete, a result message is shown:

  • Pruned N session(s) — The number of sessions that were removed
  • No sessions to prune — No archived sessions matched the retention criteria

Retention Protection

Individual archived sessions can be protected from automatic pruning regardless of their age. This is useful for sessions you want to keep as reference — for example, a session with an important architectural decision or a complex debugging investigation.

To protect a session, toggle the retainArchive flag on the session. Protected sessions are skipped during both automatic hourly sweeps and manual "Prune now" operations.

Data Storage

The retention setting is stored in the project's settings file:

~/.braide/projects/<project-id>/settings.json

The archiveRetentionDays field is part of the project preferences. When absent or disabled, no automatic pruning occurs for that project.

Related