> ## 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.
# Checkpoint Storage
> Where Entire keeps checkpoints, which backend a repository uses, and how the two backends coexist.
Entire writes checkpoints into your own Git repository, in objects separate from your source branches. Your code stays on your source branches, while prompts, transcripts, session context, and checkpoint metadata live in checkpoint storage.
We verified this page against **Entire CLI 0.10.2**. Run `entire version` to check what you have installed.
## 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.
Change this when checkpoint history should follow a different storage or access boundary:
* [**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.
| Backend | How it stores checkpoints | Checkpoint ID |
| ------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Ref-based** (`git-refs`) | One Git ref per checkpoint, at `refs/entire/checkpoints//` | 26-character, time-sortable ULID, such as `01KVBJCWYA4YW6J5M9GP655HZN` |
| **Branch-based** (`git-branch`) | Every checkpoint on the shared [`entire/checkpoints/v1`](/glossary#checkpoints-branch) branch | 12-character hexadecimal ID, such as `a3b2c4d5e6f7` |
**Ref-based storage is the default.** Since Entire CLI 0.10.0, `entire enable` writes it during a first-time setup and no longer asks you to choose. A repository you enabled before 0.10.0 stays branch-based until you change it.
Each ref points at a commit whose tree root is that one checkpoint's contents, so Entire pushes and fetches a single checkpoint without moving the rest, and multiple agents can save checkpoints at once without competing to update one branch. Under branch-based storage, each checkpoint sits at `//` in the branch tree, so every condensation rewrites one branch tip and the whole history travels together on push.
## 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 `` is the last two characters of the ID and `` 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
```bash theme={null}
entire enable --checkpoint-backend refs # first-time setup
entire configure --checkpoint-backend refs # already enabled
```
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.
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.
```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
```
## 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
Push checkpoint history to a repository separate from your code.
Capture checkpoints without pushing them anywhere.
See every location Entire writes to and what redaction covers.
Fix checkpoints that did not sync or landed in the wrong place.