Who token-optimizer-mcp is for#
Solo developers using Claude Code or Codex across long-running projects
Agents re-deriving architectural decisions, revisiting the same file repeatedly, and forgetting session conclusions are the primary cost drivers this tool targets. The knowledge graph captures those conclusions as a side effect of normal work, at about 150 tokens per finding versus the full re-derivation cost.
Skip if:
Your sessions are short and self-contained with no context carried between them. If each session starts fresh by design, graph delivery provides less value.
Teams maintaining multiple codebases with shared patterns
The cross-project graph scope pools findings from related repositories through opaque project IDs. When an agent working in one service touches a file pattern it has analyzed in a sibling service, relevant findings from that sibling are available without a separate lookup.
Skip if:
Your repositories have no meaningful shared patterns or architecture. Isolated codebases with unrelated domains see no cross-project benefit.
Developers measuring and reducing per-session AI costs
The dashboard tracks gross token reduction, net verified MCP transport savings, optional cost equivalents priced from provider receipts, and per-client attribution across all 16 supported clients. Each row shows what was avoided, what still reached the model, and what the graph cost to maintain.
Skip if:
Your primary goal is code generation quality, not context efficiency. Token Optimizer optimizes what reaches the model; it does not change the model's output behavior.
Engineering teams on corporate machines without external API access
The semantic harvest step can point at a local model endpoint, keeping all finding extraction on-machine with nothing sent externally. When no credential is configured, the server skips semantic harvest and uses the structural graph and derive-based findings, which require no outbound connection.
Skip if:
You are evaluating this for a managed cloud environment where installing local Node.js services or native CLI hooks is not permitted.
The problem it solves#
AI coding agents waste a disproportionate share of their context window on work they have already done. Reading an unchanged 200 KB file costs the full token load even when only three lines matter. Running an unbounded search returns thousands of results when one would do. And every session ends with all derived conclusions gone: the next session re-derives them from scratch, at full cost, every time.
The knowledge problem is separate from the file-reading problem. Even a well-tuned agent that avoids redundant reads still cannot remember what it worked out about a specific function three sessions ago. There is no place to store the finding "the skew fix was reverted once already" except in the active context, which gets summarized away. When the next agent session opens the same file, it starts over from zero.
How it solves it#
Zero-turn file read refusal
When an agent calls Read on a file it already accessed this session, the request is intercepted and only the diff against the cached version is returned inside the refusal. The agent does not need a second round-trip to get the answer. Turn cost drops from one full file load to zero.
Per-project knowledge graph
Nodes for files, symbols, tasks, and findings accumulate from ordinary agent traffic with no ingestion job and no rebuild step. Edges encode derived_from, contains, supersedes, contradicts, and related relationships. Carrying a finding costs about 150 tokens; re-deriving the same finding costs 5,000 to 50,000 tokens.
Per-agent token attribution
A local dashboard at localhost:3100 breaks down tokens avoided, context returned, and cost equivalents by client identity. Codex, Claude Code, and Gemini get separate rows. Old records without identity stay explicitly unattributed rather than being folded into whichever client is currently open.
Support for 16 CLI clients
Native adapters cover Claude Code, Codex, Gemini CLI, and 13 other AI coding clients. The MCP server adds model-visible tools to any compliant client; native adapters add lifecycle hooks, automatic routing, and capture health reporting for clients whose protocol supports it.
Honest measurement, no manufactured savings
Gross token savings and deliberate expansions are tracked separately. Graph substitution estimates stay apart from verified MCP transport savings. The dashboard does not manufacture a savings estimate from missing data; rows without enough evidence say Not measured or Collecting explicitly.
No telemetry, fully local
The graph, the ledger, and the diagnostic logs stay on the local machine. No session content, file paths, or tool output leave the host. The semantic harvest step that extracts findings from agent work can point at a local model endpoint, keeping every step private and on-machine.
Strengths and trade-offs#
Strengths
- Enforced at the tool layer, not advisoryThe file-read interception works at the plugin layer: the expensive call is blocked before the model makes it. Approaches that rely on the model choosing to call a smarter tool fail when the model is mid-task and ignoring system prompt instructions. Enforcement beats suggestion when the model is under pressure.
- Carries verdicts, not raw evidenceThe knowledge graph stores derived conclusions, not raw file chunks. Classic retrieval-augmented approaches return evidence the model must still interpret at full cost. Token Optimizer delivers the finished reasoning at about 150 tokens per finding, versus the 5,000 to 50,000 tokens it cost to produce originally.
- MIT license, commercial use allowedMIT means you can run it at work, include it in internal tooling, and modify it without restriction. No fair-code or source-available terms govern what you can do with your deployment. The README confirms commercial use is allowed.
- Staleness is computed, not hiddenWhen a graph finding is outdated, the system delivers it with the invalidating diff rather than serving the stale version silently. Content hashes drive invalidation. A finding that no longer applies is surfaced with the reason, not served as if it were still current.
Trade-offs
- -Node.js 22 or later requiredThe server requires Node.js 22 or later. Projects on older Node versions or environments that already pin a different Node version need to verify compatibility before adding the server to their tool chain.
- -Knowledge graph starts emptyThe graph accumulates from real agent traffic, not from a batch ingest of your codebase. Coverage follows attention: files the agent has never touched have no graph data, and new repositories need several sessions before graph delivery meaningfully reduces re-derivation costs.
- -Semantic harvest requires a model credential or local endpointThe model-based finding extraction path requires either an external API key or a locally running model endpoint. Without one it reports off:no-key and skips that path. The structural graph and derive-based findings still work without a credential, but semantic harvest coverage is absent until a model is configured.
token-optimizer-mcp vs alternatives#
Token Optimizer MCP vs Letta
Letta (formerly MemGPT) is a managed cloud service for persistent agent memory. Token Optimizer MCP solves an adjacent problem through a different mechanism and runs entirely on local infrastructure rather than a hosted service.
| Feature | Token Optimizer MCP | Letta (managed) |
|---|---|---|
| License | MIT | Proprietary |
| Deployment | Local, self-hosted | Managed cloud |
| Memory model | Knowledge graph (verdicts and traversal) | Virtual context (paging and archival) |
| Token accounting | Per-agent dashboard, measured | Not a product feature |
| Client support | 16 CLI coding clients | API-based agents |
| Telemetry | None | Cloud service |
| Cost | Free | Paid above free tier |
Token Optimizer MCP is the better choice for developers using CLI coding agents who want context optimization to run entirely locally. The tool intercepts operations at the plugin layer, blocking the expensive read before it happens. The knowledge graph stores verdicts (derived conclusions) rather than paged-in memories, so the agent receives finished reasoning at about 150 tokens per finding rather than raw evidence it must re-interpret at full cost.
Letta's managed cloud is the better fit when you need a hosted memory layer with no infrastructure to maintain, or when you are building custom agent pipelines via API rather than using CLI coding tools. Its paging and archival model handles very long agent conversations in ways that Token Optimizer MCP, focused on session-level coding tool optimization, does not address.
Install and self-host#
Install via npm to set up the token accounting server.
```bash
npm install @ooples/token-optimizer-mcp
```What it's built on#
- Languages
- JavaScriptTypeScript
- Frameworks
- Express
FAQ#
How does Token Optimizer MCP block redundant file reads?
When an agent calls Read on a file it already accessed this session, the plugin intercepts the call and returns only the diff against the cached version inside the refusal message. The full file never enters context. The agent does not need a second call because the diff arrives inside the refusal itself, dropping the turn cost to zero.
Does the knowledge graph send data to any external service?
No. The graph, ledger, and logs stay on the local machine. The semantic harvest step reports off:no-key when no credential is configured and skips entirely. Pointing it at a local model endpoint keeps every step on-machine with nothing sent externally at any stage.
How is the knowledge graph different from RAG?
Classic retrieval-augmented approaches retrieve evidence; the model re-derives meaning each time. The knowledge graph retrieves verdicts: the reasoning already happened, so the agent receives the finished conclusion rather than the raw content it was derived from. Retrieval uses graph traversal from the file being touched, not similarity search. Staleness is computed from content hashes rather than served silently.
How long does it take to build a useful knowledge graph?
The structural graph (files, symbols, tasks, and the edges between them) starts accumulating from the first session with no configuration. Finding coverage follows attention: files the agent has touched several times build up findings faster than untouched files. New repositories need several sessions before graph delivery meaningfully reduces re-derivation costs.
Does Token Optimizer MCP work with AI clients other than Claude Code?
Yes. Sixteen CLI clients are supported, including Codex and Gemini CLI. The MCP server adds model-visible tools to any compliant client; native adapters add lifecycle hooks and per-client attribution for clients whose protocol supports them. Clients without native hook support get MCP tools but not automatic routing or capture health reporting.
Similar open-source tools#
OpenCode
OpenCode is an open-source AI coding agent that assists developers in
leanctx
Drop-in LLM token compression. Code stays verbatim; prose compresses.
llama-swap
Hot-swap AI models on your local inference server
magnitude
Local models for your agent, tuned for your hardware
sie
One self-hosted cluster for all the models your agents need
heretic
Decensor local LLMs automatically with directional ablation