Token Savior Recall

An MCP server that provides structural code navigation and persistent memory for AI coding agents. Achieves 100% on the tsbench coding benchmark with −77% active tokens and −76% wall time compared to plain Claude Code.

Key Features

Structural Code Navigation

Indexes codebases by symbol (functions, classes, imports, call graph) enabling pointer-based navigation instead of full-file reads. Measured 97% reduction in characters injected across 170+ sessions.

Persistent Memory Engine

• Storage: SQLite WAL + FTS5 + vector embeddings with 12 observation types
• Hybrid search: BM25 + vector (all-MiniLM-L6-v2, 384d) fused via RRF
• Progressive disclosure: 3-layer contract (memory_index → memory_search → memory_get)
• Bayesian validity: Each observation carries validity priors and update rules
• Contradiction detection: Triggered at save time against existing index
• Decay + TTL: Per-type TTL with LRU scoring
• Symbol staleness: Observations linked to symbols invalidated on content-hash changes
• ROI tracking: Access count × context weight with auto-promotion
• MDL distillation: Compresses redundant observations into conventions

Benchmark Results (96 tasks, Claude Opus 4.7)

• Score: 192/192 (100.0%) vs 141/180 (78.3%) plain Claude
• Active tokens/task: 3,929 (−77%)
• Wall time/task: 26.6s (−76%)
• Win/Tie/Loss: 25/65/0

Tools (90 total)

Core Navigation (14 tools)

• find_symbol - Locate functions, classes by name
• get_function_source - Direct retrieval without grep/cat chain
• get_change_impact - Show direct and transitive dependents
• get_backward_slice - Extract relevant lines for a variable

Memory Engine (21 tools)

• memory_index - Layer 1 shortlist (~15 tokens/result)
• memory_search - Layer 2 detailed search (~60 tokens/result)
• memory_get - Layer 3 full retrieval (~200 tokens/result)
• Citation URIs: ts://obs/{id} for reusable references

Dependencies & Graph (9 tools)

Git & Diffs (5 tools)

Safe Editing (8 tools)

Checkpoints (6 tools)

Test & Run (6 tools)

Config & Quality (8 tools)

Docker & Multi-project (2 tools)

Advanced Context (6 tools)

Slicing, packing, RWR, prefetch, verify

Reasoning (3 tools)

Plan/decision traces

Stats & Health (10 tools)

Project Management (7 tools)

Profiles

Filter advertised tools via TOKEN_SAVIOR_PROFILE:

Defer-Loading with ts_search

The tiny profile exposes only 6 tools. Access ~60 others just-in-time:

ts_search(query="find dependents of update_user", top_k=5)
# → {"matched_tools": [{"name": "get_dependents", "score": 0.68, ...}]}

Embeddings (Nomic 768d) score tool descriptions against queries, mirroring the Tool Attention paper (−95% prefix tokens).

Bench-Mode Optimization

For cold-start/benchmark workloads:

export TOKEN_SAVIOR_PROFILE=lean
export TS_MEMORY_DISABLE=1
export TS_CAPTURE_DISABLED=1
export TS_HOOK_MINIMAL=1
export TS_NO_HINTS=1

Reduces active tokens from 17,221 (plain) → ~5,500 while maintaining 100% benchmark score.

Usage

Progressive Disclosure Pattern

1. Layer 1: memory_index - Quick shortlist (~15 tokens/result)
2. Layer 2: memory_search - Detailed results if Layer 1 matched (~60 tokens)
3. Layer 3: memory_get - Full observation if Layer 2 confirmed (~200 tokens)

Each Layer 1 row includes [ts://obs/{id}] citation URIs.

Optional Features

• Web viewer: Set TS_VIEWER_PORT for htmx + SSE interface
• LLM auto-extraction: TS_AUTO_EXTRACT=1 + TS_API_KEY for PostToolUse observation extraction
• Telegram feed: TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID for critical observations
• Vector search: Install with [memory-vector] extra for hybrid FTS + vector

Installation

uvx (no clone required):

uvx token-savior-recall

pip:

pip install "token-savior-recall[mcp]"
# Optional vector search:
pip install "token-savior-recall[mcp,memory-vector]"

Claude Code:

clauده mcp add token-savior -- /path/to/venv/bin/token-savior

Comparison with claude-mem

Token Savior Recall is a superset that adds:

• Bayesian validity + contradiction detection
• Per-type decay + TTL
• Symbol staleness tracking (content-hash linked)
• ROI tracking + auto-promotion
• MDL distillation into conventions
• Code graph/AST navigation (90 tools, cross-language)
• Progressive disclosure contract (3 layers)
• Hybrid FTS + vector search (RRF)

Links

• Website: https://mibayy.github.io/token-savior/
• Benchmark: https://github.com/Mibayy/tsbench
• PyPI: https://pypi.org/project/token-savior-recall/
• Progressive Disclosure Docs: docs/progressive-disclosure.md