token-compressor

token-compressor

在保留语义的同时，将大模型提示词的 Token 数减少 30–70%。

mcp-name: io.github.base76-research-lab/token-compressor

面向大模型工作流的语义提示词压缩。减少 40–60% 的 Token 用量，同时不丢失含义。

由 Base76 Research Lab 构建 —— 专注于认知 AI 架构的研究。

---

在线演示

Intent Compiler MVP 现已上线，并将本项目用于 idea -> spec -> compressed output 流程：

• 在线体验：https://intent-compiler-mvp.pages.dev
• 产品代码库：https://github.com/base76-research-lab/token-compressor

---

功能介绍

token-compressor 是一个两阶段流水线，会在提示词到达大模型之前对其进行压缩：

1. 大模型压缩 — 本地模型（通过 Ollama 运行的 llama3.2:1b）会将提示词改写为语义最精简的形式，同时保留所有条件和否定表述
2. 嵌入验证 — 原始文本与压缩文本嵌入的余弦相似度必须超过阈值（默认值：0.85）；否则会原样发送原文

结果：提示词更短、成本更低、意图不变。

Input prompt (300 tokens)
        ↓
  LLM compresses
        ↓
  Embedding validates (cosine ≥ 0.85?)
        ↓
  Pass → compressed (120 tokens)   Fail → original (300 tokens)

核心设计原则： 绝不牺牲条件性。如果提示词写着“仅当 Y 成立时才执行 X”，这一约束会在压缩后保留。

---

要求

• Python 3.10+
• 本地运行的 Ollama
• 拉取以下两个模型：

ollama pull llama3.2:1b
ollama pull nomic-embed-text

• Python 依赖项：

pip install ollama numpy

---

快速开始

from compressor import LLMCompressEmbedValidate

pipeline = LLMCompressEmbedValidate()
result = pipeline.process("Your prompt text here...")

print(result.output_text)   # compressed (or original if validation failed)
print(result.report())      # MODE / COVERAGE / TOKENS saved

结果对象：

字段	描述
output_text	要发送给大模型的文本
mode	compressed / raw_fallback / skipped
coverage	余弦相似度（0.0–1.0）
tokens_in	估算的输入 Token 数
tokens_out	估算的输出 Token 数
tokens_saved	差值

---

CLI 用法

echo "Your long prompt here..." | python3 cli.py

输出：压缩后的文本写入 stdout，统计信息写入 stderr。

---

Claude Code 钩子（推荐配置）

在 ~/.claude/settings.json 的 hooks → UserPromptSubmit 下添加：

{
  "type": "command",
  "command": "echo \"${CLAUDE_USER_PROMPT:-}\" | python3 /path/to/token-compressor/cli.py > /tmp/compressed_prompt.txt 2>/tmp/compress.log || true"
}

每次提交提示词时都会运行，并将压缩后的版本写入临时文件；随后可通过第二个钩子或 MCP 服务将其注入上下文。

---

MCP 服务

MCP 服务将压缩功能作为工具提供，可供 Claude Code 和任何兼容 MCP 的客户端调用。

安装：

pip install token-compressor-mcp

工具： compress_prompt

• 输入：text（字符串）
• 输出：压缩后的文本 + 统计信息页脚

Claude Code MCP 配置（~/.claude/settings.json）：

{
  "mcpServers": {
    "token-compressor": {
      "command": "uvx",
      "args": ["token-compressor-mcp"]
    }
  }
}

或从源代码运行：

{
  "mcpServers": {
    "token-compressor": {
      "command": "python3",
      "args": ["-m", "token_compressor_mcp"],
      "cwd": "/path/to/token-compressor"
    }
  }
}

---

配置

pipeline = LLMCompressEmbedValidate(
    threshold=0.85,          # cosine similarity floor (lower = more aggressive)
    min_tokens=80,           # skip pipeline below this (not worth compressing)
    compress_model="llama3.2:1b",
    embed_model="nomic-embed-text",
)

---

工作原理

阶段 1 — 大模型压缩

压缩提示词会指示模型：

• 保留所有条件（if、only if、unless、when、but only）
• 保留所有否定表述
• 删除填充内容、模棱两可的表述和冗余内容
• 将长度压缩至原文的 40–60%

阶段 2 — 嵌入验证

使用 nomic-embed-text 计算原文与压缩文本之间的余弦相似度。如果相似度低于阈值，则原样返回原文。这可防止含义在不知不觉中丢失。

---

结果

在瑞典语和英语提示词、技术文本及自然语言文本上进行了测试：

输入	输入 Token 数	输出 Token 数	节省比例
研究摘要（EN）	89	38	57%
会话意图（SV）	32	18	44%
技术指令	47	22	53%
短命令（<80t）	—	—	已跳过

---

研究背景

此工具实现了以下论文中的架构：

Wikström, B. (2026). 当对齐降低不确定性：认识论方差坍缩及其对元认知 AI 的影响。 DOI：10.5281/zenodo.18731535

这是 Base76 Research Lab 认识论 AI 基础设施工具链的一部分。

---

许可证

MIT — Base76 Research Lab，瑞典