Problem: worker/UI port in use: "Is port 37777 in use?" —— Trove problem library

What you will run into

After a Windows reboot (or installing several agent tools), claude-mem's worker fails to start with Is port 37777 in use? or Address already in use, and the memory UI won't open. You think the software is broken and reinstall it - same result.

In fact the port is taken by a leftover process; nothing to do with the software itself.

Why this happens

claude-mem's worker is a local resident process that listens on a fixed port for UI/plugin communication. Port occupation has three main causes:

• Note the port changes with the version: old docs say 37777; the measured version here (plugin 13.16.1) prints Worker port: 37700 at install - check the actual output before troubleshooting, don't hunt the wrong port from old docs.
• The fix isn't "reinstall": first see the port -> kill the occupier -> change the port if needed.

A resident worker communicates with the UI/plugin over a fixed-port contract: at startup the worker binds a port, and the UI/plugin connect to that port by convention — the port is their "communication address".

Ports are exclusive resources: only one socket can bind a given address at a time; the second binder gets Address already in use immediately.

The three occupation sources map to three lifecycle problems: leftover process (after a Windows reboot the old worker didn't exit cleanly; the process is still alive and still holds the port), another program (coincidental port collision), TIME_WAIT (the port was just released;

per the TCP spec the kernel must wait before allowing a rebind — protocol requirement, not a fault).

Once "port equals contract" is understood, two conclusions follow naturally: first, the port changes with the version (the contract is decided by the version — 37700 here, 37777 in old docs; trust the install output); second, changing the port is legitimate (the port is claude-mem's own contract;

switching it affects nothing else, just restart the worker after).

Step by step

1. Confirm the actual port — Required

Look at the Worker port: in the install output or claude-mem status - don't assume 37777:

lsof -i :37700   # replace with the actual port; no output = port free

Windows PowerShell:

netstat -ano | findstr 37700

2. Kill the occupying process — Required

macOS/Linux:

kill -9 $(lsof -t -i:37700)

Windows (use the PID from netstat above):

taskkill /F /PID <PID>

3. Still stuck? Change the port — Required

Set an env var, or change it in config:

export CLAUDE_MEM_WORKER_PORT=37701   # or write it to ~/.claude-mem/settings.json

How to confirm it works

claude-mem status prints the version and worker state, and the memory UI opens (measured output shape):

Worker port: 37700
worker running

Other environments

Symptom

The worker fails to start, reporting a port in use (common after Windows reboot); the memory UI won't open.

Cause

The old/partial versions' worker uses fixed port 37777, occupied by a leftover process or another program; zombie sockets (TIME_WAIT) not released.

Solution

1. Confirm the actual port first (trust the install output / claude-mem status): lsof -i :37700 (this version) or lsof -i :37777 (old docs).
2. Clear the occupier: kill -9 $(lsof -t -i:37700) (replace with the actual port).
3. Change the port: CLAUDE_MEM_WORKER_PORT env var, or configure it in ~/.claude-mem/settings.json.