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 proven orphaned background processes so you can restart cleanly.
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 | Classifies workspace owners, live editor/agent MCP sessions, proven orphaned MCP sessions, sidecars, and processes whose parent state cannot be proved. |
| 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:
$ memtrace doctor --fix --repair-install
Fix mode#
--fix applies local cleanup immediately. It can stop the workspace owner, terminate MCP sessions whose parent is proven dead, free the dashboard port, and delete stale PID/runtime state files. It reports but leaves live editor/agent-owned and unclassified MCP sessions alone. It does not remove your graph database, credentials, team configuration, or source files.
| Mode | Effect |
|---|---|
memtrace doctor --fix | Clean stale runtime state, terminate proven orphaned MCP sessions, stop the workspace owner, 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 acts immediately and does not ask for confirmation. It does not kill MCP sessions with live editor/agent parents. To tear those down too, pause the clients first and use memtrace stop --all-mcp.
Flags#
| Flag | Description |
|---|---|
--fix | Apply local cleanup for stale runtime state, proven orphaned MCP sessions, the workspace owner, 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 uses npx to run the skills installer. If npx is not available on PATH, doctor reports that as part of the repair failure.
Examples#
$ 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.