# Token Saver

> A local Claude Desktop MCP extension that queries large PDFs with 92–98% fewer tokens using hybrid RAG search, returning page-cited answers while keeping documents private on your machine.

Token Saver is an open-source Claude Desktop extension developed at Marktechpost AI Media Inc by Arnav Rai (a CS student at Rochester Institute of Technology) during his internship, supervised by Jean-marc Mommessin and Asif Razzaq. It installs as a single `.mcpb` file and enables users to query large PDF documents with dramatically fewer tokens by performing local hybrid retrieval before anything reaches the model. The project is licensed under MIT and hosted on GitHub.

## What It Is

Token Saver is a one-click Claude Desktop extension that solves a specific problem: pasting large PDFs into a chat context is expensive and often counterproductive, because models buried in hundreds of irrelevant pages reason less accurately. Token Saver intercepts the query, runs a local hybrid search (BM25 keyword scoring plus local semantic embeddings), and hands Claude only the most relevant passages — with exact page citations. The PDF itself never leaves your machine.

## How the Hybrid RAG Pipeline Works

The retrieval pipeline runs entirely in a local resident process:

- PDFs are extracted into 180-word overlapping chunks, embedded locally, and indexed in SQLite held in RAM
- Each query runs both BM25 (stemmed, stop-word filtered) and cosine similarity over local embeddings, blended at a 0.4/0.6 ratio
- An abstain gate filters results before they reach the model; if nothing matches, the tool refuses to guess rather than hallucinate
- The index evicts after 30 idle minutes; the embedding model needs no internet after its first download
- If the embedding model cannot load, retrieval automatically degrades to keyword-only scoring and notifies the user

Measured on 30 author-written gold questions over two real documents (the 213-page *Dobbs v. Jackson* opinion and the 152-page Berkshire Hathaway 2023 annual report), the README reports hybrid recall@5 of **0.90** and a false-abstain rate of **0.00** as of 2026-07-25.

## Token Savings by Document Size

The README documents that the returned slice is roughly constant (~2.5k tokens) regardless of document size, so savings scale with document length:

- ~20 pages: ~14% vs pasting once, ~83% vs re-pasting each turn
- ~80 pages: ~78% vs pasting once, ~96% vs re-pasting each turn
- ~300 pages: ~94% vs pasting once, ~99% vs re-pasting each turn

The crossover point is around 15–20 pages — below that, the retrieval overhead can cost more than simply pasting the file. Every answer session ends with a running savings block showing estimated tokens sent versus a naive baseline.

## Setup Path

No Python, no Terminal, and no config files are required for end users — the extension bundles everything into a single `.mcpb` file:

1. Download `token-saver-ccr.mcpb` from the GitHub Releases page
2. Install via Claude Desktop → Settings → Extensions → Install extension
3. Toggle Enabled on (a "not verified by Anthropic" warning is normal for file-installed extensions)
4. Click Configure and point it at a small, dedicated folder containing the PDFs to query
5. On the first question, grant "Always allow" permission; the first run also downloads the local embedding model (2–5 minutes)

All current Claude models (Opus, Sonnet, Haiku) are supported; Sonnet or Opus is recommended for best single-turn accuracy.

## Known Limitations and Tradeoffs

The README states these limitations plainly:

- The abstain gate keys on keyword presence, so incidental word overlap can surface off-topic passages (false accepts) — citations should be checked
- File resolution is the weaker half: in a 16-PDF folder test, the resolver chose the correct document for 12 of 14 requests
- Generic nouns (e.g., "the textbook") can route to the wrong file when the term appears in neither filename nor early pages; naming the subject fixes it
- Page-only citations give no section provenance, so in documents with majority and dissenting sections the model must infer which side a passage came from

## Update: Token Saver v1.2

The latest release, Token Saver v1.2 (published 2026-07-31), is available on the GitHub Releases page as `token-saver-ccr.mcpb`. The README notes that retrieval metrics changed between an earlier 2026-07-09 run (hybrid 0.97 / keyword 0.93) and the current 2026-07-25 measurement (hybrid 0.90 / keyword 0.90), attributing the shift to retrieval changes including query-side stop words, light stemming, and an eligibility gate — not corpus drift. The repository had 111 stars and 13 forks as of early August 2026.

## Features
- Local hybrid RAG search (BM25 + semantic embeddings)
- 92–98% token reduction for large PDFs
- Exact page number citations in every answer
- Privacy-first: documents never leave your machine
- One-click .mcpb install for Claude Desktop
- Automatic fallback to keyword-only if embedding model unavailable
- 30-minute in-RAM index with auto-eviction
- Running token savings block after each answer
- Multi-document folder support with natural-language file resolution
- Abstain gate to avoid hallucination when nothing matches
- Reproducible retrieval eval with gold question sets
- MIT licensed open-source codebase

## Integrations
Claude Desktop, Anthropic Claude (Opus, Sonnet, Haiku), MCP (Model Context Protocol), SQLite, BM25 keyword search, Local sentence embeddings, tiktoken, Python 3.10+

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
version1.2

## Links
- Website: https://github.com/Marktechpost/Token-Saver
- Documentation: https://github.com/Marktechpost/Token-Saver/blob/main/INSTALL_GUIDE.md
- Repository: https://github.com/Marktechpost/Token-Saver
- EveryDev.ai: https://www.everydev.ai/tools/token-saver