Skip to content

feat(cli): add reset, vacuum, reembed, worker status/stop, config show/edit/doctor, gc#112

Open
jugrajsingh wants to merge 5 commits into
samzong:mainfrom
jugrajsingh:feat/maintenance-cli
Open

feat(cli): add reset, vacuum, reembed, worker status/stop, config show/edit/doctor, gc#112
jugrajsingh wants to merge 5 commits into
samzong:mainfrom
jugrajsingh:feat/maintenance-cli

Conversation

@jugrajsingh

@jugrajsingh jugrajsingh commented Jul 18, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds an operator-facing maintenance surface to the CLI. Six subcommands, grouped because they share the same safety scaffolding (confirmation gates, non-interactive guards) and the same src/maintenance.rs module:

  • recall reset — drops and rebuilds the index from scratch. FTS-trigger-safe: the reset path accounts for the FTS5 triggers on sessions/message_vec so a reset can't leave the trigger-maintained index out of sync with the base tables.
  • recall vacuum — reclaims space after large deletes.
  • recall reembed — clears the vector store and re-queues every session for the background worker to rebuild embeddings.
  • recall worker status — reports whether the background embedding worker is running via a flock probe on the worker lock file (no live IPC needed: acquiring the lock non-blockingly means no live holder exists), plus its pid.
  • recall worker stop — signals the worker to shut down via a safe SIGTERM sequence, with an optional --clear-queue to also drop computed embeddings and re-queue every session. The queue-clear path is guarded to skip while the worker is still running, avoiding a race between the CLI and the worker over session_embedding_state rows.
  • recall config show|edit|doctorshow prints the resolved config as JSON; edit opens it in $EDITOR (requires a TTY), creating a default file first if none exists, and re-validates after the editor exits; doctor runs file-permission, adapter-label, and embedding-backend-availability checks and prints a pass/warn/fail report, exiting 1 on any failure. Includes a doctor remedy wording fix (chmod 600 -> chmod go-w) for the group/world-writable warning.
  • recall gc — deletes indexed sessions no longer worth keeping, classified into four buckets: keep (source enabled, backing file present), disabled (source turned off in config), orphan (backing file missing), and unverifiable (source cannot be checked, e.g. remote adapters). Only disabled and orphan are ever deleted; unverifiable is always kept as a safe-keep guard — gc never deletes a session when its source root is unavailable or its path is unknown. Supports --dry-run to report without deleting and --yes to skip the confirmation prompt. Partial-deletion failures are reported per-session instead of aborting the whole run.

Destructive commands (reset, reembed, gc) prompt for confirmation unless --yes is passed, and refuse to prompt in a non-interactive context (no TTY) rather than blocking forever or silently proceeding.

Adds Store::distinct_session_sources (session-source enumeration for gc classification) and embedding::availability_summary (a cheap, download-free device probe for CUDA/Metal/CPU, used by config doctor).

Verification

  • cargo build, cargo fmt -- --check, cargo test --workspace — green.
  • 39 new tests covering: gc's four-bucket classification (including the unverifiable safe-keep case), worker lock probe against a live vs. stale lock file, config doctor's pass/warn/fail checks, reembed's queue-clear race guard, and reset's FTS-trigger consistency.

Test plan

  • recall gc --dry-run → reports classification without deleting
  • recall gc with a source whose root is unavailable → session kept, not deleted
  • recall worker status while worker running → reports pid, held lock
  • recall worker stop --clear-queue while worker still running → queue-clear skipped, no race
  • recall config doctor on a group-writable config file → warns with chmod go-w remedy
  • recall reset → FTS index stays consistent with base tables after rebuild

@jugrajsingh
jugrajsingh requested a review from samzong as a code owner July 18, 2026 09:54
Adds recall reset to wipe all indexed data while keeping config, with
a confirmation prompt guarded by --yes. Adds recall vacuum to compact
the sqlite database and reclaim disk space.

Extends Store with reset_all_data, vacuum, and path accessors used by
both commands, plus a humanize_bytes utility for reporting reclaimed
space in human-readable form.
Adds recall reembed to clear the vector store and re-queue every
session for the background worker to rebuild, guarded by a
confirmation prompt with --yes to skip it.

Adds Store::clear_semantic_queue, which deletes message_vec and
resets session_embedding_state rows to pending in a single
transaction so state and vectors never diverge. Full-text search
stays available while vectors rebuild in the background.
Adds recall worker status to report whether the background embedding
worker is running (via a flock probe on the worker lock file) and its
pid. Adds recall worker stop to signal it to shut down, with an
optional --clear-queue to also drop computed embeddings and re-queue
every session.

Adds worker_lock_pid/worker_lock_is_held helpers in semantic.rs that
probe the lock file with a non-blocking try_lock_exclusive: acquiring
it means no live holder exists. Guards the queue-clear path so it is
skipped while the worker is still running, avoiding a race between
the CLI and the worker over session_embedding_state rows.
Adds recall config show to print the resolved config as JSON, and
recall config edit to open it in $EDITOR (requires a TTY), creating a
default file first if none exists, and re-validating after the editor
exits.

Adds recall config doctor to run a set of checks (file permissions,
adapter labels, embedding backend availability) and print a pass/warn
/fail report; exits 1 if any check fails. Includes the doctor remedy
wording fix (chmod 600 -> chmod go-w) for the group/world-writable
warning.

Adds embedding::availability_summary, a cheap download-free device
probe (CUDA/Metal/CPU) used by the doctor's embedding check.
…ions

Adds recall gc to delete indexed sessions that are no longer worth
keeping, classified into four buckets: keep (source enabled and
backing file present), disabled (source turned off in config),
orphan (backing file missing), and unverifiable (source cannot be
checked, e.g. remote adapters). Only disabled and orphan sessions are
deleted; unverifiable sessions are always kept as a safe-keep guard.
Supports --dry-run to report without deleting and --yes to skip the
confirmation prompt.

Adds Store::distinct_session_sources to enumerate sources present in
the index for classification.

Reports partial-deletion failures per session instead of aborting the
whole run, and covers the disabled-source deletion path alongside the
orphan path.
@jugrajsingh
jugrajsingh force-pushed the feat/maintenance-cli branch from 07aaee2 to 6219371 Compare July 21, 2026 07:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant