Introducing a new way to review your PRs.

Read the announcement

thedotmack / claude-mem

Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More

View on GitHub

47 documents · Updated Nov 20, 2026

docs / automatic-update-lifecycle

Automatic update lifecycle

Automatic updates move a supported local worker to the promoted product release while preserving the user's setup and protecting active work. The lifecycle checks whether an update is allowed, waits for a safe time, applies the release through the install path, verifies that the new worker can run, and exposes recovery guidance when the switch is incomplete.

This page is part of Distribution integrations. Read Installation and npx CLI for the user-started install path and External notification integrations for update-related notices.

Update eligibility

The update checker is the policy gate for the lifecycle. It protects user choices, avoids development or remote installs, and accepts only a standard local worker with a known release version.

Update switches

The update is enabled only when claude-mem settings and the host editor settings allow it. The check also avoids installs that would change the runtime, restart ownership, or undo a user's choice to disable the plugin. Claude Code's own marketplace updater must not be active at the same time.

The worker and the Auto-update doctor row use the same readers. This keeps the status shown to an engineer aligned with the decision that the worker will make.

References: src/…/auto-update-check.ts• L827-920 src/…/auto-update-switch-readers.ts• L25-64 src/…/doctor.ts• L651-789

Release discovery

The checker reads a promoted-release document and then confirms that the promoted version is fully published in the product registry. It applies only a newer exact release. A bad network read, an unknown release format, or incomplete publication stops the attempt without changing the installation.

The worker performs its first check after startup and then checks often enough to find a safe quiet period. Network checks are limited to about once per day, so a temporary network failure does not create repeated background traffic.

flowchart LR
    A[Local settings and host settings] --> B{Update allowed?}
    B -- No --> C[Record disabled decision]
    B -- Yes --> D[Read promoted release]
    D --> E{New and fully published?}
    E -- No --> F[Record check result]
    E -- Yes --> G[Wait for safe application]

References: src/…/auto-update-check.ts• L510-699 src/…/auto-update-state-file.ts• L27-46 src/…/worker-service.ts• L696-728

Deadline and state handling

The lifecycle uses durable state to coordinate work across the worker, the update supervisor, startup readers, and diagnostics. Deadlines make each wait finite while the state records whether an attempt is still active, ended, or needs help.

Busy deferral

The checker treats active sessions, requests, queues, and important background work as busy. It defers an otherwise valid update while that work is active. If the worker stays busy for a full check cycle, the update proceeds so a continuously used machine does not remain permanently outdated.

The quiet rule protects work that a restart could interrupt. It is a scheduling choice rather than a release decision: the promoted release remains the same while the checker waits.

References: src/…/auto-update-check.ts• L609-739 src/…/worker-service.ts• L730-819

Attempt state

The file src/…/auto-update-state-file.ts defines the shared update record. It keeps the last network check, the last promoted version, any busy deferral, the active attempt, the last outcome, failed versions, check errors, and the last worker decision.

An active attempt has a target version, the prior version, a start time, and supervisor information. The supervisor phase distinguishes target installation from restoration. A release that failed after its files changed is blocked from automatic retry, while a failure that changed nothing can be tried at the next due check.

State reads use safe defaults for missing or malformed known fields and preserve fields added by newer releases. A non-missing file read error does not get treated as an empty state because that could forget an active installation.

References: src/…/auto-update-state-file.ts• L80-224 src/…/auto-update-state-file.ts• L246-345 src/…/auto-update-state.ts• L63-115

Installation transition

Once the checker approves an update, the worker hands the operation to a separate supervisor. The supervisor runs the normal non-interactive update path, checks the resulting installation, and either keeps the target or restores the prior version.

Detached supervisor

The worker writes the attempt state and starts a detached hop. The hop starts the detached supervisor and exits. This removes the supervisor and its installer from the worker's process tree before the worker restarts or recycles.

The supervisor runs the update command from its own controlled run area and uses the registry that the checker verified. The installer has a finite deadline. If its process tree does not stop after that deadline, the supervisor does not start another installer beside it.

sequenceDiagram
    participant W as Worker
    participant H as Detached hop
    participant S as Update supervisor
    participant I as Installer
    participant N as New worker

    W->>W: Record attempt in flight
    W->>H: Start detached hop
    H->>S: Start detached supervisor
    H-->>W: Exit after supervisor exists
    S->>I: Run product update
    I-->>S: End or reach deadline
    S->>N: Start or observe resolved worker
    N-->>S: Report finished startup
    S->>W: Record final outcome

References: src/…/auto-update-launch.ts• L1-31 src/…/auto-update-launch.ts• L301-369 src/…/auto-update-launch.ts• L967-1096 tests/…/auto-update-supervisor-survives-tree-kill.test.ts• L163-217

Installation proof

An installer exit is not enough to declare success. The supervisor checks that the installation resolves to the target release and that a worker on that release finishes startup. A worker that is alive but still starting is not treated as proof of a usable update.

The supervisor checks the install again before it starts a restoration. If another updater has moved to a newer release, it does not downgrade that release. If the target changed the database schema beyond what the prior release understands, the prior release is not restored; the target remains the only version that can safely use the database.

References: src/…/auto-update-apply.ts• L433-503 src/…/auto-update-apply.ts• L545-598 src/…/auto-update-apply.ts• L682-800 src/…/auto-update-launch.ts• L551-570

Installer handoff

The supervisor invokes the same update command exposed by the CLI. An update keeps saved agent, provider, runtime, and host preferences instead of treating the operation as a fresh setup. The installer refreshes the plugin cache and runtime, preserves the marketplace update setting already chosen by the worker, and starts the worker again when the worker runtime was in use.

The CLI entry point maps npx claude-mem update and upgrade to this update mode. Runtime commands use the installed plugin root, while install-side commands run without Bun, so the supervisor can perform the handoff without depending on the worker process.

References: src/…/index.ts• L1-8 src/…/index.ts• L197-202 src/…/install.ts• L1202-1235 src/…/install.ts• L3154-3170 src/…/install.ts• L3220-3247 src/…/install.ts• L3357-3401

Reader coordination

Update state has several readers with different jobs. The worker resolves abandoned attempts, the startup launcher warns before hooks run, and the doctor explains current status. They share the same state rules so a repair message does not disagree with the worker's own view.

Attempt readers

An attempt remains active while its supervisor may still be working. A dead supervisor is considered interrupted only after the recorded deadline rules allow it. The worker then inspects the install to decide whether nothing changed, the target was applied, or a partial switch needs a fix.

The worker does not save a new decision over a supervisor's claim. The supervisor writes its process and phase only when the attempt identity still matches. This prevents a late worker or supervisor write from erasing the other process's ownership.

References: src/…/auto-update-check.ts• L547-591 src/…/auto-update-apply.ts• L301-376 src/…/auto-update-state-file.ts• L394-480

Startup recovery

When a worker finishes starting on the version the install resolves to, it can mark an unresolved update failure as resolved. This covers a repair command, a manual update, or a worker that became ready after the supervisor stopped waiting. The original outcome stays available for history, but startup notices and doctor warnings stop asking for action.

The SessionStart launcher reports only a likely broken install. It does not report every failed attempt because a failed attempt can leave the prior release working. The doctor provides the wider status view, including the last decision, check error, attempt stage, and repair instruction.

References: src/…/worker-service.ts• L822-859 src/…/ensure-launcher.ts• L109-128 src/…/doctor.ts• L698-758 src/…/auto-update-install-shape.ts• L37-70

CLI health view

The read-only npx claude-mem doctor command gives operators one view of the install root, runtime health, hook launcher, and update state. Its Auto-update row shows the worker's last decision when available. Before the worker records a decision, doctor reads the same switches in the terminal environment and says that the result came from doctor.

The view separates an update that failed while the old install still works from an update that may have left the install unusable. It also reports whether Claude Code's background marketplace update is active and whether claude-mem changed that setting.

References: src/…/doctor.ts• L651-789 src/…/doctor.ts• L1092-1135

Cache and installation safety

Each update creates a runnable versioned plugin source and then removes only cache entries that no active consumer needs. This keeps the new release available while protecting a live worker, an open host session, and the version registered for launch.

Cache retention

The installer prunes old cache versions after it copies the new release. The standalone npx claude-mem prune command exposes the same plan and supports a dry run or a different retention count. If a running worker exists but its version cannot be read, the safe result is to retain all versions.

The cache plan protects more than the newest releases. It also keeps the live worker's version, the registered install, the resolver's launch version, the newest complete runtime, and versions still loaded by active Claude Code sessions. This prevents cleanup from breaking a process that already started from an older release.

References: src/…/install.ts• L1005-1036 src/…/prune.ts• L1-19 src/…/prune.ts• L70-110

Backup coordination

Database snapshots are managed by the worker, while npx claude-mem backup is a thin read or request client. This keeps snapshot creation and restore safety in the worker that owns the database instead of adding a second database writer to the update path.

The command can show snapshot status, create a snapshot, or list available snapshots. It reports when the worker is not running and does not seed local settings merely to make a backup request.

References: src/…/backup.ts• L1-5 src/…/backup.ts• L19-37 src/…/backup.ts• L65-145

Safety boundaries

The update path limits damage from races, partial writes, process loss, and unintended environment changes. Its main safety rule is to prefer a known working version or an explicit repair instruction over an ambiguous switch.

User ownership

The checker leaves the update off when the user or an administrator has disabled the plugin, removed its user-scope registration, selected another runtime, or configured Claude Code to update the marketplace itself. It does not silently restore those choices during an unattended update.

The installer preserves the marketplace update choice when it registers the marketplace again. It also keeps non-user plugin registrations and does not change optional host memory preferences during update mode. The installer marks its run as automatic so unattended update telemetry is separate from user install results.

References: src/…/auto-update-check.ts• L837-920 src/…/install.ts• L187-243 src/…/install.ts• L315-328 src/…/install.ts• L4015-4034

Worker and runtime ownership

The CLI resolves the same plugin root that the worker uses. This allows a cache-based install to remain a valid install even when the marketplace copy is not the active root. A worker or update command fails clearly when no plugin root or Bun runtime is available.

Update mode does not re-run server bootstrap when the saved runtime is already known. The server runtime has its own process and storage ownership, while the worker runtime returns to the worker service after installation.

References: src/…/runtime.ts• L13-36 src/…/runtime.ts• L85-110 src/…/install.ts• L1202-1230 src/…/install.ts• L3160-3170

Failure recovery

After a switch starts, the supervisor either proves the target or restores the prior version when the database still permits that version. A partial switch or failed restoration becomes restore_failed with a concrete repair command and a time condition. If the database has moved beyond the prior version, the repair points forward to a release newer than the failed target.

The result is recorded as applied, failed, restored, or restore_failed. This distinction lets the next worker tick retry only safe cases and lets human-facing readers show action only when the install may not work.

References: src/…/auto-update-apply.ts• L18-51 src/…/auto-update-apply.ts• L682-800 src/…/auto-update-state-file.ts• L48-77 src/…/auto-update-state-file.ts• L434-500

Uninstall boundary

Uninstall stops the worker before removing the marketplace, cache, registrations, launcher, and integration links. It preserves the data directory, leaves a running process named when shutdown cannot be confirmed, and keeps the marketplace when a host integration still needs it for a safe retry.

This boundary matters to updates because cache cleanup and registration changes must not remove files from a process that still owns the database or a host integration that still points at the package.

References: src/…/uninstall.ts• L227-272 src/…/uninstall.ts• L290-350 src/…/uninstall.ts• L353-450

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the promoted-release format, registry publication proof, and installer source aligned. The checker must verify the same release source that the supervisor installs.
  • Keep the shared state shape aligned across the worker check, supervisor, ready-worker recovery, SessionStart launcher, and doctor row. A new field or outcome must keep its read and repair meaning in each reader.
  • Keep install version readings and worker readiness proof aligned. A successful installer process must not become a successful product update without a usable worker.
  • Preserve the detached process boundary and the attempt identity checks. A worker recycle must not kill an active update or overwrite its supervisor claim.
  • Keep schema compatibility checks before restoration. A prior release must not be reinstalled over a database that it cannot open.
  • Keep cache retention protection aligned with every process that can load a plugin version. A new launch path must not make pruning remove its source.
  • Keep CLI command routing aligned with supervisor invocation. Update mode must preserve saved runtime and setup choices instead of entering fresh-install prompts.

Important failure modes

TriggerConsequenceGuard
The promoted release or registry metadata cannot be readThe update does not start and the failed check is recordedA due check has a bounded fetch and treats the network read as the check result
The worker stays busyThe update waits instead of interrupting active workBusy time is tracked and capped at one check cycle
The installer writes only part of the targetThe install may resolve to mixed or incomplete filesThe supervisor classifies the switch, marks the target, and restores only when safe
The supervisor disappears during installationThe next worker tick must not mistake an unfinished attempt for successThe state keeps the attempt deadline and phase, then readers inspect the install shape
Another updater installs a newer releaseA restore could downgrade the newer releaseThe supervisor re-reads the install before each installer and stops when it sees a newer version
The target advances the database schema and cannot startThe prior release cannot safely be restoredThe supervisor keeps the target and gives a forward repair instruction
A worker recycle kills the launcher treeA directly attached supervisor and installer would stopThe detached hop removes the supervisor from the worker's descendant tree
Cache cleanup cannot read the live worker versionCleanup could remove the source of a running workerPruning retains all versions when worker ownership is uncertain
Update mode starts server bootstrap againA saved server URL or key can be replacedUpdate mode reuses the stored runtime when no runtime flag is given

Key files

FileWhy to read it
src/…/auto-update-check.tsDefines eligibility gates, release checks, busy deferral, and the launch decision.
src/…/auto-update-state-file.tsDefines shared state and the meanings read by recovery, startup, and diagnostics.
src/…/auto-update-launch.tsShows the worker-to-hop-to-supervisor handoff, installer boundary, and readiness proof.
src/…/auto-update-apply.tsShows how the supervisor proves, restores, or blocks an update after a switch starts.
src/…/auto-update-switch-readers.tsShows how the worker and doctor obtain the same host and install decisions.
src/…/worker-service.tsShows when checks run and how a ready worker resolves an interrupted or failed update.
src/…/ensure-launcher.tsShows the startup warning path for an install that may be broken after an update.
src/…/index.tsShows how user update, runtime, doctor, prune, and backup commands enter the system.
src/…/install.tsShows how update mode preserves setup, refreshes the install, starts the worker, and prunes old versions.
src/…/doctor.tsShows the human-facing update status and repair view.
src/…/prune.tsShows the operator-facing cache retention and dry-run boundary.
src/…/uninstall.tsShows the shutdown and cleanup boundary that protects active processes and data.