Token Savior

Symbol-level code navigation, structural editing and cross-session memory for coding agents

By Mibay (individual) Python Local · stdio Developer toolsKnowledge and memory

66 popularity score ★ 1.2k ↓ 1.4k/mo

Connect your client

Local (PyPI)

Add in one click

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal
claude mcp add token-savior -- uvx --from token-savior-recall token-savior
Claude Desktopclaude_desktop_config.json
{
  "mcpServers": {
    "token-savior": {
      "command": "uvx",
      "args": [
        "--from",
        "token-savior-recall",
        "token-savior"
      ]
    }
  }
}
Cursor~/.cursor/mcp.json
{
  "mcpServers": {
    "token-savior": {
      "command": "uvx",
      "args": [
        "--from",
        "token-savior-recall",
        "token-savior"
      ]
    }
  }
}
VS Code.vscode/mcp.json
{
  "servers": {
    "token-savior": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "token-savior-recall",
        "token-savior"
      ]
    }
  }
}
Codex~/.codex/config.toml
[mcp_servers.token-savior]
command = "uvx"
args = ["--from", "token-savior-recall", "token-savior"]
Gemini CLITerminal
gemini mcp add --scope user token-savior uvx -- --from token-savior-recall token-savior

Settings 8

WORKSPACE_ROOTS Optional: Comma-separated project folders to index; defaults to the current directory.
TOKEN_SAVIOR_PROFILE Optional: Tool set to advertise: full (default, 72 tools), optimized (15), auto, compact-only.
TOKEN_SAVIOR_CLIENT Optional: Client label such as claude-code; auto-detected when unset.
TS_MEMORY_DISABLE Optional: Set to 1 to turn off the memory engine and its tools.
TS_CODE_MODE_DISABLE Optional: Set to 1 to drop the ts_execute Node sandbox tool.
TS_BASH_REWRITE Optional: Set to 1 to enable the PreToolUse shell command rewriter (with ts init).
TS_BASH_COMPACT Optional: Set to 1 to enable the PostToolUse output compactors (with ts init).
TOKEN_SAVIOR_MAX_FILES Optional: Maximum files indexed per project, default 10000.

What it does

Token Savior indexes a local codebase by symbol (functions, classes, imports and the call graph) so a coding agent can ask where something is defined, fetch one function's source, or see who depends on it, in place of reading whole files and grepping. It also edits by symbol (replace a function, insert next to one, move it to another file and fix imports), runs impacted pytest files or detected project actions, and audits a project for dead code, import cycles, breaking API changes against a git ref, config secrets and Dockerfiles.

A second half is a persistent memory store in local SQLite with full-text search: the agent saves decisions, conventions and reasoning traces, and a compact summary is offered again at the start of the next session. Optional Claude Code hooks, enabled with TS_BASH_COMPACT and TS_BASH_REWRITE plus the `ts init` command, rewrite noisy shell commands before they run and keep long command output in a searchable store.

The tool surface depends on TOKEN_SAVIOR_PROFILE. With no profile set the server starts in `full` and advertises 72 tools at version 4.23.2 (counted in tool_schemas.py and server.py at that tag), not the 68 the README's profile table gives; `optimized`, which the README recommends, advertises 15. Filtered-out tools still run if called by name. The headline benchmark figures in the README are, by its own account, not independently reproducible because the harness repository is not public.

What it needs

RuntimePython 3.11+

Python 3.11 or later; the uvx command needs uv, or install with pip install "token-savior-recall[mcp]" and point the client at the venv's token-savior program. Hybrid vector search needs the memory-vector extra. The ts_execute tool needs Node.js on PATH (TS_CODE_MODE_NODE). Memory auto-extraction needs an Anthropic API key (TS_API_KEY). The Bash hooks need Claude Code, Cursor, Gemini, Codex or OpenClaw and a run of `ts init`.

Limits

The README's `uvx token-savior-recall` does not start the server: the package has no program of that name (pyproject.toml at v4.23.2 lists ts, token-savior, token-savior-dashboard, token-savior-bench), so use `uvx --from token-savior-recall token-savior`. By default indexing stops at 10,000 files per project and skips files over 500,000 bytes (TOKEN_SAVIOR_MAX_FILES, TOKEN_SAVIOR_MAX_FILE_SIZE); read_lines returns up to 400 lines and run_project_action times out after 120 s. The PostToolUse compactors do not shrink the current turn. On Claude Code 2.1.28x and later the README says tools go unused unless alwaysLoad is set.

Who it suits

Suits developers running a local coding agent, mainly Claude Code, on medium or large repositories who want fewer file reads and memory that survives sessions. It runs entirely on your machine with no account. It is not a hosted service and is not official to any vendor. If you already use serena for symbol navigation, the README suggests running Token Savior with the compact-only profile for the shell hooks alone; if you only want memory or only navigation, the profile and TS_MEMORY_DISABLE switches trim it down. Pick something else if you cannot install Python 3.11.

Tools 60 of 72

list_projects
Lists registered workspace projects and their index state
switch_project
Changes the active project
set_project_root
Registers a new project root and makes it active
reindex
Rebuilds the symbol index for a project
get_project_summary
Gives an overview: file count, packages, main classes and functions
list_files
Lists indexed files, optionally by glob
get_structure_summary
Outlines one file's functions, classes and imports, or the whole project
read_lines
Returns a line range of a file and names the enclosing symbol
get_function_source
Returns a function or method's source by name
get_class_source
Returns a class body with its methods
get_functions
Lists functions in a file or project
get_classes
Lists classes with lines, methods and bases
get_imports
Lists a file's imports
find_symbol
Locates a symbol's definition with signature and preview
get_dependencies
Shows what a symbol calls or uses
get_dependents
Shows direct callers and users of a symbol
get_change_impact
Lists direct and transitive dependents of a symbol
get_full_context
Bundles a symbol's location, source and dependency links
get_call_chain
Finds the shortest dependency path between two symbols
get_edit_context
Gathers source, callers, siblings and impacted tests before an edit
get_file_dependencies
Lists files a file imports
get_file_dependents
Lists files that import a file
search_codebase
Searches code and names the function or class around each hit
search_in_symbols
Regex search returning the enclosing symbol per match
get_feature_files
Finds files for a feature keyword, sorted by role
replace_symbol_source
Rewrites a whole function or class by name
edit_lines_in_symbol
Replaces exact text inside a named symbol
insert_near_symbol
Inserts content before or after a symbol
move_symbol
Moves a symbol to another file and updates imports
add_field_to_model
Adds a field to a Prisma, Python or TypeScript model
checkpoint
Creates, lists, restores, compares or deletes file checkpoints
get_diagnostics
Reports type-checker errors grouped by file
get_git_status
Returns branch, ahead/behind and file states
get_changed_symbols
Summarises worktree changes at symbol level
build_commit_summary
Drafts a commit or review summary from changes
detect_breaking_changes
Compares the API against a git ref for breaking changes
find_impacted_test_files
Infers pytest files affected by changes
run_impacted_tests
Runs pytest on files affected by worktree changes
discover_project_actions
Detects test, lint, build and run actions from build files
run_project_action
Runs a detected project action with output and time limits
get_routes
Lists Next.js App Router routes and pages
get_env_usage
Traces where an environment variable is defined and read
analyze_config
Audits config files for duplicates, secrets and orphans
find_dead_code
Finds functions and classes with no callers
find_hotspots
Ranks functions by complexity or Java allocation and performance
find_semantic_duplicates
Finds duplicate functions by AST hash or embeddings
find_import_cycles
Detects cycles in the file import graph
analyze_docker
Audits Dockerfiles: base images, stages, ports, ENV/ARG
get_db_schema
Summarises tables, keys and indexes from SQL migrations
get_entry_points
Scores functions by how likely they are entry points
memory_save
Stores a fact, guardrail or note for later sessions
memory_search
Full-text search over stored memory
memory_get
Returns full memory entries by ID
memory_delete
Archives a memory entry
memory_index
Lists recent memory entries in compact form
memory_admin
Runs memory maintenance: status, dedup, distill and more
corpus_build
Builds a themed set from memory entries
corpus_query
Formats a memory set as context for a question
reasoning_save
Stores a reasoning trace for reuse
reasoning_search
Finds stored reasoning traces by goal

Similar servers