claude-mem Windows 预览全修复指南windows-megafix 僵尸进程、端口卡死与静默搜索故障的实测与原理【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem导读本文基于 claude-mem 仓库中面向 Windows 测试者的公开测试征集文档plans/windows-testers-post.md系统梳理了 Windows 平台上最困扰用户的一批预览分支级故障——后台搜索助手退出后残留僵尸进程、worker 端口被占导致单会话 834 次阻断、uv 构建残留堆积出 144 GB 垃圾文件、错误 Python 环境导致记忆搜索静默失效——并逐一对应到仓库源码中的进程树销毁、PID 身份校验、uvx 子进程环境净化等实现给出了可在真实 Windows 机器上复现的 10 分钟测试流程、判定成功标准与问题回报清单。读完后你既能按图索骥完成一次完整的 Windows 预览回归测试也能理解为什么 Windows 上杀进程必须整棵树一起杀这类底层原理。一、问题背景为什么 Windows 会留下杀不干净的搜索助手claude-mem 会在会话后台启动一个用于记忆检索的搜索助手即基于 uv 的向量检索链路。从仓库规划文档 plans/2026-08-18-chroma-windows.md 可以看到这条原生进程链的真实深度worker → uvx.exe → uv.exe → python.exe → chroma-mcp在 POSIX 系统上子进程会被进程组管理父进程退出时通过process.kill(pid, signal)通常可以按组回收。但 src/shared/kill-process-tree.ts 的文件头注释明确指出了 Windows 的本质差异Windows has no process groups, and Nodesprocess.kill(pid, signal)force-terminates exactly one PID. Any spawn chain deeper than one level (uvx - uv - python - chroma-mcp, or a.cmdshim wrapping a real binary) leaves descendants running — they inherit listening sockets and wedge the worker port.即Windows 没有 POSIX 意义上的进程组Node 每次process.kill只能强行终止恰好一个 PID。当进程链超过一层uvx → uv → python只杀顶层进程后下层进程会作为孤儿存活下来并继续持有监听端口与临时文件。四大典型症状结合测试征集文档这四种孤儿后遗症可归纳为一张表症状现象仓库中的问题号与量化证据 遗留程序搜索助手退出时只杀掉了顶层进程下层 helper 像僵尸一样一直存活见 src/shared/worker-utils.ts 中ensureWorkerRunning的注释指向 #3482 端口卡死僵尸进程继续占用 worker 启动所需的端口导致无法重启、每个提示词都被阻塞同一条注释记录了单会话内 834 次健康检查失败的实测 磁盘被吃光进程被中途强杀构建用临时目录永远无人清理规划文档记录 uv 缓存builds-v0/.tmp*泄漏实测达144.21 GB / 696 个目录#3540 搜索静默死亡搜索助手抓错了机器上的 Python随后无报错、无警告地停止工作记忆搜索悄悄失效环境变量污染问题指向 #3552见下文需要说明的是前两类症状其实并非 Windows 独有——在 POSIX 上同样的残留子进程只是被 re-parent 到 init 后以几乎相同的方式继续存活。这正是该问题跨平台危害广、且被反复报告的深层原因。端口卡死的完整因果链测试征集文档提到一位用户单次会话内被卡了 834 次。仓库源码把这条因果链写得非常清楚。在 src/shared/worker-utils.ts 的版本回收逻辑ensureWorkerRunning中有一段长注释a single-PID kill here orphans the stale workers whole spawn chain (uvx - uv - python - chroma-mcp). Those descendants inherited the workers listening socket, so they keep the port bound after the root dies:waitForWorkerPortClosed()below never succeeds, every hook hard-blocks, and the recycle repeats forever (834 health-check failures observed).也就是说杀掉 worker 根进程后其子进程继承了 worker 的监听 socket → 端口仍被绑定 → 等待端口关闭的逻辑永远超时 → 每次 hook 事件都硬阻塞 → 无限循环。修复前服务端只能干等用户端则表现为每个 prompt 都被挡在外面。二、修复思路让关闭动作覆盖整个进程家族测试征集帖列出了该预览分支windows-megafix所做的四项核心修复每一条都能在源码中找到对应实现关闭时销毁整个进程树而不是只销毁父进程不再中途强杀正在下载/构建的任务让临时垃圾文件不再堆积错误的 Python 无法再混入搜索助手的环境杜绝误杀无关进程——该守卫经过7 轮代码评审才收敛。下面分别展开其底层实现。2.1 整树销毁共享的killProcessTree核心实现在 src/shared/kill-process-tree.ts 中导出的killProcessTree(pid, options)kill-process-tree.ts。它是从 Chroma 管理器的私有实现中原样抽取、并路由到所有 Windows 杀进程调用点的一个共享工具。在 Windows 分支上它使用系统级的整树强杀命令// Windows: taskkill /T /F for full subtree teardown. await execFileAsync(taskkill, [/PID, String(pid), /T, /F], { timeout: 5_000, windowsHide: true });其中/T表示连同所有子进程一起终止/F表示强制无条件、无优雅期返回码128表示目标进程本就不存在被归类为可容忍的已经死了不算错误其余错误访问被拒绝、超时、/T遍历被卡住会抛出ProcessTreeKillError让server stop等调用方绝不能把一次失败的杀进程报告成成功。POSIX 侧则采用先枚举全部后代 → 叶子先于祖先收到信号 → 优雅期 500ms → 汇总前后两次快照的并集再 SIGKILL的算法保证深层后代即使被 re-parent 也能被追到。2.2 杜绝误杀PID 复用身份校验7 轮评审的产物只杀对的进程、绝不误杀是这次修复中最难的部分。源码中为此专门引入了进程启动令牌start token机制见 src/shared/process-identity.ts裸 PID 不是稳定句柄操作系统会复用 PID 编号快照时记录的 PID到真正发信号时可能已经指向一个完全无关的进程。因此每次跨await持有 PID 的销毁路径都会同时记录一个启动令牌并在每次发信号前重新校验。Windows 上令牌取 CIM 查询得到的进程CreationDate精确到微秒的yyyyMMddHHmmss.ffffff格式isSameProcess()在做授权一次不可逆的杀进程判断时刻意绕过缓存重新读 OS否则 5 秒 TTL 内的缓存会让校验退化成恒真的同义反复——被复用的 PID 就会被认证成原进程交给taskkill /T /F连带误杀一个无关进程的整棵子树。文件注释里提到的round 6round 7正是在多轮评审中逐步封堵各种 PID 复用窗口的痕迹与测试帖7 轮评审的说法相互印证。此外其失败语义是刻意不对称的只有能成功读到令牌且确证不一致才算复用读不到令牌时默认放行——因为拒绝杀必须比误杀更谨慎否则反而会让真正的孤儿漏网。2.3 错误 Python 进不来uvx 子进程环境净化搜索助手拿错 Python 然后静默死掉的根因是外部环境变量污染。用户在 shell 里激活过的虚拟环境venv/conda 等会通过VIRTUAL_ENV、PYTHONPATH等变量渗入 uvx 子进程导致它捡起一个错误的 CPython典型的后果是 numpy ABI 不兼容、语义同步悄悄失败。仓库中的修复在 src/shared/uvx-env.tsexport const FOREIGN_PYTHON_ENV_VARS [ VIRTUAL_ENV, PYTHONHOME, PYTHONPATH, CONDA_PREFIX, CONDA_DEFAULT_ENV, ] as const;这五类变量在构建 uvx 子进程环境时被全部剔除。特别值得注意的是 Windows 大小写语义Windows 环境变量不区分大小写但 CPython 只认精确大小写的删除因此 win32 上还会额外移除PYTHONPATH等变量的全部大小写变体避免同一个键以两种写法同时传给子进程对操作系统而言它们是同一个变量重复传递属于未定义行为。对应测试见 tests/shared/uvx-env-sanitization.test.ts。2.4 不再中途强杀让临时文件停止堆积修复思路是不要在构建进行到一半时强杀 uv并配合清理策略。在规划文档 plans/2026-08-18-chroma-windows.md 中可以看到完整方案Chrom 拆除路径先尝试优雅退出宽限期过后才升级到taskkill /T /Fuv 缓存目录builds-v0下超过保守阈值的陈旧.tmp*目录会在 Chroma 启动时而非关闭时因为关闭可能是一次硬杀被扫描清理且绝不删除属于存活 uv 进程的目录、绝不在解析出的 uv 缓存根目录之外做任何删除。2.5 补上真正的 Windows 测试测试征集帖坦承此前 claude-mem 的测试从不在 Windows 上真正启动搜索助手这正是这些 bug 反复溜过的主要原因。预览分支修复后测试会在每次变更时于 Windows 上真实拉起该进程链。仓库中的佐证之一是 tests/shared/kill-process-tree-cross-platform.test.ts它用跨平台的两层进程树夹具Windows 上是cmd.exe /c ping -n 120 127.0.0.1POSIX 上是/bin/sh -c sleep 120 wait针对 Windows 特有的三个机制——CIM 进程表读取、taskkill退出码分类、根进程身份闸门——逐一通过生产代码路径做断言。规划文档的 Phase 5 更进一步设计了 Windows CI 作业在windows-2022运行器上安装 uv → 通过生产代码路径拉起真实 chroma-mcp → 完成建集合→写入→查询往返 → 关闭 worker →断言零孤儿进程无 chroma-mcp/uv.exe/python.exe 残留→ 断言.tmp*数量未增长。第 5、6 步正是必须在 main 上失败、在修复后通过的回归闸门。三、真机验证结论不是应该能用是跑过并通过测试征集文档强调下列验证结果不是理论推演而是在真实的 Windows 机器上执行并通过的✅ 搜索助手能启动、能保存一条记忆、并能再次检索到它✅ 关闭后零残留进程✅ 即使在混乱的 Python 环境下多版本、多虚拟环境共存依然正常工作。四、10 分钟实测手册如何安装 windows-megafix 预览分支该预览把所有 Windows 修复合并到了一个分支里对应上游 PR#3661。文档给出的完整流程如下运行前提是机器上已装好Node.js与Git且构建需要几分钟时间文档建议先泡杯咖啡。打开PowerShell逐条粘贴执行git clone claude-mem 仓库地址 cd claude-mem git checkout windows-megafix npm install npm run build-and-sync node dist\npx-cli\index.js doctor各条命令的含义与预期行为命令作用git clone 仓库地址克隆 claude-mem 源码仓库以你实际可访问的克隆地址为准cd claude-mem进入仓库根目录git checkout windows-megafix检出汇集全部 Windows 修复的预览分支npm install安装依赖npm run build-and-sync构建产物并同步到 marketplace 运行时仓库 package.json 中该脚本实际为npm run build npm run sync-marketplace node scripts/restart-marketplace-worker.cjsnode dist\npx-cli\index.js doctor以源码本地路径运行健康检查对应 src/npx-cli/commands/doctor.ts最后一条doctor会打印一份健康体检报告。它做的是只读探测绝不改动任何状态全部必需检查通过时退出码为 0否则为 1因此也适合写进 CI 脚本。五、怎么判断修好了成功的可见标准5.1doctor全绿正常时应看到多条绿色/OK 行。根据 src/npx-cli/commands/doctor.ts 的实际实现doctor 至少会检查以下项目检查项状态类别说明Bun runtime必需claude-mem 的 hook 跑在 Bun 上缺失即failuv (vector search)警告级只在向量/语义搜索需要时强制缺失仅降级搜索能力不硬失败Plugin installed必需检测 marketplace 中是否已安装插件Marketplace runtime视情况检查node_modules与.install-version标记是否就位开发构建build-and-sync通常不写 npx 标记属正常信息而非失败Worker daemon警告级向http://host:port/api/health探测worker 可被有意停掉因此不作为硬性失败Git Bash (Windows)必需仅 Windows 生效所有 hook 通过bash执行Windows 上由 Git for Windows 提供缺失时会给出清晰提示而非崩溃测试帖点名的三项——Bun、uv、Worker daemon——对应表中第 1、2、5 行是预览验证时最需要盯紧的绿灯。5.2 行为级验证✅ Claude Code 能正常启动没有任何被阻塞的提示词✅ 记忆搜索真正返回结果而不是静默返回空✅ 关闭 claude-mem 后执行下面这条命令应什么都看不到——这是整场修复的一行式验收Get-Process uv,python -ErrorAction SilentlyContinue没有任何残留输出就代表整个进程家族而非仅仅父进程都已被正确回收。六、遇到问题怎么办一份可用的失败报告同样有价值预览的意义正在于收集真实世界的失败样本。若测试中出现异常请按以下清单回报node dist\npx-cli\index.js doctor的完整输出 你的 Windows 版本号%USERPROFILE%\.claude-mem\logs\目录下最新的一份日志文件。测试征集文档特别强调一份失败的回报与一份成功的回报价值相同——这正是公开测试存在的意义。claude-mem 的日志目录与数据目录布局可在 src/shared/paths.ts 等路径模块中进一步确认。想退出预览一条命令回到正式版npx claude-memlatest install该命令会把插件重新装回已发布的正式版本无需手工撤销任何改动或清理残留文件。七、预览分支包含的 PR 一览本次windows-megafix分支把下列 PR 全部汇总对应上游 PR#3661。需要再次强调这些 PR 在测试征集发布时尚未合并到主干——你要测试的是一份预览这正是作者此刻最需要的反馈。PR解决的问题#3661汇总分支windows-megafix合并了下列所有改动#3644大头残留进程、端口卡死、磁盘垃圾、搜索静默死亡#3647Windows 上代码搜索静默返回空结果#3648设置中使用~\时数据被存到错误目录#3649缺少 Git Bash 时给出清晰提示而非令人费解的崩溃#3657修复在 Windows 上从源码构建此前依赖一个仅 macOS/Linux 可用的工具与 #3657 相关的从源码构建体验可从 doctor 对 marketplace 运行时的容错逻辑中看到配套处理开发构建如build-and-sync产物不会写.install-version标记doctor 对此明确判定为正常而非失败见 src/npx-cli/commands/doctor.ts 中相关注释。八、延伸阅读想继续深挖可以看这些仓库文件共享整树销毁实现与跨平台进程表读取src/shared/kill-process-tree.tsPID 复用防护的身份令牌原语src/shared/process-identity.ts版本回收路径中的树杀调用点#3482 注释所在地src/shared/worker-utils.tsuvx 子进程环境净化src/shared/uvx-env.tsWindows 跨平台树杀测试与身份校验测试tests/shared/kill-process-tree-cross-platform.test.ts、tests/shared/kill-process-tree-identity.test.ts、tests/shared/kill-process-tree-pid-reuse.test.ts本批修复背后更完整的执行规划分 6 个 Phase 描述抽取、路由、泄漏清理、环境净化与 CI 证明plans/2026-08-18-chroma-windows.md健康检查命令的完整检查项实现src/npx-cli/commands/doctor.ts【免费下载链接】claude-memPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode More项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考