{
"markdown": "# Sophon\n\n> **Deterministic context compression for MCP agents.** One Rust binary. Zero ML at query time. Reproducible benchmarks, real-data measurements.\n\n[](https://www.npmjs.com/package/mcp-sophon)\n[](https://www.npmjs.com/package/mcp-sophon)\n[](https://github.com/lacausecrypto/mcp-sophon/releases)\n[](https://github.com/lacausecrypto/mcp-sophon/actions/workflows/ci.yml)\n[](./LICENSE)\n[](https://www.rust-lang.org)\n[](https://modelcontextprotocol.io)\n[](./BENCHMARK.md)\n\nSophon is a deterministic context layer for agents speaking the Model Context Protocol. It compresses prompts, conversation memory, code digests, file deltas, and shell output — without an embedding model at query time, without a GPU, and without API keys.\n\n**Single 5.2 MB Rust binary.** MCP-native. `cl100k_base`-accurate. Default build pulls no Python, no ML weights, no network.\n\n---\n\n## What it does, in 30 seconds\n\n| Tool | What it solves |\n|---|---|\n| `compress_prompt` | Long structured prompt → keep only sections relevant to the query |\n| `compress_history` | Growing conversation → summary + facts + recent window + optional retrieval |\n| `compress_output` | Shell stdout/stderr → 21 domain-aware filters (git, cargo, docker, kubectl, JSON, …) |\n| `read_file_delta` / `write_file_delta` | Re-reads + edits → diffs only, never the whole file |\n| `encode_fragments` | Repeated boilerplate → single token reference |\n| `update_memory` | Append turn → JSONL persist + incremental rolling summary |\n| `navigate_codebase` | Repo digest with tree-sitter / regex + PageRank, ranked by query |\n\n11 MCP tools total ([full table below](#what-the-binary-ships)).\n\n---\n\n## Real numbers — measured on this repo's own dev cycle\n\nWe built four independent benches that each capture a different chunk of an agent's tool traffic. All four run against this repo's actual git history + working tree on the operator's machine. **Reproducible byte-for-byte** by anyone with `cargo build --release`.\n\n| Dimension | What it measures | Saved | Bench |\n|---|---|---|---|\n| **history** | `compress_history` over real commits | **94.6 %** | [`real_session_capture.py`](./benchmarks/real_session_capture.py) |\n| **shell** | `compress_output` on real `git`/`cargo`/`gh`/`ls` stdout | **84.4 %** | [`real_session_shell.py`](./benchmarks/real_session_shell.py) |\n| **filereads** | `compress_prompt` on real Rust / Python / Markdown / TOML files | **71.7 %** | [`real_session_filereads.py`](./benchmarks/real_session_filereads.py) |\n| **search** | `compress_output` on real `grep`/`find` patterns | **79.5 %** | [`real_session_search.py`](./benchmarks/real_session_search.py) |\n| **🎯 Weighted blend** (35/30/20/15) | typical agent session estimate | **84.7 %** | [`real_session_holistic.py`](./benchmarks/real_session_holistic.py) |\n\n`real_session_holistic.py` runs all four sub-benches with `--json`, parses them, and produces the weighted blend. Default weights reflect this repo's observed shape; pass `--weights \"history=0.4,...\"` to model your own workload.\n\n### USD economy on Claude Opus 4.7\n\n| | Saved per session |\n|---|---|\n| **Naive input pricing** ($15/MT) | **$2.03** |\n| **With prompt caching** (25-turn reads at $1.50/MT) | **$3.24** |\n\n> Pass `--model sonnet` or `--model haiku` to [`real_session_deep_dive.py`](./benchmarks/real_session_deep_dive.py) if you're re-pricing for a cheaper tier.\n\n### Where each dimension falls short (we say it ourselves)\n\n- **history** measures only what `git` captures (commits + diffs) — typically ~5-10 % of a real session's *tool traffic*. The 94.6 % is the **upper bound**, not the typical case.\n- **shell** mixes commands that compress well (`git diff` 95 %) with commands that don't (`gh repo view --json` *adds* tokens, **−9 %**). 84.4 % is a real-world average, not a curated highlight.\n- **filereads** uncovered that `compress_prompt` on raw source files compresses by budget cap, not by query routing — same file with 3 different queries → identical output. Section detection only fires on structured input (Markdown headers, XML tags). Documented inline in the bench.\n- **search** depends entirely on YOUR repo's state. A repo with no TODOs gets 0 % on `grep TODO`.\n\nThe blended 84.7 % is napkin-math from a linear weighted average across four real measurements. **Not a cherry-picked synthetic.** Run the benches yourself to verify.\n\n### Other reproducible benchmarks (synthetic, on-thesis)\n\n| Test | Result | Bench |\n|---|---|---|\n| `compress_output` across 18 command families | **90.1 %** weighted aggregate | [`compress_output_per_command.py`](./benchmarks/compress_output_per_command.py) |\n| 25-turn synthetic Claude Code session | **68.1 %** session tokens saved | [`session_token_economics.py`](./benchmarks/session_token_economics.py) |\n| `compress_prompt` across 22 prompt shapes | **70.2 %** mean, **36 ms** mean latency | [`prompt_compression_extended.py`](./benchmarks/prompt_compression_extended.py) |\n| Code retrieval on \"where is X?\" questions | **recall@3 = 70 %** (vs grep 10 %, FULL 20 %) | [`repo_qa.py`](./benchmarks/repo_qa.py) |\n| vs LLMLingua-2 on structured prompts | **+8.9 pt accuracy at 35× lower latency** | [`llmlingua_compare.py`](./benchmarks/llmlingua_compare.py) |\n| **Sophon + Anthropic prompt caching** | **+24 % tokens / +49 % $** on top of caching | [`sophon_plus_prompt_caching.py`](./benchmarks/sophon_plus_prompt_caching.py) |\n| **Sophon + mem0** | Additional savings on retrieved memories | [`sophon_plus_mem0.py`](./benchmarks/sophon_plus_mem0.py) |\n\n---\n\n## Why Sophon — \"in front of X\"\n\nSophon is **not** a memory platform, a recall system, an OCR stack, or a replacement for provider-side caching. It's a **deterministic compressor that slots in front of** whatever memory / cache / code-nav layer you already use, and attacks the tokens those layers can't.\n\n### In front of Anthropic / OpenAI prompt caching\n\nProvider caching handles the **static** half of a request — system prompt, tool definitions, reused documents. It doesn't touch the dynamic half (growing conversation history, tool outputs). Sophon compresses exactly that half. The two stack cleanly.\n\n> **+24 % tokens / +49 % $** saved on top of prompt caching on a 25-turn Claude session — because the uncached dynamic block is billed at 10× the cached rate. See [`sophon_plus_prompt_caching.py`](./benchmarks/sophon_plus_prompt_caching.py).\n\n### In front of mem0 / Letta / Zep / Graphiti\n\nMemory systems retrieve the right memories. Sophon shrinks what gets sent to the LLM **after** retrieval. If mem0 returns 2 kB of raw memories, `compress_prompt` keeps only the sections the query actually references.\n\n> Honest caveat: on very short retrieved blocks (< ~200 tokens) Sophon's wrapper adds overhead and you should pass through. The bench reports this directly.\n\n### In front of Claude Code / Cursor / Cline\n\nPrimary use case. Every repeat file read becomes a `read_file_delta`; every shell command output goes through `compress_output`; every repeated boilerplate block gets a `fragment_cache` token. Install transparently with `sophon hook install --agent claude --global`.\n\n### In front of a RAG pipeline\n\n`navigate_codebase` produces a PageRanked repo digest that a RAG retriever would otherwise spend expensive embedding calls to build. Tree-sitter / regex symbol extraction over 11 languages, sub-second.\n\n### When NOT to use Sophon\n\n- **Long-form conversational recall above 80 %** — Sophon caps at ~40 % on LOCOMO and we don't chase it. Run [mem0](https://github.com/mem0ai/mem0) / [Letta](https://github.com/letta-ai/letta) / [Zep](https://github.com/getzep/zep) for recall, then optionally pipe their output through Sophon.\n- **Multi-hop reasoning on massive documents** — that's [HippoRAG](https://github.com/OSU-NLP-Group/HippoRAG) or [GraphRAG](https://github.com/microsoft/graphrag).\n- **OCR / PDF layout** — out of scope. Use [Docling](https://github.com/docling-project/docling) / Marker / Unstructured upstream.\n- **Very small inputs (< ~200 tokens)** — Sophon's section scaffolding can cost more than it saves.\n\n---\n\n## Quick start\n\n### Install via npm (recommended)\n\n```bash\nnpm install -g mcp-sophon\nsophon doctor # verify install + show config\n```\n\nThe postinstall script downloads the right prebuilt binary for your platform from the [GitHub Releases](https://github.com/lacausecrypto/mcp-sophon/releases) page. Supported: macOS arm64/x64, Linux arm64/x64, Windows x64.\n\n### Build from source\n\n```bash\ngit clone https://github.com/lacausecrypto/mcp-sophon\ncd mcp-sophon/sophon\ncargo build --release -p mcp-integration # ~5.2 MB binary\n```\n\nOptional features:\n\n```bash\n# 11-language tree-sitter AST extraction (~25 MB):\ncargo build --release -p mcp-integration --features codebase-navigator/tree-sitter\n\n# BGE-small semantic embedder (~34 MB), activate with SOPHON_EMBEDDER=bge:\ncargo build --release -p mcp-integration --features bge\n\n# All features (~42 MB):\ncargo build --release -p mcp-integration --features \"codebase-navigator/tree-sitter,bge\"\n```\n\nRequires Rust 1.75+.\n\n### Wire it into an MCP client\n\nMost clients accept this snippet (Claude Desktop, Claude Code, Cursor, Cline, Continue):\n\n```json\n{\n \"mcpServers\": {\n \"sophon\": {\n \"command\": \"sophon\",\n \"args\": [\"serve\"]\n }\n }\n}\n```\n\nRun `sophon doctor` to print the right config path for your client.\n\n### Recommended runtime setup\n\n```bash\n# Persistent memory + on-disk retriever store + BM25+Hash hybrid\nexport SOPHON_MEMORY_PATH=~/.sophon/memory.jsonl\nexport SOPHON_RETRIEVER_PATH=~/.sophon/retriever\nexport SOPHON_HYBRID=1\n\nsophon serve\n```\n\n### Quick CLI\n\n```bash\nsophon exec -- cargo test # run + compress combined output\nsophon compress-prompt --prompt ./system.txt --query \"rust errors\" --max-tokens 500\nsophon hook install --agent claude --global # transparent Claude Code integration\nsophon stats --period session # token savings rollup\n```\n\n### Programmatic (one-shot JSON-RPC)\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"compress_prompt\",\"arguments\":{\"prompt\":\"?: operatorfetch()\",\"query\":\"rust errors\",\"max_tokens\":500}}}' \\\n | sophon serve\n```\n\n---\n\n## What the binary ships\n\n**11 MCP tools, all stdio:**\n\n| Tool | What it does |\n|---|---|\n| `compress_prompt` | Keep query-relevant sections of a long prompt |\n| `compress_history` | Summary + facts + recent + optional retrieval over the conversation |\n| `compress_output` | Strip noise from command stdout/stderr (21 domain filters + JsonStructural) |\n| `navigate_codebase` | tree-sitter / regex digest of a repo, PageRanked by query |\n| `update_memory` | Append messages, JSONL persist, optional rolling summary |\n| `read_file_delta` | Version/hash-aware file read, unchanged → minimal payload |\n| `write_file_delta` | Send edits as diffs, not full files |\n| `encode_fragments` / `decode_fragments` | Detect repeated boilerplate, swap with tokens |\n| `count_tokens` | `cl100k_base`-accurate token count |\n| `get_token_stats` | Session-level savings rollup |\n\n**Binary sizes by feature set:**\n\n| Build | Size |\n|---|---|\n| Default (regex extractors, HashEmbedder) | **5.2 MB** |\n| + tree-sitter (11 languages) | ~25 MB |\n| + BGE semantic embedder | ~34 MB |\n| All features | ~42 MB |\n\n**MCP protocol:** `2025-06-18`. `notifications/cancelled` actually drops the response (since v0.5.4). Structured JSON-RPC error codes (`-32000..-32099` reserved for Sophon). Infallible dispatcher — a malformed request can't kill the stdio loop.\n\n---\n\n## Configuration\n\nRun **`sophon doctor`** to see every `SOPHON_*` env var currently set with validation warnings. Full catalogue (24 flags) lives in [`runtime_flags.rs`](./sophon/crates/mcp-integration/src/runtime_flags.rs). The flags worth knowing:\n\n| Flag | Effect | Cost |\n|---|---|---|\n| `SOPHON_RETRIEVER_PATH=/dir` | Activate the semantic retriever (chunk store on disk) | ~0 |\n| `SOPHON_MEMORY_PATH=/file.jsonl` | Persistent conversation memory across `sophon serve` runs | ~0 |\n| `SOPHON_HYBRID=1` | BM25 sparse-lexical + HashEmbedder fused via RRF | ~1 ms |\n| `SOPHON_ROLLING_SUMMARY=1` | Build rolling summary at `update_memory` time, not at query time | LLM call moved to ingest |\n| `SOPHON_CHUNK_TARGET=500` | Bigger chunks preserve cross-sentence context | ~0 |\n| `SOPHON_EMBEDDER=bge` | Swap HashEmbedder for BGE-small (needs `--features bge`) | model load at startup |\n| `SOPHON_LLM_CMD=\"claude -p --model haiku\"` | LLM shell-out command (used by summarizer when configured) | per-call subprocess |\n\n**Deprecated v0.4.0 recall-chasing flags** — `SOPHON_HYDE`, `SOPHON_FACT_CARDS`, `SOPHON_ENTITY_GRAPH`, `SOPHON_ADAPTIVE`, `SOPHON_LLM_RERANK`, `SOPHON_TAIL_SUMMARY`, `SOPHON_REACT`, `SOPHON_GRAPH_MEMORY`, `SOPHON_MULTIHOP_LLM` — chase LOCOMO recall, an axis we no longer optimise. Still functional but `sophon doctor` flags them. Removed in a future major.\n\n---\n\n## Honest limitations\n\nThe full list lives in [BENCHMARK.md § 8](./BENCHMARK.md#-8--limitations). Headlines:\n\n- **LOCOMO conversational recall caps at ~40 %.** mem0 / HippoRAG hit 80-90 % with neural retrieval at query time — we chose determinism + sub-100 ms p99 instead. **Pipe mem0 in front of Sophon if you need that recall.**\n- **HashEmbedder is keyword-bound.** \"favorite food\" ↔ \"weakness for ginger snaps\" doesn't match. Activate BGE (`SOPHON_EMBEDDER=bge`) for semantic recall — costs +25 MB binary + model load.\n- **No multimodal ingestion.** Images / PDFs / audio out of scope. Run Docling / Marker / Unstructured upstream.\n- **Rolling summary doesn't help on small sessions.** When the un-summarised tail fits the budget, the rolling cache is a no-op. Useful for long-running sessions with `SOPHON_LLM_CMD` set.\n- **Some commands don't compress.** `gh repo view --json` *adds* tokens, `git log --oneline` saves 0.4 %. Sophon's job isn't to compress already-compact output — it's to compress redundant verbose output. The benches name the gaps explicitly.\n\n---\n\n## Project layout\n\n```\n.\n├── README.md ← you are here\n├── BENCHMARK.md ← full per-section benchmark detail\n├── CHANGELOG.md ← version history + deprecated numbers\n├── benchmarks/ ← reproducible scripts for every number above\n├── npm/ ← npm wrapper package\n└── sophon/crates/ ← 11-crate Rust workspace\n ├── prompt-compressor/ compress_prompt\n ├── memory-manager/ compress_history, update_memory, rolling summary\n ├── delta-streamer/ read/write_file_delta\n ├── fragment-cache/ encode/decode_fragments\n ├── semantic-retriever/ chunker + HashEmbedder + BM25 + entity graph\n ├── output-compressor/ 21 command-aware filters + JsonStructural\n ├── codebase-navigator/ tree-sitter / regex + PageRank\n ├── cli-hooks/ transparent agent installer\n └── mcp-integration/ stdio server, async dispatch, cancellation\n```\n\n---\n\n## Contributing\n\nPRs welcome. Run the test suite:\n\n```bash\ncd sophon && cargo test --workspace --lib --tests --exclude prompt-compressor # 405 tests\ncd sophon && cargo test --features codebase-navigator/tree-sitter # +AST tests\ncd sophon-py && .venv/bin/pytest tests/ # 4 Python tests\n```\n\nEvery benchmark claim is reproducible — pointers to the scripts live in [BENCHMARK.md](./BENCHMARK.md). If a number doesn't reproduce on your machine, open an issue.\n\nParticularly welcome:\n\n- TypeScript bindings (Python bindings ship in `sophon-py/`)\n- `gh` family filter (`gh run list`, `gh pr list`, `gh repo view --json`) — the bench shows this is currently a gap\n- `SOPHON_EMBEDDER_CMD` shell-out plugin pattern (mirror of `SOPHON_LLM_CMD`) for Voyage / OpenAI / Cohere\n- Multi-repo `real_session_holistic.py` runs against popular open-source repos\n\n---\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n",
"bytes": 16485,
"sha": "9be09b3e314a4a106ba877423cdd3388525a62fbf4352312114cfeb19460c166",
"repo_slug": "lacausecrypto/mcp-sophon",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_lacausecrypto_sophon_716940c5/readme"
}