Token Savior MCP
Token Savior indexes code by symbol, keeps memory between sessions and rewrites noisy Bash commands so the agent spends fewer tokens
- 1,187 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The structural editing tools change project files, and `ts_execute` runs code in a Node.js sandbox
- The PreToolUse rewriter changes Bash commands before they run, and `ts init` edits the agent's `settings.json`
- Memory keeps decisions and output of your sessions in a local database, and optional modules send data to the Anthropic API and Telegram
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/token-saviorDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The structural editing tools change project files, and `ts_execute` runs code in a Node.js sandbox
- The PreToolUse rewriter changes Bash commands before they run, and `ts init` edits the agent's `settings.json`
- Memory keeps decisions and output of your sessions in a local database, and optional modules send data to the Anthropic API and Telegram
This is third-party code. Review the repository files before installing.
What it does
Token Savior is an MCP server in Python from the `token-savior-recall` package. It indexes a project by symbol: functions, classes, imports and the call graph, so the agent goes to the right place by symbol reference instead of reading a whole file. The tools `find_symbol`, `get_function_source`, `search_codebase` and `get_change_impact` return one function's source, where it is used and the circle of code an edit touches. There is structural editing that keeps the index in step with the files, plus the checks `detect_breaking_changes`, `find_dead_code` and `analyze_config`. The second layer is memory. Decisions, bug fixes, conventions and session summaries are stored in SQLite (WAL mode, FTS5 full-text search and vector embeddings), ranked by a validity score and usefulness, and returned as a compact digest at the start of the next session. The `ts init --agent claude` command adds PostToolUse and PreToolUse hooks to the agent's settings: it prints a diff, backs up `settings.json` and changes nothing on a repeat run. It works the same way with Cursor, Gemini CLI, Codex and OpenClaw. The third layer is Bash. The PreToolUse rewriter (10 rules) changes a command before it runs so the output comes back shorter. Thirty-four PostToolUse compactors append a condensed version of the output and put the full one in a capture sandbox, where it survives context compaction. Both are off until `TS_BASH_REWRITE=1` and `TS_BASH_COMPACT=1` are set. The `TOKEN_SAVIOR_PROFILE` variable picks the toolset: the `optimized` profile shows the agent 15 tools, `full` shows 68.
Who it is for. For developers who work on large codebases in Claude Code, Codex, Cursor or Gemini CLI and want the agent to read less than it must and remember decisions from earlier sessions.
Good fit when
- The agent reads a whole file for three lines and the context fills up on the first tasks
- Every session you have to explain the team's agreements and the project's decisions again
- The output of `git`, `pytest` or `kubectl` bloats a turn, and you want rewritten commands with a short result
- Before an edit you need to see what will break: `get_change_impact` and `detect_breaking_changes` answer that
- You want to see where the agent could have saved: `ts_discover` parses Claude Code session transcripts and finds chains of Read, Grep and Read again
Not a fit when
- You need memory as readable notes: Token Savior keeps it in an SQLite database, while Basic Memory keeps plain Markdown files
- You already get symbol navigation from serena: the author advises running Token Savior with the `compact-only` profile
- You want only the Bash layer without navigation and memory: take the `compact-only` profile, it shows a single tool
- The machine has no Python 3.11 or newer: the package requires it
Example request
Connect Token Savior to this project and show which parts of the code a change to the PaymentService class would touchMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
WORKSPACE_ROOTS- Comma-separated project roots to index, the current folder by default
TOKEN_SAVIOR_PROFILE- Toolset profile; optimized is recommended, full by default
TS_API_KEYsecret- Anthropic API key for automatic memory extraction together with TS_AUTO_EXTRACT=1
Limitations
- The author's 97.9% (188 of 192 tasks) and minus 80% tokens come from a closed benchmark with no public repository, and the author himself calls the figures unverifiable. He withdrew the 9 August measurement because the server's tools were barely called in it. A repeat measurement on 7 October 2026 (8 tasks, Claude Haiku 4.5) gave minus 45% cost and minus 59% new tokens, but wall time rose 40% and file edits showed no gain.
- In Claude Code 2.1.28x and later, without `"alwaysLoad": true` the tools sit behind `ToolSearch` and the agent keeps reading files itself.
- PostToolUse compactors run after the tool has answered: the output is preserved for later and the current turn stays as long as it was.
- In Codex, shell variables do not reach the server: set `WORKSPACE_ROOTS` in `config.toml` under `[mcp_servers.token-savior]`.
- Version 4.24.0, MIT license.
How to disable. Remove the server from the MCP settings (for Claude Code, `claude mcp remove token-savior`) and run `pip uninstall token-savior-recall`. Delete the hooks that `ts init` added from the agent's `settings.json`; a backup with the suffix `.bak-YYYYMMDD-HHMMSS` sits next to it. `TS_MEMORY_DISABLE=1` turns memory off. Data and statistics live in `~/.local/share/token-savior`.
FAQ
How does the `optimized` profile differ from `full`?
`optimized` shows the agent 15 tools with trimmed schemas, and the manifest takes about 1.5 thousand tokens. `full` shows 68 tools and about 6 thousand tokens. The author recommends `optimized` as the default, and it is what `ts init` sets.
Why does the config carry `alwaysLoad: true`?
In Claude Code 2.1.28x and later, without that flag the server's tools sit behind the `ToolSearch` lookup and the model reaches for the already loaded `Read` and `Grep`. In the author's measurement before the flag existed, one session in 143 called the server. With it, the manifest costs a few thousand cached tokens per session.
How do I turn on the command rewriter?
It is off by default and switched on with `TS_BASH_REWRITE=1`. A JSONL log of every rewrite goes to the file named in `TS_BASH_REWRITE_LOG`. `ts init --agent claude --yes` adds the hooks to the agent's settings.
Can I use it without MCP, for example in Cursor or Aider?
Yes. For agents without MCP there is the `ts` CLI: `ts use /path/to/project`, `ts get my_function`, `ts search 'pattern'`. `ts daemon start` keeps a process running, so a call takes about 145 ms instead of 1.5 s on a cold start. In Claude Code the author recommends MCP, which is cheaper than the CLI.
Where is the data stored and is there a dashboard?
Statistics live in `~/.local/share/token-savior`, and `TOKEN_SAVIOR_STATS_DIR` changes the folder. The dashboard listens on 127.0.0.1 at port 8921, and a web viewer for memory observations is switched on by a port in `TS_VIEWER_PORT`. Captured command output is purged after 30 days, and `TS_CAPTURE_TTL_DAYS` sets that period.
Discussion
No questions or reviews yet.
Related
MCP serversToken Optimizer MCP
token-optimizer-mcp
Context compression and caching, token savings tracking per agent. Global npm install turns on Claude hooks and wraps commands; telemetry is off by default
A local proxy with a terminal dashboard: shows how many tokens each Claude Code and Codex request sends and saves the prompts to files
An MCP server of long-term memory for coding agents: search over past sessions on a local BGE-m3 model and a check for drift from earlier rules
Memory for coding agents in plain Markdown: the agent keeps specs, decisions and lessons itself, and each new session starts from them. No vector database
A skill that cuts an agent's prose output, plus a local proxy that compresses what the agent reads
One local memory for Codex, Claude Code, Cursor, Hermes Agent and OpenClaw: agents hand off tasks, review each other and refine their skills overnight
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Token Savior (this entry) | no | not required | 1,187 | |
| codebase-memory-mcp | no | not required | 47,351 | builds a code graph of functions, classes, calls and routes and answers structural queries locally |
| Basic Memory | no | not required | 4,334 | agent memory in local Markdown files with a link graph and semantic search |
| Code Context Engine | no | not required | 436 | a local MCP server that indexes your code so the agent pulls the |
README in short
The repository's front page opens with a table of measurements and the story of a withdrawn measurement, followed by a quick start, switching on the Bash layer, a catalog of 34 compactors, a description of `ts_discover`, a profile comparison and a compatibility table with neighbouring tools. At the end come installation, a description of the benchmark harness, the `ts` CLI and a full list of environment variables. The repository holds a changelog, tests (the author reports 1898 passing), measurement scripts, hooks for Claude Code, Codex, Gemini and OpenClaw, and a migration guide from version 3.