superlocalmemory 3.6.10 → 3.6.11

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to SuperLocalMemory V3 will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.6.11] - 2026-06-14 — Optimize Everywhere: three surfaces (proxy · MCP tools · skill)
+
+Cache + compress across **every setup** — proxy, MCP tools, or skill. Five new MCP tools land directly inside `slm mcp` (no proxy, full 1M context window preserved). A new `slm-optimize` skill makes compression and routed-result caching zero-config for Claude Code users. Overclaim in prior docs fixed; three-surfaces table added.
+
+### Added — Surface B: MCP Optimize Tools (proxy-free)
+
+Five new tools registered in `slm mcp` from v3.6.11+:
+
+- **`slm_compress`** — compress text or tool output. `mode=normalize` is lossless whitespace normalization; `mode=auto`/`aggressive` delegates to the existing CompressRouter engine. Lossy + reversible stores the original in CCR and returns a `ccr_id`. Content >1 MB is stored unreversed. All fail-open.
+- **`slm_retrieve`** — recover the exact original bytes from a `ccr_id` UUID4 returned by `slm_compress`. Validates UUID format before lookup.
+- **`slm_cache_set`** — cache any string result the agent routes through SLM (file reads, bash output, search results, sub-model calls). Key is SHA-256 namespaced `mcpkv:{agent_id}:{key}` — no cross-agent collisions. TTL default 24 h.
+- **`slm_cache_get`** — retrieve a cached result by key. Returns `hit:True/False`. Increments in-module `_kv_hits`/`_kv_misses` counters for stats.
+- **`slm_optimize_stats`** — session compression + cache statistics. Proxy counters read from `CacheDB.metrics_load()` (daemon-persisted, accurate across restarts); KV counters are in-module for this MCP process session.
+
+All five are **fail-open**: any internal error returns `{ok: False, note: <error>}` with the original content unchanged — never raises to the agent.
+
+### Added — Surface C: slm-optimize Skill (zero-config)
+
+- **`skills/slm-optimize/SKILL.md`** and **`ide/skills/slm-optimize/SKILL.md`** — agent-behavior instruction file. Eight behavioral rules: compress CLAUDE.md at session start, compress large tool outputs via `slm_compress`, KV-cache repeated file reads and bash/search results, recover originals with `slm_retrieve`, never-compress list (secrets, JSON, code/Edit/Write outputs), emit stats on request, fail-open on `ok:False`. Compatible with Claude Code, Cursor, Antigravity, Codex, and any IDE that supports MCP tool calls.
+- **`skills/slm-optimize/README.md`** — human install guide: prerequisites, install steps, activation options, feature table, and explicit "what it does NOT do" section.
+
+### Changed — `CacheDB` (new public method)
+
+- **`CacheDB.get_value(cache_key, tenant_id)`** added to `optimize/storage/db.py` — pure `SELECT` lookup with no `hit_count` side-effect (unlike `get()`). Used by `slm_cache_get` to avoid inflating proxy cache counters when agents read KV entries. Fail-open: returns `None` on any SQLite/decryption/zlib error.
+
+### Changed — MCP server registration
+
+- Five optimize tool names added to `_ESSENTIAL_TOOLS` frozenset in `mcp/server.py` (v3.6.11 Surface B). Without this the `_FilteredServer` wrapper silently drops tools whose names are not in the set.
+- `register_optimize_tools(_target)` call added after other `register_*` calls.
+
+### Fixed — Overclaim in README / docs
+
+- Replaced "Save up to 90% on every LLM API call" headline with accurate three-surfaces framing: proxy (full-turn caching on metered API), MCP tools (routed-result caching + compression), skill (auto-applied compression). Hard constraint documented: primary Claude conversation turn cannot be cached without a proxy — never implied otherwise.
+
 ## [3.6.10] - 2026-06-14 — Optimize correctness (cache + lossless compression) · MCP per-agent identity · runtime toggles · benchmark + shadow-capture · Issue #38
 
 This release makes the **Optimize** subsystem (the HTTP proxy that caches and compresses LLM API calls) correct, observable, and **independently controllable at runtime**, adds **per-agent identity** to the HTTP MCP transport, ships a **benchmark + shadow-capture** harness that proves the cache and compression behaviour, and fixes GitHub issue #38. Cache and compression remain **default-OFF** and are now separately toggleable from the dashboard.

package/README.md

@@ -2,18 +2,18 @@
   <img src="https://superlocalmemory.com/assets/logo-mark.png" alt="SuperLocalMemory" width="200"/>
 </p>
 
-<h1 align="center">SuperLocalMemory V3.6</h1>
-<p align="center"><strong>Save up to 90% on every LLM API call. Cache. Compress. Remember.</strong><br/><em>The only local-first memory system that SKIPS repeat calls (100% saved), SHRINKS prompts 60-95%, and REMEMBERS everything — locally, for free. For Claude Code, Cursor, Windsurf, and any AI client.</em></p>
-<p align="center"><code>v3.6.0 "Optimize"</code> — <strong>Cache & Compress & Align. Save up to 90% on every LLM API call — locally.</strong> One command: <code>slm wrap claude</code><br>Also includes v3.5 Scale-Ready: 6-channel recall &lt;1s, CozoDB + LanceDB, Core Memory Block. Your database auto-migrates.</p>
+<h1 align="center">SuperLocalMemory V3.6.11</h1>
+<p align="center"><strong>Cache. Compress. Remember. Three surfaces — proxy, MCP tools, or skill. Every setup covered.</strong><br/><em>The only local-first layer that pairs persistent memory with compression + caching across every Claude plan. Full 1M window preserved in MCP and skill mode.</em></p>
+<p align="center"><code>v3.6.11 "Optimize Everywhere"</code> — <strong>Compress + cache on any plan, three ways in.</strong><br/>Proxy (full-turn cache): <code>slm wrap claude</code> &nbsp;·&nbsp; MCP (proxy-free): add <code>slm_compress</code> to your MCP config &nbsp;·&nbsp; Skill (zero-config): <code>~/.claude/skills/slm-optimize/</code></p>
 <p align="center"><strong>Backed by 3 published research papers</strong> (arXiv preprints + Zenodo-archived) · <a href="https://arxiv.org/abs/2603.02240">arXiv:2603.02240</a> · <a href="https://arxiv.org/abs/2603.14588">arXiv:2603.14588</a> · <a href="https://arxiv.org/abs/2604.04514">arXiv:2604.04514</a></p>
 
 <p align="center">
-  <code>Saves up to 90% on LLM API costs</code> &nbsp;·&nbsp; <code>+10.6pp vs Mem0 zero-LLM</code> &nbsp;·&nbsp; <code>85% Open-Domain (best zero-LLM score)</code> &nbsp;·&nbsp; <code>EU AI Act Ready</code>
+  <code>Proxy · MCP tools · Skill — three surfaces</code> &nbsp;·&nbsp; <code>+10.6pp vs Mem0 zero-LLM</code> &nbsp;·&nbsp; <code>85% Open-Domain (best zero-LLM score)</code> &nbsp;·&nbsp; <code>EU AI Act Ready</code>
 </p>
 
 <p align="center">
   <a href="https://arxiv.org/abs/2603.14588"><img src="https://img.shields.io/badge/arXiv-2603.14588-b31b1b?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv Paper"/></a>
-  <a href="https://img.shields.io/badge/Saves_90%25_on_LLM_Costs-22c55e?style=for-the-badge"><img src="https://img.shields.io/badge/Saves_90%25_on_LLM_Costs-22c55e?style=for-the-badge" alt="Saves 90% on LLM Costs"/></a>
+  <a href="#three-surfaces-proxy--mcp-tools--skill"><img src="https://img.shields.io/badge/Proxy_|_MCP_|_Skill-22c55e?style=for-the-badge" alt="Three Surfaces: Proxy, MCP Tools, Skill"/></a>
   <a href="https://pypi.org/project/superlocalmemory/"><img src="https://img.shields.io/pypi/v/superlocalmemory?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"/></a>
   <a href="https://www.npmjs.com/package/superlocalmemory"><img src="https://img.shields.io/npm/v/superlocalmemory?style=for-the-badge&logo=npm&logoColor=white" alt="npm"/></a>
   <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/License-AGPL_v3-blue.svg?style=for-the-badge" alt="AGPL v3"/></a>
@@ -33,7 +33,9 @@
 <details>
 <summary><strong>What's New in V3.6 — Optimize: SKIP, SHRINK, DISCOUNT, REMEMBER</strong> (click to expand)</summary>
 
-> V3.6 is the only local-first layer that SKIPS repeat LLM calls (cache: 100% saved on a hit), SHRINKS prose prompts (compress: lossless-by-default, opt-in LLMLingua-2), and DISCOUNTS prefix costs (align: native KV-cache) — and remembers everything — in one install. **Your first cache hit pays for the install time. Hours of coding on repeat, minimal API cost.**
+> V3.6 is the only local-first layer that SKIPS repeat LLM calls (cache: 100% on a hit), SHRINKS tool outputs and injected context (compress: lossless-by-default, opt-in LLMLingua-2), and DISCOUNTS prefix costs (align: native KV-cache) — and remembers everything — in one install.
+>
+> **v3.6.11 "Optimize Everywhere":** Three surfaces. **Proxy** (Surface A) — full-turn cache + compress on transport; needs `ANTHROPIC_BASE_URL`, shrinks the context window. **MCP tools** (Surface B) — `slm_compress`, `slm_retrieve`, `slm_cache_set`, `slm_cache_get`, `slm_optimize_stats`; no proxy, no window shrink, works on any Claude subscription. **Skill** (Surface C) — `slm-optimize` installs in `~/.claude/skills/`; zero-config auto-compress for large tool outputs and CLAUDE.md. No proxy, full 1M window. [See Three Surfaces →](#three-surfaces-proxy--mcp-tools--skill)
 >
 > **v3.6.10:** cache and compression are now **independent runtime switches** (cache-only, compress-only, both, or neither — toggle live from the dashboard, no restart). Compression was rebuilt to be **lossless by default** (the old string/array/code truncation is gone); aggressive mode adds LLMLingua-2 for **prose only** — never code, numbers, structured data, or the current turn.
 
@@ -120,6 +122,57 @@ Full docs:
 
 ---
 
+## Three Surfaces: Proxy · MCP Tools · Skill
+
+v3.6.11 delivers one engine across **three ways in** — choose the surface that fits your setup:
+
+| Surface | How you use it | Requires proxy? | Window effect | Cache scope |
+|---------|---------------|:---------------:|:-------------:|-------------|
+| **A — Proxy** | `slm wrap claude` or `ANTHROPIC_BASE_URL=http://127.0.0.1:8765` | **Yes** | Shrinks (proxy intercepts full context) | Full-turn cache — every Claude call |
+| **B — MCP tools** | Add 5 tools to MCP config; call `slm_compress`, `slm_cache_set/get` | **No** | **Preserved** (full 1M) | Results you explicitly route through SLM |
+| **C — Skill** | Copy `skills/slm-optimize/SKILL.md` → `~/.claude/skills/` | **No** | **Preserved** (full 1M) | Auto-applied by the agent per skill rules |
+
+**How to choose:**
+- On a **metered API** (pay-per-token) and want to cache every call → **Proxy (A)**
+- On a **Pro/Max/Team subscription** or any plan where you can't or won't run a proxy → **MCP tools (B)** or **Skill (C)**
+- Want zero configuration → **Skill (C)**: install once, auto-compresses CLAUDE.md and large outputs
+- Want agent-controlled caching of repeated file reads and tool outputs → **MCP tools (B)**
+
+**The hard constraint:** The primary Claude conversation turn cannot be cached without a proxy — the MCP/skill path caches results you explicitly route through SLM (tool outputs, file reads, sub-model calls).
+
+### MCP Tools Setup (Surface B)
+
+Add to your `claude_desktop_config.json` or IDE MCP config alongside your existing SLM entry:
+
+```json
+{
+  "mcpServers": {
+    "superlocalmemory": {
+      "command": "slm",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+The 5 optimize tools (`slm_compress`, `slm_retrieve`, `slm_cache_set`, `slm_cache_get`, `slm_optimize_stats`) are included automatically from v3.6.11+. Verify with `slm_optimize_stats()`.
+
+### Skill Setup (Surface C)
+
+```bash
+mkdir -p ~/.claude/skills/slm-optimize
+cp $(pip show superlocalmemory | grep Location | awk '{print $2}')/superlocalmemory/skills/slm-optimize/SKILL.md \
+   ~/.claude/skills/slm-optimize/SKILL.md
+```
+
+Then reference in your `CLAUDE.md`:
+```markdown
+## Context Management
+Use the `slm-optimize` skill to compress large outputs and cache repeated reads.
+```
+
+---
+
 <details>
 <summary><strong>What's New in V3.3 — The Living Brain Evolves</strong> (click to expand)</summary>
 
@@ -296,6 +349,7 @@ No manual commands. No data loss. Zero downtime.
 
 | Version | Codename | Key Features |
 |---|---|---|
+| **v3.6.11** | Optimize Everywhere | **Three surfaces** — Proxy (A: full-turn cache), MCP tools (B: `slm_compress`/`slm_retrieve`/`slm_cache_set`/`slm_cache_get`/`slm_optimize_stats` — proxy-free, 1M window), Skill (C: `slm-optimize` zero-config). `CacheDB.get_value()` (pure KV lookup). 23 new tests. Links: [Three Surfaces →](#three-surfaces-proxy--mcp-tools--skill) · [docs/optimize-overview.md](docs/optimize-overview.md) |
 | **v3.6.0** | Optimize | **Cache** (skip repeat calls, 100% on hit) · **Compress** (shrink prompts 60-95%) · **Align** (KV-cache stabilization) · `slm optimize\|cache\|compress\|proxy\|wrap` CLI · Live savings dashboard (USD/INR/tokens) · Hot-reload config · Safe defaults · Links: [docs/optimize-overview.md](docs/optimize-overview.md) · [V3.6 Wiki](https://github.com/qualixar/superlocalmemory/wiki/V3.6-Overview) |
 | **v3.5.0** | Scale-Ready + Context Injection v2 | CozoDB/LanceDB migration, 6-channel recall <1s, Core Memory Block, BM25→FTS5, context injection v2, score normalization |
 | **v3.4.5** | Scale-Ready (foundation) | Tiered storage (active/warm/cold), graph pruning, BackendOrchestrator scaffolding, CozoDB + LanceDB init + migration code (read path wired in v3.5.0) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.6.10",
+  "version": "3.6.11",
   "description": "Information-geometric agent memory with mathematical guarantees. 4-channel retrieval, Fisher-Rao similarity, zero-LLM mode, EU AI Act compliant. Works with Claude, Cursor, Windsurf, and 17+ AI tools.",
   "keywords": [
     "ai-memory",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.6.10"
+version = "3.6.11"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}

package/skills/slm-optimize/README.md

@@ -0,0 +1,55 @@
+# slm-optimize — Context Optimizer Skill
+
+Automatically compresses large tool outputs and caches repeated reads, reducing
+context window usage without a proxy and without losing the full 1M window.
+
+## Prerequisites
+
+- SuperLocalMemory v3.6.11+
+- `slm mcp` daemon running
+- `slm_compress` visible in `tools/list` (verify with your IDE's MCP tool inspector)
+
+## Install (Claude Code)
+
+```bash
+cp skills/slm-optimize/SKILL.md ~/.claude/skills/slm-optimize/SKILL.md
+```
+
+## Activate
+
+**Option A — On demand:**
+Invoke via the `Skill` tool: `Skill("slm-optimize")`
+
+**Option B — Auto-activate:**
+Add to your project or global `CLAUDE.md`:
+```markdown
+## Context Management
+Use the `slm-optimize` skill to compress large outputs and cache repeated reads.
+Invoke at session start if context > 50k tokens.
+```
+
+## Verify
+
+After activation, run `slm_optimize_stats()` from Claude Code. If it returns `ok:True`,
+all 5 optimize tools are reachable and the skill is working.
+
+## What it does
+
+| Feature | How |
+|---|---|
+| Compresses large tool outputs | `slm_compress` → compressed text + optional `ccr_id` |
+| Caches repeated file reads | `slm_cache_set` / `slm_cache_get` keyed by file path |
+| Caches repeated bash/search | Same KV tools, keyed by command |
+| Recovers exact originals | `slm_retrieve(ccr_id)` when byte-identical content needed |
+| Session stats | `slm_optimize_stats()` |
+
+## What it does NOT do
+
+- **Full-turn caching**: impossible without a proxy (`ANTHROPIC_BASE_URL`).
+  Use Surface A (proxy mode) for that.
+- **Guarantee savings**: results depend on content type and daemon compress config.
+
+## For Cursor, Antigravity, Codex
+
+Same SKILL.md works — all IDEs that support MCP tool calls can use the 5 tools.
+The skill itself is pure Markdown with no IDE-specific code.

package/skills/slm-optimize/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: slm-optimize
+description: >
+  Context optimizer for Claude Code + SLM. Compresses large outputs via
+  slm_compress (reversible CCR), caches repeated reads via slm_cache_set/get,
+  recovers originals via slm_retrieve. Works on any Claude plan, no proxy,
+  full context window preserved.
+  Requires SuperLocalMemory v3.6.11+ with optimize MCP tools enabled.
+version: "3.6.11"
+license: AGPL-3.0-or-later
+triggers:
+  - "slm-optimize"
+  - "compress context"
+  - "optimize context"
+  - "reduce tokens"
+---
+
+# slm-optimize: Context Optimizer for Claude Code
+
+Reduces context window usage through compression and caching.
+No proxy required. Full 1M window preserved.
+
+**What this skill does NOT do:**
+- Cache the primary Claude conversation turn (impossible without a proxy).
+- Guarantee any specific savings percentage — results depend on content type and daemon config.
+
+---
+
+## When This Skill Is Active
+
+Apply these rules automatically throughout the session once this skill is loaded.
+
+---
+
+## Decision Rules
+
+### RULE 1 — Session start: compress CLAUDE.md if large
+
+At the start of any session where this skill is loaded:
+1. Read `CLAUDE.md` (or project CLAUDE.md).
+2. If `len(content) > 3000` characters: call `slm_compress(content=<text>, mode="normalize", reversible=False)`.
+3. Replace the in-context CLAUDE.md block with the compressed version.
+4. **Do not modify the actual file** — compress only the in-context representation.
+
+### RULE 2 — Large tool output: compress before processing
+
+After any tool call that returns > 2000 characters:
+1. Call `slm_compress(content=<output>, mode="auto", reversible=True)`.
+2. Work from `compressed` in the response.
+3. If `lossy=True`, store the returned `ccr_id` — call `slm_retrieve` only if you need the exact original for verification, diffing, or code parsing.
+
+**Never compress** (see RULE 6 for the complete exclusion list).
+
+### RULE 3 — Repeated file reads: KV cache
+
+Before calling `Read(file_path)` for a file you have already read this session:
+1. `slm_cache_get(key=f"file:{file_path}")`.
+2. If `hit=True` → use `value` directly. Skip the `Read` call.
+3. If `hit=False` → call `Read`, then `slm_cache_set(key=f"file:{file_path}", value=<content>, ttl_seconds=1800)`.
+
+If you edit a file via Edit/Write, immediately update or invalidate the cache entry.
+
+### RULE 4 — Repeated bash/search results: KV cache
+
+For any Bash or WebSearch call whose result you expect to reuse:
+1. `slm_cache_set(key=f"bash:{command[:64]}", value=<output>, ttl_seconds=600)`.
+2. On the next identical call: `slm_cache_get` first.
+
+Use `ttl_seconds=3600` for web search results (more expensive to re-run).
+
+### RULE 5 — Retrieve original via slm_retrieve
+
+If you compressed content with `lossy=True` and need the exact original:
+1. Call `slm_retrieve(ccr_id=<ccr_id from prior compress response>)`.
+2. Check `size_bytes` before retrieving if context is nearly full.
+3. Do not retrieve unless you actually need byte-identical content.
+
+### RULE 6 — What NOT to compress or cache
+
+- **Code being sent to Edit/Write**: never compress — the editor needs exact bytes.
+- **JSON or structured data you will parse**: compression can alter whitespace and break parsers.
+- **Secrets, API keys, credentials, tokens**: never store via `slm_cache_set`.
+- **CCR IDs**: never cache via `slm_cache_set` — treat as ephemeral session values.
+- **Very short outputs (< 500 chars)**: compression overhead exceeds the gain.
+
+### RULE 7 — Stats and awareness
+
+If the user asks "how much context have you saved?" or "what is the optimization status?":
+1. Call `slm_optimize_stats()`.
+2. Report `cache_kv_hits`, `compress_runs`, and `tokens_saved_compress` clearly.
+3. Note that proxy stats are daemon-persisted; KV stats are this session only.
+
+### RULE 8 — Fail-open behavior
+
+If any `slm_compress`, `slm_retrieve`, `slm_cache_set`, `slm_cache_get`, or
+`slm_optimize_stats` call returns `ok:False`:
+- Continue with the original (uncompressed/uncached) content.
+- Do not retry. Do not surface the error unless the user asks about optimization.
+- Optimization is always advisory — it must never block any primary task.
+
+---
+
+## Examples
+
+### Compress a large file read
+
+```
+# Instead of working with 8000-char file output directly:
+result = slm_compress(content=<file_content>, mode="auto", reversible=True)
+# Work from result["compressed"]; keep result["ccr_id"] if lossy=True
+```
+
+### Cache a repeated grep result
+
+```
+cached = slm_cache_get(key="bash:grep -rn MyClass src/")
+if not cached["hit"]:
+    output = Bash("grep -rn MyClass src/")
+    slm_cache_set(key="bash:grep -rn MyClass src/", value=output, ttl_seconds=600)
+```
+
+### Recover original when needed
+
+```
+original = slm_retrieve(ccr_id=<ccr_id>)
+# original["content"] is byte-identical to what was compressed
+```
+
+---
+
+## Stats and Troubleshooting
+
+Run `slm_optimize_stats()` to see current session counters.
+
+If tools return `ok:False`, the daemon may be down or the optimize module may not be
+configured. Continue with normal tool calls — this skill degrades gracefully.
+
+Verify tools are available: check that `slm_compress` appears in your MCP `tools/list`.
+Requires SuperLocalMemory v3.6.11+ with `slm mcp` running.

package/src/superlocalmemory/mcp/server.py

@@ -104,6 +104,8 @@ _ESSENTIAL_TOOLS: set[str] = {
     "reinforce_assertion", "contradict_assertion",
     # v3.4.11: Skill evolution (3)
     "evolve_skill", "skill_health", "skill_lineage",
+    # v3.6.11: Surface B Optimize tools (5)
+    "slm_compress", "slm_retrieve", "slm_cache_set", "slm_cache_get", "slm_optimize_stats",
 }
 
 # v3.4.4: Mesh tools — enabled if mesh_enabled in config or SLM_MCP_MESH_TOOLS=1
@@ -189,6 +191,8 @@ register_code_graph_tools(_target, get_engine)  # CodeGraph: filtered like other
 register_mesh_tools(_target, get_engine)  # v3.4.4: Mesh P2P tools — ships with SLM, no separate slm-mesh needed
 register_learning_tools(_target, get_engine)  # v3.4.7: Two-way learning tools
 register_evolution_tools(_target, get_engine)  # v3.4.11: Skill evolution tools
+from superlocalmemory.mcp.tools_optimize import register_optimize_tools
+register_optimize_tools(_target)  # v3.6.11: Surface B Optimize tools (proxy-free)
 
 
 # V3.3.21: Eager engine warmup — start initializing BEFORE first tool call.

package/src/superlocalmemory/mcp/tools_optimize.py

@@ -0,0 +1,304 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
+
+"""SLM v3.6.11 — Surface B: MCP Optimize Tools.
+
+Five proxy-free tools exposing compression (reversible via CCR) and
+routed-result caching WITHOUT touching ANTHROPIC_BASE_URL, so the full
+1M context window is preserved on any Claude subscription.
+
+Primary Claude conversation turns CANNOT be cached without a proxy.
+These tools cache results the agent explicitly routes through SLM.
+
+Fail-open: every tool body is wrapped in try/except Exception.
+Any internal error returns the input unchanged with ok:False — never raises.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import threading
+import time
+
+from mcp.types import ToolAnnotations
+
+from superlocalmemory.mcp.agent_context import get_current_agent_id
+from superlocalmemory.optimize.compress.ccr import CCRStore, _UUID4_RE
+from superlocalmemory.optimize.compress.router import CompressRouter
+from superlocalmemory.optimize.storage.db import CacheDB, _normalize_tenant_id
+
+logger = logging.getLogger("slm.mcp.tools_optimize")
+
+# ─── Size caps (CWE-400 guards) ───────────────────────────────────────────────
+
+_MAX_COMPRESS_BYTES: int = 1_000_000
+_MAX_KV_VALUE_BYTES: int = 1_000_000
+_MAX_KV_KEY_CHARS: int = 512
+
+# ─── Exported tool name list (used by server.py + tests) ─────────────────────
+
+_OPTIMIZE_TOOL_NAMES = (
+    "slm_compress",
+    "slm_retrieve",
+    "slm_cache_set",
+    "slm_cache_get",
+    "slm_optimize_stats",
+)
+
+# ─── In-module KV counters (thread-safe; MetricsCollector is process-scoped) ─
+
+_kv_lock = threading.Lock()
+_kv_hits: int = 0
+_kv_misses: int = 0
+
+
+def _tenant() -> str:
+    # get_current_agent_id() never returns ""; "mcp_client" is its stdio sentinel.
+    return get_current_agent_id()
+
+
+# ─── Tool registration ────────────────────────────────────────────────────────
+
+
+def register_optimize_tools(server) -> None:
+    """Register the 5 Surface B optimize tools on *server*.
+
+    *server* is duck-typed: must support @server.tool() decorator pattern.
+    Compatible with FastMCP, _FilteredServer, and test _MockServer.
+    """
+
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False))
+    async def slm_compress(
+        content: str,
+        mode: str = "auto",
+        reversible: bool = True,
+        ttl_seconds: int = 86400,
+    ) -> dict:
+        """Compress text or tool output to reduce context window usage.
+
+        Returns compressed text. If lossy and reversible=True, also returns a
+        ccr_id — pass it to slm_retrieve to recover the exact original.
+
+        Args:
+            content: Text to compress (max 1MB).
+            mode: "normalize" (lossless whitespace) | "auto" | "aggressive".
+            reversible: Store original in CCR for later retrieval.
+            ttl_seconds: CCR lifetime in seconds (default 24h).
+        """
+        try:
+            if not isinstance(content, str) or not content:
+                return {
+                    "ok": False, "compressed": content or "",
+                    "strategy": "none", "tokens_before": 0, "tokens_after": 0,
+                    "ratio": 1.0, "lossy": False, "ccr_id": None,
+                    "note": "empty input",
+                }
+
+            note_parts: list[str] = []
+            if len(content.encode("utf-8")) > _MAX_COMPRESS_BYTES:
+                reversible = False
+                note_parts.append("content over 1MB: ccr skipped")
+
+            if mode == "normalize":
+                # @staticmethod — lossless whitespace collapse, no config/daemon dep.
+                normalized = CompressRouter._normalize_whitespace(content)
+                tb = len(content.split())
+                ta = len(normalized.split())
+                ratio = round(ta / tb, 4) if tb else 1.0
+                return {
+                    "ok": True, "compressed": normalized, "strategy": "normalize",
+                    "tokens_before": tb, "tokens_after": ta, "ratio": ratio,
+                    "lossy": False, "ccr_id": None,
+                    "note": " | ".join(note_parts) or None,
+                }
+
+            if mode == "aggressive":
+                note_parts.append(
+                    "aggressive mode requires daemon compress_mode=aggressive in config"
+                )
+
+            res = CompressRouter.get_instance().compress_text(content)
+
+            ccr_id = None
+            if res.lossy and reversible:
+                stored = CCRStore.get_instance().store(
+                    content.encode("utf-8"),
+                    tenant_id=_tenant(),
+                    ttl_seconds=ttl_seconds,
+                )
+                ccr_id = stored or None
+                if ccr_id:
+                    note_parts.append("reversible: call slm_retrieve with this ccr_id")
+
+            ratio = (
+                round(res.tokens_after / res.tokens_before, 4)
+                if res.tokens_before else 1.0
+            )
+            return {
+                "ok": True, "compressed": res.compressed_text, "strategy": res.strategy,
+                "tokens_before": res.tokens_before, "tokens_after": res.tokens_after,
+                "ratio": ratio, "lossy": res.lossy, "ccr_id": ccr_id,
+                "note": " | ".join(note_parts) or None,
+            }
+
+        except Exception as exc:
+            logger.error("slm_compress failed (fail-open): %s", exc)
+            t = len(content.split()) if isinstance(content, str) else 0
+            return {
+                "ok": False,
+                "compressed": content if isinstance(content, str) else "",
+                "strategy": "none", "tokens_before": t, "tokens_after": t,
+                "ratio": 1.0, "lossy": False, "ccr_id": None,
+                "note": f"internal error: {exc}",
+            }
+
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    async def slm_retrieve(ccr_id: str) -> dict:
+        """Retrieve original text stored during a lossy slm_compress call.
+
+        Do not log or share ccr_ids — they are unguessable session tokens, but
+        if exposed they allow retrieval by anyone with the daemon's decryption key.
+
+        Args:
+            ccr_id: UUID4 returned by slm_compress when reversible=True.
+        """
+        try:
+            if not ccr_id or not _UUID4_RE.match(ccr_id):
+                return {
+                    "ok": False, "content": None, "size_bytes": 0,
+                    "error": "ccr_id must be a UUID4",
+                }
+            original = CCRStore.get_instance().retrieve(ccr_id)
+            if original is None:
+                return {
+                    "ok": False, "content": None, "size_bytes": 0,
+                    "error": "not found (expired / never stored / wrong id)",
+                }
+            size = len(original)
+            try:
+                text = original.decode("utf-8")
+            except UnicodeDecodeError:
+                text = original.decode("latin-1")
+            return {"ok": True, "content": text, "size_bytes": size, "error": None}
+
+        except Exception as exc:
+            logger.error("slm_retrieve failed (fail-open): %s", exc)
+            return {
+                "ok": False, "content": None, "size_bytes": 0,
+                "error": f"internal error: {exc}",
+            }
+
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False))
+    async def slm_cache_set(key: str, value: str, ttl_seconds: int = 86400) -> dict:
+        """Cache a result you want to reuse (tool output, file read, search result).
+
+        This caches results the agent explicitly routes through SLM — NOT the
+        Claude conversation turn (impossible without a proxy).
+
+        Do not cache secrets, credentials, or ccr_ids via this tool.
+
+        Args:
+            key: Cache key (max 512 chars). Namespaced per agent automatically.
+            value: Value to store as string (max 1MB).
+            ttl_seconds: Time-to-live in seconds (default 24h).
+        """
+        try:
+            if not key or len(key) > _MAX_KV_KEY_CHARS:
+                return {
+                    "ok": False, "stored": False,
+                    "note": f"key must be 1–{_MAX_KV_KEY_CHARS} chars",
+                }
+            value_bytes = value.encode("utf-8")
+            if len(value_bytes) > _MAX_KV_VALUE_BYTES:
+                return {"ok": False, "stored": False, "note": "value exceeds 1MB limit"}
+
+            tenant = _tenant()
+            cache_key = hashlib.sha256(f"mcpkv:{tenant}:{key}".encode()).hexdigest()
+            norm_tid = _normalize_tenant_id(tenant)
+            ttl_exp = time.time() + ttl_seconds
+
+            CacheDB.get_default().set(
+                cache_key, norm_tid, value_bytes,
+                model="mcp-kv", ttl_expires=ttl_exp, tags=["mcp-kv"],
+            )
+            return {"ok": True, "stored": True, "note": None}
+
+        except Exception as exc:
+            logger.error("slm_cache_set failed (fail-open): %s", exc)
+            return {"ok": False, "stored": False, "note": f"internal error: {exc}"}
+
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    async def slm_cache_get(key: str) -> dict:
+        """Retrieve a previously cached result.
+
+        Returns hit:True + value if the key exists and has not expired.
+        Returns hit:False (never raises) on miss, expiry, or any error.
+
+        Args:
+            key: Cache key used in slm_cache_set.
+        """
+        global _kv_hits, _kv_misses
+        try:
+            if not key or len(key) > _MAX_KV_KEY_CHARS:
+                return {
+                    "ok": False, "hit": False, "value": None,
+                    "note": f"key must be 1–{_MAX_KV_KEY_CHARS} chars",
+                }
+            tenant = _tenant()
+            cache_key = hashlib.sha256(f"mcpkv:{tenant}:{key}".encode()).hexdigest()
+            norm_tid = _normalize_tenant_id(tenant)
+
+            blob = CacheDB.get_default().get_value(cache_key, norm_tid)
+            if blob is None:
+                with _kv_lock:
+                    _kv_misses += 1
+                return {"ok": True, "hit": False, "value": None, "note": None}
+            with _kv_lock:
+                _kv_hits += 1
+            return {"ok": True, "hit": True, "value": blob.decode("utf-8"), "note": None}
+
+        except Exception as exc:
+            logger.error("slm_cache_get failed (fail-open): %s", exc)
+            return {
+                "ok": False, "hit": False, "value": None,
+                "note": f"internal error: {exc}",
+            }
+
+    @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    async def slm_optimize_stats() -> dict:
+        """Return compression and cache statistics.
+
+        Proxy/compress stats are daemon-persisted (accurate across restarts).
+        KV stats are in-module counters for this MCP process session only.
+        """
+        try:
+            snap = CacheDB.get_default().metrics_load()
+            with _kv_lock:
+                kv_h = _kv_hits
+                kv_m = _kv_misses
+            return {
+                "ok": True,
+                "compress_runs": snap.compress_runs,
+                "tokens_saved_compress": snap.tokens_saved_compress,
+                "cache_proxy_hits": snap.hits,
+                "cache_proxy_misses": snap.misses,
+                "cache_kv_hits": kv_h,
+                "cache_kv_misses": kv_m,
+                "ccr_note": (
+                    "CCR entry count not tracked per-session; "
+                    "see daemon /api/v1/metrics"
+                ),
+                "note": "proxy stats are daemon-persisted; kv stats are this session only",
+            }
+        except Exception as exc:
+            logger.error("slm_optimize_stats failed (fail-open): %s", exc)
+            return {
+                "ok": False,
+                "compress_runs": 0, "tokens_saved_compress": 0,
+                "cache_proxy_hits": 0, "cache_proxy_misses": 0,
+                "cache_kv_hits": 0, "cache_kv_misses": 0,
+                "ccr_note": None,
+                "note": f"internal error: {exc}",
+            }

package/src/superlocalmemory/optimize/storage/db.py

@@ -421,6 +421,30 @@ class CacheDB:
             logger.warning("CacheDB.get failed (cache miss): %s", exc)
             return None
 
+    def get_value(self, cache_key: str, tenant_id: str) -> bytes | None:
+        """Pure value lookup — no hit_count increment (unlike get()).
+
+        Used by MCP KV tools which manage their own hit/miss counters.
+        Caller must have already normalized tenant_id. Fail-open: returns None on error.
+        """
+        try:
+            rows = self._db.execute(
+                "SELECT value_blob, compressed FROM llmcache_entries "
+                "WHERE cache_key = ? AND tenant_id = ? "
+                "AND (ttl_expires IS NULL OR ttl_expires > ?) LIMIT 1",
+                (cache_key, tenant_id, time.time()),
+            )
+            if not rows:
+                return None
+            row = dict(rows[0])
+            plaintext = self._decrypt(row["value_blob"])
+            if row.get("compressed", 0):
+                plaintext = zlib.decompress(plaintext)
+            return plaintext
+        except (sqlite3.Error, ValueError, zlib.error) as exc:
+            logger.warning("CacheDB.get_value failed (fail-open): %s", exc)
+            return None
+
     def set(
         self,
         key: str,

package/src/superlocalmemory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superlocalmemory
-Version: 3.6.10
+Version: 3.6.11
 Summary: Information-geometric agent memory with mathematical guarantees
 Author-email: Varun Pratap Bhardwaj <admin@superlocalmemory.com>
 License: AGPL-3.0-or-later
@@ -95,18 +95,18 @@ Dynamic: license-file
   <img src="https://superlocalmemory.com/assets/logo-mark.png" alt="SuperLocalMemory" width="200"/>
 </p>
 
-<h1 align="center">SuperLocalMemory V3.6</h1>
-<p align="center"><strong>Save up to 90% on every LLM API call. Cache. Compress. Remember.</strong><br/><em>The only local-first memory system that SKIPS repeat calls (100% saved), SHRINKS prompts 60-95%, and REMEMBERS everything — locally, for free. For Claude Code, Cursor, Windsurf, and any AI client.</em></p>
-<p align="center"><code>v3.6.0 "Optimize"</code> — <strong>Cache & Compress & Align. Save up to 90% on every LLM API call — locally.</strong> One command: <code>slm wrap claude</code><br>Also includes v3.5 Scale-Ready: 6-channel recall &lt;1s, CozoDB + LanceDB, Core Memory Block. Your database auto-migrates.</p>
+<h1 align="center">SuperLocalMemory V3.6.11</h1>
+<p align="center"><strong>Cache. Compress. Remember. Three surfaces — proxy, MCP tools, or skill. Every setup covered.</strong><br/><em>The only local-first layer that pairs persistent memory with compression + caching across every Claude plan. Full 1M window preserved in MCP and skill mode.</em></p>
+<p align="center"><code>v3.6.11 "Optimize Everywhere"</code> — <strong>Compress + cache on any plan, three ways in.</strong><br/>Proxy (full-turn cache): <code>slm wrap claude</code> &nbsp;·&nbsp; MCP (proxy-free): add <code>slm_compress</code> to your MCP config &nbsp;·&nbsp; Skill (zero-config): <code>~/.claude/skills/slm-optimize/</code></p>
 <p align="center"><strong>Backed by 3 published research papers</strong> (arXiv preprints + Zenodo-archived) · <a href="https://arxiv.org/abs/2603.02240">arXiv:2603.02240</a> · <a href="https://arxiv.org/abs/2603.14588">arXiv:2603.14588</a> · <a href="https://arxiv.org/abs/2604.04514">arXiv:2604.04514</a></p>
 
 <p align="center">
-  <code>Saves up to 90% on LLM API costs</code> &nbsp;·&nbsp; <code>+10.6pp vs Mem0 zero-LLM</code> &nbsp;·&nbsp; <code>85% Open-Domain (best zero-LLM score)</code> &nbsp;·&nbsp; <code>EU AI Act Ready</code>
+  <code>Proxy · MCP tools · Skill — three surfaces</code> &nbsp;·&nbsp; <code>+10.6pp vs Mem0 zero-LLM</code> &nbsp;·&nbsp; <code>85% Open-Domain (best zero-LLM score)</code> &nbsp;·&nbsp; <code>EU AI Act Ready</code>
 </p>
 
 <p align="center">
   <a href="https://arxiv.org/abs/2603.14588"><img src="https://img.shields.io/badge/arXiv-2603.14588-b31b1b?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv Paper"/></a>
-  <a href="https://img.shields.io/badge/Saves_90%25_on_LLM_Costs-22c55e?style=for-the-badge"><img src="https://img.shields.io/badge/Saves_90%25_on_LLM_Costs-22c55e?style=for-the-badge" alt="Saves 90% on LLM Costs"/></a>
+  <a href="#three-surfaces-proxy--mcp-tools--skill"><img src="https://img.shields.io/badge/Proxy_|_MCP_|_Skill-22c55e?style=for-the-badge" alt="Three Surfaces: Proxy, MCP Tools, Skill"/></a>
   <a href="https://pypi.org/project/superlocalmemory/"><img src="https://img.shields.io/pypi/v/superlocalmemory?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI"/></a>
   <a href="https://www.npmjs.com/package/superlocalmemory"><img src="https://img.shields.io/npm/v/superlocalmemory?style=for-the-badge&logo=npm&logoColor=white" alt="npm"/></a>
   <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/License-AGPL_v3-blue.svg?style=for-the-badge" alt="AGPL v3"/></a>
@@ -126,7 +126,9 @@ Dynamic: license-file
 <details>
 <summary><strong>What's New in V3.6 — Optimize: SKIP, SHRINK, DISCOUNT, REMEMBER</strong> (click to expand)</summary>
 
-> V3.6 is the only local-first layer that SKIPS repeat LLM calls (cache: 100% saved on a hit), SHRINKS prose prompts (compress: lossless-by-default, opt-in LLMLingua-2), and DISCOUNTS prefix costs (align: native KV-cache) — and remembers everything — in one install. **Your first cache hit pays for the install time. Hours of coding on repeat, minimal API cost.**
+> V3.6 is the only local-first layer that SKIPS repeat LLM calls (cache: 100% on a hit), SHRINKS tool outputs and injected context (compress: lossless-by-default, opt-in LLMLingua-2), and DISCOUNTS prefix costs (align: native KV-cache) — and remembers everything — in one install.
+>
+> **v3.6.11 "Optimize Everywhere":** Three surfaces. **Proxy** (Surface A) — full-turn cache + compress on transport; needs `ANTHROPIC_BASE_URL`, shrinks the context window. **MCP tools** (Surface B) — `slm_compress`, `slm_retrieve`, `slm_cache_set`, `slm_cache_get`, `slm_optimize_stats`; no proxy, no window shrink, works on any Claude subscription. **Skill** (Surface C) — `slm-optimize` installs in `~/.claude/skills/`; zero-config auto-compress for large tool outputs and CLAUDE.md. No proxy, full 1M window. [See Three Surfaces →](#three-surfaces-proxy--mcp-tools--skill)
 >
 > **v3.6.10:** cache and compression are now **independent runtime switches** (cache-only, compress-only, both, or neither — toggle live from the dashboard, no restart). Compression was rebuilt to be **lossless by default** (the old string/array/code truncation is gone); aggressive mode adds LLMLingua-2 for **prose only** — never code, numbers, structured data, or the current turn.
 
@@ -213,6 +215,57 @@ Full docs:
 
 ---
 
+## Three Surfaces: Proxy · MCP Tools · Skill
+
+v3.6.11 delivers one engine across **three ways in** — choose the surface that fits your setup:
+
+| Surface | How you use it | Requires proxy? | Window effect | Cache scope |
+|---------|---------------|:---------------:|:-------------:|-------------|
+| **A — Proxy** | `slm wrap claude` or `ANTHROPIC_BASE_URL=http://127.0.0.1:8765` | **Yes** | Shrinks (proxy intercepts full context) | Full-turn cache — every Claude call |
+| **B — MCP tools** | Add 5 tools to MCP config; call `slm_compress`, `slm_cache_set/get` | **No** | **Preserved** (full 1M) | Results you explicitly route through SLM |
+| **C — Skill** | Copy `skills/slm-optimize/SKILL.md` → `~/.claude/skills/` | **No** | **Preserved** (full 1M) | Auto-applied by the agent per skill rules |
+
+**How to choose:**
+- On a **metered API** (pay-per-token) and want to cache every call → **Proxy (A)**
+- On a **Pro/Max/Team subscription** or any plan where you can't or won't run a proxy → **MCP tools (B)** or **Skill (C)**
+- Want zero configuration → **Skill (C)**: install once, auto-compresses CLAUDE.md and large outputs
+- Want agent-controlled caching of repeated file reads and tool outputs → **MCP tools (B)**
+
+**The hard constraint:** The primary Claude conversation turn cannot be cached without a proxy — the MCP/skill path caches results you explicitly route through SLM (tool outputs, file reads, sub-model calls).
+
+### MCP Tools Setup (Surface B)
+
+Add to your `claude_desktop_config.json` or IDE MCP config alongside your existing SLM entry:
+
+```json
+{
+  "mcpServers": {
+    "superlocalmemory": {
+      "command": "slm",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+The 5 optimize tools (`slm_compress`, `slm_retrieve`, `slm_cache_set`, `slm_cache_get`, `slm_optimize_stats`) are included automatically from v3.6.11+. Verify with `slm_optimize_stats()`.
+
+### Skill Setup (Surface C)
+
+```bash
+mkdir -p ~/.claude/skills/slm-optimize
+cp $(pip show superlocalmemory | grep Location | awk '{print $2}')/superlocalmemory/skills/slm-optimize/SKILL.md \
+   ~/.claude/skills/slm-optimize/SKILL.md
+```
+
+Then reference in your `CLAUDE.md`:
+```markdown
+## Context Management
+Use the `slm-optimize` skill to compress large outputs and cache repeated reads.
+```
+
+---
+
 <details>
 <summary><strong>What's New in V3.3 — The Living Brain Evolves</strong> (click to expand)</summary>
 
@@ -389,6 +442,7 @@ No manual commands. No data loss. Zero downtime.
 
 | Version | Codename | Key Features |
 |---|---|---|
+| **v3.6.11** | Optimize Everywhere | **Three surfaces** — Proxy (A: full-turn cache), MCP tools (B: `slm_compress`/`slm_retrieve`/`slm_cache_set`/`slm_cache_get`/`slm_optimize_stats` — proxy-free, 1M window), Skill (C: `slm-optimize` zero-config). `CacheDB.get_value()` (pure KV lookup). 23 new tests. Links: [Three Surfaces →](#three-surfaces-proxy--mcp-tools--skill) · [docs/optimize-overview.md](docs/optimize-overview.md) |
 | **v3.6.0** | Optimize | **Cache** (skip repeat calls, 100% on hit) · **Compress** (shrink prompts 60-95%) · **Align** (KV-cache stabilization) · `slm optimize\|cache\|compress\|proxy\|wrap` CLI · Live savings dashboard (USD/INR/tokens) · Hot-reload config · Safe defaults · Links: [docs/optimize-overview.md](docs/optimize-overview.md) · [V3.6 Wiki](https://github.com/qualixar/superlocalmemory/wiki/V3.6-Overview) |
 | **v3.5.0** | Scale-Ready + Context Injection v2 | CozoDB/LanceDB migration, 6-channel recall <1s, Core Memory Block, BM25→FTS5, context injection v2, score normalization |
 | **v3.4.5** | Scale-Ready (foundation) | Tiered storage (active/warm/cold), graph pruning, BackendOrchestrator scaffolding, CozoDB + LanceDB init + migration code (read path wired in v3.5.0) |

package/src/superlocalmemory.egg-info/SOURCES.txt

@@ -283,6 +283,7 @@ src/superlocalmemory/mcp/tools_core.py
 src/superlocalmemory/mcp/tools_evolution.py
 src/superlocalmemory/mcp/tools_learning.py
 src/superlocalmemory/mcp/tools_mesh.py
+src/superlocalmemory/mcp/tools_optimize.py
 src/superlocalmemory/mcp/tools_v28.py
 src/superlocalmemory/mcp/tools_v3.py
 src/superlocalmemory/mcp/tools_v33.py