Token Savior Recall

Token Savior Recall is an MCP server for AI coding workflows that connects Claude Code and other MCP-compatible clients to a structural code navigation engine, a persistent memory system, dependency analysis, edit validation, checkpointing, and project-level automation.

It’s ideal for developers who work in medium to large codebases and want an agent to navigate symbols, inspect impact, recall past decisions, and apply scoped edits with less context waste.

The MCP server focuses on two recurring problems in agent-assisted development. The first problem is token waste during code navigation. The second problem is session amnesia across repeated work on the same project.

Token Savior Recall addresses both through symbol-aware indexing, query tools that return narrow code slices, and a SQLite-backed memory engine that stores prior observations, bugs, conventions, warnings, commands, and research notes.

Features

• Reduces token usage by up to 97 percent during code navigation compared to raw grep and cat operations.
• Stores session observations in a SQLite database with full-text search and LRU-based relevance scoring.
• Provides 75 tools across navigation, memory, dependencies, git, checkpoints, editing, and analysis categories.
• Builds a project index that updates incrementally using symbol-level content hashing for 19x faster reindexing.
• Supports Python, TypeScript, JavaScript, Go, Rust, C#, C, C++, GLSL, JSON, YAML, TOML, INI, ENV, HCL, Dockerfile, Markdown, and generic text files.
• Extracts functions, classes, methods, imports, and dependency graphs from supported languages.
• Injects relevant memory observations at session start and before tool calls using delta-based updates.
• Ranks code symbols by relevance using a PageRank variant with Random Walk with Restart on the dependency graph.
• Computes backward program slices to isolate the minimal set of lines affecting a variable at a given line.
• Packs an optimal bundle of symbols into a fixed token budget using a greedy fractional knapsack algorithm.
• Prefetches likely next tool calls using a Markov model with 77.8 percent accuracy.
• Attaches a static analysis certificate to every code edit that verifies signature, exception, and side-effect preservation.
• Detects semantically duplicate functions across a codebase using AST normalization and alpha-conversion.
• Captures critical observations and sends them to a Telegram feed when configured.
• Exports memory to Markdown and supports git versioning of the memory store.

Use Cases

• Navigate a large Python codebase to find the exact source of a function without opening the entire file.
• Identify every direct and transitive dependent of a class before attempting a refactor.
• Recall a bugfix pattern from six weeks ago that applies to a similar issue in a different module.
• Capture a project convention about error handling and surface it automatically when editing related code.
• Determine the minimal set of lines that influence a variable at a specific line during a debugging session.
• Verify that a proposed edit to a core utility function does not change its public signature or raise new exceptions.
• Find duplicate implementations of the same logic across multiple files and annotators.
• Generate a commit summary that lists every symbol changed in a patch.
• Create a checkpoint of the project index before a large-scale refactor and compare the symbol graph afterward.
• Run impacted tests automatically after modifying a function with known dependents.
• Analyze a Dockerfile to extract FROM instructions, multi-stage build steps, and environment variables.
• Build a relevance-ranked list of symbols related to a query and pack them into a context window budget.
• Capture the output of a significant bash command as a memory observation for future sessions.
• Switch between multiple projects and maintain separate indexes and memory stores for each.
• Use the command-line memory tool to search, retrieve, and manage observations without an AI assistant.

How To Use It

Installation

Quick start with uvx

Run the server directly from PyPI without creating a virtual environment or cloning the repository.

uvx token-savior-recall

Development installation

Clone the repository, create a virtual environment, and install the package in editable mode with MCP extras.

git clone https://github.com/Mibayy/token-savior
cd token-savior
python3 -m venv .venv
.venv/bin/pip install -e ".[mcp]"

Configuration

Add Token Savior Recall to your MCP client configuration file. The file location varies by client. For Claude Code and Cursor, use .mcp.json or ~/.claude/settings.json.

{
  "mcpServers": {
    "token-savior-recall": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "token_savior.server"],
      "env": {
        "WORKSPACE_ROOTS": "/path/to/project1,/path/to/project2",
        "TOKEN_SAVIOR_CLIENT": "claude-code",
        "TELEGRAM_BOT_TOKEN": "YOUR_TELEGRAM_BOT_TOKEN",
        "TELEGRAM_CHAT_ID": "YOUR_TELEGRAM_CHAT_ID"
      }
    }
  }
}

Environment variables

Custom MCP client YAML configuration

mcp_servers:
  token-savior-recall:
    command: /path/to/venv/bin/token-savior-recall
    env:
      WORKSPACE_ROOTS: /path/to/project1,/path/to/project2
      TOKEN_SAVIOR_CLIENT: my-client
    timeout: 120
    connect_timeout: 30

Guiding the AI assistant to use the tools

AI assistants default to using grep and cat for code exploration even when Token Savior Recall tools are available. Add the following guidance to your CLAUDE.md file or the equivalent instruction file for your client.

## Codebase Navigation — MANDATORY
You MUST use token-savior-recall MCP tools FIRST.
- ALWAYS start with: find_symbol, get_function_source, get_class_source,
  search_codebase, get_dependencies, get_dependents, get_change_impact
- For past context: memory_search, memory_get, memory_why
- Only fall back to Read/Grep when tools genuinely don't cover it
- If you catch yourself reaching for grep to find code, STOP

Available Tools

Core Navigation (14 tools)

Memory Engine (16 tools)

Advanced Context (6 tools)

Dependencies (7 tools)

Git & Diff (5 tools)

Checkpoints (6 tools)

Edit & Validate (4 tools)

Analysis (6 tools)

Project (7 tools)

Programmatic Usage

Token Savior Recall can be used as a Python library for scripting and automation.

from token_savior.project_indexer import ProjectIndexer
from token_savior.query_api import ProjectQueryEngine
indexer = ProjectIndexer("/path/to/project")
index = indexer.index()
engine = ProjectQueryEngine(index)
print(engine.get_project_summary())
print(engine.find_symbol("MyClass"))
print(engine.get_change_impact("send_message"))

Memory CLI

The memory engine includes a command-line interface named ts for managing observations without an active MCP session.

ts memory status
ts memory search "auth migration"
ts memory get obs_123
ts memory save "Always use async fixtures in pytest"
ts memory top
ts memory why obs_123
ts memory doctor
ts memory relink