Token Savior
Structural code navigation, persistent memory, and Bash output compaction for AI coding agents.
Add to your client
Copy the config for your MCP client and paste it into its config file.
pip install "token-savior-recall[mcp]"Paste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"token-savior": {
"command": "/path/to/venv/bin/token-savior",
"args": [],
"env": {
"WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
"TOKEN_SAVIOR_CLIENT": "claude-code",
"TOKEN_SAVIOR_PROFILE": "optimized"
}
}
}
}Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- Python 3.11+
- An MCP-compatible client (e.g. Claude Code, Cursor, Gemini, Codex)
- Install the token-savior-recall PyPI package (with the [mcp] extra), or run via uvx
About Token Savior
An MCP server that reduces token usage for AI coding agents by indexing the codebase by symbol (navigate by pointer, not by reading whole files), maintaining a persistent SQLite + FTS5 + vector memory engine across sessions, and compacting noisy Bash output. The recommended optimized profile exposes 15 hot tools and is reported to win the project's tsbench benchmark at roughly -80% active tokens. Install via pip or uvx; works with any MCP client and ships a ts CLI for non-MCP agents.
Tools & capabilities (9)
find_symbolLocate a symbol (function, class, import) by name and navigate to it by pointer instead of reading the whole file — e.g. find_symbol("send_message") returns ~67 chars vs a full-file read.
get_function_sourceReturn the source of a named function directly, replacing a grep + cat chain.
get_change_impactReport the change impact / call-graph dependents for a symbol (e.g. get_change_impact("LLMClient")).
get_edit_contextProvide the surrounding context needed to make a safe edit at a location.
memory_indexIndex/store persistent memory observations (decisions, bugfixes, conventions, guardrails, session rollups) into the SQLite WAL + FTS5 + vector store.
memory_searchSearch the persistent memory store, ranked by Bayesian validity and ROI, for relevant prior context.
capture_getRetrieve the full original output that was sandboxed when hybrid compact mode emitted only a compact preview for a bulky Bash result.
get_usage_statsReport token-usage statistics: a 30-day ASCII sparkline, a 7-day daily breakdown table, top tools cumulative, with optional format="json".
ts_discoverScan ~/.claude/projects/*/*.jsonl transcripts to flag missed Token Savior opportunities (Read->Grep->Read chains, sequential find_symbol, edits without get_edit_context, memory_search without memory_index, native shell on code files). Supports project=None for all projects and format="adoption"/"adoption_json" for TS-vs-native ratios per session.
When to use it
- Cut active token usage and wall-clock time for AI coding agents by navigating code structurally instead of reading whole files
- Persist project knowledge (decisions, conventions, bugfixes) across sessions and re-inject it as a compact delta at the next session start
- Compact noisy Bash output (git, gh, pytest/jest/vitest, cargo, tsc, docker, kubectl, aws, package managers, grep/find/cat/curl) to save turn budget
- Audit a project's transcripts to discover where structural tools would have been cheaper than what the agent actually did
Security notes
Core navigation and memory require no credentials. Optional integrations use environment variables: TS_API_KEY (only for LLM auto-extraction of memory observations via TS_AUTO_EXTRACT=1) and TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID (critical-observation feed). Bash compaction (TS_BASH_COMPACT=1) and the PreToolUse command rewriter (TS_BASH_REWRITE=1) are opt-in; the rewriter supports an optional JSONL audit log of every rewrite via TS_BASH_REWRITE_LOG. The server reads local Claude Code transcripts under ~/.claude/projects for ts_discover and benchmarking; args are pruned to load-bearing keys (described as PII-safe).
Token Savior FAQ
Which profile should I use?
The README recommends `optimized` (set TOKEN_SAVIOR_PROFILE=optimized). It exposes 15 hot tools with a thin inputSchema (~1.5 KT manifest), disables capture sandboxing, and gates memory hooks for cross-project safety — the configuration it reports as the Pareto win on tsbench. Other profiles: auto (adaptive), tiny (6 tools), lean (51), full (68).
How do I enable Bash compaction and command rewriting?
They are opt-in. Set TS_BASH_COMPACT=1 (PostToolUse output compactors) and/or TS_BASH_REWRITE=1 (PreToolUse rewriter), then run `ts init --agent claude --yes` to auto-merge the hook config into ~/.claude/settings.json. `ts init` is idempotent, prints a unified diff, and backs up settings.json before writing.
Can I use it without MCP?
Yes. The `ts` CLI exposes a subset of tools via shell for non-MCP agents (Cursor, Aider, Continue, scripts, CI): e.g. `ts use <path>`, `ts get <symbol>`, `ts search <pattern>`, `ts daemon start`. On Claude Code the README recommends the MCP server, which it measured as cheaper than the CLI on Opus 4.7.
Does it require an API key?
No. Core code navigation and memory need no credentials. An API key (TS_API_KEY) is only needed for optional LLM auto-extraction of memory observations (TS_AUTO_EXTRACT=1), and Telegram tokens are only for the optional critical-observation feed.
Alternatives to Token Savior
Compare all alternatives →
Microsoft's official browser-automation MCP using Playwright's accessibility tree (no vision model).
Up-to-date, version-specific library documentation injected into your coding agent.
LSP-powered coding agent toolkit: semantic symbol search, references and structural edits.
Compare Token Savior with: