memtrace doctor

Diagnose stale runtime state, port conflicts, and agent setup, then optionally clean up local state non-interactively.

Usage#

memtrace doctor [--fix] [--repair-install] [--purge-legacy] [--json]

memtrace doctor checks the local Memtrace runtime and reports anything that could make the CLI, dashboard, or agent connection behave strangely. With no flags it only reports findings. With --fix it cleans up stale local state and stops conflicting background processes so you can restart cleanly.

USE THIS BEFORE REINSTALLING

If memtrace start says another owner is running, the dashboard port is stuck, or an agent cannot see Memtrace tools after setup, run memtrace doctor first. It tells you whether the problem is runtime state, a port conflict, or missing agent registration.

What it checks#

Run without flags, doctor checks these local conditions without changing anything:

Check	What it means
Running Memtrace processes	Reports whether multiple local Memtrace processes appear to be active at once.
Workspace owner health	Checks whether the saved workspace owner is alive and whether its local health endpoint responds.
PID and runtime files	Finds stale or unreadable local state files that can make a stopped runtime look alive.
Dashboard port	Reports which process is listening on the configured dashboard port, default 3030.
Legacy background services	Finds older OS-level services that could restart an outdated Memtrace process after you stop it.
Agent setup	Checks whether supported coding agents have Memtrace MCP registration and skills installed.

When a finding has a known recovery path, doctor prints the next command to run. For a broken or incomplete agent setup, the usual repair path is:

terminal

$ memtrace doctor --fix --repair-install

Fix mode#

--fix applies local cleanup immediately. It can stop conflicting Memtrace background processes, free the dashboard port, and delete stale PID/runtime state files. It does not remove your graph database, credentials, team configuration, or source files.

Mode	Effect
`memtrace doctor --fix`	Clean stale runtime state, stop conflicting local Memtrace processes, and free the dashboard port when needed.
`memtrace doctor --fix --repair-install`	Also reinstalls Memtrace skills and MCP registration for detected agents using `npx -y memtrace-skills@latest install --local`.
`memtrace doctor --fix --purge-legacy`	Also removes older OS-level Memtrace service entries that could restart an outdated background process.

FIX MODE IS NON-INTERACTIVE

--fix acts immediately and does not ask for confirmation. Close any work that depends on a currently running Memtrace process before using it.

Flags#

Flag	Description
`--fix`	Apply local cleanup for stale runtime state, conflicting processes, and port ownership.
`--repair-install`	Repair agent skills and MCP registration. Use with `--fix` for the normal recovery flow.
`--purge-legacy`	Remove older OS-level service entries. Use with `--fix`; by itself it only reports the normal doctor findings.
`--json`	Print a machine-readable report instead of the human-readable terminal output.

Automation#

Doctor is safe to run from scripts because report mode does not mutate anything. For automation, prefer memtrace doctor --json and inspect the findings you care about instead of relying on the process exit code alone.

REPAIR INSTALL REQUIRES NPX

--repair-install uses npx to run the skills installer. If npx is not available on PATH, doctor reports that as part of the repair failure.

Examples#

terminal

$ memtrace doctor
# Report local runtime and agent setup issues. Nothing changes.

$ memtrace doctor --fix
# Clean stale runtime state and free conflicting local ownership.

$ memtrace doctor --fix --repair-install
# Clean runtime state and repair agent MCP/skills registration.

$ memtrace doctor --fix --purge-legacy
# Also remove older OS-level service entries that could restart Memtrace.

$ memtrace doctor --json
# Print a machine-readable report.

If doctor reports a healthy runtime but your agent still cannot call Memtrace tools, check Troubleshooting, memtrace status, and memtrace start.