lossless-context-mcp

lossless-context-mcp

Agent 上下文的飞行记录仪。 一份由钩子持续写入的记录，保存编码 Agent 看到的每个文件版本——这样压缩就不会摧毁工作集，子 Agent 群组也不必为相同文件重复付出 N 次成本，而且你之后还能证明模型具体看到了什么。

                      ┌──────────────────────┐
  ledger reads ──────▶│                      │──▶ RESTORE   working set survives /compact
  (read_file, MCP)    │   flight recorder    │──▶ PACKS     one cache-cached prefix for a fan-out fleet
  transcript sweeps ─▶│  (content-addressed  │──▶ RECEIPTS  signed, git-bound "what did it see"
  (native Read/Edit)  │   archive on disk)   │──▶ METERING  where the read tokens went, in dollars
                      └──────────────────────┘

直观演示

压缩会摧毁 Agent 的工作集。现在不会了——在 PreCompact 时进行扫描，之后注入清单，阻止盲目编辑，恢复工作集，然后允许编辑：

两个 Agent，一个文件——空中交通管制。 第二个 Agent 被中途拦下，并指出了肇事者：

这些录制中的每一行都是真实运行已发布代码的输出——演示由 docs/demo/make-demo.mjs 生成，它会驱动真实的钩子和服务，并呈现它们实际输出的内容。你可以亲自重新运行。

1. 恢复：压缩再也无法摧毁你的工作集

Claude Code 进行压缩时，典型上下文中大约三分之二是工具输出——主要是文件内容——而压缩会永久丢弃这些内容。随后模型就会手忙脚乱：重新读取它只记得一部分的文件，甚至更糟，根据已经不再拥有的内容进行猜测（#27242 就是相关诉求，获得了 80 个 👍）。

飞行记录仪会自动完成整个流程：

1. PreCompact — 扫描钩子解析会话记录，并归档会话接触过的每个文件（包括原生的 Read/Edit/Write，而不仅仅是 MCP 读取），然后写入按优先级排序的工作集清单。速度足够快，可以用于压缩流程——一次真实的 14 MB 会话记录仅用 361 ms 就完成扫描；你也可以测测自己的数据： node bench/sweep-bench.mjs <transcript.jsonl>。
2. SessionStart(compact) — 注入钩子将精简清单放回全新的上下文中：“你的工作集包含以下 12 个文件（已编辑的排在前面）；请恢复其中任何文件，而不是进行猜测。”
3. restore_context — 从当前磁盘状态重新输出工作集，并限制预算上限，同时标注模型上次看到文件之后发生的任何变更。

跨会话记忆工具（claude-mem 及同类工具）会总结发生过的事情，供下一次会话使用。这是与之互补的会话中层：精确恢复你刚才正在处理的文件版本。

2. 盲目编辑防护：将记录仪用作主动安全网

记录仪确切知道模型在当前上下文周期实际看到过哪些文件版本。PreToolUse 钩子利用这一点，在写入发生之前阻止两种最糟糕的编辑失败：

• 压缩后凭猜测编辑 — 模型在上下文压缩或重置后，没有重新读取文件就进行编辑，依据的是摘要中对内容的记忆。（没有文档说明，运行框架自身的先读取再编辑追踪机制能否在压缩后保留；而且新模型甚至可以编辑未读取的文件。）此类编辑会被拒绝，并向模型显示一行原因：先读取文件（或使用 restore_context），然后重试。 能自行修复——恰好只需额外读取一次。
• 基于过时版本编辑 — 文件在模型读取后，磁盘上的内容发生了变化（由另一个 Agent、你或格式化程序修改）。通过内容哈希进行比对，而不是根据修改时间猜测。此类编辑会被拒绝，并给出同样的重新读取指示。

按设计优先放行：有任何疑虑（会话记录无法解析、读取不完整、模型刚刚自行编辑的文件、超大文件）→ 编辑不受阻碍地继续。可随时通过 LOSSLESS_GUARD=off 禁用。

3. 协调：并发 Agent 的空中交通管制

在同一个仓库中运行两个 Agent 会话，却没有任何协调，它们就会互相覆盖：B 修改了 A 十分钟前读过的文件；A 根据过时的副本进行修改；合并结果一团糟，而双方都没察觉。市面上还没有能在本地协调这些操作的产品——但记录器已经知道每个会话中的 Agent 持有什么、正在编辑什么。v2 会让这些信息发挥作用：

• 检测正在进行的编辑 — 当一个 Agent 进程获准编辑时，它会向本地存在状态目录（~/.lossless-context/presence/，每个进程一个文件，无守护进程、无锁）发布意图。另一个 Agent 几秒后尝试编辑同一文件时，会被拒绝，并指出责任方：“Agent 会话 3f2a91b0 于 12 秒前开始编辑此文件，编辑可能尚未完成。” 同一会话的兄弟子 Agent 也适用。
• 检测跨会话的过期基准 — 当另一个会话已完成的编辑晚于你当前会话持有的版本，且你上次联系时没有留下可验证的哈希，编辑就会被拒绝，并提示重新读取。常规漂移检查触发时，原因现在会指出是谁修改了文件。
• 雷达 — coordination_status 会显示所有可见的 Agent 会话、它们编辑过的内容，以及哪些文件存在跨会话或正在进行的活动。

明确说明其局限：这只是建议机制，不是锁。未安装钩子的会话不可见；同一秒内的竞态仍可能发生；存在状态文件是未经身份验证的本地 JSON——任何本地进程都可以伪造文件，从而导致误拒绝（从结构上看，不会误放行；存在状态信息只能增加拒绝类别）。如果编辑意图随后在权限提示中被拒绝，该意图最长会保留 LOSSLESS_COORD_INTENT_SECS（90 s）后才过期。它能大幅缩小并发覆盖的时间窗口，但无法彻底消除，而且实际上能捕获多少问题尚未测量。LOSSLESS_COORD=off 可在不影响防护机制的情况下单独禁用协调功能。（防护机制的压缩跟踪以会话为范围；只有去重引擎使用机器级的全局 epoch 文件，跨会话更新该文件只会带来一次保守的完整重发。）

4. 内容包：不再为每个子 Agent 反复处理相同文件

令牌浪费主要发生在扇出任务中。对 195 次真实多 Agent 运行的测量显示：所有子 Agent Read 令牌中有 19.6% 是兄弟 Agent 对相同内容的重复读取（518 万 / 2640 万令牌）——每个兄弟 Agent 都从零开始，读取相同的 CLAUDE.md、相同的规范和相同的核心模块。

export_pack 会根据跨会话读取历史，为归档中稳定的热门文件排序，并将它们渲染为一个确定性区块，供自定义 Agent 类型的系统提示词使用。该区块是稳定前缀，因此整个 Agent 集群都能命中提供商的提示词缓存。在一次真实的审查扇出任务中，测得它比基线便宜 46.55%；而按任务注入同一内容包时，成本反而高出 19.6%（每个兄弟 Agent 都会将其写入缓存），因此工具会告诉你应该把它放在哪里。这两项数据都由外部人员在一个真实语料库上测得，并非通过本仓库中的测试工具得出——准确数值、方法和相关说明见 BENCHMARK.md。每次运行只生成一次内容包，并原样嵌入：排序依据实时读取历史，因此重复调用 export_pack 可能得到不同结果。

5. 追溯：Agent 当时看到了什么，才会那样做？

context_blame（也可通过 CLI 调用：lossless-context-mcp blame <path>）可以回答每份 Agent 事件报告都希望弄清的调试问题：对于指定文件，它会列出模型看到的每个内容版本（SHA-256 和 git blob SHA-1、首次 / 最后出现时间、捕获来源、会话），以及所选时刻上下文中的其他内容。当 Agent 做出错误修改时，你可以查询记录，而不是争论 Agent 的自述。

6. 收据：证明模型看到了什么，并与 git 绑定

可观测性供应商会将 Agent 读取的内容存入可变的跟踪记录库。没有人会为其签名或将其与仓库身份绑定——而且 Agent 的自我报告并非证据（可以问问那些遇到过 Agent 声称自己“已验证”某事，实际上却从未读取相关内容的人）。

context_receipt 会签发一份由 HMAC-SHA256 签名的证明：其中包含展示过的每个文件/视图、每个内容版本的 SHA-256、每个版本的 git blob SHA-1（因此任何拥有克隆仓库的验证者都可以检查 git cat-file -e <sha1>——该内容是否曾被提交？）、签发时的仓库 HEAD、交付类型、token 总数，以及一份明确说明其证明所覆盖捕获路径的 coverage 声明（mcp，以及启用 include_sweep 后的 transcript-sweep）。默认情况下，它使用与 trust-mcp 收据相同的密钥文件签名，因此一把密钥即可验证完整的证据链：Agent 看到了什么 + 它做了什么。

诚实说明其范围：收据仅证明通过账本和扫描流程的内容——绝不声称覆盖未经中介的路径，并会在自身的 coverage.note 中明确说明。

7. 计量（以及对节省 token 的现实检验）

context_stats 会显示会话中读取文件所消耗的 token 分布——按仓库、按文件统计，并以美元计价，使用真正的分词器进行计数。

现实检验：由于确实如此，这段说明从早期版本沿用至今： 作为会话内节省 token 的手段，在真实的 Claude Code 记录中，它的效果约为 0%（使用永不丢失引擎时为 +0.4%；原生文件状态缓存已经消除了可优化空间——完整数据见 BENCHMARK.md）。确实存在的节省来自跨 Agent 场景（见上文的包）。读取路径去重仍然保留，因为它经证实不会丢失信息，且绝不会带来负面影响——而不是因为它本身能为你节省多少 token。

安装（两条命令）

npm i -g lossless-context-mcp
lossless-context-mcp init        # wires all hooks into ~/.claude/settings.json
claude mcp add lossless-context --scope user -- lossless-context-mcp

init 具有幂等性（升级后可重新运行——它会更新路径，而不会重复添加），会先备份设置文件；若设置文件无法解析，则拒绝修改；也绝不会移除并非由它自身添加的钩子。--dry-run 可预览操作。它会配置：

• sweep-transcript.mjs（PreCompact + SessionEnd）——捕获工作集和精确版本；在 PreCompact 时递增去重纪元；绝不会阻止压缩。
• inject-manifest.mjs（SessionStart，匹配器 compact）——在压缩后注入恢复的工作集清单。
• reset-epoch.mjs（SessionStart）——确保新会话中的读取去重不会丢失信息。
• guard-edit.mjs（PreToolUse，Edit|Write|MultiEdit）——盲目编辑防护（设置 LOSSLESS_GUARD=off 可禁用，无需解除钩子）。

初始化后重启 Claude Code。没有这些钩子，所有功能仍可运行——只是会失去原生工具的自动捕获、压缩后的注入和防护；此时账本只会记录 MCP 读取。

工具

工具	功能
read_file(path, symbol?, lines?, force_full?)	无损读取：完整内容／未变标记／差异。可选查看单个 symbol 或 lines:"40-90"。拒绝读取二进制文件。
read_files(paths[], force_full?)	一次调用读取一组文件；单个文件出错不会导致整批失败。
working_set(limit?)	按热度排序的表格，列出记录器本次会话（以及最近 24h）掌握的信息，并标注与磁盘内容的过时情况。
restore_context(files?, budget_tokens?)	压缩后重新输出工作集——默认提供清单中的前 K 项，受预算限制，并标注变更。
export_pack(repo?, top?, budget_tokens?, days?)	根据跨会话读取历史生成确定性扇出上下文包，供 Agent 类型的系统提示词使用。
context_blame(path, at?, window_minutes?)	取证：模型看过的文件每个版本，以及某个时刻前后的共现上下文。也可在 Shell 中运行：lossless-context-mcp blame <path>。
coordination_status()	雷达：可见的 Agent 会话、近期编辑、跨会话文件和处理中文件。
outline(path)	文件的轻量结构图（仅声明）。
context_stats()	本次会话读取内容的 Token／费用明细。
context_receipt(artifact, include_sweep?)	经过签名、绑定 Git 且明确标示覆盖范围的上下文凭证。
verify_context_receipt(receipt, signature)	以恒定时间执行规范化验证。

隐私与存储

归档位于 ~/.lossless-context/archive（可通过 LOSSLESS_CONTEXT_DIR 覆盖）， 采用内容寻址，容量上限为 512 MiB（LOSSLESS_ARCHIVE_BYTES），并按 LRU 淘汰；事件 日志在 30 天后过期（LOSSLESS_EVENTS_DAYS）。任何内容都不会离开你的设备。 匹配机密模式的文件（.env*、密钥／证书、.ssh／.aws 路径、凭据—— 以及你自定义的 LOSSLESS_ARCHIVE_EXCLUDE glob）绝不会被存储。检查会同时涵盖 请求路径及其解析后的真实路径，因此指向机密文件的符号链接也无法绕过检查。对于排除的文件，只会记录路径、访问次数和时间戳 （不记录内容，也不记录哈希或大小等源自内容的元数据，因为这些信息可能帮助 离线确认低熵机密）。

为什么读取路径不会损害质量

只有在引擎能够证明模型仍保有相关内容时，才会暂缓提供内容或提供差异；此操作受上下文纪元限制（钩子会在压缩时递增纪元，因此压缩后的读取 始终提供完整内容）。一项包含 400 次随机操作的不变量测试断言，每次操作后模型可重建的视图都与磁盘上的实际内容一致。凡是无法证明的内容，都会完整发送。

客观限制

• 恢复操作提供的是当前磁盘状态（内容发生变化时会加注说明），而不是对话的时间机器；准确的历史版本保存在归档中，供凭证使用。
• 转录格式属于 Claude Code 内部格式，可能发生变化；扫描刻意分为两层（发现稳定表层信息＋尽力精确捕获），并且采用静默失败机制——格式变化只会降低捕获能力，不会中断会话。
• 凭证仅证明经由本工具处理的路径，并会明确说明这一点；凭证采用 HMAC（共享密钥），而非可由第三方验证的签名。如有需要，可在未来版本中考虑 Ed25519 凭证。
• Pack 的效果取决于提供商的提示词缓存和稳定前缀；46.55% 是针对一项实测工作负载的结果，并非保证。
• 符号提取采用启发式括号／缩进扫描，而非解析器（已评估 tree-sitter，但因 WASM／ABI 易出问题而暂缓使用）。

状态

v2.0.0 — 在完整的飞行记录器之上，新增协调平面：持久化的内容寻址归档、转录扫掠 + 清单注入钩子、工作集恢复、扇出包、绑定 Git 的回执 v2、一条命令即可运行的 init、盲改防护、上下文归因，以及跨 Agent 协调（进行中的意图、已落地编辑冲突、coordination_status 雷达）。121 项测试全部通过，包括无损性不变量；端到端冒烟测试覆盖扫掠 → 注入 → 恢复 → 防护 → 协调 → 回执；在真实数据上验证了真实转录扫掠和防护运行。MIT。