# CacheLane > MCP server from Aditya-Tripuraneni/CacheLane. - **Type:** MCP server - **Install:** `agentstack add mcp-aditya-tripuraneni-cachelane` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Aditya-Tripuraneni](https://agentstack.voostack.com/s/aditya-tripuraneni) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [Aditya-Tripuraneni](https://github.com/Aditya-Tripuraneni) - **Source:** https://github.com/Aditya-Tripuraneni/CacheLane - **Website:** https://cache-lane.vercel.app/ ## Install ```sh agentstack add mcp-aditya-tripuraneni-cachelane ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # CacheLane [](https://cache-lane.vercel.app/) [](https://nodejs.org) [](LICENSE) > **A local cache-discipline layer for Claude Code.** > > CacheLane sits between Claude Code and `api.anthropic.com` and reorganizes each turn's prompt so Anthropic's prompt cache fires far more often, then prunes stale tool output. The result is **30% to 60% lower input-token cost** on long sessions, with **zero change to how you use Claude Code**. > > 🌐 **Website:** [cache-lane.vercel.app](https://cache-lane.vercel.app/) --- ## Quickstart ```bash # 1. Install the CLI npm install -g cachelane # 2. Wire it into Claude Code (idempotent, safe to re-run) cachelane install # 3. Restart Claude Code so it picks up the new settings ``` **That's it.** You don't start a server, run a proxy, or change any commands. After the restart, CacheLane intercepts and optimizes every turn automatically. > ⚠️ **Do not run `cachelane proxy` yourself.** The proxy is started *for you* (see [How it works](#how-it-works)). Running it manually collides on port 7332 and crashes with `EADDRINUSE`. ### Verify it's working ```bash cachelane doctor # health check: node, config, db, mcp, hooks cachelane sessions # list recorded sessions + cache savings cachelane stats --scope session # stats for the current project's latest session ``` Run `cachelane stats` **from your project directory**. It scopes to that project automatically (see [Reading your stats](#reading-your-stats)). --- ## Why it saves money (the intuition) > **In one breath:** the Claude API is stateless, so Claude Code re-sends your whole conversation on every turn and you pay for it again and again. CacheLane marks the unchanging part with cache breakpoints so it stays identical and rides Anthropic's prompt cache at **one-tenth** the price, then trims stale tool output. The longer the session, the more you save. ### 1. The problem: the API is stateless Claude does not keep your conversation on Anthropic's servers between requests. The Messages API is **stateless**, which means the client (Claude Code) has to send the **entire** conversation again on every turn: ``` Turn 1 sends: [ system + tools ][ file ][ msg 1 ] Turn 2 sends: [ system + tools ][ file ][ msg 1 ][ reply ][ msg 2 ] Turn 3 sends: [ system + tools ][ file ][ msg 1 ][ reply ][ msg 2 ][ reply ][ msg 3 ] |............ the same stuff, re-sent every turn ............| ``` Normally you pay full price for all of it on every turn. That repetition is the waste CacheLane removes. > **Source:** Anthropic, [Using the Messages API](https://docs.anthropic.com/en/api/messages-examples): *"The Messages API is stateless, which means that you always send the full conversational history to the API."* New turns are added by **appending** to the `messages` array, so conversation cost grows with length. > > **"But Claude has a memory feature."** That is a different mechanism and it does not change the above. Memory tools and memory files work by saving notes to a file and then reading that file back **into the prompt** on later turns. The content still travels inside every request; the model is not recalling it from a saved server-side session. ### 2. The discount it chases Anthropic's prompt cache bills a *repeated prefix* at a fraction of the normal input price. The exact multipliers, straight from Anthropic's documentation: | Token type | Price vs. base input | |---|---| | Normal input (uncached) | **1×** | | Cache **write** (5-minute TTL) | **1.25×** | | Cache **write** (1-hour TTL) | **2×** | | Cache **read** (hit) | **0.1×** | > **Source:** Anthropic, [Prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching): *"5-minute cache write tokens are 1.25 times the base input tokens price; 1-hour cache write tokens are 2 times the base input tokens price; cache read tokens are 0.1 times the base input tokens price."* See also Anthropic [Pricing](https://docs.anthropic.com/en/docs/about-claude/pricing). The catch is in **how** the cache matches. Anthropic caches the **prefix** of a request up to a `cache_control` breakpoint, and a request reuses *"the longest prefix that a prior request already wrote to the cache."* The match stops at the first token that differs; everything after that point is billed at full price. New turns append to the **end** of the conversation, so the front is naturally stable. The thing that actually breaks caching is **volatile content sitting ahead of stable content**: a freshly injected tool result, a changing system reminder, or a block whose order or formatting shifts between turns. If any of that lands before your expensive stable content (system prompt, tool schemas, large files), the prefix diverges early and the stable content after it can no longer be served from cache. > **Source:** Anthropic, [Prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching): *"Cache writes happen only at your breakpoint. Marking a block with `cache_control` writes exactly one cache entry: a hash of the prefix ending at that block."* The system *"automatically find[s] the longest prefix that a prior request already wrote to the cache."* > > **What about Anthropic's _automatic caching_?** Anthropic can place one breakpoint for you — on the *last cacheable block*, advanced as the conversation grows, with a 20-block lookback ([Prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching)). But it still only *places a breakpoint*: it never reorders your prompt and never prunes idle content. CacheLane's breakpoint placement is on par with using native caching well — its **additional** savings come from K-pruning and keepalive (below), which the API has no equivalent for. ### 3. The trick: mark the cache boundaries (without moving anything) CacheLane classifies each request into three **volatility regions** and places two `cache_control` breakpoints at the boundaries. It does **not** reorder your conversation: the API already sends `system` and `tools` before `messages`, and new turns append to the end, so the stable material is naturally at the front. CacheLane only marks *where* the cache boundaries sit (and strips/replaces any breakpoints Claude Code already set): ``` +----------------------------------------+ | STABLE system prompt, tool schemas, | identical every turn | CLAUDE.md, pinned rules | -> billed at 0.1x | ============ cache breakpoint ======== | | SEMI recent turns + files read | | ============ cache breakpoint ======== | | VOLATILE your newest message + latest | the only genuinely new part | tool output | -> full price, but small +----------------------------------------+ ``` The expensive stable block sits at the front of every request by API structure and stays byte-identical, so the breakpoint lets Anthropic serve it from cache cheaply. The volatile material is already at the back — where its churn can't invalidate anything above it — so CacheLane never has to move it. Only the small new piece at the bottom pays full price. ### 4. Worked example: "read a file" Say the unchanging stuff (system + tools + the file) is **15,000 tokens**, and each new message is **500 tokens**. | Turn | What happens | Cost (token-units) | |------|--------------|--------------------| | 1 (read file X) | Nothing cached yet; the stable block is *written* to cache at 1.25× | `15,000×1.25 + 500` ≈ **19,250** | | 2 (explain `foo`) | Stable block is now a cache hit at 0.1× | `15,000×0.1 + 500` ≈ **2,000** | | 3, 4, 5 … | Same cheap path every turn | ≈ **2,000** each | Per-turn cost collapses after the first turn: ``` cost/turn 19k | # turn 1: pay once to seed the cache | 10k | | 2k | # # # # # # # # # every turn after: flat and cheap +------------------------------- 1 2 3 4 5 6 7 8 9 ... ``` > **"Read that file again"?** It's already in the cached front, so it costs 0.1×, basically free. You never re-pay full price for it. ### 5. Why the savings grow with session length (the math) Let `S` = the size of the **repeated** part of your prompt (system + tools + files already read), the part CacheLane keeps stable. Over `N` turns, what do you pay for that part? ``` Without caching: N x S (full 1x price, every turn) With CacheLane: 1.25 * S (write it once, on turn 1) + (N - 1) * 0.1*S (cheap 0.1x read, every turn after) ``` Divide the CacheLane cost by `N` to get the **average per-turn cost** (per unit of `S`): ``` 1.25*S + (N - 1)*0.1*S 1.15 ----------------------- = ( 0.1 + -------- ) * S N N ``` That single formula is the whole story (the multipliers `1.25` and `0.1` are the cited Anthropic rates above): | Turns `N` | avg per-turn cost | savings vs. full price | |-----------|-------------------|------------------------| | 1 | 1.25× | (just the write) | | 2 | 0.675× | ~32% | | 10 | 0.215× | ~78% | | 50 | 0.123× | ~88% | | large N | **0.1×** | **90% (the ceiling)** | As the session grows, the one-time `1.15/N` write cost shrinks toward zero and the average slides down to **0.1×**, i.e. a **90% discount** on the repeated part. That 90% is not a marketing number. It is exactly the cache-read multiplier (`0.1×`) from the table above, and it is the theoretical ceiling. Real sessions also carry a small always-full-price "new" part each turn plus the occasional cache miss, which pulls the *measured* number down to roughly **80%**, which is what `cachelane stats` reports in practice. Short chats sit low on this curve; long coding sessions ride near the top. ### 6. Keeping it lean: K-pruning and stubs Caching makes the prompt *cheap*, but a long session still makes it *big*. Old tool outputs and file dumps pile up after they stop being relevant. So CacheLane tracks how many turns each block goes untouched, and once a block has been idle for **K turns** (default `K = 3`) it swaps the full content for a tiny **stub**: ``` Claude Code sends: [ ...history... ][ 5,000-token file ][ new msg ] | idle for K turns v CacheLane substitutes (forwarded copy only) Anthropic receives: [ ...history... ][ stub: id + summary + expand() ][ new msg ] ``` K-pruning is **lossless and metadata-only**. Claude Code still holds the original and re-sends it every turn; CacheLane just masks it in the copy forwarded to Anthropic. If the model needs it back, it calls the `cachelane_expand` MCP tool, CacheLane flips that block from "stub" to "live", and the real content flows through again on the next turn. (Expanding is far cheaper than re-reading the file from scratch: the call carries just a block id, and it re-uses the existing cache entry instead of paying a fresh `1×` read **plus** a `1.25×` cache write for newly-read content.) ### 7. Why there's a database Placing breakpoints on one request needs no memory, but pruning and restoring are stateful across turns. So CacheLane keeps a local SQLite database (`~/.cachelane/cachelane.db`) holding metadata: - **Idle counters:** "this block has been untouched for 3 turns" is impossible to know without history. - **Stub state and refetch handles:** which blocks are currently masked, and how `cachelane_expand` puts them back. - **Prefix hashes:** to confirm the stable region really stayed byte-identical (so the cache will hit) and to detect drift. - **Keepalive state:** which sessions are idle and how big their prefix is. - **Stats:** token counts, hit ratios, and savings that power `cachelane stats`, `sessions`, and `explain`. - **Optional retained originals:** only when `compression.retention.enabled` is explicitly enabled, CacheLane may store original tool outputs locally so Claude can retrieve them through `cachelane_retrieve_tool_output`. By default CacheLane does not store prompts, code, or tool-output bodies. Enabling compression retention changes that privacy posture for tool outputs only; retained originals are scoped to the local workspace/session and expire according to `compression.retention.ttl_days`. ### 8. Keeping the cache warm (keepalive) Anthropic's cache lives about 5 minutes by default; a 1-hour tier is available at 2× write cost ([Prompt caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching)). If you step away mid-session, the cache would expire and your next turn would pay full price to re-seed it. So a keepalive worker sends a minimal synthetic ping (`max_tokens=1`) during idle gaps to keep the prefix hot, and CacheLane promotes large prefixes (≥ 50k tokens) to that 1-hour tier automatically. --- ## How it works `cachelane install` makes two edits to your Claude Code configuration: 1. **Registers an MCP server** in `~/.claude.json` (`mcpServers.cachelane`). Claude Code launches `cachelane mcp` automatically every time it starts. 2. **Redirects API traffic** by setting `ANTHROPIC_BASE_URL=http://127.0.0.1:7332` in `~/.claude/settings.json`. This is what routes Claude Code's requests through CacheLane. The `cachelane mcp` process does **two jobs in one process**: - Exposes MCP tools to Claude (`cachelane_stats`, `cachelane_explain`, `cachelane_expand`, `cachelane_health`). - Because `auto_proxy` is on by default, it **also starts the HTTP proxy** on `127.0.0.1:7332` in the same process. So a single auto-launched process owns everything. That's why you never start anything by hand, and why running `cachelane proxy` separately would fight it for the port. For each turn the proxy: 1. Intercepts the outgoing request from Claude Code. 2. Runs the pipeline (**compress tool outputs → classify → prune → place `cache_control` breakpoints**) — measured at ** ``` Sessions are keyed by Claude Code's own session id, so the value in the `cachelane sessions` table is exactly what `--session-id` expects. ### Per-block cost attribution (`explain --top-blocks`) `cachelane stats` shows aggregate savings, but it doesn't tell you *which blocks* are eating your budget. The `--top-blocks` flag on `explain` breaks that down: ```bash cachelane explain --top-blocks # top 10 blocks by token weight (default) cachelane explain --top-blocks 5 # top 5 cachelane explain --turn 3 --top-blocks 20 # specific turn, top 20 ``` Sample output: ``` Turn 42 — Top blocks by token weight Block ID Kind Region Tokens Tier Est. Cost ────────────────────────────────────────────────────────────────────────────────────────────────── block-2-file1 file_read STABLE 15000 cache_read 1500.0 cu block-3-file2 file_read SEMI 8500 cache_creation_5m 10625.0 cu block-6-tool2 tool_output VOLATILE 4500 input (1x) 4500.0 cu block-1-system system_prompt STABLE 4000 cache_read 400.0 cu block-4-tool tool_output SEMI 3200 cache_creation_5m 4000.0 cu block-5-user user_message VOLATILE 50 input (1x) 50.0 cu Region totals: STABLE : 19000 tokens → cache_read (0.1x) → 1900.0 cu SEMI : 11700 tokens → cache_creation_5m (1.25x/2x) → 14625.0 cu VOLATILE: 4550 tokens → input (1x) → 4550.0 cu Total effective: 21075.0 cu (vs. 35250.0 baseline — 40.2% savings) ``` Each block shows: - **Region**: which volatility bucket (STABLE / SEMI / VOLATILE) the block landed in. - **Tier**: the actual billing tier from the API response — `cache_read` (0.1×), `cache_creation_5m` (1.25×), `cache_creation_1h` (2×), or `input` (1×). - **Est. Cost**: token coun … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Aditya-Tripuraneni](https://github.com/Aditya-Tripuraneni) - **Source:** [Aditya-Tripuraneni/CacheLane](https://github.com/Aditya-Tripuraneni/CacheLane) - **License:** Apache-2.0 - **Homepage:** https://cache-lane.vercel.app/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-aditya-tripuraneni-cachelane - Seller: https://agentstack.voostack.com/s/aditya-tripuraneni - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.