# Pitfall Log / 踩坑日志

项目：thedotmack/claude-mem

摘要：发现 39 个潜在踩坑项，其中 13 个为 high/blocking；最高优先级：安装坑 - 来源证据：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)。

## 1. 安装坑 · 来源证据：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_24ed2d144536406bb1235c9249013f81 | https://github.com/thedotmack/claude-mem/issues/2521 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX attacched
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a6c844000d9b4adead4a2fdb73660c8d | https://github.com/thedotmack/claude-mem/issues/2426 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2a88889db8f4416a9daf23d9979fee71 | https://github.com/thedotmack/claude-mem/issues/2432 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e1a68c6d9a77481897440b34fca959e4 | https://github.com/thedotmack/claude-mem/issues/2438 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 5. 安装坑 · 来源证据：v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_13c1450c63bb4900bed699a4f9b2abb2 | https://github.com/thedotmack/claude-mem/issues/2407 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 来源证据：v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d56c3d9492594acab8d0bb29a46a6fee | https://github.com/thedotmack/claude-mem/issues/2520 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 7. 安装坑 · 来源证据：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_510ecb03a1de412f940987e370c68fac | https://github.com/thedotmack/claude-mem/issues/2433 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 8. 配置坑 · 来源证据：Use node to run mcp for windows environment

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Use node to run mcp for windows environment
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_95d37c5d34a749f7a25fdd5fe1dc7969 | https://github.com/thedotmack/claude-mem/issues/2446 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 9. 配置坑 · 来源证据：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_77fdc7c371f042eeb70fbeb52a7a2788 | https://github.com/thedotmack/claude-mem/issues/2438 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 10. 运行坑 · 来源证据：自动运行时突然报下图所示内容，然后插件就不能用了

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：自动运行时突然报下图所示内容，然后插件就不能用了
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2d5aa43a4c5a4e46a0f2122dea46947a | https://github.com/thedotmack/claude-mem/issues/2441 | 来源类型 github_issue 暴露的待验证使用条件。

## 11. 安全/权限坑 · 来源证据：Feature: Vertex AI support for Gemini provider

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: Vertex AI support for Gemini provider
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_77bf4085ec9e46c59fdaffa4ad889dcc | https://github.com/thedotmack/claude-mem/issues/2522 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 12. 安全/权限坑 · 来源证据：Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f38d625f3d834e7d8179d4a3176f3a73 | https://github.com/thedotmack/claude-mem/issues/2509 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 13. 安全/权限坑 · 来源证据：v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_fbb9eadf507d4876b859b92bd87d2ab2 | https://github.com/thedotmack/claude-mem/issues/2485 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 14. 安装坑 · 失败模式：installation: OpenClaw installer fails with TypeScript build error on Linux

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: OpenClaw installer fails with TypeScript build error on Linux
- 对用户的影响：Developers may fail before the first successful local run: OpenClaw installer fails with TypeScript build error on Linux
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: OpenClaw installer fails with TypeScript build error on Linux. Context: Observed when using node, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_f6c0a0d684fa5f1135ac669cd98df70e | https://github.com/thedotmack/claude-mem/issues/2530 | OpenClaw installer fails with TypeScript build error on Linux

## 15. 安装坑 · 失败模式：installation: Windows worker spawn silently fails when user home path contains a space (four stacked bugs,...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)
- 对用户的影响：Developers may fail before the first successful local run: Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0). Context: Observed when using windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_0190fe2b64cffaffac244e9ef7033f4e | https://github.com/thedotmack/claude-mem/issues/2521 | Windows worker spawn silently fails when user home path contains a space (four stacked bugs, still present in v13.2.0)

## 16. 安装坑 · 失败模式：installation: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new s...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session
- 对用户的影响：Developers may fail before the first successful local run: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session. Context: Observed when using node, windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_967ff316b7cd3cebcc05db7b0d3c8d9d | https://github.com/thedotmack/claude-mem/issues/2432 | Worker PID file not cleaned up after system sleep/hibernate, Worker fails to restart on new session

## 17. 安装坑 · 失败模式：installation: [Bug] 13.x worker fails with "Cannot find module 'zod/v3'" — package-lock.json missing zod entry

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Bug] 13.x worker fails with "Cannot find module 'zod/v3'" — package-lock.json missing zod entry
- 对用户的影响：Developers may fail before the first successful local run: [Bug] 13.x worker fails with "Cannot find module 'zod/v3'" — package-lock.json missing zod entry
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] 13.x worker fails with "Cannot find module 'zod/v3'" — package-lock.json missing zod entry. Context: Observed when using node, python, macos, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_577adec48438b667deb5de48f5dca7f0 | https://github.com/thedotmack/claude-mem/issues/2437 | [Bug] 13.x worker fails with "Cannot find module 'zod/v3'" — package-lock.json missing zod entry

## 18. 安装坑 · 失败模式：installation: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain
- 对用户的影响：Developers may fail before the first successful local run: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain. Context: Observed when using node, windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_4f334c0890e60adcd2706806e12f126c | https://github.com/thedotmack/claude-mem/issues/2528 | [Windows] bun-runner.js spawn EPERM when antivirus (360/Defender) blocks cmd → bun.cmd chain

## 19. 安装坑 · 失败模式：installation: [feat] Option to load only memory-related skills

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [feat] Option to load only memory-related skills
- 对用户的影响：Developers may fail before the first successful local run: [feat] Option to load only memory-related skills
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [feat] Option to load only memory-related skills. Context: Observed during installation or first-run setup.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_838f002b6acafaa53828fd03d9450ed6 | https://github.com/thedotmack/claude-mem/issues/2448 | [feat] Option to load only memory-related skills

## 20. 安装坑 · 失败模式：installation: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection
- 对用户的影响：Developers may fail before the first successful local run: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection. Context: Observed when using python, windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_9195685a79daaf4720e0243904f7946d | https://github.com/thedotmack/claude-mem/issues/2438 | chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection

## 21. 安装坑 · 失败模式：installation: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle
- 对用户的影响：Developers may fail before the first successful local run: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle. Context: Observed when using node, python, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_a54bc450a4d11e378deac2c0452f8c0f | https://github.com/thedotmack/claude-mem/issues/2450 | claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle

## 22. 安装坑 · 失败模式：installation: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)
- 对用户的影响：Developers may fail before the first successful local run: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote). Context: Observed when using node, windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_910a8a9b41ad8e6e15c1867e5ad4f96c | https://github.com/thedotmack/claude-mem/issues/2407 | v13.0.0 marketplace install bundle ships without bundled node_modules (zod, shell-quote)

## 23. 安装坑 · 失败模式：installation: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0
- 对用户的影响：Developers may fail before the first successful local run: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0. Context: Observed when using node, python, macos
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_32ef30e0e80f6e41f6f07078c0659311 | https://github.com/thedotmack/claude-mem/issues/2485 | v13.2.0: observer SDK responses dropped by parser as non-XML; observations table stays at 0

## 24. 安装坑 · 失败模式：installation: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars un...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)
- 对用户的影响：Developers may fail before the first successful local run: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux). Context: Observed when using node, python, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_25d358b5f6dfe891ef20a29ba6e827dc | https://github.com/thedotmack/claude-mem/issues/2520 | v13.2.0: smart_outline / smart_unfold / smart_search silently no-op — tree-sitter grammars unresolvable due to missing node_modules (Linux)

## 25. 安装坑 · 失败模式：installation: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_s...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated
- 对用户的影响：Developers may fail before the first successful local run: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated. Context: Observed when using python, macos
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_62407cc74d1dc4a1fbebe438679ae0be | https://github.com/thedotmack/claude-mem/issues/2533 | v13.x: observations never persisted — hooks reach worker, pending_messages stays empty, sdk_sessions.memory_session_id never populated

## 26. 安装坑 · 来源证据：Codex CLI: PreToolUse hook returned unsupported suppressOutput

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI: PreToolUse hook returned unsupported suppressOutput
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9022a732f6e54ba39309c5377cf2d8fa | https://github.com/thedotmack/claude-mem/issues/2360 | 来源类型 github_issue 暴露的待验证使用条件。

## 27. 安装坑 · 来源证据：[feat] Option to load only memory-related skills

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[feat] Option to load only memory-related skills
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_efa30fc4873343aea26f804c8d1113ec | https://github.com/thedotmack/claude-mem/issues/2448 | 来源类型 github_issue 暴露的待验证使用条件。

## 28. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | host_targets=claude, claude_code

## 29. 配置坑 · 失败模式：configuration: Feature: Vertex AI support for Gemini provider

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Feature: Vertex AI support for Gemini provider
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Feature: Vertex AI support for Gemini provider
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Feature: Vertex AI support for Gemini provider. Context: Observed during installation or first-run setup.
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_d3519e41cb7b1df860b0a5e6ae7db82e | https://github.com/thedotmack/claude-mem/issues/2522 | Feature: Vertex AI support for Gemini provider

## 30. 配置坑 · 失败模式：configuration: Use node to run mcp for windows environment

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Use node to run mcp for windows environment
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Use node to run mcp for windows environment
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Use node to run mcp for windows environment. Context: Observed when using node, windows, macos, linux
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_7e6bf076e8e465cee8256dd4cb41c3d4 | https://github.com/thedotmack/claude-mem/issues/2446 | Use node to run mcp for windows environment

## 31. 配置坑 · 失败模式：configuration: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraint...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection. Context: Observed when using node, python, windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_e40a2ed6db40844214cbb7d7c39088e4 | https://github.com/thedotmack/claude-mem/issues/2509 | Windows: chroma-mcp connection fails instantly — cmd.exe interprets < > in version constraints as redirection

## 32. 配置坑 · 失败模式：configuration: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.e...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects
- 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects. Context: Observed when using node, python, windows
- 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
- 证据：failure_mode_cluster:github_issue | fmev_b7f38212a7bbb06091eda408d7b08fbb | https://github.com/thedotmack/claude-mem/issues/2529 | [Windows] chroma-mcp fails to start — '>' and '<' in version constraints interpreted as cmd.exe redirects

## 33. 配置坑 · 来源证据：Native Azure AI Foundry support (ANTHROPIC_FOUNDRY_* env vars)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Native Azure AI Foundry support (ANTHROPIC_FOUNDRY_* env vars)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b7808109101d47ccb8519f238757da11 | https://github.com/thedotmack/claude-mem/issues/2524 | 来源类型 github_issue 暴露的待验证使用条件。

## 34. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | README/documentation is current enough for a first validation pass.

## 35. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | last_activity_observed missing

## 36. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | no_demo; severity=medium

## 37. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | no_demo; severity=medium

## 38. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | issue_or_pr_quality=unknown

## 39. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | release_recency=unknown