Maintenance

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

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—use a resident maintenance path where offered or stop that Profile's Gateway.

Automatic Resident Housekeeping

The resident Gateway runs a bounded semantic maintenance pass at startup, every 24 hours, and when the object store signals that cleanup work is ready. It can:

• release already delivered parent-session inbox payloads;
• expire temporary audit receipts and pending artifacts whose retention has ended;
• release stale execution-recovery data;
• collect unreferenced content-addressed objects; and
• checkpoint and incrementally reclaim free SQLite pages.

This pass does not select canonical conversation transcripts, Memory files, bound or pinned Artifacts, Workspace files, or still-owned evidence for deletion. Under a storage-full recovery path, Anyy may also discard the rebuildable lexical search cache; canonical records remain the source for rebuilding it.

The last automatic pass and pending-cleanup counts appear under the storage section of anyy status --json. This housekeeping is different from the manual database-copy and token-cache commands below.

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.

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
Automatic maintenance reports an error	Check anyy status --json, free local storage if needed, then inspect redacted Gateway logs