claude-mem Issue Triage 报告94 个开放问题的根因分类、优先级体系与六阶段修复路线图【免费下载链接】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 项目于 2026-03-29 执行的一次完整 Issue Triage问题分诊实录报告展示了如何从 112 个 Issue 中关闭 18 个重复合并、模糊不可操作、过期作废将剩余 94 个按 8 大根因类别worker-lifecycle、windows、chromadb 等归类并赋予 P0–P2 优先级最终沉淀为 6 个代码修复阶段Phase 02–07。读完后你将掌握一套可复用的开源项目问题分诊方法论重复合并策略、根因标签体系、优先级判定标准以及从分诊报告直接派生修复 Phase 的工作方式并能在仓库源码中找到各根因对应的实际实现位置。分诊背景与总体统计该报告由 Maestro agentissues-triage-3-29-2026对 claude-mem 仓库的全量 Issue 执行原始记录见 triage-report.md其关联的两个执行 Phase 为 Phase-01关闭重复与过期 Issue 和 Phase-02修复 __dirname 与 Worker 启动。指标数量分诊前 Issue 总数112分诊期间关闭的 Issue18剩余开放 Issue94分诊动作本身对应 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 的核心修复对象#标题重复于#1419Worker service fails on non-developer machines due to hardcoded __dirname in CJS bundle#1410#1428Hardcoded __dirname in worker-service.cjs breaks mode file loading on non-dev machines#1410#1433Hardcoded __dirname in worker-service.cjs prevents DB initialization#1410#1434worker-service.cjs: __dirname hardcoded to developers local path, breaks database initialization#1410#1437v10.6.1: Worker daemon fails to start - esbuild inlines __dirname with developers local path#1410#1438Bundled worker-service.cjs hardcodes developer paths, breaking daemon spawn and mode loading#1410#1396[10.6.0] Setup hook references setup.sh that doesnt exist in package#1340#1521Security issue: possible command injection in GitHub Actions workflow#1285Phase-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 缺乏复现步骤或错误细节无法定位到具体代码路径按分诊标准直接关闭#标题关闭理由#1492Bug Report标题泛化无复现步骤或细节#1436bug无描述、无复现步骤#1362(Chinese, no repro)无复现步骤或错误细节#1385mem still not save细节不足以诊断#1488Consumed 25% of my tokens使用量顾虑非 Bug#1459Featured in awesome-claude-code-workflows社区祝贺不可执行#1378Test failure: test run failed无测试输出或版本信息过期 / 已被取代 Issue关闭 3 个#标题关闭理由#1268(regression)已在 10.6.x 修复#1137(plan mode pending messages)被 #1262 取代#1219version bump to 10.4.1版本早已被超越剩余 94 个开放 Issue 的根因分类分诊的核心价值在于把 Issue 从“症状”维度重排到“根因”维度使后续 Phase 可以按类批量修复。以下完整继承报告中的分类结果。root:worker-lifecycle23 个——最重的根因桶Worker 守护进程是 claude-mem 的中心进程hooks 通过本地端口与它通信其生命周期问题影响面最大#标题优先级#1410bug: hardcoded __dirname in worker-service.cjs prevents initialization on end-user machinesP0#1435Binary embeds stale worker version (10.3.1) mismatching plugin version (10.6.1), causes infinite restart loopP0#1490Worker daemon repeatedly killed by version mismatch shutdown, startup fratricide, and session SIGTERMP0#1505SessionStart hooks fail on cold start: worker-start exits 137, context hook races workerP0#1469Linux/WSL2: UserPromptSubmit fires before worker is ready - all observations silently droppedP0#1420worker-service.cjs exits immediately on WSL (code 0, no output)P0#1522/compact command causes worker crash requiring system rebootP1#1477Hot session monopolizes SDK pool slots via infinite restart loopP1#1447Worker startup race condition causes 2 SessionStart hook errors on every first sessionP1#1446Stale worker PIDs in supervisor.json cause SessionStart:resume hook 500 errorsP1#1430Worker not available {}P1#1426aggressiveStartupCleanup SIGKILLs hook process on cold startP1#1423Worker daemon cold start exceeds POST_SPAWN_WAIT timeout (5s) on macOS ARM64P1#1412Error: Error calling Worker API: fetch failed (Mac Book)P1#1399Windows worker service hangs with CLOSE_WAIT zombie socketsP1#1397SessionStart context hook gets empty data on cold start (race condition)P1#1392Windows: zombie socket holds port 37777 after worker crash, blocking restartP1#1389SDK agent pool deadlock: idle processes block pool slotsP1#1323Race condition: Database not initialized error on session-init hookP1#1289Worker silently fails init when node not in PATHP1#1266Loss of connection to MCPs even though localhost:37777 was activeP1#1245worker-service.cjs start subcommand causes SIGKILL under systemdP1#1509Feature request: Support Node.js runtime via better-sqlite3 to avoid Bun memory leaksP2这一桶的问题在仓库源码中有明确的落点冷启动健康检查与重试位于 worker-utils.tsensureWorkerRunning()版本不匹配时的重启协调与结构化启动诊断位于 worker-service.tsensureWorkerStarted()、collectStartupDiagnostics()而 #1392 中反复出现的 37777 端口正是 cmem-memory-credentials.ts 中定义的HOST_OBSERVER_DEFAULT_PORT 37777默认端口——僵尸 socket 占住该端口即会阻塞 worker 重启与 Issue 描述吻合。root:windows14 个Windows/WSL 平台特性导致的挂起、路径与进程枚举问题#标题优先级#1420worker-service.cjs exits immediately on WSL (code 0, no output)P0#1366Windows: claude-mem 10.5.5 causes Claude Code hooks to hang, CLI becomes unresponsiveP0#1482claude-mem plugin breaks claude --print (pipe mode) on WindowsP1#1476Windows: aggressiveStartupCleanup WQL filter fails due to single-quote nesting in PowerShellP1#1452Windows: bun-runner.js spawn ENOENT when bun is installed via npm shimP1#1489Windows: chroma-mcp spawn fails with EINVAL when using uvx.cmdP1#1399Windows worker service hangs with CLOSE_WAIT zombie socketsP1#1395SessionEnd hook session-complete fails with Hook cancelled on WindowsP1#1392Windows: zombie socket holds port 37777 after worker crashP1#1342mcp-server.cjs has CRLF line endings - shebang fails on macOS/LinuxP1#1281Windows: Stop hooks fail with MODULE_NOT_FOUND due to backslash path corruptionP1#1225Windows: chroma-mcp Received request before initialization was completeP1#1503DEP0190 warning in bun-runner.js on Windows (Node 22)P2#1247smart-explore fails silently on Windows - tree-sitter CLI requires C compilerP2该桶对应修复 Phase 见 Phase-03Windows 平台加固涵盖 hook 超时/挂起、僵尸端口时序、PowerShell 转义、CRLF.gitattributes、WQL 进程枚举边界与isProcessAlive()工具函数。root:chromadb9 个ChromaDB 向量检索子进程通过 uvx/chroma-mcp 拉起的资源与生命周期问题#标题优先级#1248chroma-mcp spins at 250-360% CPU indefinitely on macOS (v10.5.2)P0#1369chroma-mcp subprocess leak: callTool and onclose null transportP1#1361chroma-mcp processes leak after session exit, repeatedly downloading ONNX model (~15GB wasted)P1#1297macOS: chroma-mcp crashes when CWD contains .env.localP1#1261MCP Search fails with Collection setup failed error on cacheDir initializationP1#1489Windows: chroma-mcp spawn fails with EINVAL when using uvx.cmdP1#1225Windows: chroma-mcp Received request before initialization was completeP1#1470ChromaDB search fails on WSL/Linux with SOCKS proxy - missing socksioP2#1424chroma-mcp subprocess fails when ALL_PROXY uses socks:// schemeP2对应的 Phase-04ChromaDB 子进程生命周期计划加入 60 秒健康监控、CPU 空转检测、进程组 kill、chromaPid写入 worker.pid、chromaAvailable标志以及优雅的 SQLite 回退——即向量检索不可用时降级到本地 SQLite 全文检索而非整体报错。root:session-integrity12 个会话数据一致性问题直接威胁 claude-mem“跨会话记忆”的核心价值#标题优先级#1262pending_messages queue grows unbounded, causes 100% CPU on startupP0#1269CPU 100% caused by saved_hook_context in Claude Code session filesP0#1519Session completion can finalize too early when summarize is still in flightP1#1514regenerate-claude-md.ts finds 0 observations despite data existing in databaseP1#1511Session context not persisting between sessions despite previous workP1#1360parseSummary creates empty SESSION SUMMARY records from observation responsesP1#1335Observer sessions trigger ECCs observe.sh hook - double Haiku loopP1#1274Stop hook crashes with Transcript path missing after context compactionP1#1260Duplicate observations still occurring - concurrent hooks bypass content-hash dedupP1#1234Stop hook crashes in git worktrees: transcript path not foundP1#1218feat: Add runtime self-healing for stuck processing messages and orphaned pending queuesP2#1359Viewer crashes: files_modified stored as bare path instead of JSON arrayP2其中 #1234 的 git worktree 场景在仓库中有专门处理worktree.ts 提供detectWorktree()配合 project-name.ts 中的getProjectContext()区分 worktree 会话与父项目。root:security5 个——P0 密度最高的桶#标题优先级#1204watch.context.pathin settings can write AGENTS.md content to arbitrary file pathsP0#1255Worker port collision causes cross-account data leakage on multi-user macOS systemsP0#1285[Security Issue] possible command injection in GitHub Actions workflowP0#1493Sub-agents bypass user permission settings (permissionMode: default hardcoded)P0#1251Security Audit: Comprehensive Code Review of claude-memP1#1204 与 #1255 解释了为什么需要“路径白名单”与“端口冲突即身份告警”worker 固定使用默认端口 37777见 cmem-memory-credentials.ts多用户机器上若发生端口碰撞不同账户的会话数据可能串到同一 worker这属于数据越界而非单纯可用性故障。#1285 已被 #1521 重复合并关闭实际修复在 Phase-06安全修复。root:project-scoping6 个项目隔离是记忆系统的正确性前提——同名目录共享记忆意味着跨项目数据串味#标题优先级#1256basename(cwd) project detection causes data fragmentation in monoreposP0#1458Projects with same folder name share memories due to basename-only scopingP0#1473Codex and Claude sessions can bleed into the same context and viewer dataP1#1478Project resolver doesnt expand ~ to home directory pathP2#1318Feature Request: Workspace-Based Memory IsolationP2#1320feat: per-project disable/exclude functionalityP2从当前源码看project-name.ts 的getProjectName()已经演进为先用expandHome()展开~对应 #1478再通过git rev-parse --show-toplevel解析 git 仓库根目录使 monorepo 子目录和 worktree 得到稳定项目名对应 #1256/#1458非 git 目录才回退到 basenamegetProjectContext()则返回包含primary、parent、isWorktree、allProjects的完整上下文。配套的migrateProjectNames()逻辑带 legacy/ 前缀迁移旧项目名可推断已落在 observer-health.ts 等文件中正是 Phase-05 所述“项目身份统一到 parent/basename legacy 前缀迁移”的实现。root:installer8 个#标题优先级#1471MCP server not registered - marketplace root .mcp.json is emptyP1#1497Update now fails: Marketplace directory not foundP1#1456OpenClaw installer fails when plugins.allow contains claude-memP1#1371Installer fails in a loop when plugins.allow is validated before plugin is installedP1#1367OpenClaw plugin returns 401 when calling worker APIP1#1340Setup hook references missing scripts/setup.sh in v10.5.5P1#1242PR #1229 fallback path points to marketplace source, not installed cacheP1#1156np (npm publish tool) should be a devDependency, not a runtime dependencyP2#1340 是重复桶 #1396 的规范 Issue#1371/#1456 属于安装器“先校验后安装”的幂等性缺陷。安装链路的当前实现分布在 installer.js、install.sh 与 openclaw/install.sh 等入口修复见 Phase-07。root:mcp-schema8 个#标题优先级#1413search tool inputSchema missing query parameterP1#1384MCP search/timeline tools have empty inputSchema properties, 3s API timeoutP1#1342mcp-server.cjs has CRLF line endings - shebang fails on macOS/LinuxP1#1331SSE new_prompt broadcast stops after /reload-pluginsP1#1266Loss of connection to MCPs even though localhost:37777 was activeP1#1263search (MCP) Worker API error (500)P1#1471MCP server not registered - .mcp.json is emptyP1#1339Web UI #ID numbers dont match MCP get_observations IDsP2MCP 工具侧的 schema 与可见性控制对应 mcp-server.ts 与 mcp-tool-visibility.ts#1413/#1384 的“inputSchema 缺 query / 属性为空”直接影响 LLM 客户端能否正确生成工具调用参数。root:aws-bedrock2 个#标题优先级#1496AWS Bedrock auth not supported in SDK pipeline (10.6.0)P1#1373AWS Bedrock env vars not passed to CLI subprocess - observations fail silentlyP1两者共性是“环境变量透传”Bedrock 的 region/凭证 env 未随 spawn 链传递给观察者子进程导致静默失败。仓库中环境处理集中在 EnvManager.ts 与 spawn 封装 spawn.tsPhase 07 将其列为 env 透传修复项。未标记 / 独立 Issue15 个#标题优先级#1390Default model CLAUDE_MEM_MODEL still set to claude-sonnet-4-5 instead of claude-sonnet-4-6P2#1484Feature request: CLAUDE_MEM_DISABLED env var for headless/agent sessionsP2#1464Feature: option to disable claude-mem context injection for spawned subagentsP2#1462Feature: Promote worktree observations to parent project after PR mergeP2#1431timeline-report script ignores custom port in settings.jsonP2#1364Missing mode file for zh-TW (Traditional Chinese)P2#1322Restore manual save_memory MCP tool for explicit memory creationP2#1299mock.module() leak in context-reinjection-guard test pollutes parallel workersP2#1284Integration idea: claude-brain for cross-machine memory sync?P2#1273Feature Request: UUID observation IDs to enable multi-machine sync/mergeP2#1272Feature Request: Add option to disable subdirectory CLAUDE.md generationP2#1265Feature Request: Display model name on observation/summary cards in web UIP2#1259Gemini Flash Lite produces hallucinated observations; Gemini 2.5 Flash fixes itP2#1252Feature request: Embedded/in-process mode for OpenClaw pluginP2#943Feature Request: Support custom API endpoint / LiteLLM proxyP2这一桶几乎全部为 P2 特性请求其中 #943自定义 API 端点/LiteLLM 代理已在文档 litellm-gateway.mdx 中有对应使用指南#1273 的 UUID observation ID 与多机同步方向呼应了 cloud-sync.mdx 描述的云同步能力。优先级体系与分布报告定义了明确的 P0–P2 判定标准这是分诊可审计性的关键P0 阻塞所有用户或是安全漏洞P1 影响大量用户群体P2 锦上添花或单一用户报告优先级数量判定P015阻塞所有用户或安全漏洞P154影响大量用户群体P225锦上添花或单用户报告P0 15 P1 54 P2 25 合计 94与剩余开放 Issue 总数一致多标签 Issue 在计数时按主标签归桶跨桶重复出现。多标签 Issue跨根因的交叉点8 个 Issue表中实际列出 11 行因部分 Issue 跨两个桶被两侧各记一次横跨多个根因类别它们是修复顺序设计中的“依赖枢纽”#标签#1420root:worker-lifecycle, root:windows#1399root:worker-lifecycle, root:windows#1392root:worker-lifecycle, root:windows#1489root:windows, root:chromadb#1225root:windows, root:chromadb#1342root:windows, root:mcp-schema#1266root:worker-lifecycle, root:mcp-schema#1471root:installer, root:mcp-schema#1269root:worker-lifecycle, root:session-integrity#1234root:worker-lifecycle, root:session-integrity#1339root: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 的分诊动作本身Phase 02: 修复 __dirname 与 Worker 启动——替换 esbuild 产物中硬编码的__dirname为冷启动 worker 初始化加入重试循环实现原子重启锁文件防止启动踩踏并加入结构化失败诊断。Phase 03: Windows 平台加固——修复 hook 超时/挂起、僵尸端口时序、PowerShell 转义工具函数、CRLF.gitattributes、WQL 进程枚举边界与isProcessAlive()工具。Phase 04: ChromaDB 子进程生命周期——60 秒健康监控、CPU 空转检测、进程组 kill、chromaPid写入 worker.pid、chromaAvailable标志、优雅 SQLite 回退。Phase 05: 项目作用域与会话完整性——项目身份统一到 parent/basename、migrateProjectNames()带 legacy/ 前缀迁移、过早 finalize 保护、会话级去重唯一索引、队列大小上限。Phase 06: 安全修复——GitHub Actions env 块注入修复、isPathSafe()白名单工具、端口冲突时的项目身份告警、hook 输入校验审计。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.lockTTL 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 本身就是一个可复制的开源项目分诊范式值得单独总结先做减法18 个关闭项8 重复 7 模糊 3 过期把 112 个 Issue 压缩到 94 个且每个关闭都有明确理由重复于哪个规范 Issue、缺什么信息、被什么版本/Issue 取代。重复 Issue 必须指向唯一的“规范 Issue”如 #1410避免修复时遗漏合并面。按根因而非症状分桶同一个“worker 起不来”的症状在 Windows、WSL、macOS ARM64、systemd 下表现各异#1420、#1366、#1423、#1245归入同一root:worker-lifecycle后就能由一个 Phase 统一修复而不是四个互不相关的补丁。优先级标准可审计P0 只有两条入口——“阻塞所有用户”或“安全漏洞”因此 security 桶 5 个 Issue 中 4 个是 P0而 15 个特性请求全部落在 P2。分诊产出直接派生执行计划报告的 “Next Steps” 不是建议而是带任务清单的 Phase 文档02–07每个 Phase 的任务项都写明“读哪个文件、改哪一段、怎么验证”使分诊到落地的链路闭环。如果你正在维护一个拥有本地守护进程 hook 集成 跨平台部署的项目这份报告展示的分类维度进程生命周期 / 平台 / 外部子进程 / 数据完整性 / 安全 / 命名作用域 / 安装分发 / 接口契约可以直接作为标签体系模板迁移使用。【免费下载链接】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），仅供参考