agentmemory 端口冲突排查手册：4 个默认端口一张表快速定位残留进程

agentmemory 端口冲突排查手册4 个默认端口一张表快速定位残留进程【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemoryagentmemory 是面向 AI 编码代理的持久化记忆工具它为 Claude Code、Cursor、Codex 等智能体提供跨会话的记忆存储与召回。由于 agentmemory 同时绑定 4 个端口3111 / 3112 / 3113 / 49134重启时最常遇到的报错就是port in use端口被占用。本手册给出一张残留进程快速定位表帮助你在 3 分钟内找到占端口的进程并安全清理。一、先搞清楚agentmemory 默认占用的 4 个端口agentmemory 基于 iii-engine 构建启动时由agentmemory worker和iii-engine两个进程共同绑定 4 个端口。搞不清哪个端口归谁清理就容易误杀或漏杀。端口占用进程用途环境变量覆盖3111agentmemoryREST API MCP HTTP 健康检查/agentmemory/healthIII_REST_PORT3112iii-engine内部 streams worker被 agentmemory 与 viewer 消费III_STREAMS_PORT3113agentmemory实时可视化 viewerhttp://localhost:3113AGENTMEMORY_VIEWER_PORT49134iii-engineWebSocket 通道worker 在此注册、OTel 遥测流经此处III_ENGINE_URL完整 URL 记忆技巧3111 是 REST 锚点端口。streams 端口固定为 REST1engine WebSocket 端口为 REST4602331114602349134。只要移动 3111其余端口会自动跟随推导逻辑见 src/config.ts。上图是 agentmemory 配套的 III Console Workers 页面每个已注册 worker含 agentmemory 自身都标注了PID、运行时版本、函数数量——排查时可以直接在这里对照谁还活着。二、快速定位表端口被占 → 该找哪个进程崩溃或异常退出后端口仍被绑定时用下表反查目标进程现象占用者定位命令macOS / Linux处理3111in useagentmemory worker 残留lsof -i :3111核对 PID 后kill pid3112in useiii-engine streams 残留lsof -i :3112同上3113in useviewer 进程残留lsof -i :3113同上49134in useiii-engine 主进程lsof -i :49134同上Windows 全部任意上述进程netstat -ano \| findstr :3111 :3112 :3113 :49134taskkill /F /PID pid一次性定位 4 个端口的完整命令来自 README.md 官方建议# macOS / Linux lsof -i :3111,3112,3113,49134 pkill -f agentmemory || true pkill -f iii || true⚠️ 注意以上手动清理仅用于崩溃后 pidfile 未留下的场景。正常关机时agentmemory stop会自动回收 worker 与 engine 的 pidfile无需手动干预。三、首选方案用 doctor 命令自动诊断agentmemory 自带交互式诊断命令能直接检查stale-pidfile僵尸 pidfile和viewer 端口不可达两类端口相关问题agentmemory doctor # 交互模式逐项 Fix / Skip / More agentmemory doctor --all # CI 场景自动应用所有修复 agentmemory doctor --dry-run # 只展示将做什么不实际执行诊断项定义在 src/cli/doctor-diagnostics.ts其中stale-pidfilepidfile 里记录的 PID 已不存在典型触发kill -9、OOM、宿主机重启后 pidfile粘在磁盘上viewer-unreachableviewer 端口默认 3113 REST2打不开最常见原因正是端口冲突如果引擎是原生启动但 state 文件丢失还可以用强制模式清理agentmemory stop --force该命令会绕过 Docker 启发式守卫直接对 pidfile lsof 报告的 REST 端口进程发信号实现见 src/cli.ts 中 stop 命令分支。四、换个端口跑多实例共存的最快方法与其杀进程不如让新实例搬家。只改III_REST_PORTstreams 与 engine 端口自动跟随III_REST_PORTstreams 端口engine WebSocket32113212ws://localhost:4923433113313→自动3312ws://localhost:49334默认31113112ws://localhost:49134端口自动推导的完整规则与边界情况含III_STREAM_PORT、III_ENGINE_PORT、III_ENGINE_URL单独覆盖有专门测试覆盖见 test/multi-instance-port.test.ts。配置建议写入~/.agentmemory/.envWindows 为%USERPROFILE%\.agentmemory\.env避免每个 shell 都手动 exportIII_REST_PORT3211五、排查速查清单 看报错端口→ 对照第一节四端口表确认是 agentmemory 还是 iii-engine先跑agentmemory doctor→ 多数 stale-pidfile 问题可一键修复仍占用→lsof -i :端口拿 PID核对进程名后再 kill避免误杀 Docker/vpnkit/colima 等 VM 端口持有者CLI 默认也拒绝接管这类进程频繁冲突→ 用III_REST_PORT整体换端口段多实例互不干扰按以上四步操作绝大多数 port in use 问题都能在几分钟内解决。更多部署细节Docker、Fly、Railway 等可参考 deploy/ 目录下的官方配置说明。【免费下载链接】agentmemory#1 Persistent memory for AI coding agents based on real-world benchmarks项目地址: https://gitcode.com/GitHub_Trending/age/agentmemory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考