Expand description
asd gc — preview, and on request perform, a garbage-collection sweep of
the ASG store behind this repository.
Every asd index commits a fresh state tree. Content addressing shares the
unchanged parts, but the interior nodes on each changed path are new, so the
store grows with every run. Until AgentStateGraph v1.2.2 each of those
checkpoints also pinned its snapshot as a milestone, which kept nearly all of
it reachable: measured on one store, 7.9 GB whose live state was 3.4% of its
objects. asd gc is how that space comes back.
By default it only previews. Nothing is deleted without --sweep, and
the preview reports exactly what a sweep under the same policy would keep and
reclaim. When mutating, the steps run in this order:
- Distil any not-yet-extracted history. A sweep refuses while any commit is undistilled, so its signal is never lost with its state.
--unpin-legacy: stop pinning milestones distilled before v1.2.2. One time, deletes nothing; without it a sweep of an older store reclaims little.--sweep: delete every object outside the retention policy’s keep-set. AgentStateGraph holds the store’s write lock from computing that keep-set to the last delete, so another ASD process committing meanwhile — a git hook,asd-serve, an MCP server — waits or fails rather than losing data.--vacuum: shrink the file. A sweep frees pages inside the database; only a vacuum returns them to the OS.
Mutation is deliberately CLI-only: asd-serve exposes the preview, never
the sweep. Run this on the machine that owns the database.