densely

densely

面向大模型的无损上下文压缩。 将任意文本打包成少 2x–8x token 的形式，并保证能够逐字节精确还原——每次解压都会通过 sha256 验证。

MIT 许可，永久免费。（面向团队的托管版本即将推出—— 候补名单。）

一个 o200k token 最多可承载约 17.6 bit 信息，但典型代码中每个 token 仅承载约 5–6 bit。densely 会回收这部分差值：

text -> lzma -> 16-bit chunks -> 65,536 single-token English words

每个载体词（" the"、" of" 等）恰好占用 1 个 token——o200k 预分词器不会跨词边界合并——因此载荷中的每个 token 都承载 2 字节的压缩数据（理论可用的约 17.6 bit 中的 16 bit，即通道容量的 91%）。

基准测试

运行 python3 bench.py 复现（固定种子，标准库代码样本）：

场景	后端	Token（o200k）	比率	节省
代码（argparse.py + densely）	lzma	21,659 → 10,726	2.02x	50.5%
代码（相同样本）	neural	21,659 → 2,538	8.53x	88.3%
模型从未见过的代码	neural	3,433 → 472	7.27x	86.3%
JSON（代码搜索，100 个结果）	lzma	15,465 → 1,995	7.75x	87.1%
日志（SRE 事件，约 1600 行）	lzma	117,766 → 16,962	6.94x	85.6%

神经网络后端（--backend neural、python3 bench.py --neural）使用 Qwen2.5-Coder-0.5B 的下一个 token 概率驱动整数算术编码器，并采用 NNCP 风格的分段批处理。88.3% 的结果受益于模型在训练期间见过 Python 标准库；86.3% 这一行测的是本仓库自己的源代码——这些代码在 2026-08-08 之前尚不存在——这是衡量新代码的真实数据（约 0.56 bit/字节）。

基于真实数据的测量结果

使用同一套流程处理未经我们筛选的数据：本仓库自己的源代码、已安装的 pip 模块、真实 macOS /var/log/install.log 的一段内容、真实的 package-lock.json，以及 npm 注册表中 express 的实时响应。 使用 tiktoken 在本地统计 o200k；通过 Anthropic 自己的 count_tokens 端点统计 Claude（Sonnet 5，已校准并扣除请求开销），使用 claude1 字母表。每一行数据都经过往返验证，确保逐字节精确还原。

数据	大小	o200k 原始 → 载荷	节省	Claude 原始 → 载荷	节省
本仓库自己的代码	25 KB	7,008 → 4,254	39.3%	10,724 → 6,811	36.5%
已安装的 pip 模块（factory.py）	32 KB	6,332 → 3,956	37.5%	10,625 → 6,334	40.4%
真实系统日志（install.log）	195 KB	65,684 → 4,204	93.6%	104,328 → 6,732	93.5%
真实 package-lock.json	27 KB	11,421 → 3,690	67.7%	15,743 → 5,910	62.5%
npm 注册表实时 JSON（express）	195 KB	76,167 → 12,293	83.9%	113,444 → 19,672	82.7%

作为比较，Headroom 报告称，编码 Agent 可节省 15–20%，JSON 可节省 60–95%——这是通过从上下文中删除内容实现的，原始内容则存放在带 TTL 的本地缓存中。densely 会将完整数据保留在上下文中，无需外部存储，也不会过期，并且可以逐字节还原。

低于数据熵的无损压缩在数学上是不可能的（Shannon；另见提示词压缩的基本限制）——在这一界限内，densely 已接近确定性、仅依赖 CPU 的方法所能达到的实际极限。

用法

pip install "densely[mcp]"
# extras: [neural] for the neural backend (torch + transformers)

densely compress  big_context.txt -o payload.dense
densely compress  src.py -o payload.dense --backend neural
densely decompress payload.dense   -o restored.txt   # byte-identical
densely stats     file1.py file2.json                # token savings

库：

from densely import compress, decompress

payload = compress(text)        # ~2x-8x fewer tokens
assert decompress(payload) == text  # always true, sha256-checked

CLI 中的 compress 会在写入输出前自行验证往返结果； 遇到任何损坏或哈希不匹配时，decompress 会抛出 ValueError。

在 Claude Code / Cursor 中使用（MCP）

# Claude Code
claude mcp add --scope user densely -- "$(which densely-mcp)"

# Cursor (~/.cursor/mcp.json) and other MCP clients
{"mcpServers": {"densely": {"command": "/absolute/path/to/densely-mcp"}}}

三个工具：

• compress_file(path) — Agent 调用此工具，而不是读取大型日志/JSON/转储文件：获取预览 + 密集载荷，所需令牌数减少 2 到 8 倍。
• compress_text(text) — 对已获取的大型工具输出执行相同操作。
• expand(payload | payload_file, start_line, end_line) — 精确还原原始内容，并通过 sha256 验证；行范围让 Agent 只需为所需片段付费。

每次压缩还会在原文件旁写入一个 .dense 伴随文件——这是一个纯文本文件，你可以提交、分发或归档；没有缓存，没有 TTL，也没有过期之说。较小的载荷还会以内联形式返回。这对上下文压缩很重要：压缩摘要会替换旧的对话内容，因此单独的内联载荷可能会在摘要中被概括掉；但磁盘上的伴随文件（以及会保留在摘要中的文件路径）不会。如果你直接使用 Anthropic 的 compaction API beta，请将以下内容添加到 instructions，以确保载荷引用原样保留：

在摘要中原样保留任何密集载荷引用（以 .dense 结尾的路径，或以 DENSE1/DENSE2 开头的行）。编写此摘要时不要调用任何工具。

自动模式（钩子）

无需费力即可节省令牌：PostToolUse 钩子会实时压缩每个大型工具输出（Bash 输出、读取非代码文件的结果、令牌数 >= 5,000）——Agent 会看到预览 + 统计信息，仍可通过搜索/展开获取精确内容，并且每次替换都会记录在节省情况账本中（使用 stats 工具查看，或查看每次替换中显示的累计总数）。

添加到 ~/.claude/settings.json（使用绝对路径——钩子在你的 shell PATH 之外运行）：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Read|Bash",
      "hooks": [{
        "type": "command",
        "command": "/absolute/path/to/densely-hook",
        "timeout": 30
      }]
    }]
  }
}

（安装后运行 which densely-hook 可获取绝对路径——钩子在你的 shell PATH 之外运行，因此只能使用绝对路径。）

使用 DENSELY_HOOK_MIN_TOKENS 调整（默认值为 5000）。Agent 正在编辑的代码文件不会被处理。

何时能节省令牌（何时不能）

Agent 会话每轮都会将完整历史记录重新发送到 API，因此上下文中的任何内容都会被反复计费。densely 对各类内容的处理效果如下：

上下文中的内容	节省比例	原因
Agent 正在积极编辑的代码	不节省——不要压缩	Agent 必须读取这些代码；载荷无法阅读
参考代码（读取一次后，为了“以防万一”而保留）	20–40%	精确副本仍然很精简；需要时用 expand 展开某个行范围
工具输出：日志、JSON、转储	78–87%	Agent 无需读取全部 1,500 行——预览 + 按需展开即可满足需要
必须在压缩后保留的内容	间接节省	载荷会原样通过压缩；摘要则不会

关于提示词缓存的说明：缓存历史记录的成本更低，但上下文窗口大小不变——densely 主要为你腾出空间，其次才是省钱。

与其他方案比较

主要竞品各有不同的取舍（数据来自各项目自行发布的基准测试）：

	densely	Headroom	claw-compactor
方法	熵编码 -> 单令牌载体	有损筛选，输出可供模型读取	14 个可读转换阶段（其中 2 个有损）
精确还原	始终可还原：通过 sha256 验证，在对话中完成	TTL 缓存，按需检索	LRU「RewindStore」，未说明是否验证
日志	85.6%	~92%（有损）	24.1%
JSON	87.1%（无损）	60–95%（有损）	81.9%（通过有损抽样）
代码（积极使用中）	不压缩——这是有意设计	15–20%（AST 骨架）	25%
模型读取输出	否（使用搜索/展开工具）	是	是
Agent 集成	MCP + 钩子 + 技能（Claude Code、Cursor）	代理 + 封装 + MCP	仅命令行

理念各异：通过静默降级实现最大节省，还是保证精确，否则宁可不做。可读的有损工具适用于模型必须持续读取的内容；当数据绝不能出错，且必须经受上下文压缩、导出和机器迁移时，densely 更合适。两者可以同时使用。

坦诚说明

• 载荷不可读——无论对人类还是模型而言都是如此。它看起来像一串随机的英文单词。可将其用作高密度载体，承载精确数据（聊天记录、工具输出、源文件），同时附上可读摘要；需要精确内容时，再通过工具调用将其展开。
• 节省量取决于冗余度：高度重复的数据（JSON、日志）可压缩 7 倍以上，密集的散文约为 1.5–2 倍，已压缩或随机数据则约为 0%（载荷最多只会比原始输入多几个标头 token——发布前请检查 stats）。
• 密度取决于分词器；还原始终是逐字节精确的。目前提供两种字母表：o200k（65,536 个单词，在 OpenAI o200k 上每个 token 恰为 16 位）和 claude1（1,024 个单词，在 Claude Sonnet 5 / Opus 5 / Fable 5 上每个 token 恰为 10 位——通过 count_tokens API 实测采集，因为 Anthropic 的词汇表并未公开）。MCP 服务和 hook 默认使用 claude1；CLI 默认使用 o200k（可通过 --alphabet / DENSELY_ALPHABET 覆盖）。在一个 172 KB 的日志上用 Sonnet 5 的 count_tokens 测得：原始内容为 93,117 个 token，claude1 载荷为 25,904 个（节省 72.2%；o200k 字母表在该数据上的表现仅为 47.8%）。使用 python3 tools/calibrate.py 验证任意字母表与任意目标的兼容性；使用 tools/build_alphabet.py 采集新的字母表。
• 何时不需要它（一位 Reddit 用户提出了中肯的看法）：如果你能端到端地控制自己的 Agent 框架，就可以自行实现同样的模式——将大型输出用 zstd/lzma 压缩到文件中，为 Agent 提供搜索工具，并让载荷不进入模型输入。densely 将这种架构打包在一起（另加 sha256 验证、按行检索，以及面向必须留在提示词内部的子集的分词器专属载体字母表——这些内容必须原样保留以应对上下文压缩，或随导出的会话一起传递）。它在封闭式框架（Claude Code、Cursor）、临时沙盒，以及任何“可靠磁盘 + grep”无法触及的地方都能发挥价值。
• 神经网络后端注意事项：速度较慢（约 85 KB 的代码在 Apple Silicon 上需要几分钟，而 lzma 只需几毫秒），且需要 torch + 首次使用时下载约 1 GB 的模型。只有在解压运行的模型/软件栈与压缩时相同时，还原才能做到逐位精确——因此，compress(backend="neural") 会在返回前验证完整的往返过程，并在出现任何不匹配时静默回退到 lzma。100% 的保证绝不会依赖神经网络路径。

Densely Pro（即将推出）

该库采用 MIT 许可，且会一直免费。我们正在为生产环境中运行 Agent 的团队构建一个托管层：

• 云端神经网络压缩——无需本地 GPU，即可将代码压缩至 86%
• 托管代理——无需修改代码即可节省用量
• 团队仪表盘——按 Agent、按天统计 token 节省量，并以美元显示
• 跨机器载荷——在 CI 中压缩，可在任何地方展开

加入候补名单 →（按早期访问顺序提供 + 创始用户价格，不会突然毁约——该库仍采用 MIT 许可）

路线图

• 实现神经网络后端的跨机器确定性（整数/定点推理，或可容忍不匹配的编码器），使在一台机器上压缩的载荷可在另一台机器上解压。
• 通过 llama.cpp 使用更大/更快的模型，以更高速度获得更好的压缩比。

测试

python3 -m pytest tests/test_core.py tests/test_mcp.py   # fast suites
python3 -m pytest tests/test_neural.py                   # slow (~1 min): real LLM round trips

快速测试套件：逐字节精确往返（Unicode、CJK、emoji、随机字节、类似载荷的输入）、篡改检测、载体字母表密度。 神经网络测试套件：单段和多段往返、无静默回退、优于 lzma 检查。