项目定位

memtomem-stm 是一个面向 LLM Agent 的 MCP（Model Context Protocol）短期记忆代理服务器，以独立进程的形式作为 stdio 服务嵌入到支持 MCP 的客户端（例如 Claude Desktop、其他 MCP host）中。它通过 stdio 与客户端通信，对外暴露 13 个 MCP 工具，并附带一个 mms 命令行工具用于运维。

资料来源：pyproject.toml:1-40 资料来源：src/memtomem_stm/server.py:1845-1860

项目的核心定位可以从三个维度概括：

1. 代理（Proxy）：作为 MCP server 与一组上游 MCP server 之间的中介，统一处理 call_tool、list_tools、list_resources、read_resource 等调用，并对外屏蔽上游拓扑。
2. 短期记忆（Short-Term Memory, STM）：在调用链路上插入 REORDER / FILTER / COMPRESS / INDEX / DECIDE / SURFACE 六个阶段，对工具结果做相关性打分、截断、压缩、隐私扫描与回写，让"被淹没"的工具输出变成可消费的经验。
3. 可观测与可调优（Observability & Tuning）：把每次调用的评分、反馈、隐私决策写入本地 SQLite，并通过 MCP 工具与 CLI 暴露，避免 Agent 重新踩坑。

核心架构概览

整个系统的入口与装配中心是 server.main()，它同时承担日志配置、组件装配与 MCP server 启动三件事：

资料来源：src/memtomem_stm/server.py:1802-1845 资料来源：src/memtomem_stm/config.py:135-144 资料来源：CHANGELOG.md:1-30

数据流可以用下面的简化视图描述：MCP 客户端 → server.py 入口 → ProxyManager._fetch_upstream → （REORDER/FILTER/COMPRESS/INDEX/DECIDE/SURFACE）→ 写入 stm_feedback.db / stm_proxy_stats → 经 MCP 工具或 mms CLI 反馈给运维者与 Agent。

核心价值主张

1. 把"工具噪声"压成"可执行记忆"

传统 MCP 直连时，工具调用结果要么被截断要么被丢弃。STM 路径在 COMPRESS 阶段对超大结果做摘要，再在 SURFACE 阶段把命中的片段以 memory 形式回写到会话上下文，从而让 Agent 在后续轮次能"想起"前面的工具输出。

2. 相关性优先于字面匹配

RelevanceScorer 通过 embedding 提供商（Ollama 或 OpenAI 兼容端点）对查询与候选条目打分，使 REORDER 与 FILTER 阶段可以按分数而非字面顺序工作。

3. 隐私与外部 LLM 边界的可控性

系统在内置的 PrivacyScanner 与可选的外部 LLM 抽取/压缩之间设置显式开关，避免敏感文本在用户不知情的情况下被外发。

4. 运维自洽

mms CLI 提供 health、stats、config、secrets、detect、tune、daemon 等子命令；其中 stm_surfacing_stats 会在评分方差为零时主动告警（v0.1.31 新增），帮助运维发现"评分完全无效"的退化态。

资料来源：CHANGELOG.md:1-20 资料来源：src/memtomem_stm/__init__.py:1-20

当前状态与社区焦点

截至 v0.1.31，仓库拥有约 71k LOC 的测试代码（120 个测试文件），整体覆盖率"广泛良好"，但 2026-07-04 的服务审查指出若干已知缺口，正在被追踪为 GitHub Issue：

• #608：call_tool 路径尚未接入 per-upstream 熔断器，SECURITY.md 中的承诺与实现不一致。
• #618：RelevanceScorer 的 _embed_ollama / _embed_openai 使用同步 httpx.post，最坏情况下会阻塞 asyncio 事件循环一整个超时窗口。
• #611：未识别的配置键会被静默忽略，解析失败也会静默回退到默认值；计划引入 mms config validate。
• #610：关闭 privacy_scan_enabled 时，原始上游文本会被静默发往外部 LLM 提供商，需要更显眼的告警甚至熵值启发式。
• #612：服务器日志当前只写 stderr，MCP stdio 模式下可能被客户端吞掉，需要可选的轮转文件日志。
• #617：mypy 当前在 4 个文件中有 9 处错误，处于"建议性"状态。
• #616：auto_index / extraction 配置键被接受但实际未生效（#288 仅以文档方式闭合），需要决定是补齐 index engine 还是退役该配置面。

资料来源：CHANGELOG.md:1-30 资料来源：src/memtomem_stm/server.py:1845

这些 issue 共同勾勒出项目的下一阶段重点：把已经"可用"的代理补成"可靠且可被生产运维"的代理——也就是在观测、日志、配置校验、类型安全、隐私边界与弹性（熔断）这几个维度上同时收敛差距。

1. 概述与设计目标

memtomem-stm 在客户端（MCP host）与上游 MCP server 之间插入了一个有状态代理层 ProxyManager，其核心职责是把上游返回的"原始调用结果"逐级转换为"可被模型在多轮会话中复用的高质量记忆"。该转换被显式拆分为四个有序阶段：CLEAN → COMPRESS → SURFACE → INDEX。这种"管线下推 + 阶段隔离"的设计让隐私清洗、可逆压缩、相关性筛选与索引写入可以独立演进与单元测试，资料来源：src/memtomem_stm/proxy/manager.py:1-80。

每个阶段都是 Protocol 类型的可注入组件，遵循同一组 CleaningStage / CompressionStage / SurfacingStage / IndexStage 接口，资料来源：src/memtomem_stm/proxy/protocols.py:1-120。ProxyManager 在构造时按依赖注入方式装配阶段对象；当任一阶段缺失时（例如 bundled mms server 未注入 index_engine），相关阶段会被标记为 inert，并在启动日志中给出明确告警，资料来源：src/memtomem_stm/proxy/manager.py:415-450。

2. 管线四阶段职责

下表给出每个阶段的输入、产出、关键配置与典型实现位置。

资料来源：src/memtomem_stm/proxy/pipeline_stages.py:30-140。

2.1 CLEAN — 隐私与边界清洗

PrivacyScanCleaner 在 COMPRESS 之前对原始文本执行正则 + 熵启发式检测，命中规则后将 token 替换为 [REDACTED:<kind>]，避免原始凭据进入任何 LLM 提示词或日志。资料来源：src/memtomem_stm/proxy/cleaning.py:45-160。当 privacy_scan_enabled=false 时，最近的评审（#610）指出仍会默默把原文发往外部 LLM 提供商，因此该开关需在配置层做更严格的告警提示。

2.2 COMPRESS — 结果压缩

Compressor 支持多种策略（truncate / head_tail / summary / regex_strip），并在 max_result_chars 之内生成保留可逆性的中间表示，供 SURFACE 阶段打分时复用上下文。资料来源：src/memtomem_stm/proxy/compression.py:60-210。stm_tuning_recommendations 会针对每个 tool 输出 max_result_chars 与策略建议，目前需手工应用到 stm_proxy.json（参见 #615 mms tune --apply）。

2.3 SURFACE — 相关性筛选

RelevanceScorer 接收 COMPRESS 后的条目，调用 embedding provider（_embed_ollama / _embed_openai）计算与当前 query 的相似度，过滤掉低于 min_score 的结果。资料来源：src/memtomem_stm/proxy/relevance.py:180-240。需要注意的是，#618 指出这两个方法当前仍使用同步 httpx.post(...)，会阻塞 asyncio 事件循环直至超时，是当前最显著的并发瓶颈之一。

2.4 INDEX — 持久化与可检索

IndexEngine（默认基于 SQLite FTS，可选向量后端）把条目写入 stm_memory.db，供后续 session 通过 stm_recall 等 MCP 工具检索。资料来源：src/memtomem_stm/proxy/extraction.py:90-200。bundled mms server 因未注入 index_engine，INDEX 阶段为惰性状态——auto_index / extraction 配置虽被接受但不起作用，#616 正在决定是否真正接入引擎或下线该配置面。

3. 阶段编排与容错

ProxyManager.process_call_result 是管线的总入口，依次串联四个阶段并在阶段间传递带类型的中间结构 PipelinePayload（参见 protocols.py:30-90）。每一阶段在异常时被转换为结构化错误 ErrorDetails，通过 MCP tools/call 的 isError 与 content 字段回传，而非直接抛出 Python 异常，资料来源：src/memtomem_stm/proxy/manager.py:120-260。

管线内嵌三类横切关注点：

1. 观测埋点：调用次数、压缩比、打分分布通过 observability/tracing（Langfuse 集成）发出；stm_surfacing_stats 在 v0.1.31 起新增零方差告警（#573），提示过滤已退化为随机选择。
2. 重连与熔断：上游 call_tool 重试循环位于 _fetch_upstream；#608 指出该路径尚未实现 SECURITY.md 宣称的 per-upstream 熔断器，是当前最突出的可靠性差距；#622 同时提示该循环的中途重连日志存在凭证 URL 泄露。
3. 统计口径差异：mms stats 仅读取磁盘 DB，而 stm_proxy_stats 来自进程内计数器，#613 正在收敛两者以避免静默分歧，资料来源：src/memtomem_stm/cli/proxy.py:833 与 src/memtomem_stm/server.py:1700-1850。

4. 演进方向与社区关注点

围绕该管线的近期社区议题集中在四方面，可作为后续贡献的切入点：

• 可靠性（#608、#622）：补齐 per-upstream 熔断、修补重连日志的凭证泄露。
• 并发（#618）：把 _embed_ollama / _embed_openai 改为 httpx.AsyncClient 异步调用。
• 可发现性（#613、#615）：统一 mms stats / stm_proxy_stats、提供 mms tune --apply。
• 配置正确性（#611、#616、#610）：新增 mms config validate、明确 auto_index 是否接入、或下线该配置面，并对 privacy_scan_enabled=false 给出声告警。

资料来源：src/memtomem_stm/proxy/manager.py:415-450、src/memtomem_stm/proxy/relevance.py:196-208、src/memtomem_stm/server.py:1802-1850。

memtomem-stm 的命令行入口是一个由 Click 组成的 mms 多级命令树，把"代理 (proxy) 调优与统计""主机 (host) 注册""项目 (project) 初始化""数据导入 (import)""后台守护进程 (daemon)"这几类运维动作收口到一个可执行文件里。cli/__init__.py 负责把这些子模块组装为统一的 mms 顶层命令，并把 proxy、host、project、import、daemon 等子命令挂到主入口下。资料来源：src/memtomem_stm/cli/__init__.py。

命令体系总览

mms 的命令空间按"对象 → 动作"两层组织，常见子命令大致如下：

这种分层让代理层（proxy server）和 CLI 层共用同一个 cli/ 包，运维脚本可以单独调用而无需启动 MCP 服务本身。资料来源：src/memtomem_stm/cli/proxy.py, src/memtomem_stm/cli/mms_host.py, src/memtomem_stm/cli/mms_project.py。

代理运维命令 (proxy)

cli/proxy.py 是 CLI 的核心，约八百行，承载与 ProxyManager 直接交互的所有运维动作。其中：

• mms stats 读取磁盘上的 stm_proxy.db / stm_feedback.db 等落盘数据并打印聚合结果；它与运行中的 stm_proxy_stats 是两条不同的数据通道，前者只看磁盘。资料来源：src/memtomem_stm/cli/proxy.py:833。
• mms tune 会调用服务器端 stm_tuning_recommendations 工具产出按工具维度的 max_result_chars、策略与保留期建议；当前版本仍需用户手工写入 stm_proxy.json，社区已记录后续 --apply 自动落盘的改进方向。资料来源：src/memtomem_stm/cli/proxy.py。
• mms config validate 计划新增，用以解决"未知键被静默忽略、解析失败回退到默认值"这两类暗失败模式——目前任何 Pydantic 模型默认 extra="ignore"，拼错键会被默默丢掉。资料来源：src/memtomem_stm/cli/proxy.py。

需要注意的是，cli/proxy.py 中部分统计路径只读磁盘，运行时 in-memory 状态由 13 个 MCP 观测工具暴露，二者需要分别查阅才不会出现"明明在线指标正常却报 0"的误判。资料来源：src/memtomem_stm/cli/proxy.py:833。

主机、项目与导入

mms_host.py、mms_project.py、mms_import.py 三个文件分别承担"上游注册""本地项目脚手架""批量导入"三类相对独立的工作：

• mms host add/list/remove 维护 stm_proxy.json 中 upstreams 列表，是配对上层 call_tool 路径上游熔断、凭据重命名等安全策略的入口（参见 #608、#622）。资料来源：src/memtomem_stm/cli/mms_host.py。
• mms project init/status/list 在工作目录下生成 stm_proxy.json 骨架，并区分 status 与 list 的语义——社区已记录二者语义重叠的合并建议。资料来源：src/memtomem_stm/cli/mms_project.py。
• mms import 负责把外部记忆/反馈文件批量灌入 SQLite 持久层，是离线迁移和回填 stm_feedback.db 的常用入口。资料来源：src/memtomem_stm/cli/mms_import.py。

守护进程管理 (daemon_cmd.py)

cli/daemon_cmd.py 提供 daemon run / start / stop / status 等子命令，把 server.main() 包成可后台运行的进程。当前实现约定日志输出到 stderr，级别由环境变量 MEMTOMEM_STM_LOG_LEVEL 控制，默认 WARNING。资料来源：src/memtomem_stm/cli/daemon_cmd.py。

两个已知缺口值得在排障时留意：

1. 没有可选的滚动文件日志：在 MCP stdio 启动模式下 stderr 可能被宿主丢弃，运维需要长期留存时只能自行重定向，社区已记录增加 ~/.memtomem/ 下 rotating log 的改进方向。资料来源：src/memtomem_stm/cli/daemon_cmd.py。
2. run 与 start 命名重叠，且缺乏直接测试覆盖：CLI 的一致性改造与 daemon_cmd 的单元测试补齐被列为同一批次（参见 #614、#619）。

运维一致性提示

CLI 层目前还存在若干一致性细节待收敛（社区已记录在 #614）：并非所有子命令都支持 --json 输出、daemon run/start 语义重叠、status/list 在某些子命令组中语义重合。建议在编写调用脚本前先确认目标子命令是否支持机器可读输出，必要时通过环境变量而非 CLI 标志传入配置，以避开静默的键名忽略。资料来源：src/memtomem_stm/cli/__init__.py, src/memtomem_stm/cli/proxy.py, src/memtomem_stm/cli/daemon_cmd.py。

概览与范围

memtomem-stm 在 src/memtomem_stm/utils/ 目录下沉淀了一组面向"运行时质量"的基础设施模块，聚焦三类能力：弹性（熔断隔离）、可观测性（日志脱敏、统计输出）、运维（优雅关闭、原子文件 I/O、私有 SQLite 访问）。这些工具被上层 MCP 服务器与代理（ProxyManager、server.main()、cli/proxy.py）复用，构成与外部 LLM 提供方、上游 MCP 服务器交互的横切关注点。

flowchart LR
  subgraph 运行时横切
    CB[circuit_breaker.py<br/>熔断]
    RD[redact.py<br/>凭据脱敏]
    SD[anyio_shutdown.py<br/>优雅关闭]
  end
  subgraph 持久化
    FI[fileio.py<br/>原子写入]
    SQL[sqlite_private.py<br/>私有 DB]
    NU[numeric.py<br/>数值辅助]
  end
  PROXY[ProxyManager] --> CB
  PROXY --> RD
  SERVER[server.main] --> SD
  SERVER --> RD
  CLI[cli/proxy.py] --> FI
  CLI --> SQL
  ST[surfacing/feedback_store] --> NU

弹性：熔断器与上游隔离

circuit_breaker.py 为按上游（per-upstream）粒度提供故障隔离，是 SECURITY.md 中"per-upstream circuit breaker isolation"承诺的代码落点。其设计目标是：当某一个上游 MCP 服务器或 LLM 提供方进入失败窗口时，短路后续调用，避免将异常扩散到请求方并触发雪崩。社区评审（2026-07-04 全服务回顾）指出该承诺与现状存在落差：_fetch_upstream 这条 retry 路径尚未接入熔断器，相关 issue #608 已追踪该缺口。资料来源：src/memtomem_stm/utils/circuit_breaker.py

可观测性：日志脱敏与统计

凭据脱敏

redact.py 为日志与错误上报提供凭据脱敏函数，配套于 #605/#606 的"credential-redaction sweep"。脱敏覆盖 _reconnect_server 的重连/清理路径，以及 _fetch_upstream 中的 deadline/protocol/terminal 失败位点。然而 issue #622 在实现 #608 的同一 retry 循环时发现，重连失败日志中仍然泄漏带凭据的上游 URL，说明脱敏覆盖矩阵尚未完整。资料来源：src/memtomem_stm/utils/redact.py

统计与零方差告警

v0.1.31 起，stm_surfacing_stats 对零方差（zero-variance）评分分布发出告警（issue #573，源自 #560 步骤 3）——之前所有 surfacing 评分恒定不变时，统计工具仍正常输出但不提示该分布已丧失排序意义，导致 min_score 过滤在静默退化状态。资料来源：src/memtomem_stm/utils/numeric.py

日志通道现状

当前 server.main() 仅将日志写到 stderr，默认级别 WARNING，由环境变量 MEMTOMEM_STM_LOG_LEVEL 控制（社区报告见 issue #612）。stdio MCP 模式下 stderr 可能被客户端捕获或丢弃，因此新增"按需轮转文件日志（位于 ~/.memtomem/）"被列为运维体验改进项。资料来源：src/memtomem_stm/utils/anyio_shutdown.py

可靠性：优雅关闭与重试循环

anyio_shutdown.py 基于 anyio 的结构化并发原语实现服务关闭：监听信号或 MCP 客户端断开事件，取消进行中的任务并等待 _fetch_upstream 等长循环退出，避免悬挂连接。该模块与重连/重试逻辑（_reconnect_server、_fetch_upstream 的 deadline 处理）紧邻，是 #622 中"mid-loop reconnect-failure"日志路径的同一切面。资料来源：src/memtomem_stm/utils/anyio_shutdown.py

运维：文件 I/O 与私有 SQLite

原子文件写入

fileio.py 为 CLI 与反馈库提供原子写入工具，常用于 stm_proxy.json 等配置文件的覆盖——通过"写入临时文件 + os.replace"保证中途崩溃不会留下半截配置。这一机制是 mms tune --apply（issue #615）将 stm_tuning_recommendations 自动落盘的先决条件。资料来源：src/memtomem_stm/utils/fileio.py

私有 SQLite 通道

sqlite_private.py 为 stm_feedback.db、stm_proxy_stats.db 等私有数据库提供受控访问：统一打开/关闭、WAL 模式与 busy_timeout 设置，确保 mms stats 与在线 stm_proxy_stats 统计的读取一致——这是 issue #613 标记的"mms stats 仅读磁盘，与运行期内存统计静默偏离"的修复基础。资料来源：src/memtomem_stm/utils/sqlite_private.py

数值辅助

numeric.py 提供评分聚合与统计所需的数值运算，被 surfacing 反馈管线复用，间接支撑前述零方差告警（v0.1.31）。资料来源：src/memtomem_stm/utils/numeric.py

已知缺口与后续动作

资料来源：src/memtomem_stm/utils/circuit_breaker.py、src/memtomem_stm/utils/redact.py、src/memtomem_stm/utils/anyio_shutdown.py、src/memtomem_stm/utils/fileio.py、src/memtomem_stm/utils/sqlite_private.py、src/memtomem_stm/utils/numeric.py

Pitfall Log / 踩坑日志

项目：memtomem/memtomem-stm

摘要：发现 36 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: ci: supply-chain hardening — dependency audit, Dependabot, action SHA pinning, top-level work...。

1. 安全/权限坑 · 失败模式：security_permissions: ci: supply-chain hardening — dependency audit, Dependabot, action SHA pinning, top-level work...

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: ci: supply-chain hardening — dependency audit, Dependabot, action SHA pinning, top-level workflow permissions
• 对用户的影响：Developers may expose sensitive permissions or credentials: ci: supply-chain hardening — dependency audit, Dependabot, action SHA pinning, top-level workflow permissions
• 证据：failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/609 | ci: supply-chain hardening — dependency audit, Dependabot, action SHA pinning, top-level workflow permissions

2. 安全/权限坑 · 失败模式：security_permissions: privacy: disabling privacy_scan_enabled silently sends raw upstream text to external LLM prov...

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: privacy: disabling privacy_scan_enabled silently sends raw upstream text to external LLM providers — warn loudly; consider entropy heuristic
• 对用户的影响：Developers may expose sensitive permissions or credentials: privacy: disabling privacy_scan_enabled silently sends raw upstream text to external LLM providers — warn loudly; consider entropy heuristic
• 证据：failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/610 | privacy: disabling privacy_scan_enabled silently sends raw upstream text to external LLM providers — warn loudly; consider entropy heuristic

3. 安全/权限坑 · 失败模式：security_permissions: tests: fill direct-coverage gaps — observability/tracing, mms/secrets, mms/detect, cli/daemon...

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: tests: fill direct-coverage gaps — observability/tracing, mms/secrets, mms/detect, cli/daemon_cmd, relevance embedding paths
• 对用户的影响：Developers may expose sensitive permissions or credentials: tests: fill direct-coverage gaps — observability/tracing, mms/secrets, mms/detect, cli/daemon_cmd, relevance embedding paths
• 证据：failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/619 | tests: fill direct-coverage gaps — observability/tracing, mms/secrets, mms/detect, cli/daemon_cmd, relevance embedding paths

4. 安装坑 · 失败模式：installation: proxy: upstream call_tool path has no circuit breaker — SECURITY.md claims per-upstream break...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: proxy: upstream call_tool path has no circuit breaker — SECURITY.md claims per-upstream breaker isolation
• 对用户的影响：Developers may fail before the first successful local run: proxy: upstream call_tool path has no circuit breaker — SECURITY.md claims per-upstream breaker isolation
• 证据：failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/608 | proxy: upstream call_tool path has no circuit breaker — SECURITY.md claims per-upstream breaker isolation

5. 安装坑 · 失败模式：installation: v0.1.29

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.1.29
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.29
• 证据：failure_mode_cluster:github_release | https://github.com/memtomem/memtomem-stm/releases/tag/v0.1.29 | v0.1.29

6. 安装坑 · 来源证据：config: unknown keys are silently ignored and parse failures silently fall back — add `mms config validate` and louder…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：config: unknown keys are silently ignored and parse failures silently fall back — add mms config validate and louder failure
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/611 | 来源类型 github_issue 暴露的待验证使用条件。

7. 安装坑 · 来源证据：proxy: ProxyManager.stop() never closes the sqlite pending stores (leaked connection on config-change rebuild)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：proxy: ProxyManager.stop() never closes the sqlite pending stores (leaked connection on config-change rebuild)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/601 | 来源类型 github_issue 暴露的待验证使用条件。

8. 安装坑 · 来源证据：server: stderr-only logging — add optional rotating file log under ~/.memtomem/

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：server: stderr-only logging — add optional rotating file log under ~/.memtomem/
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/612 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/memtomem/memtomem-stm | host_targets=claude, mcp_host, claude_code, cursor

10. 配置坑 · 失败模式：configuration: Harden non-startup exc_info cleanup logs against credential leaks (follow-up to #580/#593)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Harden non-startup exc_info cleanup logs against credential leaks (follow-up to #580/#593)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Harden non-startup exc_info cleanup logs against credential leaks (follow-up to #580/#593)
• 证据：failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/605 | Harden non-startup exc_info cleanup logs against credential leaks (follow-up to #580/#593)

11. 配置坑 · 失败模式：configuration: cli/docs polish batch: --json coverage, daemon run/start naming, status/list overlap, CHANGEL...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: cli/docs polish batch: --json coverage, daemon run/start naming, status/list overlap, CHANGELOG upgrade-notes
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: cli/docs polish batch: --json coverage, daemon run/start naming, status/list overlap, CHANGELOG upgrade-notes
• 证据：failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/614 | cli/docs polish batch: --json coverage, daemon run/start naming, status/list overlap, CHANGELOG upgrade-notes

12. 配置坑 · 失败模式：configuration: cli: mms tune --apply — apply stm_tuning_recommendations to stm_proxy.json instead of hand-ed...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: cli: mms tune --apply — apply stm_tuning_recommendations to stm_proxy.json instead of hand-editing
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: cli: mms tune --apply — apply stm_tuning_recommendations to stm_proxy.json instead of hand-editing
• 证据：failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/615 | cli: mms tune --apply — apply stm_tuning_recommendations to stm_proxy.json instead of hand-editing

13. 配置坑 · 失败模式：configuration: config: unknown keys are silently ignored and parse failures silently fall back — add `mms co...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: config: unknown keys are silently ignored and parse failures silently fall back — add mms config validate and louder failure
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: config: unknown keys are silently ignored and parse failures silently fall back — add mms config validate and louder failure
• 证据：failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/611 | config: unknown keys are silently ignored and parse failures silently fall back — add mms config validate and louder failure

14. 配置坑 · 失败模式：configuration: decide: wire an index engine into the bundled mms server, or retire the inert auto_index/extr...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: decide: wire an index engine into the bundled mms server, or retire the inert auto_index/extraction config surface (follow-up to #288)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: decide: wire an index engine into the bundled mms server, or retire the inert auto_index/extraction config surface (follow-up to #288)
• 证据：failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/616 | decide: wire an index engine into the bundled mms server, or retire the inert auto_index/extraction config surface (follow-up to #288)

15. 配置坑 · 失败模式：configuration: proxy: ProxyManager.stop() never closes the sqlite pending stores (leaked connection on confi...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: proxy: ProxyManager.stop() never closes the sqlite pending stores (leaked connection on config-change rebuild)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: proxy: ProxyManager.stop() never closes the sqlite pending stores (leaked connection on config-change rebuild)
• 证据：failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/601 | proxy: ProxyManager.stop() never closes the sqlite pending stores (leaked connection on config-change rebuild)

16. 配置坑 · 失败模式：configuration: server: stderr-only logging — add optional rotating file log under ~/.memtomem/

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: server: stderr-only logging — add optional rotating file log under ~/.memtomem/
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: server: stderr-only logging — add optional rotating file log under ~/.memtomem/
• 证据：failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/612 | server: stderr-only logging — add optional rotating file log under ~/.memtomem/

17. 配置坑 · 失败模式：configuration: types: mypy burn-down — 9 errors in 4 files, then re-enable the attr-defined suppression

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: types: mypy burn-down — 9 errors in 4 files, then re-enable the attr-defined suppression
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: types: mypy burn-down — 9 errors in 4 files, then re-enable the attr-defined suppression
• 证据：failure_mode_cluster:github_issue | https://github.com/memtomem/memtomem-stm/issues/617 | types: mypy burn-down — 9 errors in 4 files, then re-enable the attr-defined suppression

18. 配置坑 · 失败模式：configuration: v0.1.27

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.1.27
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.27
• 证据：failure_mode_cluster:github_release | https://github.com/memtomem/memtomem-stm/releases/tag/v0.1.27 | v0.1.27

19. 配置坑 · 失败模式：configuration: v0.1.30

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.1.30
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.30
• 证据：failure_mode_cluster:github_release | https://github.com/memtomem/memtomem-stm/releases/tag/v0.1.30 | v0.1.30

20. 配置坑 · 失败模式：configuration: v0.1.31

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.1.31
• 对用户的影响：Upgrade or migration may change expected behavior: v0.1.31
• 证据：failure_mode_cluster:github_release | https://github.com/memtomem/memtomem-stm/releases/tag/v0.1.31 | v0.1.31

21. 配置坑 · 来源证据：cli/docs polish batch: --json coverage, daemon run/start naming, status/list overlap, CHANGELOG upgrade-notes

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：cli/docs polish batch: --json coverage, daemon run/start naming, status/list overlap, CHANGELOG upgrade-notes
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/614 | 来源类型 github_issue 暴露的待验证使用条件。

22. 配置坑 · 来源证据：cli: mms tune --apply — apply stm_tuning_recommendations to stm_proxy.json instead of hand-editing

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：cli: mms tune --apply — apply stm_tuning_recommendations to stm_proxy.json instead of hand-editing
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/615 | 来源类型 github_issue 暴露的待验证使用条件。

23. 配置坑 · 来源证据：decide: wire an index engine into the bundled mms server, or retire the inert auto_index/extraction config surface (fol…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：decide: wire an index engine into the bundled mms server, or retire the inert auto_index/extraction config surface (follow-up to #288)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/616 | 来源类型 github_issue 暴露的待验证使用条件。

24. 配置坑 · 来源证据：tests: fill direct-coverage gaps — observability/tracing, mms/secrets, mms/detect, cli/daemon_cmd, relevance embedding…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：tests: fill direct-coverage gaps — observability/tracing, mms/secrets, mms/detect, cli/daemon_cmd, relevance embedding paths
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/619 | 来源类型 github_issue 暴露的待验证使用条件。

25. 配置坑 · 来源证据：types: mypy burn-down — 9 errors in 4 files, then re-enable the attr-defined suppression

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：types: mypy burn-down — 9 errors in 4 files, then re-enable the attr-defined suppression
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/617 | 来源类型 github_issue 暴露的待验证使用条件。

26. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/memtomem/memtomem-stm | README/documentation is current enough for a first validation pass.

27. 运行坑 · 来源证据：proxy/relevance: embedding providers use synchronous httpx.post — blocks the event loop for up to the full timeout

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：proxy/relevance: embedding providers use synchronous httpx.post — blocks the event loop for up to the full timeout
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/618 | 来源类型 github_issue 暴露的待验证使用条件。

28. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/memtomem/memtomem-stm | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/memtomem/memtomem-stm | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/memtomem/memtomem-stm | no_demo; severity=medium

31. 安全/权限坑 · 来源证据：Harden non-startup exc_info cleanup logs against credential leaks (follow-up to #580/#593)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Harden non-startup exc_info cleanup logs against credential leaks (follow-up to #580/#593)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/605 | 来源类型 github_issue 暴露的待验证使用条件。

32. 安全/权限坑 · 来源证据：ci: supply-chain hardening — dependency audit, Dependabot, action SHA pinning, top-level workflow permissions

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ci: supply-chain hardening — dependency audit, Dependabot, action SHA pinning, top-level workflow permissions
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/609 | 来源类型 github_issue 暴露的待验证使用条件。

33. 安全/权限坑 · 来源证据：privacy: disabling privacy_scan_enabled silently sends raw upstream text to external LLM providers — warn loudly; consi…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：privacy: disabling privacy_scan_enabled silently sends raw upstream text to external LLM providers — warn loudly; consider entropy heuristic
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/610 | 来源类型 github_issue 暴露的待验证使用条件。

34. 安全/权限坑 · 来源证据：proxy: upstream call_tool path has no circuit breaker — SECURITY.md claims per-upstream breaker isolation

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：proxy: upstream call_tool path has no circuit breaker — SECURITY.md claims per-upstream breaker isolation
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/memtomem/memtomem-stm/issues/608 | 来源类型 github_issue 暴露的待验证使用条件。

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/memtomem/memtomem-stm | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/memtomem/memtomem-stm | release_recency=unknown