遥测¶

Claude-mem 包含匿名使用情况分析（通过 PostHog），用于帮助确定修复和功能的优先级。

默认开启（可选择退出）。 事件是匿名的，仅通过随机安装 UUID 标识，并且每个分析属性都经过严格的白名单过滤 — 请参阅下面的收集哪些数据和绝不收集哪些数据。关闭它只需一条命令：

npx claude-mem telemetry disable

标准的 DO_NOT_TRACK 环境变量也会被遵循，并覆盖所有其他设置。安装程序会在 npx claude-mem install 结束时询问一次，因此对于新安装而言，默认设置绝不会默默生效 — 你的回答（无论内容如何）都会被记住，并且绝不会再次询问；当设置了 DO_NOT_TRACK 或在 CI/非交互式安装中时，该提示会被完全跳过。

埋点工作原理¶

Claude-mem 只有一条埋点路径（src/services/telemetry/instrument.ts 中的 instrument()）。每个可观测事件只描述一次，然后分发到两个接收端：

• 本地日志 — 始终以完整保真度记录。 即使遥测关闭，日志记录仍会继续工作，且本地日志绝不会经过清理器。完整、未脱敏的详细信息就在这里 — 在你的机器上。
• 遥测 — 仅在获得同意时发送。 遥测副本会经过清理（结构化属性使用白名单；错误文本使用先允许后脱敏），并且对于高量级事件，会在发送之前汇总为按会话/按时间窗口的聚合数据。

因此，单一事实来源同时生成了丰富的本地日志和最小化、保护隐私的遥测数据 — 二者永远不会产生偏差，清理只发生在遥测分支上。

关于会话回放的说明： PostHog 会话回放不适用于 claude-mem。回放记录的是浏览器 DOM 会话；claude-mem 是一个没有浏览器界面的 Node 后台工作进程，因此没有任何内容可供回放，它也永远不会被启用。

收集哪些数据¶

启用后，事件是匿名的，仅通过随机安装 UUID（crypto.randomUUID()，在首次使用时于本地生成）标识。

低量级生命周期事件（install_*、uninstall_completed、worker_started）会构建一个以该随机 UUID 为键的分析画像，从而可以计算聚合留存率和同期群统计 — 该画像仅包含下面白名单中的字段（平台、版本、IDE/提供商选择）。它不可能与你关联起来：其中没有姓名、邮箱、IP、硬件 ID 或任何其他标识符。所有高量级活动均以 $process_person_profile: false 发送，且完全不构建任何画像。

关于所观测 IDE 会话的身份，claude-mem 仅收集其模型 ID（observed_model）和计费层级（observed_billing）— 绝不收集账户 ID、邮箱或令牌。

高量级事件会被汇总，而不是流式发送。 与为每次压缩或上下文注入各发送一个事件不同，claude-mem 在本地聚合它们并发送一份摘要：

• observer_turn_rollup — 一个按会话的累加器。会话中的每次压缩都会并入一个持续运行的汇总，并在会话结束时一次性发出（而不是每轮发出一个 session_compressed 事件）。它带有一个 rollup_reason 说明刷新原因（session_end | worker_shutdown | safety_flush），以及一个 window_seq 部分刷新计数器（普通一次性会话为 0；只有当长期会话触发周期性安全扫描时才为 0,1,2,…）。
• context_injected_rollup — 一个针对上下文注入的5 分钟时间窗口累加器。

正是这种汇总模型将高量级事件流削减了约 99.9%。现在不再有任何代码路径会直接发出原始 session_compressed 或 context_injected 事件 — 该活动到达 PostHog 的唯一路径就是汇总。

每个事件属性都会经过严格的白名单清理器 — 表中没有的键会在发送前被静默丢弃：

有一个值是在服务端推导出来的，而非由客户端发送：PostHog 在接收数据时将请求发送方的 IP 解析为粗略位置（国家 / 地区 / 城市），随后 IP 本身即被丢弃。客户端绝不会在任何事件上附加 IP，原始 IP 也绝不被存储 — 参见绝不收集的内容。

事件¶

工作状态用量与诊断限制¶

工作状态汇总仅包含计数。它们绝不包含任务标题、字段、提示词、项目名称、路径、原始会话或 agent ID，也不包含推断出的模型。platform 是固定的受支持宿主名称、other 或 unknown；agent_role 是 main、subagent 或 unknown（使用与捕获相同的 subagent 谓词）。

captured_ 和 mcp_ 的读/写计数器也都有以 _ok_count、_error_count、_excluded_count、_disabled_count 或 _unknown_count 结尾的结果计数器。只有明确保存的回执才能确认写入成功。两个来源可能观察到同一次调用：切勿将它们作为不同用量相加。

instruction_state 描述该确切本地会话/agent 作用域中事件之前的最近一次已知钩子交接。早于最近交接的延迟活动具有 instruction_state=unknown；后续指令绝不会追溯应用。没有原始时间戳的捕获提示词和工具会被省略。在观察到交接之前，其为 unknown。直接 MCP 调用、仅服务器运行时捕获、缺失钩子以及 worker 不可用都可能使覆盖范围未知。Live Pi、OpenCode 和 OMP 的提示词回调带有其原始时序；Pi 即使在回放时也使用持久化的用户消息时间戳。通用 DSH 客户端调用和 OpenClaw 合成初始化路径缺乏经过验证的提示词时序，因此仍不计入捕获的提示词/工具计数。OMP 有其自身的受限平台标签；缺失稳定工具 ID 只会产生未识别到达的诊断信息。较旧的适配器已经提供了默认宿主，无法与明确报告宿主的宿主区分开。缺失计数器或事件并不证明零用量或零遵从；一个普通问题可能正确地不需要任何写入。不会计算合规百分比或任务分类。

本地哈希回执密钥可在 30 天内抑制跨 worker 重启的重复提示、工具重放和重复的 spool 投递。在活动期间进行清理，每小时至多一次，移除较早的回执；较早的事件会被丢弃而不是重新计数。即使分析功能关闭，也会维护一个本地的、不含内容的公开/私有轮次位，因此在私有工作期间重新选择加入时，无法重用之前的公开提示。只有严格更新且带有时间戳的公开提交才能重新打开公开覆盖，包括当重复文本重用某条提示行时；私有轮次在时间戳并列时胜出。这些密钥和该位都不会发送给 PostHog。该 worker 使用现有的 30 秒同意缓存。遥测仍然尽力而为：退出选择会禁用分析，而在 rollup 刷新之前发生崩溃可能会丢失计数。此功能不会回填过去的版本。

错误跟踪¶

Claude-mem 会以 $exception 事件的形式将真实错误捕获到 PostHog Error Tracking。这是对旧有的仅白名单立场的刻意改变： 错误消息和堆栈跟踪是自由格式文本，因此属性白名单（只允许已知封闭集合的键）会把它们全部丢弃。相反，错误文本走一条独立的 先允许后脱敏 路径（src/services/telemetry/error-scrub.ts）：我们保留诊断文本，并积极剥离任何可能泄露 PII 或秘密的内容。

以下内容会保留（并已脱敏）：

• 错误类型（构造函数名称，如 TypeError），上限 100 字符。
• 错误消息，已脱敏且上限 500 字符。
• 堆栈跟踪——仅保留顶部 10 帧，每帧均已脱敏，总大小上限约 2KB。
• 一个 occurrence_count（当前窗口内该错误指纹触发了多少次）。

以下内容会从该文本中被脱敏掉（依次替换为 [REDACTED]）：

• 主目录（/Users/you → ~）——首先处理，这样嵌入在主目录路径中的用户名绝不会残留。
• 绝对文件系统路径 → 折叠为基名（POSIX、Windows 驱动器路径和 UNC 路径）——保留下“哪个文件”，但不保留目录树。
• URL / 连接字符串凭据和查询字符串——任何 scheme://…（http、ws、postgres、redis、mongodb+srv、amqp 等）中的 userinfo（user:pass@）以及 ?…/#… 都会被剥离，因此数据库连接字符串凭据和签名 URL 令牌都会失效。
• 电子邮件。
• API 令牌和密钥：带提供方前缀的密钥（sk-、phc_、ghp_、xoxb- 等）、Bearer 令牌、AWS 访问密钥 ID（AKIA…）、JWT、UUID、长 hex 块（24+ 字符）以及通用高熵令牌。
• IPv4 地址（会在网络错误中泄露的内部 IP/主机名）。

脱敏管道是纯函数且永不抛错的——恶意输入（null、循环引用、带有会抛出异常的 getter 的对象、200KB 的 blob）始终会产生安全且受限的结果，因为遥测绝不能破坏或阻塞 worker。在任何正则运行之前，原始输入会被硬性限制为 8KB（ReDoS 防御）。

速率限制。 每个错误指纹每 60 秒至多发送一条 $exception 事件。错误通过“类型 + 规范化消息模板 + 顶部堆栈帧”进行指纹识别，因此带有不同 ID/数字的“相同”错误风暴会被去重为一次发送，并附带发生次数。这同样适用于我们手动捕获和任何 SDK 自动捕获。（自动捕获在发送前会额外重新脱敏——posthog-node 从磁盘读取的原始源码上下文行会被删除，文件名会脱敏为基名。）

受同意机制约束，并带有独立的紧急停止开关。 错误捕获受常规遥测同意链约束（退出遥测也会禁用错误捕获）并受独立的 CLAUDE_MEM_TELEMETRY_ERRORS 开关约束——参见 如何退出。不会为 $exception 事件构建个人画像（$process_person_profile: false）。

历史回填¶

遥测比 claude-mem 本身上线得更晚，因此早于遥测的安装所拥有的活动，是实时事件从未见过的。升级后的第一次 worker 启动时，claude-mem 会执行一次一次性的遥测前历史回填——仅包含匿名计数，并与其它所有数据一样经过相同的白名单清理器：

与一切其它数据一样，这些仅包含计数和封闭集合值——绝不包含标题、提示、文件内容或项目名称。同样的匿名安装 UUID 标识它们，每个属性都会通过白名单清理器。

有几点值得了解：

• 它只运行一次。 成功发送后会写入一个完成标记（claude-mem 数据目录中的 backfill.json），从而防止回填再次运行。在运行成功之前不会写入标记，因此失败的尝试只会在下一次 worker 启动时重试。
• 它与实时遥测遵循完全相同的同意门控 — DO_NOT_TRACK、CLAUDE_MEM_TELEMETRY=0 以及 telemetry.json 中的 enabled: false 都会阻止它，并且调试模式会在不发送的情况下打印应有的载荷。
• 在升级后的第一次 worker 启动之前退出选择可完全阻止它。 在你选择退出期间不会发送任何内容，也不会写入标记——不过如果你之后重新选择加入，回填届时将运行。
• 位置是上传时的时间，而非历史时间。 PostHog 在摄入时推导出的粗略位置（见上文）反映的是事件上传地点，而不是这些历史日期所描述的你当时所在的位置。

哪些数据绝不会被收集¶

一个诚实坦白的例外：错误消息。 自错误追踪加入以来，经过脱敏处理的错误消息和堆栈跟踪确实会被收集（作为 $exception 事件）——这是对之前仅收集粗略分类数据的立场的刻意改变，并且它以同意为前提，配有独立的终止开关。原始路径、提示词、项目名称、源代码和模型输出仍然绝不被收集——它们在错误文本离开你的机器之前就已从中剥离。

分析属性在代码层面强制执行：它们经过白名单（只有收集了哪些数据表格中的字段得以保留），而非黑名单。每个白名单字段要么是数字、布尔值，要么是我们定义的封闭集合中的某个值——不存在任何能承载自由格式用户内容的分析字段。错误文本是唯一的自由格式路径，它改而经过单独的「先允许、后脱敏」清洗器处理。

如何选择退出（四种方式）¶

以下任意一种都能让遥测保持关闭——它们按此顺序检查，首个匹配项生效：

1. DO_NOT_TRACK——通用退出机制。设置 DO_NOT_TRACK=1 即可强制关闭遥测，覆盖所有其他设置。
2. CLAUDE_MEM_TELEMETRY=0（也接受 false / off）——环境变量覆盖。（CLAUDE_MEM_TELEMETRY=1 则相反，强制开启。）
3. 遥测配置文件——在 telemetry.json 中设置 enabled: false（见下文）。
4. CLI 命令：

   npx claude-mem telemetry disable
   

错误追踪的独立退出¶

错误追踪（携带已脱敏消息/堆栈的 $exception 事件）可以单独禁用，而无需关闭匿名分析：

CLAUDE_MEM_TELEMETRY_ERRORS=0   # also accepts 'false' / 'off'

这是唯一承载自由格式（脱敏）文本的遥测路径，一旦被摄取便是一道单向门，因此它为那些能接受匿名计数器、但不能接受错误文本的运营者提供了独立的终止开关。只要遥测同意处于开启状态，它默认就是开启的；上述四种退出方式中的任何一种也会隐式禁用它（没有同意 ⇒ 没有错误）。

随时查看当前状态——以及四层中是哪一层作出的决定：

npx claude-mem telemetry status

调试模式¶

想确切地看到将发送什么？设置：

CLAUDE_MEM_TELEMETRY_DEBUG=1

开启调试模式（且遥测已启用）时，每个本应发送的事件负载都会打印到 stderr，并且不会通过网络发送任何内容。

配置文件位置¶

同意设置与匿名安装 ID 存储在 claude-mem 数据目录内的 telemetry.json 中：

• 默认：~/.claude-mem/telemetry.json
• 如果你已覆盖数据目录，则为 $CLAUDE_MEM_DATA_DIR/telemetry.json

{
  "enabled": false,
  "installId": "<random UUID>",
  "decidedAt": "2026-06-09T21:00:00.000Z"
}

enabled 字段仅在你做出明确选择（安装程序中的提示、telemetry enable 或 telemetry disable）后才会存在。如果文件只有 installId，则表示未记录任何决定，此时适用默认值（开启）。删除该文件即可完全重置——下次使用时将生成全新的安装 ID。