Token Savior: an MCP server that indexes your repo, and a benchmark it retracted

What the server actually gives the agent

Token Savior is an MCP server for AI coding agents, and the description in the package metadata is precise about the mechanism. It is an optimized MCP server for AI coding agents, with structural codebase navigation and a persistent memory engine, written in Python, published to PyPI as token-savior-recall, and requiring Python 3.11 or newer.

The idea is that a coding agent spends most of its budget reading code. The server indexes the repository, understands its structure, and exposes tools that return the part you need, which is the same promise every code navigation tool makes, and the one the project is trying to prove rather than assert.

The technical base is tree-sitter. The dependencies list tree-sitter itself along with tree-sitter-java and tree-sitter-ruby, which means the structural analysis is done by parsing grammars rather than by regular expressions, and the package keywords name the languages it cares about, including c, glsl, python, typescript, go, rust, shell and php.

There is also a persistent memory engine, and a second feature that is easy to miss in the headline: Bash command rewriting, where the server intercepts the agent's own shell calls and compacts the output. The Bash compaction and the PreToolUse rewriter are opt-in, enabled with two environment variables and one CLI call, and the PostToolUse compactors number 34.

The releases are frequent and descriptive, with v4.23.1 called smaller session start and reachable tools, v4.23.2 called the launch directory is the active project, and v4.24.0 called lighter edit context, architecture map and review prompts.

The headline number, with the caveat the project prints next to it

The benchmark section is the first thing a reader sees, and the project is unusually careful about how it is framed.

The headline table is for 96 real coding tasks, run with Claude Opus 4.7 in May 2026. Plain Claude Code scored 141 out of 180, which is 78.3 percent, and with Token Savior the score was 188 out of 192, which is 97.9 percent. Active tokens per task went from 17221 to 3395, a reduction of 80 percent, and wall time per task from 110.6 seconds to 18.9 seconds, a reduction of 83 percent.

Then the sentence that matters. The harness that produced these numbers is described below, its repository is not public at the moment, and therefore you should take the figures as reported rather than as independently verifiable.

That is a stronger position than it first appears. A project that simply published a benchmark number would be asking you to trust it. This one is telling you in the same breath that you cannot check it, which is a sign of a maintainer who has been burned by a number rather than one who is trying to launder a number.

It also puts a specific weight on the second measurement, the one with the tools actually called, since the first one cannot be verified and the second one can at least be reasoned about.

The withdrawn benchmark, and the lesson it produced

This is the most valuable paragraph in the README, and it is the reason the project is worth reading even if you never install it.

A re-measurement was published on 2026-08-09 and withdrawn on 2026-08-10. It reported new-token savings from a small replacement harness, and the explanation of why it was withdrawn is specific rather than vague.

Those numbers did not measure this server at all. Across 143 benchmark sessions, exactly one called a Token Savior tool. The client running the harness had MCP deferred-tool loading enabled, so all 18 tools sat behind a ToolSearch lookup instead of appearing in the model's manifest. The model never saw them and fell back to Grep and Read, with 66 greps and 30 reads against that single MCP call. What varied between the profiles was the size of the cached prefix, not what the agent did.

So the benchmark compared two identical agents and reported a difference in cost, and the difference was an artefact of prompt caching. The lesson the project draws from it is the sentence in bold. A benchmark of an MCP server must assert that its tools were actually called. Theirs did not, so it happily compared two identical agents, and that assertion now exists in the harness.

That is a genuinely reusable piece of engineering advice for anyone evaluating agent tooling. The failure mode is not exotic: a tool that is installed but never surfaced to the model produces a plausible looking cost saving and zero benefit, and the only way to tell the difference is to count the calls.

The re-measurement, where wall time gets worse

The second benchmark was re-measured on 2026-10-07 with the tools actually called, and it is a smaller and more believable experiment.

It used the same 8 tasks on a frozen copy of the project repository, at commit 9d15a1e, with no CLAUDE.md, and Claude Haiku 4.5, comparing plain Claude Code against the auto profile with alwaysLoad. The results are given as a mean and standard deviation over 3 passes, and the harness checks that the Token Savior sessions really called the server.

Cost for the 8 tasks was 0.226 dollars plus or minus 0.011 plain, and 0.123 plus or minus 0.020 with the server, which is a 45 percent reduction with a range of 39 to 53 percent. New tokens fell from 92609 plus or minus 6731 to 38150 plus or minus 7618, a 59 percent reduction. Sessions that used the server: 23 out of 24. All 48 sessions succeeded.

And then the number that goes the other way. Wall time was 157 plus or minus 26 seconds plain, and 216 plus or minus 9 seconds with the server, which is 40 percent slower.

The explanation is mechanical: each benchmark session starts a fresh server that indexes the repository first, so a short session pays the indexing cost in full, while a long-lived session pays it once. That also explains why a token-focused summary would be misleading, because the saving is amortised and the cost is not.

Two more measurements are reported with the same honesty. v4.22.0, measured once, saved 14 percent and used the tools in 5 sessions out of 8. And editing, measured on 2026-10-08 on the same repository with 3 tasks in files of 1900 to 3700 lines, where every session of both arms succeeded and the cost was too noisy to call a gain, ranging from minus 54 to plus 16 percent per pass, because the native Edit only needs a partial Read and there is little left to remove there.

alwaysLoad is the setting that decides whether any of this happens

The installation is a pip command and a block of MCP configuration.

pip install "token-savior-recall[mcp]"

{
  "mcpServers": {
    "token-savior-recall": {
      "command": "/path/to/venv/bin/token-savior",
      "alwaysLoad": true,
      "env": {
        "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
        "TOKEN_SAVIOR_CLIENT": "claude-code",
        "TOKEN_SAVIOR_PROFILE": "optimized"
      }
    }
  }
}

The alwaysLoad flag is the one the README emphasises, and the reason is the failure from the withdrawn benchmark. On Claude Code 2.1.28x and later, without alwaysLoad every tool of the server sits behind ToolSearch and the model reaches for Read and Grep, which are already loaded. The project measured this on its own benchmark before the option existed, and found that one session in 143 called a Token Savior tool. With it, the manifest costs a few thousand cached tokens per session, which is the price of the tool being visible.

The optimized profile is then described as the Pareto-optimum configuration that wins the benchmark, and it bundles a specific list: tiny_plus, which is a 15 hot tools manifest, thin inputSchema for a 44 percent smaller manifest, the capture sandbox disabled, and memory hooks gated for cross-project safety.

The project says no other tuning is needed, and given what the withdrawn measurement showed, that sentence should be read together with alwaysLoad rather than instead of it.

Compaction, rewriting, and the launch directory

Two of the features are opt-in and controlled by environment variables, and the compaction one is the more interesting of the pair.

The Bash compaction and the PreToolUse rewriter are enabled with two env vars and one CLI call, and the first flag shown is TS_BASH_COMPACT=1, which turns on the PostToolUse output compactors, of which there are 34.

The idea is that an agent's context is filled mostly by the output of its own shell commands, and much of that output is noise. Compacting it after the fact shrinks what the model carries into the next turn, and rewriting the commands themselves stops the noisy output from being produced in the first place.

The other recent change worth noting is in the release titles rather than the documentation. v4.23.2 is called the launch directory is the active project, which is a statement about how the server decides which project it is working on, and it follows the earlier work of v4.23.1, smaller session start and reachable tools. The reasoning behind them is a cost question: the more context the server puts in front of the model at the start of a session, the more every session costs, and the project is clearly optimising for the small number of tools an agent actually reaches for.

There is also a side project in the repository, starscope, built because GitHub restricted stargazer and watcher lists to repo admins and collaborators on 2026-06-30, which broke every tool that tried to answer who starred a repository. The replacement only reads repositories you own or can push to.

How the package is built and what the release cadence looks like

The packaging is Hatchling rather than the more common setuptools or poetry, and the dependency list is where the engineering discipline shows.

Every requirement carries an upper bound on the next incompatible major, and the comment in the manifest explains why. Without one, an upstream release breaks existing installs with no commit on your side, and bumping a bound is a deliberate act made on purpose.

The pinned dependencies are mcp for the protocol, PyYAML, watchfiles, and the tree-sitter packages. The optional extra named mcp is kept for compatibility, and the comment says in French that mcp is now a base dependency and the extra does nothing any more, and that the extra is still published in the README and on PyPI since v2. That is a small example of careful deprecation, keeping an install command working for people who read it a year ago.

The repository is a normal Python project layout with src/, tests/, benchmarks/, a bench_local_chaine.py script, hooks/, scripts/, bin/, docs/, a server.json and a glama.json for MCP server metadata, an llms-install.md, and both AGENTS.md and CLAUDE.md for the agent tooling that works on this repository. There is a CHANGELOG.md, and the project is explicit that release notes live in the places that cannot drift out of sync with the code, the changelog, the releases and PyPI.

The version is 4.24.0, the last push was on 2026-10-15, and the three most recent releases are v4.23.1, v4.23.2 and v4.24.0, all from the past two weeks.

Editorial conclusion

Token Savior fits a team running an MCP-capable coding agent over a large repository, where the agent spends its budget reading files it did not need to read, and where the cost of an index pass at session start is acceptable. It does not fit a team that needs a published, independently reproducible benchmark, since the project itself says the harness is not public and asks you to take the figures as reported. Verify three things before you rely on the numbers: that the tools are actually being called in your setup, which the withdrawn measurement shows is not automatic and is the single failure mode that produces fake savings, that alwaysLoad is set if the client defers tool loading, and that the wall time cost is what you expect, because the project reports a 40 percent increase there that a token-focused summary leaves out.

Frequently asked questions

Official sources

1. License: MIT
2. Mibayy/token-savior on GitHub
3. Project website
4. README
5. Releases