claude-mem Issue Triage 报告：94 个开放问题的根因分类、优先级体系与六阶段修复路线图

本文为 claude-mem 项目于 2026-03-29 执行的一次完整 Issue Triage（问题分诊）实录：报告展示了如何从 112 个 Issue 中关闭 18 个（重复合并、模糊不可操作、过期作废），将剩余 94 个按 8 大根因类别（worker-lifecycle、windows、chromadb 等）归类并赋予 P0–P2 优先级，最终沉淀为 6 个代码修复阶段（Phase 02–07）。读完后你将掌握一套可复用的开源项目问题分诊方法论：重复合并策略、根因标签体系、优先级判定标准，以及从分诊报告直接派生修复 Phase 的工作方式，并能在仓库源码中找到各根因对应的实际实现位置。

分诊背景与总体统计

该报告由 Maestro agent（issues-triage-3-29-2026）对 claude-mem 仓库的全量 Issue 执行，原始记录见 triage-report.md，其关联的两个执行 Phase 为 Phase-01（关闭重复与过期 Issue） 和 Phase-02（修复 __dirname 与 Worker 启动）。

指标	数量
分诊前 Issue 总数	112
分诊期间关闭的 Issue	18
剩余开放 Issue	94

分诊动作本身对应 Phase 01 的“问题清理”，而修复工作则从 Phase 02 开始，这体现了“先清障、再按根因批量修复”的分诊组织思路。

关闭的 18 个 Issue：三类清理策略

重复 Issue（关闭 8 个）

重复项全部合并到“规范 Issue”上，其中最典型的是 __dirname 硬编码问题——它产生了 7 个重复报告（#1419、#1428、#1433、#1434、#1437、#1438），全部指向规范 Issue #1410。从当前仓库源码看，worker-service.ts 中曾通过 path.join(__dirname, 'mcp-server.cjs') 定位伴生脚本，esbuild 打包为 CJS 时若 __dirname 被内联为构建机绝对路径，用户机器上 worker 就无法初始化数据库和加载 mode 文件。这正是 Phase 02 的核心修复对象：

#	标题	重复于
#1419	Worker service fails on non-developer machines due to hardcoded __dirname in CJS bundle	#1410
#1428	Hardcoded __dirname in worker-service.cjs breaks mode file loading on non-dev machines	#1410
#1433	Hardcoded __dirname in worker-service.cjs prevents DB initialization	#1410
#1434	worker-service.cjs: __dirname hardcoded to developer's local path, breaks database initialization	#1410
#1437	v10.6.1: Worker daemon fails to start - esbuild inlines __dirname with developer's local path	#1410
#1438	Bundled worker-service.cjs hardcodes developer paths, breaking daemon spawn and mode loading	#1410
#1396	[10.6.0] Setup hook references setup.sh that doesn't exist in package	#1340
#1521	Security issue: possible command injection in GitHub Actions workflow	#1285

Phase-02 文档记录了实际落地方式：在 scripts/build-hooks.js 的三处 CJS esbuild 配置（worker-service、mcp-server、context-generator）中显式加入 define: { '__dirname': '__dirname', '__filename': '__filename' }，保证打包产物中 __dirname 在运行时解析为脚本自身目录，并验证产物中 0 条硬编码 /Users/ 路径、9 处运行时 __dirname/__filename 引用。构建产物可对照 plugin/scripts/worker-service.cjs 检查。

模糊 / 不可操作 Issue（关闭 7 个）

这类 Issue 缺乏复现步骤或错误细节，无法定位到具体代码路径，按分诊标准直接关闭：

#	标题	关闭理由
#1492	Bug Report	标题泛化，无复现步骤或细节
#1436	bug	无描述、无复现步骤
#1362	(Chinese, no repro)	无复现步骤或错误细节
#1385	mem still not save	细节不足以诊断
#1488	Consumed 25% of my tokens	使用量顾虑，非 Bug
#1459	Featured in awesome-claude-code-workflows	社区祝贺，不可执行
#1378	Test failure: test run failed	无测试输出或版本信息

过期 / 已被取代 Issue（关闭 3 个）

#	标题	关闭理由
#1268	(regression)	已在 10.6.x+ 修复
#1137	(plan mode pending messages)	被 #1262 取代
#1219	version bump to 10.4.1	版本早已被超越

剩余 94 个开放 Issue 的根因分类

分诊的核心价值在于把 Issue 从“症状”维度重排到“根因”维度，使后续 Phase 可以按类批量修复。以下完整继承报告中的分类结果。

root:worker-lifecycle（23 个）——最重的根因桶

Worker 守护进程是 claude-mem 的中心进程（hooks 通过本地端口与它通信），其生命周期问题影响面最大：

#	标题	优先级
#1410	bug: hardcoded __dirname in worker-service.cjs prevents initialization on end-user machines	P0
#1435	Binary embeds stale worker version (10.3.1) mismatching plugin version (10.6.1), causes infinite restart loop	P0
#1490	Worker daemon repeatedly killed by version mismatch shutdown, startup fratricide, and session SIGTERM	P0
#1505	SessionStart hooks fail on cold start: worker-start exits 137, context hook races worker	P0
#1469	Linux/WSL2: UserPromptSubmit fires before worker is ready - all observations silently dropped	P0
#1420	worker-service.cjs exits immediately on WSL (code 0, no output)	P0
#1522	/compact command causes worker crash requiring system reboot	P1
#1477	Hot session monopolizes SDK pool slots via infinite restart loop	P1
#1447	Worker startup race condition causes 2 SessionStart hook errors on every first session	P1
#1446	Stale worker PIDs in supervisor.json cause SessionStart:resume hook 500 errors	P1
#1430	Worker not available {}	P1
#1426	aggressiveStartupCleanup SIGKILLs hook process on cold start	P1
#1423	Worker daemon cold start exceeds POST_SPAWN_WAIT timeout (5s) on macOS ARM64	P1
#1412	Error: Error calling Worker API: fetch failed (Mac Book)	P1
#1399	Windows worker service hangs with CLOSE_WAIT zombie sockets	P1
#1397	SessionStart context hook gets empty data on cold start (race condition)	P1
#1392	Windows: zombie socket holds port 37777 after worker crash, blocking restart	P1
#1389	SDK agent pool deadlock: idle processes block pool slots	P1
#1323	Race condition: Database not initialized error on session-init hook	P1
#1289	Worker silently fails init when 'node' not in PATH	P1
#1266	Loss of connection to MCPs even though localhost:37777 was active	P1
#1245	worker-service.cjs start subcommand causes SIGKILL under systemd	P1
#1509	Feature request: Support Node.js runtime via better-sqlite3 to avoid Bun memory leaks	P2

这一桶的问题在仓库源码中有明确的落点：冷启动健康检查与重试位于 worker-utils.ts（ensureWorkerRunning()），版本不匹配时的重启协调与结构化启动诊断位于 worker-service.ts（ensureWorkerStarted()、collectStartupDiagnostics()），而 #1392 中反复出现的 37777 端口正是 cmem-memory-credentials.ts 中定义的 HOST_OBSERVER_DEFAULT_PORT = '37777' 默认端口——僵尸 socket 占住该端口即会阻塞 worker 重启，与 Issue 描述吻合。

root:windows（14 个）

Windows/WSL 平台特性导致的挂起、路径与进程枚举问题：

#	标题	优先级
#1420	worker-service.cjs exits immediately on WSL (code 0, no output)	P0
#1366	Windows: claude-mem 10.5.5 causes Claude Code hooks to hang, CLI becomes unresponsive	P0
#1482	claude-mem plugin breaks claude --print (pipe mode) on Windows	P1
#1476	Windows: aggressiveStartupCleanup WQL filter fails due to single-quote nesting in PowerShell	P1
#1452	Windows: bun-runner.js spawn ENOENT when bun is installed via npm shim	P1
#1489	Windows: chroma-mcp spawn fails with EINVAL when using uvx.cmd	P1
#1399	Windows worker service hangs with CLOSE_WAIT zombie sockets	P1
#1395	SessionEnd hook 'session-complete' fails with 'Hook cancelled' on Windows	P1
#1392	Windows: zombie socket holds port 37777 after worker crash	P1
#1342	mcp-server.cjs has CRLF line endings - shebang fails on macOS/Linux	P1
#1281	Windows: Stop hooks fail with MODULE_NOT_FOUND due to backslash path corruption	P1
#1225	Windows: chroma-mcp "Received request before initialization was complete"	P1
#1503	DEP0190 warning in bun-runner.js on Windows (Node 22+)	P2
#1247	smart-explore fails silently on Windows - tree-sitter CLI requires C compiler	P2

该桶对应修复 Phase 见 Phase-03（Windows 平台加固），涵盖 hook 超时/挂起、僵尸端口时序、PowerShell 转义、CRLF .gitattributes、WQL 进程枚举边界与 isProcessAlive() 工具函数。

root:chromadb（9 个）

ChromaDB 向量检索子进程（通过 uvx/chroma-mcp 拉起）的资源与生命周期问题：

#	标题	优先级
#1248	chroma-mcp spins at 250-360% CPU indefinitely on macOS (v10.5.2)	P0
#1369	chroma-mcp subprocess leak: callTool and onclose null transport	P1
#1361	chroma-mcp processes leak after session exit, repeatedly downloading ONNX model (~15GB wasted)	P1
#1297	macOS: chroma-mcp crashes when CWD contains .env.local	P1
#1261	MCP Search fails with "Collection setup failed" error on cacheDir initialization	P1
#1489	Windows: chroma-mcp spawn fails with EINVAL when using uvx.cmd	P1
#1225	Windows: chroma-mcp "Received request before initialization was complete"	P1
#1470	ChromaDB search fails on WSL/Linux with SOCKS proxy - missing socksio	P2
#1424	chroma-mcp subprocess fails when ALL_PROXY uses socks:// scheme	P2

对应的 Phase-04（ChromaDB 子进程生命周期）计划加入 60 秒健康监控、CPU 空转检测、进程组 kill、chromaPid 写入 worker.pid、chromaAvailable 标志以及优雅的 SQLite 回退——即向量检索不可用时降级到本地 SQLite 全文检索而非整体报错。

root:session-integrity（12 个）

会话数据一致性问题，直接威胁 claude-mem“跨会话记忆”的核心价值：

#	标题	优先级
#1262	pending_messages queue grows unbounded, causes 100%+ CPU on startup	P0
#1269	CPU 100% caused by saved_hook_context in Claude Code session files	P0
#1519	Session completion can finalize too early when summarize is still in flight	P1
#1514	regenerate-claude-md.ts finds 0 observations despite data existing in database	P1
#1511	Session context not persisting between sessions despite previous work	P1
#1360	parseSummary creates empty SESSION SUMMARY records from observation responses	P1
#1335	Observer sessions trigger ECC's observe.sh hook - double Haiku loop	P1
#1274	Stop hook crashes with 'Transcript path missing' after context compaction	P1
#1260	Duplicate observations still occurring - concurrent hooks bypass content-hash dedup	P1
#1234	Stop hook crashes in git worktrees: transcript path not found	P1
#1218	feat: Add runtime self-healing for stuck processing messages and orphaned pending queues	P2
#1359	Viewer crashes: files_modified stored as bare path instead of JSON array	P2

其中 #1234 的 git worktree 场景在仓库中有专门处理：worktree.ts 提供 detectWorktree()，配合 project-name.ts 中的 getProjectContext() 区分 worktree 会话与父项目。

root:security（5 个）——P0 密度最高的桶

#	标题	优先级
#1204	watch.context.path in settings can write AGENTS.md content to arbitrary file paths	P0
#1255	Worker port collision causes cross-account data leakage on multi-user macOS systems	P0
#1285	[Security Issue] possible command injection in GitHub Actions workflow	P0
#1493	Sub-agents bypass user permission settings (permissionMode: 'default' hardcoded)	P0
#1251	Security Audit: Comprehensive Code Review of claude-mem	P1

#1204 与 #1255 解释了为什么需要“路径白名单”与“端口冲突即身份告警”：worker 固定使用默认端口 37777（见 cmem-memory-credentials.ts），多用户机器上若发生端口碰撞，不同账户的会话数据可能串到同一 worker，这属于数据越界而非单纯可用性故障。#1285 已被 #1521 重复合并关闭，实际修复在 Phase-06（安全修复）。

root:project-scoping（6 个）

项目隔离是记忆系统的正确性前提——同名目录共享记忆意味着跨项目数据串味：

#	标题	优先级
#1256	basename(cwd) project detection causes data fragmentation in monorepos	P0
#1458	Projects with same folder name share memories due to basename-only scoping	P0
#1473	Codex and Claude sessions can bleed into the same context and viewer data	P1
#1478	Project resolver doesn't expand ~ to home directory path	P2
#1318	Feature Request: Workspace-Based Memory Isolation	P2
#1320	feat: per-project disable/exclude functionality	P2

从当前源码看，project-name.ts 的 getProjectName() 已经演进为：先用 expandHome() 展开 ~（对应 #1478），再通过 git rev-parse --show-toplevel 解析 git 仓库根目录，使 monorepo 子目录和 worktree 得到稳定项目名（对应 #1256/#1458），非 git 目录才回退到 basename；getProjectContext() 则返回包含 primary、parent、isWorktree、allProjects 的完整上下文。配套的 migrateProjectNames() 逻辑（带 legacy/ 前缀迁移旧项目名）可推断已落在 observer-health.ts 等文件中，正是 Phase-05 所述“项目身份统一到 parent/basename + legacy 前缀迁移”的实现。

root:installer（8 个）

#	标题	优先级
#1471	MCP server not registered - marketplace root .mcp.json is empty	P1
#1497	Update now fails: Marketplace directory not found	P1
#1456	OpenClaw installer fails when plugins.allow contains claude-mem	P1
#1371	Installer fails in a loop when plugins.allow is validated before plugin is installed	P1
#1367	OpenClaw plugin returns 401 when calling worker API	P1
#1340	Setup hook references missing scripts/setup.sh in v10.5.5	P1
#1242	PR #1229 fallback path points to marketplace source, not installed cache	P1
#1156	np (npm publish tool) should be a devDependency, not a runtime dependency	P2

#1340 是重复桶 #1396 的规范 Issue；#1371/#1456 属于安装器“先校验后安装”的幂等性缺陷。安装链路的当前实现分布在 installer.js、install.sh 与 openclaw/install.sh 等入口，修复见 Phase-07。

root:mcp-schema（8 个）

#	标题	优先级
#1413	search tool inputSchema missing query parameter	P1
#1384	MCP search/timeline tools have empty inputSchema properties, 3s API timeout	P1
#1342	mcp-server.cjs has CRLF line endings - shebang fails on macOS/Linux	P1
#1331	SSE new_prompt broadcast stops after /reload-plugins	P1
#1266	Loss of connection to MCPs even though localhost:37777 was active	P1
#1263	search (MCP) Worker API error (500)	P1
#1471	MCP server not registered - .mcp.json is empty	P1
#1339	Web UI #ID numbers don't match MCP get_observations IDs	P2

MCP 工具侧的 schema 与可见性控制对应 mcp-server.ts 与 mcp-tool-visibility.ts；#1413/#1384 的“inputSchema 缺 query / 属性为空”直接影响 LLM 客户端能否正确生成工具调用参数。

root:aws-bedrock（2 个）

#	标题	优先级
#1496	AWS Bedrock auth not supported in SDK pipeline (10.6.0+)	P1
#1373	AWS Bedrock env vars not passed to CLI subprocess - observations fail silently	P1

两者共性是“环境变量透传”：Bedrock 的 region/凭证 env 未随 spawn 链传递给观察者子进程导致静默失败。仓库中环境处理集中在 EnvManager.ts 与 spawn 封装 spawn.ts，Phase 07 将其列为 env 透传修复项。

未标记 / 独立 Issue（15 个）

#	标题	优先级
#1390	Default model CLAUDE_MEM_MODEL still set to claude-sonnet-4-5 instead of claude-sonnet-4-6	P2
#1484	Feature request: CLAUDE_MEM_DISABLED env var for headless/agent sessions	P2
#1464	Feature: option to disable claude-mem context injection for spawned subagents	P2
#1462	Feature: Promote worktree observations to parent project after PR merge	P2
#1431	timeline-report script ignores custom port in settings.json	P2
#1364	Missing mode file for zh-TW (Traditional Chinese)	P2
#1322	Restore manual save_memory MCP tool for explicit memory creation	P2
#1299	mock.module() leak in context-reinjection-guard test pollutes parallel workers	P2
#1284	Integration idea: claude-brain for cross-machine memory sync?	P2
#1273	Feature Request: UUID observation IDs to enable multi-machine sync/merge	P2
#1272	Feature Request: Add option to disable subdirectory CLAUDE.md generation	P2
#1265	Feature Request: Display model name on observation/summary cards in web UI	P2
#1259	Gemini Flash Lite produces hallucinated observations; Gemini 2.5 Flash fixes it	P2
#1252	Feature request: Embedded/in-process mode for OpenClaw plugin	P2
#943	Feature Request: Support custom API endpoint / LiteLLM proxy	P2

这一桶几乎全部为 P2 特性请求，其中 #943（自定义 API 端点/LiteLLM 代理）已在文档 litellm-gateway.mdx 中有对应使用指南；#1273 的 UUID observation ID 与多机同步方向呼应了 cloud-sync.mdx 描述的云同步能力。

优先级体系与分布

报告定义了明确的 P0–P2 判定标准，这是分诊可审计性的关键：

• P0 = 阻塞所有用户，或是安全漏洞
• P1 = 影响大量用户群体
• P2 = 锦上添花，或单一用户报告

优先级	数量	判定
P0	15	阻塞所有用户或安全漏洞
P1	54	影响大量用户群体
P2	25	锦上添花或单用户报告

（P0 15 + P1 54 + P2 25 合计 94，与剩余开放 Issue 总数一致；多标签 Issue 在计数时按主标签归桶，跨桶重复出现。）

多标签 Issue：跨根因的交叉点

8 个 Issue（表中实际列出 11 行，因部分 Issue 跨两个桶被两侧各记一次）横跨多个根因类别，它们是修复顺序设计中的“依赖枢纽”：

#	标签
#1420	root:worker-lifecycle, root:windows
#1399	root:worker-lifecycle, root:windows
#1392	root:worker-lifecycle, root:windows
#1489	root:windows, root:chromadb
#1225	root:windows, root:chromadb
#1342	root:windows, root:mcp-schema
#1266	root:worker-lifecycle, root:mcp-schema
#1471	root:installer, root:mcp-schema
#1269	root:worker-lifecycle, root:session-integrity
#1234	root:worker-lifecycle, root:session-integrity
#1339	root:session-integrity, root:mcp-schema

这些交叉点解释了 Phase 排序逻辑：worker 生命周期（Phase 02）必须先于 Windows 加固（Phase 03）与 ChromaDB 生命周期（Phase 04），因为 #1399、#1392、#1489 等问题同时依赖 worker 侧的进程组管理与平台侧的 spawn 修复。

Next Steps：六个代码修复阶段

分诊报告的最终产出是可直接执行的 Phase 计划（Phase 01 为本次关闭 18 个 Issue 的分诊动作本身）：

1. Phase 02: 修复 __dirname 与 Worker 启动——替换 esbuild 产物中硬编码的 __dirname，为冷启动 worker 初始化加入重试循环，实现原子重启锁文件防止启动踩踏，并加入结构化失败诊断。
2. Phase 03: Windows 平台加固——修复 hook 超时/挂起、僵尸端口时序、PowerShell 转义工具函数、CRLF .gitattributes、WQL 进程枚举边界与 isProcessAlive() 工具。
3. Phase 04: ChromaDB 子进程生命周期——60 秒健康监控、CPU 空转检测、进程组 kill、chromaPid 写入 worker.pid、chromaAvailable 标志、优雅 SQLite 回退。
4. Phase 05: 项目作用域与会话完整性——项目身份统一到 parent/basename、migrateProjectNames() 带 legacy/ 前缀迁移、过早 finalize 保护、会话级去重唯一索引、队列大小上限。
5. Phase 06: 安全修复——GitHub Actions env 块注入修复、isPathSafe() 白名单工具、端口冲突时的项目身份告警、hook 输入校验审计。
6. Phase 07: 安装器、MCP 与剩余修复——对齐 setup.sh/smart-install.js、MCP 工具显式属性 schema、AWS Bedrock env 透传、安装器幂等性、SSE 心跳/清理、带 commit 引用的 Issue 评论更新。

以 Phase 02 为例（其任务清单已逐项标记完成），可以看到分诊报告与实现之间的一一映射：

• __dirname 修复：在 scripts/build-hooks.js 的三处 CJS esbuild 配置中加入显式 define，保证 __dirname 运行时解析而非构建时内联；验证产物中 0 条硬编码绝对路径。
• 冷启动重试：重写 worker-utils.ts 的 ensureWorkerRunning() 为预算感知重试循环（至多 3 次、间隔 1 秒），新增 isWorkerStartingUp() 辅助函数通过 PID 文件存在性与新旧度（30 秒阈值）区分“正在冷启动”（值得重试）与“worker 已死”（应直接 spawn）；单次超时为 min(800ms, budget/3)，总时长受 HEALTH_CHECK_TIMEOUT_MS（默认 3 秒）约束。
• 重启踩踏防护：用原子锁文件 ~/.claude-mem/.worker-restart.lock（TTL 30 秒，O_EXCL 原子创建 + mtime 过期回退）替代脆弱的“PID 文件新旧度”协调，先检查锁、再竞争获取、健康轮询代替各自重启；锁在成功、端口释放失败、健康检查超时三条路径上释放，并由 GracefulShutdown 在关闭序列中兜底释放。
• 结构化诊断：新增 collectStartupDiagnostics(port)，在 start 失败时向 stderr 输出 JSON 诊断（端口占用状态、PID 文件状态、Bun 可用性/版本、worker.log 末 5 行），退出码 2 表示阻塞级错误并回传给 Claude 辅助诊断。
• 测试验证：Phase 02 记录新增 2 个测试文件共 13 个用例（重启锁生命周期/并发获取拒绝/过期 TTL 覆盖，以及重试成功/无 PID 不重试/预算约束），全量测试 1179 通过、32 个均为预存失败，无新增回归。

从这份报告学到的分诊方法论

这份 triage-report 本身就是一个可复制的开源项目分诊范式，值得单独总结：

1. 先做减法：18 个关闭项（8 重复 + 7 模糊 + 3 过期）把 112 个 Issue 压缩到 94 个，且每个关闭都有明确理由（重复于哪个规范 Issue、缺什么信息、被什么版本/Issue 取代）。重复 Issue 必须指向唯一的“规范 Issue”（如 #1410），避免修复时遗漏合并面。
2. 按根因而非症状分桶：同一个“worker 起不来”的症状在 Windows、WSL、macOS ARM64、systemd 下表现各异（#1420、#1366、#1423、#1245），归入同一 root:worker-lifecycle 后就能由一个 Phase 统一修复，而不是四个互不相关的补丁。
3. 优先级标准可审计：P0 只有两条入口——“阻塞所有用户”或“安全漏洞”，因此 security 桶 5 个 Issue 中 4 个是 P0，而 15 个特性请求全部落在 P2。
4. 分诊产出直接派生执行计划：报告的 “Next Steps” 不是建议而是带任务清单的 Phase 文档（02–07），每个 Phase 的任务项都写明“读哪个文件、改哪一段、怎么验证”，使分诊到落地的链路闭环。

如果你正在维护一个拥有本地守护进程 + hook 集成 + 跨平台部署的项目，这份报告展示的分类维度（进程生命周期 / 平台 / 外部子进程 / 数据完整性 / 安全 / 命名作用域 / 安装分发 / 接口契约）可以直接作为标签体系模板迁移使用。