Maintenance

Maintenance commands operate on one Profile's durable state. Start with a backup and prefer non-destructive or dry-run modes.

These commands maintain SQLite storage. They do not summarize a conversation or change model context; see Context compaction for that feature.

Before You Begin

anyy backup create
anyy gateway status

Commands that write state offline require exclusive Profile ownership. If Anyy says the Profile is in use, do not bypass the lock—stop that Profile's Gateway and retry the offline operation.

Checkpoint the State Database

anyy maintenance checkpoint-state

This checkpoints the SQLite write-ahead log into the main database file. It requires offline Profile ownership. Target a named Profile with anyy --profile work maintenance checkpoint-state.

Use it before copying raw database files only when a supported backup is not suitable. anyy backup create remains the normal way to protect a Profile.

Create a Compact Copy

The safer compaction mode writes a new database without replacing the original:

anyy maintenance compact-state --output /secure/path/state.compact.db

Inspect and protect the copy before choosing in-place replacement:

anyy maintenance compact-state --replace

--replace requires the Gateway to be stopped and exclusive Profile ownership. --output and --replace cannot be combined. Use --temp-dir only when the default temporary location lacks space.

Keep the backup until verification passes

After replacement, run anyy status and anyy doctor before deleting the backup or compact copy.

Cache Missing Token Estimates

Preview work without changing the database:

anyy maintenance cache-token-estimates

Apply estimates only to messages that do not already have a positive token count:

anyy maintenance cache-token-estimates --execute

Use --limit N to bound candidates and --json for an auditable result. Execute mode requires offline Profile ownership; dry-run mode opens existing state read-only and does not create a missing database.

Safe Sequence

1. Create a Profile backup.
2. Stop the correct Gateway if the command requires offline ownership.
3. Run the non-destructive or dry-run form.
4. Review paths and counts in the output.
5. Run the write form only if needed.
6. Start the Gateway and verify status and doctor.

Troubleshooting

Symptom	Action
Profile ownership conflict	Stop the Gateway for that exact Profile and retry
Compact output cannot be created	Check destination permissions and free space
--replace is rejected	Remove --output, stop the Gateway, and retry with a backup available
Token estimate dry run finds nothing	No retained message is missing a positive estimate