> ## Documentation Index
> Fetch the complete documentation index at: https://docs.entire.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Storage

> Where Entire stores your session and the checkpoints that are linked with your commits.

Entire stores checkpoints inside your own Git repository, separate from your source branches. Your code stays on your source branches, while prompts, transcripts, session context, and checkpoint metadata live in checkpoint storage. Most of this happens behind the scenes, so your workflow stays the same: you create, search, explain, and resume checkpoints with the same Entire commands regardless of how they are stored.

<Note>
  We verified this page against **Entire CLI 0.10.2**. Run `entire version` to check what you have installed.
</Note>

## Store Checkpoints with Your Code

This is the default and needs no configuration. Entire stores checkpoint data in the same Git repository as your code and pushes it when you push, which keeps the commit, the checkpoint, and the agent context together while leaving your normal Git history clean.

In a repository with several remotes, Entire elects one checkpoint sync remote rather than copying checkpoints everywhere you push. `entire status` names the destination and counts checkpoints that have not reached it.

This can be changed if you want your checkpoint and session storage history to reside elsewhere:

* [**Push checkpoints to a separate repository**](/guides/checkpoints/store-checkpoints-in-another-repo)
* [**Keep checkpoints local on your machine**](/guides/checkpoints/keep-checkpoints-local)

## The Two Storage Backends

The backend controls how Git organizes checkpoint data. It is a separate question from which repository receives that data.

### Ref-Based Storage

Ref-based storage (`git-refs`) is the default. It gives each new checkpoint its own Git ref, a named pointer inside your repository that Entire creates and manages for you. Each ref lives at `refs/entire/checkpoints/<shard>/<id>`, and Entire saves and retrieves each checkpoint independently.

**The benefit:** With ref-based storage, pushes and reads stay fast even as your repository accumulates more agent history. Multiple agents can also save their work at the same time without competing to update a shared branch.

Ref-based checkpoints use 26-character, time-sortable ULIDs, such as `01KVBJCWYA4YW6J5M9GP655HZN`.

Ref-based storage first shipped as an opt-in option in Entire CLI 0.8.42 and became the default in 0.10.0, where `entire enable` writes it during a first-time setup and no longer asks you to choose.

### Branch-Based Storage

Branch-based storage (`git-branch`) keeps every checkpoint on a shared Git branch called [`entire/checkpoints/v1`](/glossary#checkpoints-branch). Each checkpoint sits at `<first two characters of the ID>/<rest of the ID>/` in the branch tree.

**The benefit:** All checkpoint history lives on one branch you can check out, browse, or clone like any other branch.

Branch-based checkpoints use 12-character hexadecimal IDs, such as `a3b2c4d5e6f7`.

A repository you enabled before Entire CLI 0.10.0 uses branch-based storage and stays on it until you [switch backends](#switch-backends).

<span id="configure-checkpoint-storage" />

## Find Which Backend a Repository Uses

The backend is named by `checkpoints.primary.type` in `.entire/settings.json`, or in `.entire/settings.local.json` when someone set it for their clone alone. An absent `checkpoints` block resolves to `git-branch`, which is why a pre-0.10.0 repository keeps branch storage without any setting naming it.

Checkpoint storage is ordinary Git, so Git reads it without Entire installed. List the per-checkpoint refs:

```bash theme={null}
git for-each-ref refs/entire/checkpoints/
```

Each line names one checkpoint, where `<shard>` is the last two characters of the ID and `<id>` is always the leaf. Check for branch-backed checkpoints too:

```bash theme={null}
git show-ref entire/checkpoints/v1
```

Output from both means the repository holds checkpoints in both formats, which is the expected state after a backend switch. To confirm what reached the remote, run `git ls-remote origin 'refs/entire/checkpoints/*'`.

## Both Backends Stay Readable

Every reader routes by ID format, so one repository can hold both formats at once. This holds for the CLI, entire.io, and the Entire API.

| Checkpoint ID             | Where the read goes                                                                        |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| ULID                      | Refs only. ULIDs are minted only under ref-based storage                                   |
| Hex, branch-based backend | The `entire/checkpoints/v1` branch                                                         |
| Hex, ref-based backend    | Refs first, then the branch, since a hex checkpoint may still sit on the pre-switch branch |

`entire checkpoint list` merges both backends and de-duplicates by ID. A new checkpoint goes to the configured backend, while a backfill that adds a transcript, summary, or attribution to an existing checkpoint lands in whichever backend already holds it.

## Switch Backends

To enable ref-based storage in a new repository, run:

```bash theme={null}
entire enable --checkpoint-backend refs
```

To enable it in an existing Entire-enabled repository, run:

```bash theme={null}
entire configure --checkpoint-backend refs
```

Both commands accept `refs` and `branch`, plus the canonical `git-refs` and `git-branch` that settings store. Add `--local` when the choice should apply only to your clone.

A switch applies to new checkpoints. Checkpoints written before the switch stay exactly where they are and keep resolving through the routing above, so `entire checkpoint list`, `entire checkpoint explain`, attribution, and entire.io continue to serve them. Entire deletes nothing during a switch, and your commands and commit workflow do not change.

Two things do change after a switch to ref-based storage. New checkpoint IDs become ULIDs instead of hex, and the pre-push hook starts pushing queued per-checkpoint refs instead of the `entire/checkpoints/v1` branch. Leave that branch on the remote: it is where readers find every checkpoint captured before the switch.

## Migrate Existing Checkpoints into Refs

Migration is optional, since the routing above already resolves branch-backed checkpoints under a ref-based backend. Migrate when you want the whole history in one format, or when you want to stop carrying the v1 branch.

<Warning>
  Run the migration **before** you switch the backend to refs. The command refuses to run once ref-based storage is primary, because the refs are authoritative at that point and re-importing branch snapshots could only move them backwards.
</Warning>

```bash theme={null}
entire doctor migrate-checkpoints --dry-run
entire doctor migrate-checkpoints
```

The command wraps each checkpoint's current tree in a fresh commit and points its ref at it, keeping the hex ID as the ref name. It does not rewrite the branch commits, and it does not delete the branch. It skips checkpoints it has already converted, so you can re-run it after more branch activity.

| Flag            | Description                                                             |
| --------------- | ----------------------------------------------------------------------- |
| `--dry-run`     | Report what would be migrated without writing refs                      |
| `--remote NAME` | Push migrated refs to this remote instead of the checkpoint sync remote |

Migrated refs are queued for push. Run interactively, the command asks whether to push them now. Run without a terminal, it leaves them queued, and they flush on the next `git push` once ref-based storage is primary. Then switch and push:

```bash theme={null}
entire configure --checkpoint-backend refs
git push
```

<span id="auto-generate-checkpoint-summaries" />

## Auto-Generate Checkpoint Summaries

Checkpoint metadata can carry a summary generated at commit time. Enable it with `strategy_options.summarize.enabled`:

```json .entire/settings.json theme={null}
{
  "strategy_options": {
    "summarize": {
      "enabled": true
    }
  }
}
```

Then choose the provider and model:

```bash theme={null}
entire configure --summarize-provider PROVIDER
entire configure --summarize-model MODEL
```

## Where Storage Settings Are Saved

`entire configure` writes to `.entire/settings.json` by default, so the repository shares the setting. Add `--local` to write `.entire/settings.local.json` instead, which applies only to your clone and takes precedence over project settings.

The `checkpoints` block is a selection, not a merged document: a `checkpoints` block in `.entire/settings.local.json` replaces the one in `.entire/settings.json` outright. The `strategy_options` keys merge by layer as usual. See [Local, Project, and Global Settings](/guides/configuration/settings-layers) for the full table.

## Continue With

<CardGroup cols={2}>
  <Card title="Store Checkpoints in Another Repository" icon="database" href="/guides/checkpoints/store-checkpoints-in-another-repo">
    Push checkpoint history to a repository separate from your code.
  </Card>

  <Card title="Keep Checkpoints Local" icon="laptop" href="/guides/checkpoints/keep-checkpoints-local">
    Capture checkpoints without pushing them anywhere.
  </Card>

  <Card title="Security and Privacy" icon="shield" href="/security#where-your-data-lives">
    See every location Entire writes to and what redaction covers.
  </Card>

  <Card title="Checkpoint Troubleshooting" icon="wrench" href="/guides/sessions/troubleshooting">
    Fix checkpoints that did not sync or landed in the wrong place.
  </Card>
</CardGroup>