Sophon

Sophon

为 MCP Agent 提供确定性上下文压缩。一个 Rust 二进制文件。查询时无需 ML。基准测试可复现，采用真实数据测量。

Sophon 是一个为使用 Model Context Protocol 通信的 Agent 提供的确定性上下文层。它可以压缩提示词、对话记忆、代码摘要、文件增量和 Shell 输出——查询时无需嵌入模型、GPU 或 API 密钥。

单个 5.2 MB 的 Rust 二进制文件。 原生支持 MCP。精确匹配 cl100k_base。默认构建不需要 Python、ML 权重或网络连接。

---

30 秒了解它的功能

工具	解决的问题
compress_prompt	较长的结构化提示词 → 仅保留与查询相关的部分
compress_history	不断增长的对话 → 摘要 + 事实 + 最近对话窗口 + 可选检索
compress_output	Shell 标准输出/标准错误 → 21 种领域感知筛选器（git、cargo、docker、kubectl、JSON 等）
read_file_delta / write_file_delta	重新读取 + 编辑 → 仅处理差异，绝不读取整个文件
encode_fragments	重复的样板内容 → 单个令牌引用
update_memory	追加轮次 → 持久化为 JSONL + 增量滚动摘要
navigate_codebase	使用 tree-sitter / 正则表达式 + PageRank 生成仓库摘要，并按查询排序

总计 11 个 MCP 工具（下方有完整列表）。

---

真实数据 — 在本仓库自身的开发周期中测量

我们构建了四个独立基准测试，各自捕捉 Agent 工具流量中的不同部分。它们都会在操作者的机器上，使用本仓库的实际 Git 历史记录和工作树运行。任何人都可以通过 cargo build --release 逐字节复现结果。

维度	测量内容	节省比例	基准测试
历史记录	对真实提交运行 compress_history	94.6 %	real_session_capture.py
Shell	对真实 git/cargo/gh/ls 标准输出运行 compress_output	84.4 %	real_session_shell.py
文件读取	对真实 Rust / Python / Markdown / TOML 文件运行 compress_prompt	71.7 %	real_session_filereads.py
搜索	对真实 grep/find 模式运行 compress_output	79.5 %	real_session_search.py
🎯 加权综合（35/30/20/15）	典型 Agent 会话估算值	84.7 %	real_session_holistic.py

real_session_holistic.py 会使用 --json 运行全部四个子基准测试、解析结果并计算加权综合值。默认权重反映了本仓库观察到的情况；传入 --weights "history=0.4,..." 即可模拟你自己的工作负载。

Claude Opus 4.7 的美元成本节省

	每次会话节省
按常规输入定价（$15/MT）	$2.03
使用提示词缓存（25 轮读取，$1.50/MT）	$3.24

如果要按更便宜的层级重新计算价格，请将 --model sonnet 或 --model haiku 传给 real_session_deep_dive.py。

每个维度的不足之处（这是我们自己说的）

• history 只衡量 git 捕获的内容（提交 + 差异）——通常仅占真实会话工具流量的约 5–10 %。94.6 % 是上限，不是典型情况。
• shell 混合了压缩效果好的命令（git diff 为 95 %）和压缩效果不好的命令（gh repo view --json 反而增加 token，−9 %）。84.4 % 是真实场景的平均值，不是精心挑选的亮点。
• filereads 揭示了对原始源文件使用 compress_prompt 时，压缩依据的是预算上限，而非查询路由——同一文件搭配 3 个不同查询 → 输出完全相同。只有结构化输入（Markdown 标题、XML 标签）才会触发分段检测。基准测试中有内联说明。
• search 完全取决于你自己的仓库状态。没有 TODO 的仓库在 grep TODO 测试中结果为 0 %。

综合得出的 84.7 % 是基于四项真实测量值的线性加权平均粗略计算。**不是精挑细选的合成数据。**亲自运行基准测试验证即可。

其他可复现的基准测试（合成数据，符合预期）

测试	结果	基准测试
对 18 类命令使用 compress_output	90.1 % 加权总值	compress_output_per_command.py
25 轮合成 Claude Code 会话	节省 68.1 % 的会话 token	session_token_economics.py
对 22 种提示词形式使用 compress_prompt	平均 70.2 %，平均延迟 36 ms	prompt_compression_extended.py
针对“X 在哪里？”问题的代码检索	recall@3 = 70 %（grep 为 10 %，FULL 为 20 %）	repo_qa.py
与 LLMLingua-2 在结构化提示词上的对比	准确率提升 8.9 个百分点，延迟降低 35 倍	llmlingua_compare.py
Sophon + Anthropic 提示词缓存	在缓存基础上再节省 24 % token / 49 % $	sophon_plus_prompt_caching.py
Sophon + mem0	对检索出的记忆进一步节省	sophon_plus_mem0.py

---

为什么选择 Sophon——“置于 X 之前”

Sophon 不是记忆平台、检索系统、OCR 技术栈，也不是提供商侧缓存的替代品。它是一个确定性压缩器，可置于你已经在用的任何记忆 / 缓存 / 代码导航层之前，专门处理这些层无法压缩的 token。

置于 Anthropic / OpenAI 提示词缓存之前

提供商缓存处理请求中的静态部分——系统提示词、工具定义、复用的文档。它不会处理动态部分（不断增长的对话历史、工具输出）。Sophon 恰好压缩这一部分。两者可以无缝叠加。

在 25 轮 Claude 会话中，使用提示词缓存后再节省 24 % token / 49 % $——因为未缓存的动态块按缓存部分 10 倍的费率计费。参见 sophon_plus_prompt_caching.py。

置于 mem0 / Letta / Zep / Graphiti 之前

记忆系统负责检索相关记忆。Sophon 会在检索之后压缩发送给大模型的内容。如果 mem0 返回 2 kB 的原始记忆，compress_prompt 只保留查询实际引用的部分。

坦诚说明：对于非常短的检索内容块（< ~200 个 token），Sophon 的封装层会增加开销，此时应直接传递。基准测试如实报告了这一点。

置于 Claude Code / Cursor / Cline 之前

这是主要用例。每次重复读取文件都会变为 read_file_delta；每个 shell 命令输出都会经过 compress_output；每个重复的样板代码块都会获得一个 fragment_cache token。使用 sophon hook install --agent claude --global 即可透明安装。

置于 RAG 工作流之前

navigate_codebase 会生成 PageRank 排序的仓库摘要；否则，RAG 检索器需要耗费大量嵌入调用来构建该摘要。通过 Tree-sitter / 正则表达式提取 11 种语言的符号，耗时不到一秒。

何时不应使用 Sophon

• 长篇对话回忆率要求超过 80 % — Sophon 在 LOCOMO 上的回忆率最高约为 40 %，我们也不追求更高。可使用 mem0 / Letta / Zep 进行回忆，然后按需将其输出传入 Sophon。
• 对海量文档进行多跳推理 — 这类任务适合使用 HippoRAG 或 GraphRAG。
• OCR / PDF 布局 — 不在适用范围内。请先使用 Docling / Marker / Unstructured。
• 输入非常短（< ~200 个 token） — Sophon 的分段框架开销可能超过它节省的开销。

---

快速开始

通过 npm 安装（推荐）

npm install -g mcp-sophon
sophon doctor          # verify install + show config

postinstall 脚本会从 GitHub Releases 页面下载适用于你平台的预编译二进制文件。支持的平台：macOS arm64/x64、Linux arm64/x64、Windows x64。

从源代码构建

git clone https://github.com/lacausecrypto/mcp-sophon
cd mcp-sophon/sophon
cargo build --release -p mcp-integration       # ~5.2 MB binary

可选功能：

# 11-language tree-sitter AST extraction (~25 MB):
cargo build --release -p mcp-integration --features codebase-navigator/tree-sitter

# BGE-small semantic embedder (~34 MB), activate with SOPHON_EMBEDDER=bge:
cargo build --release -p mcp-integration --features bge

# All features (~42 MB):
cargo build --release -p mcp-integration --features "codebase-navigator/tree-sitter,bge"

需要 Rust 1.75+。

将其接入 MCP 客户端

大多数客户端都支持以下片段（Claude Desktop、Claude Code、Cursor、Cline、Continue）：

{
  "mcpServers": {
    "sophon": {
      "command": "sophon",
      "args": ["serve"]
    }
  }
}

运行 sophon doctor，即可打印适用于你客户端的配置路径。

推荐的运行时设置

# Persistent memory + on-disk retriever store + BM25+Hash hybrid
export SOPHON_MEMORY_PATH=~/.sophon/memory.jsonl
export SOPHON_RETRIEVER_PATH=~/.sophon/retriever
export SOPHON_HYBRID=1

sophon serve

CLI 快速使用

sophon exec -- cargo test                       # run + compress combined output
sophon compress-prompt --prompt ./system.txt --query "rust errors" --max-tokens 500
sophon hook install --agent claude --global     # transparent Claude Code integration
sophon stats --period session                   # token savings rollup

以编程方式使用（单次 JSON-RPC）

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"compress_prompt","arguments":{"prompt":"<rust>?: operator</rust><web>fetch()</web>","query":"rust errors","max_tokens":500}}}' \
  | sophon serve

---

二进制文件包含的内容

11 个 MCP 工具，全部使用 stdio：

工具	功能
compress_prompt	保留长提示词中与查询相关的部分
compress_history	对话摘要 + 事实 + 最近内容 + 可选检索
compress_output	清除命令 stdout/stderr 中的噪声（21 种领域过滤器 + JsonStructural）
navigate_codebase	对代码仓库进行 tree-sitter / regex 摘要，并按查询使用 PageRank 排序
update_memory	追加消息、以 JSONL 持久化、可选滚动摘要
read_file_delta	感知版本/哈希的文件读取，文件未变化 → 最小载荷
write_file_delta	以差异而非完整文件的形式发送编辑内容
encode_fragments / decode_fragments	检测重复的样板文本，并将其替换为 token
count_tokens	精确计算 cl100k_base token 数量
get_token_stats	汇总会话级别的节省量

不同功能集的二进制文件大小：

构建	大小
默认（regex 提取器、HashEmbedder）	5.2 MB
+ tree-sitter（11 种语言）	~25 MB
+ BGE 语义嵌入器	~34 MB
所有功能	~42 MB

MCP 协议： 2025-06-18。notifications/cancelled 会实际丢弃响应（自 v0.5.4 起）。结构化 JSON-RPC 错误代码（-32000..-32099 为 Sophon 保留）。无失败可能的分发器——格式错误的请求无法终止 stdio 循环。

---

文件系统限制（选择启用）

对于运行不可信提示词的客户端，请将 SOPHON_ALLOWED_ROOT 设置为一个现有工作区目录。read_file_delta、write_file_delta 和 navigate_codebase 会拒绝解析后位于此目录之外的路径。默认情况下，受信任的本地集成仍可不受限制地访问文件系统。这是路径级防护，并非经过强化的 OS 沙箱：虽然会检查已知符号链接和悬空符号链接，但能够修改目录链接的并发进程可能会在授权与后续文件操作之间替换路径（TOCTOU）。不要向能写入同一文件系统的恶意用户开放这些工具；如需严格的安全边界，请使用操作系统隔离。启用限制后，新文件必须位于现有父目录中。

配置

运行 sophon doctor，查看当前设置的所有 SOPHON_* 环境变量及其验证警告。完整目录（24 个标志）位于 runtime_flags.rs。以下是值得了解的标志：

标志	效果	开销
SOPHON_RETRIEVER_PATH=/dir	启用语义检索器（将分块存储在磁盘上）	~0
SOPHON_MEMORY_PATH=/file.jsonl	在多次 sophon serve 运行之间持久保存对话记忆	~0
SOPHON_HYBRID=1	通过 RRF 融合 BM25 稀疏词法检索与 HashEmbedder	~1 ms
SOPHON_ROLLING_SUMMARY=1	在 update_memory 时构建滚动摘要，而非查询时	将 LLM 调用移至摄取阶段
SOPHON_CHUNK_TARGET=500	更大的分块可保留跨句上下文	~0
SOPHON_EMBEDDER=bge	将 HashEmbedder 替换为 BGE-small（需要 --features bge）	启动时加载模型
SOPHON_LLM_CMD="claude -p --model haiku"	LLM shell 外部调用命令（配置后由摘要器使用）	每次调用都会启动子进程

已弃用的 v0.4.0 回忆率优化标志 — SOPHON_HYDE、SOPHON_FACT_CARDS、SOPHON_ENTITY_GRAPH、SOPHON_ADAPTIVE、SOPHON_LLM_RERANK、SOPHON_TAIL_SUMMARY、SOPHON_REACT、SOPHON_GRAPH_MEMORY、SOPHON_MULTIHOP_LLM — 这些标志用于追求 LOCOMO 回忆率，而我们已不再针对这一指标进行优化。它们仍可使用，但 sophon doctor 会对其发出提示。未来的主版本中将移除这些标志。

---

坦诚说明局限性

完整列表见 BENCHMARK.md § 8。主要内容：

• LOCOMO 对话回忆率上限约为 40%。 mem0 / HippoRAG 在查询时通过神经检索可达到 80-90%，而我们选择了确定性和低于 100 ms 的 p99 延迟。如果需要这样的回忆率，请在 Sophon 前接入 mem0。
• HashEmbedder 受关键词限制。 “favorite food”（最喜欢的食物）↔“weakness for ginger snaps”（对姜味脆饼毫无抵抗力）无法匹配。启用 BGE（SOPHON_EMBEDDER=bge）可实现语义回忆，但会增加 25 MB 二进制体积并需要加载模型。
• 不支持多模态内容摄取。 图像 / PDF / 音频不在支持范围内。请在上游使用 Docling / Marker / Unstructured 处理。
• 滚动摘要对较短的会话没有帮助。 未摘要的尾部内容在预算范围内时，滚动缓存不会产生作用。它适用于设置了 SOPHON_LLM_CMD 的长时间运行会话。
• 有些命令无法压缩。 gh repo view --json 会增加令牌数，git log --oneline 仅节省 0.4%。Sophon 的任务不是压缩本已精简的输出，而是压缩冗长且重复的输出。基准测试会明确指出这些不足。

---

项目结构

.
├── README.md           ← you are here
├── BENCHMARK.md        ← full per-section benchmark detail
├── CHANGELOG.md        ← version history + deprecated numbers
├── benchmarks/         ← reproducible scripts for every number above
├── npm/                ← npm wrapper package
└── sophon/crates/      ← 11-crate Rust workspace
    ├── prompt-compressor/    compress_prompt
    ├── memory-manager/       compress_history, update_memory, rolling summary
    ├── delta-streamer/       read/write_file_delta
    ├── fragment-cache/       encode/decode_fragments
    ├── semantic-retriever/   chunker + HashEmbedder + BM25 + entity graph
    ├── output-compressor/    21 command-aware filters + JsonStructural
    ├── codebase-navigator/   tree-sitter / regex + PageRank
    ├── cli-hooks/            transparent agent installer
    └── mcp-integration/      stdio server, async dispatch, cancellation

---

贡献

欢迎提交 PR。运行测试套件：

cd sophon && cargo test --workspace --lib --tests --exclude prompt-compressor   # 405 tests
cd sophon && cargo test --features codebase-navigator/tree-sitter               # +AST tests
cd sophon-py && .venv/bin/pytest tests/                                         # 4 Python tests

每项基准测试声明都可复现——相关脚本的链接见 BENCHMARK.md。如果某个数值在你的机器上无法复现，请提交 issue。

尤其欢迎：

• TypeScript 绑定（Python 绑定已包含在 sophon-py/ 中）
• gh 系列过滤器（gh run list、gh pr list、gh repo view --json）——基准测试表明这目前是一个不足之处
• SOPHON_EMBEDDER_CMD shell 外部调用插件模式（仿照 SOPHON_LLM_CMD），用于 Voyage / OpenAI / Cohere
• 针对热门开源仓库运行多仓库 real_session_holistic.py

---

许可证

MIT。参见 LICENSE。