worker/UI 端口占用："Is port 37777 in use?"

你会遇到什么

Windows 重启之后（或装了多个 Agent 工具后），claude-mem 的 worker 启动失败，报 Is port 37777 in use? 或 Address already in use，记忆 UI 打不开。你以为是软件坏了，重装一遍还是老样子——其实是端口被残留进程占了，跟软件本身无关。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

claude-mem 的 worker 是一个本地常驻进程，它要监听一个固定端口供 UI/插件通信。端口被占的原因主要有三类：

• 注意端口号随版本变化：老资料写的是 37777，本市场实测版本（插件 13.16.1）安装输出是 Worker port: 37700——排查前先看实际输出，别按旧资料找错端口。
• 解决思路不是"重装"，而是：先看端口 → 杀掉占用者 → 必要时换端口。

常驻 worker 与 UI/插件通信靠的是固定端口契约：worker 启动时绑定一个端口，UI/插件按约定连这个端口——端口就是它们之间的“通信地址”。端口是排他资源：同一时刻同一地址只能被一个 socket 绑定，第二个绑定者直接收到 Address already in use。

三个占用来源对应三种生命周期问题：残留进程（Windows 重启后旧 worker 没退干净，进程还在、端口还握着）、别家程序（巧合撞端口）、TIME_WAIT（端口刚释放，内核按 TCP 规范要等一段时间才能重新绑定——这是协议要求，不是故障）。

理解“端口即契约”后，两个推论自然成立：一是端口号随版本变（契约由版本决定，本版 37700、老资料 37777，以安装输出为准），二是改端口是合法的（端口是 claude-mem 自己的契约，换一个不影响别人，改完重启 worker 即可）。

实测环境：claude-mem 插件本体 13.16.1，2026-08-28 本市场实测。

一步步来

1. 先确认实际端口 — 必做

看安装输出或 claude-mem status 里写的 Worker port: 是多少，别默认 37777：

lsof -i :37700   # 按实际端口替换；没有输出 = 端口没被占

Windows PowerShell 用：

netstat -ano | findstr 37700

2. 杀掉占用进程 — 必做

macOS/Linux：

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

Windows（用上一步 netstat 拿到的 PID）：

taskkill /F /PID <PID>

3. 还不行就换端口 — 必做

设环境变量，或用配置改端口：

export CLAUDE_MEM_WORKER_PORT=37701   # 或写入 ~/.claude-mem/settings.json

端口是 claude-mem 自己用的，改端口不影响你的其它项目；改完重启 worker 即可。

怎么确认修好了

claude-mem status 能正常输出版本和 worker 状态，且记忆 UI 能打开，就算成功（实测输出示意）：

Worker port: 37700
✔ worker running

其它环境的表现

症状

worker 启动失败，报端口被占用（Windows 重启后常见）；记忆 UI 打不开。

原因

旧版/部分版本 worker 固定端口 37777，被残留进程或其它程序占用；僵尸 socket（TIME_WAIT）未释放。

解法

1. 先确认实际端口（安装输出 / claude-mem status 为准）：lsof -i :37700（本版）或 lsof -i :37777（旧版资料）。
2. 清理占用：kill -9 $(lsof -t -i:37700)（按实际端口替换）。
3. 改端口：CLAUDE_MEM_WORKER_PORT 环境变量，或 ~/.claude-mem/settings.json 中配置。