Skip to content

feat(desktop): guide local Server setup and lifecycle management #2117

Open

Description

@knqiufan

Goal

Guide personal users through local installation to a usable Memory workspace, and provide subsequent local service management within Settings & help. Keep connecting an existing Server as an independent path.

Parent: #2114. Release: #2099. Required targets are Windows 11 x64 and macOS Apple Silicon/Intel; Linux support is optional and does not block this issue.

PR breakdown

  • PR 12-A — First-run local setup. Add the local/existing-Server choice, installation plan preview, explicit execution, structured progress and connection handoff. Resolve the Server's default Scope through public operations and guide the first Memory action.
  • PR 12-B — Recovery and existing installations. Present interrupted/failed/damaged/foreign/occupied/incompatible states and supported resume or repair actions. Reopening Desktop reinspects actual operation state; existing independent installations are connected without implicit takeover.
  • PR 12-C — Local Server management. Add status, start/stop/restart, supported login-start choice, diagnosis and registration removal under Settings & help → Local Server. Distinguish app removal, service removal and user-data deletion.

Dependencies and coordination

Acceptance criteria

  • First use offers local setup and connect-existing. Selecting an existing/remote Server never installs a local Server.
  • Local setup explains resources, program/config/data locations and service/autostart effects, then executes the explicit approved plan. Users need no terminal, copied token or manually entered Scope ID for the default personal path.
  • Follow Tracking: deliver personal local Server setup and management in Desktop #2114's RFC docs(rfc): define usability and agent workflows #1733 local policy: loopback-only, SQLite/user data, model-free basic operations, and consistent local authentication/Dashboard settings; retain existing choices and remote auth.
  • Installation, configuration, registration, process startup, readiness and usable connection are separately represented. Only actual returned identity/address and successful qualification enable the authorized connection handoff.
  • Setup consent may cover initial activation and its disclosed readiness probe. Reopening the app does not silently restore a private session or retarget a connection.
  • Reopen after interruption loads/reconciles durable producer status. Resume/repair does not blindly repeat an uncertain mutation, overwrite unrelated installations, or destroy existing data.
  • Existing valid installations can be connected. Takeover, if supported, requires an explicit ownership/compatibility plan; unknown ownership or database incompatibility has a clear supported next action.
  • Local Server management uses only constrained native operations. Closing Desktop leaves the OS-managed Server independent; explicit stop/remove and data retention have clear consequences.
  • All UI includes English/Chinese, keyboard/focus, screen-reader labels, small-window/scaling behavior and usable progress/cancel/error states. No fifth top-level navigation is required.
  • On clean Windows/macOS, complete setup → exact default Scope → first save → bounded search → exact read → copy, then exercise app restart, service stop/start, login/reboot and recovery with real artifacts.

Non-goals

Automatic Agent installation/project binding, a new Client daemon, automatic updates, arbitrary old-database migration, universal offline setup, or first-wave Linux qualification.

Metadata

Metadata

Assignees

Labels

desktopDesktop application, native platform integration, and packaging

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions