Summary

uv tool uninstall memtomem (and the equivalent for other install contexts) only removes the binary — ~/.memtomem/ survives intact, so a subsequent reinstall picks up stale config/fragments/DB that may not match the new version's expectations. Documented manual cleanup is rm -rf ~/.memtomem/, which misses custom storage paths, running servers, and the per-context binary-uninstall command.

mm uninstall closes that gap: builds a categorised inventory of state files, refuses to delete while the MCP server is alive (open WAL handles risk corruption), prints the exact binary-uninstall command for the detected install context, and detects external editor MCP entries (~/.claude.json etc.) so the user can clean them up manually.

mm uninstall                  # interactive, removes everything
mm uninstall -y               # skip confirmation
mm uninstall --keep-config    # preserve config.json + config.d/* + backups
mm uninstall --keep-data      # preserve DB + memories/
mm uninstall --force          # bypass server liveness check (stale pid case)

Design highlights

• State vs binary separation — Memtomem owns ~/.memtomem/; the package manager owns the binary. The command never executes the binary uninstall (different tool's permission scope), but prints the exact command for the detected mm_binary_origin:
  • uv-tool → uv tool uninstall memtomem
  • uvx → no action (ephemeral)
  • venv-relative → uv pip uninstall memtomem (or rm -rf .venv)
  • system → pip uninstall memtomem
  • unknown → conservative fallback hint
    Reuses the existing RuntimeProfile from cli/init_cmd.py (no duplication).
• Server liveness check — probes ~/.memtomem/.server.pid via os.kill(pid, 0). If alive: refuse with exit code 2 + shutdown hint + --force override. Open WAL handles during DB deletion would corrupt the file.
• Config-load fallback — uninstall is a recovery scenario, so it can't depend on a valid config.json. Any exception escaping load_config_overrides is caught and the default DB path is used as fallback (yellow warning shown).
• Custom storage path — storage.sqlite_path outside ~/.memtomem/ is included in the deletion scope (DB + WAL/SHM/journal siblings only). Other siblings of the custom path are inventory-only — never touched. User-managed memory_dirs are never touched either.
• Ordered low→high-value deletion — pid/session → fragments → backups → config → memories → uploads → DB. Mid-flight failure exits 2 with "removed up to X, failed at Y", leaving a recoverable trail.
• External MCP detection only — ~/.claude.json, ~/.codex/config.toml, ~/.cursor/mcp.json, etc. are detected and reported. Not modified in this PR (per-editor schemas + backup + idempotency need their own design).

Tests (19 cases, all passing)

• TestEmptyState — fresh HOME, no ~/.memtomem/ → exits 0 with binary hint
• TestDefaultDeletion — full state wipe with prune
• TestKeepConfig / TestKeepData — flag preservation semantics
• TestCustomStoragePath — custom DB outside default dir included; non-DB siblings preserved
• TestUserMemoryDirsUntouched — memory_dirs paths never deleted
• TestExternalsDetectedNotModified — ~/.claude.json shown but unchanged
• TestBinaryHintPerOrigin — parametrised over all 5 mm_binary_origin values
• TestNonTtyAbort vs TestInteractiveCancellation — distinct messages, both leave state untouched
• TestServerAliveRefuses — pid=current process refused; --force bypasses
• TestPidStaleProceeds — dead pid is treated as deletable
• TestConfigFallback — load_config_overrides raise → fallback DB path used
• TestRuntimeProfileImportPin — forces follow-up if init_cmd renames/moves the runtime symbols

Out of scope (deferred to follow-up PRs)

• Modifying external editor configs (detect-and-report only here)
• Provider/model mismatch CLI banner at startup
• Schema version tracking + downgrade detection
• RuntimeProfile extraction to shared module (the import pin test catches drift; refactor itself is a separate PR per one-change-per-PR)
• Parsed mcpServers.memtomem key check (currently substring grep — false-positive-tolerant since it's detect-and-report only)
• --dry-run flag (interactive prompt + inventory is de-facto dry-run)

Verification

• uv run ruff check + uv run ruff format --check pass
• uv run mypy packages/memtomem/src/memtomem/cli/uninstall_cmd.py clean
• uv run pytest packages/memtomem/tests/test_uninstall_cmd.py → 19 passed
• uv run pytest -m "not ollama" → 2127 passed, 0 regressions
• Manual smoke under tmp HOME — empty state, populated state, server-alive refusal, --force override, --keep-config / --keep-data combinations all behave as designed
• Docs updated: docs/guides/uninstall.md gains a "Recommended: mm uninstall" section pointing at the new command

🤖 Generated with Claude Code