superlocalmemory 3.6.0 → 3.6.1

package/CHANGELOG.md

@@ -5,6 +5,57 @@ 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.1] - 2026-06-07 — Optimize module fixes: proxy liveness probe, UI tab init, PyPI CI unblock
+
+### Fixed
+- **`slm proxy` AttributeError — wrong lifecycle function name:** `proxy_cmd.py` called
+  `lifecycle.ensure_running(port=port)` which does not exist. The function signature is
+  `ensure_proxy_running()` and is designed for daemon-internal use only (requires
+  `_store` to be initialised via `_set_config_store()`). In CLI subprocess context
+  `_store is None`, so `get_optimize_config()` returns `DEFAULT_OPTIMIZE_CONFIG` with
+  `proxy_enabled=False`, causing the function to return `False` immediately. Fix: replaced
+  the entire implementation with a direct `urllib.request` HTTP probe to
+  `http://127.0.0.1:8765/health` — correct in all execution contexts without any import
+  of `lifecycle`. Also corrected missing `proxy_enabled: True` in the fields dict written
+  to ConfigStore when `slm proxy --providers ...` is invoked.
+- **`slm optimize status` always showed "Proxy: not running":** `optimize_cmd.py` called
+  `lifecycle.proxy_is_running()` which does not exist either. The call was caught by a
+  broad `except Exception: pass`, so `proxy_running` was silently always `False`. Fix:
+  same pattern — direct HTTP health probe to `http://127.0.0.1:8765/health` with a 1s
+  timeout. `slm optimize status` now accurately reflects proxy liveness.
+- **Optimize pane UI always showing all toggles OFF:** `ng-shell.js`'s `triggerTabLoad()`
+  switch statement was completely missing the `'optimize-pane'` case. `initOptimizeTab()`
+  is defined and populates the UI from the live API, but it was never called when the user
+  switched to the Optimize tab — the pane rendered HTML defaults (all OFF) forever.
+  Fix: added `case 'optimize-pane': if (typeof initOptimizeTab === 'function') initOptimizeTab(); break;`
+  to the switch. Hard-refresh (`Cmd+Shift+R`) required after install.
+- **`ConfigUpdateRequest` missing `proxy_enabled` field:** `server/routes/optimize.py`'s
+  `ConfigUpdateRequest` Pydantic model did not include `proxy_enabled`, so the UI could
+  not toggle proxy via the `PATCH /api/optimize/config` endpoint. Added
+  `proxy_enabled: bool | None = None` with the existing nullable pattern.
+- **`pytest` `import file mismatch` blocking ALL PyPI CI since v3.5.6:** `tests/test_cli.py`
+  (a legacy file with 6 basic tests) coexisted with `tests/test_cli/` (a package directory
+  with `__init__.py`). Python 3.12 on Ubuntu resolves the package name `test_cli` to the
+  directory — pytest then tries to collect the file under a conflicting module path and
+  raises `import file mismatch: imported module 'tests.test_cli' has this __file__ ...
+  which is not the same as the test file`. Every PyPI publish attempt since v3.5.6 failed
+  silently at this step (npm publishes succeeded because the npm CI workflow skips pytest).
+  Fix: `git mv tests/test_cli.py tests/test_cli_core.py` — no tests dropped, no changes
+  to test logic, collision eliminated.
+
+## [3.6.0] - 2026-06-07 — Optimize module: cache, compress, proxy (3-lever token-saving system)
+
+### Added
+- **Optimize module** — a 3-lever system for reducing LLM token spend through an SLM-hosted
+  proxy at `http://localhost:8765`. Levers: (1) **Cache** — exact and semantic caching of
+  LLM calls with separate TTLs; (2) **Compress** — prompt compression via CCR/code/prose
+  strategies; (3) **Align** — model routing. Proxy intercepts calls routed via
+  `ANTHROPIC_BASE_URL=http://localhost:8765` or the `withSLM(Anthropic())` SDK adapter.
+- `slm optimize status|on|off|savings` CLI subcommands.
+- `slm proxy` CLI to start/stop the proxy and configure providers.
+- Dashboard Optimize pane at `http://localhost:8765/#optimize-pane` with live toggle UI.
+- Separate `llmcache.db` for cache storage — never writes to `memory.db`.
+
 ## [3.5.9] - 2026-06-07 — Community bug fixes (issues #28, #29, PR #30) + zombie process hardening
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "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.0"
+version = "3.6.1"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}

package/src/superlocalmemory/__init__.py

@@ -28,7 +28,7 @@ if "OMP_NUM_THREADS" not in os.environ:
     os.environ["OMP_NUM_THREADS"] = "2"
 # ---------------------------------------------------------------------------
 
-__version__ = "3.5.9"
+__version__ = "3.6.1"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.3.0",

package/src/superlocalmemory/cli/optimize_cmd.py

@@ -67,8 +67,11 @@ def cmd_optimize_status(args: Namespace) -> None:
 
     proxy_running = False
     try:
-        from superlocalmemory.optimize.proxy import lifecycle
-        proxy_running = lifecycle.proxy_is_running()
+        import urllib.request
+        _url = f"http://127.0.0.1:{OPTIMIZE_DEFAULT_PORT}/health"
+        _req = urllib.request.Request(_url, method="GET")
+        with urllib.request.urlopen(_req, timeout=1) as _resp:
+            proxy_running = _resp.status == 200
     except Exception:
         pass
 

package/src/superlocalmemory/cli/proxy_cmd.py

@@ -20,12 +20,21 @@ def _get_store():
 
 
 def _ensure_running(port: int) -> bool:
-    """Wrap proxy.lifecycle.ensure_running. Monkeypatchable in tests."""
+    """Liveness probe: return True if the SLM daemon is responding at *port*.
+
+    Calls GET /health with a 2-second timeout.  The SLM daemon (which also acts
+    as the optimize proxy) is the process that answers on :8765; if it responds
+    the proxy layer is alive. We do NOT call lifecycle.ensure_proxy_running()
+    here because that function reads config via the daemon-internal store
+    (get_optimize_config/_store) which is None in a CLI subprocess context.
+    """
     try:
-        from superlocalmemory.optimize.proxy import lifecycle
-        return lifecycle.ensure_running(port=port)
-    except ImportError:
-        print("Error: proxy module not available.", file=sys.stderr)
+        import urllib.request
+        url = f"http://127.0.0.1:{port}/health"
+        req = urllib.request.Request(url, method="GET")
+        with urllib.request.urlopen(req, timeout=2) as resp:
+            return resp.status == 200
+    except Exception:
         return False
 
 
@@ -54,7 +63,7 @@ def cmd_proxy(args: Namespace) -> None:
         base_url=f"http://localhost:{port}",
     )
 
-    fields: dict = {"providers": providers}
+    fields: dict = {"providers": providers, "proxy_enabled": True}
     if no_compress:
         fields["compress_enabled"] = False
     if semantic:

package/src/superlocalmemory/optimize/adapters/wrap.py

@@ -16,6 +16,18 @@ from typing import Any
 from superlocalmemory.optimize.adapters._agent_registry import AGENT_REGISTRY
 from superlocalmemory.optimize.proxy.lifecycle import ensure_proxy_running, proxy_port
 
+# Mechanisms that write static config files — need proxy *configured*, not alive.
+_STATIC_MECHANISMS = {"settings-file", "config-file", "print-only"}
+
+
+def _proxy_configured() -> bool:
+    """Return True if proxy_enabled=True in optimize.json (no liveness check)."""
+    try:
+        from superlocalmemory.optimize.config import get_optimize_config
+        return get_optimize_config().proxy_enabled
+    except Exception:
+        return False
+
 
 def list_agents() -> list[str]:
     """Return all registered agent keys."""
@@ -42,19 +54,36 @@ def wrap_agent(
         )
         return 1
 
-    if not ensure_proxy_running():
-        print(
-            f"[slm wrap] proxy is not enabled in optimize.json — set "
-            f"`proxy_enabled: true` (port 8765) and re-run, or run "
-            f"`slm optimize on` first.",
-            file=sys.stderr,
-        )
-        return 1
-
     port = proxy_port()
     spec = AGENT_REGISTRY[agent_key]
     mechanism = spec.get("mechanism", "print-only")
 
+    # Static mechanisms (settings-file, config-file) only write JSON — proxy
+    # doesn't need to be alive yet.  env/subprocess mechanisms inject the proxy
+    # URL into a live process, so full liveness is required there.
+    # Static mechanisms (settings-file, config-file, print-only) write JSON and
+    # dry-run modes only print — neither needs the proxy to be alive right now.
+    # Only live subprocess launches (mechanism="env", dry_run=False) require the
+    # proxy to be running so the subprocess can actually connect.
+    needs_liveness = (mechanism not in _STATIC_MECHANISMS) and not dry_run
+    if needs_liveness:
+        if not ensure_proxy_running():
+            print(
+                f"[slm wrap] proxy is not enabled or not running — run "
+                f"`slm proxy` to start it, or `slm optimize on` first.",
+                file=sys.stderr,
+            )
+            return 1
+    else:
+        if not _proxy_configured():
+            print(
+                f"[slm wrap] proxy is not enabled in optimize.json — set "
+                f"`proxy_enabled: true` (port 8765) and re-run, or run "
+                f"`slm optimize on` first.",
+                file=sys.stderr,
+            )
+            return 1
+
     if mechanism == "print-only":
         print(f"[slm wrap] {agent_key}: manual instructions")
         print(spec.get("help_text", ""))
@@ -135,6 +164,11 @@ def wrap_agent(
         if not binary:
             print(f"[slm wrap] {agent_key}: no binary specified", file=sys.stderr)
             return 1
+        # dry_run: show intent without requiring the binary to be installed
+        if dry_run:
+            print(f"[slm wrap] would exec: {binary} {' '.join(agent_args)}")
+            print(f"[slm wrap] env: {env_vars}")
+            return 0
         if shutil.which(binary) is None:
             print(
                 f"[slm wrap] binary '{binary}' not found in PATH. "
@@ -145,10 +179,6 @@ def wrap_agent(
         full_env = os.environ.copy()
         for k, v in env_vars.items():
             full_env[k] = v.replace("{port}", str(port))
-        if dry_run:
-            print(f"[slm wrap] would exec: {binary} {' '.join(agent_args)}")
-            print(f"[slm wrap] env: {env_vars}")
-            return 0
         try:
             return subprocess.call([binary, *agent_args], env=full_env)
         except FileNotFoundError as exc:

package/src/superlocalmemory/server/routes/optimize.py

@@ -27,6 +27,7 @@ _savings_estimator = _SavingsEstimator()
 class ConfigUpdateRequest(BaseModel):
     """Partial config update — only provided fields are changed."""
     enabled: bool | None = None
+    proxy_enabled: bool | None = None
     cache_enabled: bool | None = None
     semantic_enabled: bool | None = None
     compress_enabled: bool | None = None

package/src/superlocalmemory/ui/js/ng-shell.js

@@ -389,6 +389,9 @@
         if (typeof loadAutoSettings === 'function') loadAutoSettings();
         if (typeof updateModeUI === 'function') updateModeUI();
         break;
+      case 'optimize-pane':
+        if (typeof initOptimizeTab === 'function') initOptimizeTab();
+        break;
     }
   }
 

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

@@ -94,17 +94,18 @@ Dynamic: license-file
   <img src="https://superlocalmemory.com/assets/logo-mark.png" alt="SuperLocalMemory" width="200"/>
 </p>
 
-<h1 align="center">SuperLocalMemory V3.5</h1>
-<p align="center"><strong>Every other AI forgets. Yours won't.</strong><br/><em>Infinite memory for Claude Code, Cursor, Windsurf, and any MCP-compatible AI client.</em></p>
-<p align="center"><code>v3.5.0 "Scale-Ready + Context Injection v2"</code> — <strong>Your database auto-migrates. 6-channel recall in &lt;1s. Core Memory Block + explicit pinning. CozoDB + LanceDB on the recall path.</strong><br>No manual migrations. No data loss. One command: <code>pip install -U superlocalmemory && slm restart</code></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>
 <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>+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>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>
 </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="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>
@@ -121,31 +122,89 @@ Dynamic: license-file
 
 ---
 
-## Why SuperLocalMemory?
+<details>
+<summary><strong>What's New in V3.6 — Optimize: SKIP, SHRINK, DISCOUNT, REMEMBER</strong> (click to expand)</summary>
 
-Every **hosted** AI memory platform — Mem0 Cloud, Zep Cloud, Letta Cloud, EverMemOS Cloud — sends your data to cloud LLMs by default. Their self-hosted variants exist (Mem0 OpenMemory, Letta self-hosted, Graphiti) but require Docker + a separate graph DB or Ollama config, and most still default to OpenAI until you flip env vars. After **August 2, 2026**, any of those cloud paths becomes a compliance problem under the EU AI Act.
+> V3.6 is the only local-first layer that SKIPS repeat LLM calls (cache: 100% saved), SHRINKS prompts 60-95% (compress: extractive + 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.**
 
-SuperLocalMemory V3 takes a different approach: **mathematics instead of cloud compute.** Three techniques from differential geometry, algebraic topology, and stochastic analysis replace the work that other systems need LLMs to do — similarity scoring, contradiction detection, and lifecycle management. The result is an agent memory that ships local-first out of the box — no Docker, no graph DB, no API keys — on CPU.
+### The Three Levers
 
-**The numbers** (evaluated on [LoCoMo](https://arxiv.org/abs/2402.09714), the standard long-conversation memory benchmark). Published numbers as of April 2026:
+| Lever | Mechanism | Saving | Off by default? |
+|-------|-----------|:------:|:---------------:|
+| **Cache** | Skip repeat calls — exact-match SQLite lookup, vCache-gated semantic (opt-in) | **100% on a hit** (input + output) | Cache ON, Semantic OFF |
+| **Compress** | Shrink prompts — extractive JSON/code (lossless) + LLMLingua-2 prose (opt-in) | **60–95% on a miss** (input only) | Safe mode ON, Aggressive OFF |
+| **Align** | Stabilize prefix — maximize provider prefix-cache discounts | **Lossless extra** | ON when compression is ON |
 
-| System | Score | Config | Cloud LLM required? | Open Source | Source |
-|:-------|:-----:|:-------|:-------------------:|:-----------:|:-------|
-| EverMemOS | 93.05% | Cloud (proprietary) | Yes | Core only | [evermind.ai](https://evermind.ai/) (Feb 2026) |
-| Hindsight (LoComo10) | 92.0% | Cloud | Yes | No | [benchmarks.hindsight.vectorize.io](https://benchmarks.hindsight.vectorize.io) (Apr 2026) |
-| Mem0 (token-efficient) | 91.6% | Hybrid (Cohere/OpenAI) | Yes | Partial | [mem0.ai blog](https://mem0.ai/blog/mem0-the-token-efficient-memory-algorithm) (Apr 16 2026) |
-| **SLM V3 Mode C** | **87.7%** | Local + optional LLM | Optional (Ollama OK) | **Yes (AGPL-3.0)** | In-house, repro script in `docs/benchmarks/` |
-| Zep v3 Cloud | 85.2% | Cloud | Yes | Community deprecated | [getzep.com](https://www.getzep.com/) |
-| **SLM V3 Mode A** | **74.8%** | **Local, CPU-only, zero-LLM** | **No** | **Yes (AGPL-3.0)** | In-house, repro script in `docs/benchmarks/` |
-| Mem0 (zero-retrieval-LLM) | 64.2% | Local baseline | No | Partial | Mem0 paper, zero-LLM row |
+**Memory** (v3.5's existing engine) runs in parallel — it shapes *what is in* the prompt (relevant facts); Optimize decides *whether and how* it is sent.
 
-> **How to read this table.** Scores from different papers use different LoCoMo splits, judge models, and prompt variants. We do NOT claim these numbers are apples-to-apples across rows. The rows we re-ran in-house are marked "In-house"; cited rows link to the vendor's public source and date. Mode A is the only zero-LLM configuration in the list, so the comparison that is apples-to-apples is **Mode A 74.8% vs Mem0 zero-retrieval-LLM 64.2%** (+10.6pp). Mem0's 91.6% and EverMemOS's 93.05% use cloud LLMs; Mode C uses a local LLM (Ollama). BEAM-10M, the emerging successor benchmark, will be added in a future release.
+### Quick Start
 
-**What Mode A is**: CPU-only, SQLite-only, zero-LLM retrieval pipeline on published LoCoMo questions. To the best of our knowledge it is the only publicly-released local-first memory that clears Mem0's zero-LLM baseline on this benchmark. If another fully-local system hits similar numbers, please open an issue so we can update the table.
+```bash
+# One command to start saving
+slm wrap claude
+# Your first repeat prompt → CACHE HIT → $0.00
+# Your first long prompt → COMPRESSED 70% → $0.00 per token saved
+```
 
-Mathematical layers contribute **+12.7 percentage points** on average across 6 conversations (n=832 questions), with up to **+19.9pp on the most challenging dialogues**. This isn't more compute — it's better math.
+### New CLI Commands (6 total)
 
-> **Upgrading from V2 (2.8.6)?** V3 is a complete architectural reinvention — new mathematical engine, new retrieval pipeline, new storage schema. Your existing data is preserved but requires migration. After installing V3, run `slm migrate` to upgrade your data. Read the [Migration Guide](https://github.com/qualixar/superlocalmemory/wiki/Migration-from-V2) before upgrading. Backup is created automatically.
+| Command | What It Does |
+|:--------|:-------------|
+| `slm optimize status\|on\|off\|savings` | Master Optimize control + savings report (USD/INR/tokens) |
+| `slm cache status\|clear\|invalidate\|ttl\|semantic` | Cache sub-control — exact + semantic tiers |
+| `slm compress status\|mode\|code\|prose\|ccr\|align` | Compression control — per-channel toggles |
+| `slm proxy [--port] [--provider]` | Start the interception proxy (port 8765) |
+| `slm wrap <agent>` | Proxy-activate an agent — one command to start saving |
+| `slm help-optimize [topic]` | Full developer reference + per-agent setup recipes |
+
+### Savings Dashboard
+
+All metrics tracked and displayed live — from the dashboard (Optimize tab) or CLI:
+
+```bash
+slm optimize savings --since 7
+# Savings (last 7 days):
+#   Exact cache hits:        43   (127,580 input tokens saved)
+#   Tokens saved (total): 153,096
+#   Estimated savings:  ~$2.30 (at $3.00/M tokens — Anthropic rates)
+```
+
+### Enable / Disable
+
+```bash
+slm optimize on                      # Enable cache + compress
+slm optimize off                     # Disable (proxy passes through)
+slm cache semantic on                # Enable semantic cache (needs embedding model)
+slm compress mode aggressive         # Enable prose compression (with safety warning)
+```
+
+**Safety defaults:** Optimize ON. Safe mode ON (extractive only — lossless, production-safe). Semantic OFF. Aggressive OFF. No behavior change until you explicitly enable features.
+
+### How It Works
+
+```
+Your App → Proxy/SDK/Wrap → Cache Check → HIT → Return Cached (0 tokens)
+                                   |
+                                 MISS
+                                   |
+                            Compress → Provider → Store in Cache
+                            60-95%     + Align
+```
+
+- **Fail-open** — any error passes through. Your calls never break.
+- **Separate database** — `llmcache.db` never touches `memory.db`. AES-256-GCM at rest.
+- **Hot-reload config** — UI/CLI writes `~/.superlocalmemory/optimize.json`, daemon reloads in 2s.
+
+### Links
+
+Full docs:
+- [Optimize Product Overview](docs/optimize-overview.md)
+- [Optimize CLI Reference](docs/optimize-cli.md)
+- [Optimize Config Reference](docs/optimize-config.md)
+- [Wiki: V3.6 Overview](https://github.com/qualixar/superlocalmemory/wiki/V3.6-Overview)
+- [Website: v3.6 Optimize](https://superlocalmemory.com/optimize)
+
+</details>
 
 ---
 
@@ -240,21 +299,31 @@ slm config set v33_features.all true
 
 ---
 
-<details>
-<summary><strong>What's New in V3.2 — The Living Brain</strong> (click to expand)</summary>
+## Why SuperLocalMemory?
 
-100x faster recall (<10ms at 10K facts), automatic memory surfacing, associative retrieval (5th channel), temporal intelligence with bi-temporal validity, sleep-time consolidation, and core memory blocks. All features default OFF, zero breaking changes.
+Every **hosted** AI memory platform — Mem0 Cloud, Zep Cloud, Letta Cloud, EverMemOS Cloud — sends your data to cloud LLMs by default. Their self-hosted variants exist (Mem0 OpenMemory, Letta self-hosted, Graphiti) but require Docker + a separate graph DB or Ollama config, and most still default to OpenAI until you flip env vars. After **August 2, 2026**, any of those cloud paths becomes a compliance problem under the EU AI Act.
 
-| Metric | V3.0 | V3.2 | Change |
-|:-------|:----:|:----:|:------:|
-| Recall latency (10K facts) | ~500ms | <10ms | **100x faster** |
-| Retrieval channels | 4 | 5 | +spreading activation |
-| MCP tools | 24 | 29 | +5 new |
-| DB tables | 9 | 18 | +9 new |
+SuperLocalMemory V3 takes a different approach: **mathematics instead of cloud compute.** Three techniques from differential geometry, algebraic topology, and stochastic analysis replace the work that other systems need LLMs to do — similarity scoring, contradiction detection, and lifecycle management. The result is an agent memory that ships local-first out of the box — no Docker, no graph DB, no API keys — on CPU.
 
-Enable with `slm config set v32_features.all true`. See the [V3.2 Overview](https://github.com/qualixar/superlocalmemory/wiki/V3.2-Overview) wiki page for details.
+**The numbers** (evaluated on [LoCoMo](https://arxiv.org/abs/2402.09714), the standard long-conversation memory benchmark). Published numbers as of April 2026:
 
-</details>
+| System | Score | Config | Cloud LLM required? | Open Source | Source |
+|:-------|:-----:|:-------|:-------------------:|:-----------:|:-------|
+| EverMemOS | 93.05% | Cloud (proprietary) | Yes | Core only | [evermind.ai](https://evermind.ai/) (Feb 2026) |
+| Hindsight (LoComo10) | 92.0% | Cloud | Yes | No | [benchmarks.hindsight.vectorize.io](https://benchmarks.hindsight.vectorize.io) (Apr 2026) |
+| Mem0 (token-efficient) | 91.6% | Hybrid (Cohere/OpenAI) | Yes | Partial | [mem0.ai blog](https://mem0.ai/blog/mem0-the-token-efficient-memory-algorithm) (Apr 16 2026) |
+| **SLM V3 Mode C** | **87.7%** | Local + optional LLM | Optional (Ollama OK) | **Yes (AGPL-3.0)** | In-house, repro script in `docs/benchmarks/` |
+| Zep v3 Cloud | 85.2% | Cloud | Yes | Community deprecated | [getzep.com](https://www.getzep.com/) |
+| **SLM V3 Mode A** | **74.8%** | **Local, CPU-only, zero-LLM** | **No** | **Yes (AGPL-3.0)** | In-house, repro script in `docs/benchmarks/` |
+| Mem0 (zero-retrieval-LLM) | 64.2% | Local baseline | No | Partial | Mem0 paper, zero-LLM row |
+
+> **How to read this table.** Scores from different papers use different LoCoMo splits, judge models, and prompt variants. We do NOT claim these numbers are apples-to-apples across rows. The rows we re-ran in-house are marked "In-house"; cited rows link to the vendor's public source and date. Mode A is the only zero-LLM configuration in the list, so the comparison that is apples-to-apples is **Mode A 74.8% vs Mem0 zero-retrieval-LLM 64.2%** (+10.6pp). Mem0's 91.6% and EverMemOS's 93.05% use cloud LLMs; Mode C uses a local LLM (Ollama). BEAM-10M, the emerging successor benchmark, will be added in a future release.
+
+**What Mode A is**: CPU-only, SQLite-only, zero-LLM retrieval pipeline on published LoCoMo questions. To the best of our knowledge it is the only publicly-released local-first memory that clears Mem0's zero-LLM baseline on this benchmark. If another fully-local system hits similar numbers, please open an issue so we can update the table.
+
+Mathematical layers contribute **+12.7 percentage points** on average across 6 conversations (n=832 questions), with up to **+19.9pp on the most challenging dialogues**. This isn't more compute — it's better math.
+
+> **Upgrading from V2 (2.8.6)?** V3 is a complete architectural reinvention — new mathematical engine, new retrieval pipeline, new storage schema. Your existing data is preserved but requires migration. After installing V3, run `slm migrate` to upgrade your data. Read the [Migration Guide](https://github.com/qualixar/superlocalmemory/wiki/Migration-from-V2) before upgrading. Backup is created automatically.
 
 ---
 
@@ -275,9 +344,18 @@ slm warmup    # Pre-download embedding model (~500MB, optional)
 pip install superlocalmemory
 ```
 
-### Upgrading to v3.5.0 "Scale-Ready — CozoDB + LanceDB"
+### Start Saving on LLM Costs (v3.6 Optimize)
 
-**Migration is automatic.** Upgrade the package, restart the daemon — CozoDB, LanceDB, and the vector store all self-migrate in the background.
+```bash
+# Wrap your agent — starts proxy + sets environment + launches agent
+slm wrap claude
+# Your first repeat prompt → CACHE HIT → $0.00 saved
+# See savings: slm optimize savings --since 1
+```
+
+### Upgrading to v3.6 "Optimize" + v3.5.0 "Scale-Ready"
+
+**Migration is automatic.** Upgrade the package, restart the daemon — all migrations run in the background.
 
 ```bash
 pip install -U superlocalmemory
@@ -285,7 +363,13 @@ slm restart
 slm doctor
 ```
 
-No manual commands. No data loss. Your database upgrades in-place. The daemon applies all migrations (including CozoDB graph, LanceDB vector, and the `pinned` column for Core Memory) on first start after upgrade.
+No manual commands. No data loss. Zero downtime.
+
+**What you get after upgrading to v3.6.0:**
+- **Cache** — skip repeat LLM calls entirely. Exact-match + vCache-gated semantic. **100% cost saved on hit.**
+- **Compress** — shrink prompts 60-95% before sending. Extractive JSON/code (lossless) + LLMLingua-2 prose (opt-in). CCR reversible.
+- **Align** — stabilize prompt prefix for native provider KV-cache discounts (Anthropic 90%, OpenAI 50%).
+- **Savings dashboard** — live USD/INR/tokens saved displayed in the Optimize tab.
 
 **What you get after upgrading to v3.5.0:**
 - **CozoDB on the recall path** — entity_graph channel routes through the CozoDB backend (auto-detected, no config needed). Millions of graph edges indexed and traversed in milliseconds.
@@ -300,6 +384,7 @@ No manual commands. No data loss. Your database upgrades in-place. The daemon ap
 
 | Version | Codename | Key Features |
 |---|---|---|
+| **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) |
 | **v3.4.51** | Recency Intelligence | Ebbinghaus decay + FSRS stability, age gate, session context time-awareness |
@@ -619,6 +704,20 @@ All 8 mesh tools work seamlessly across machines:
 
 ## Features
 
+### LLM Cost Optimization (v3.6 Optimize)
+- **Exact Cache** — byte-identical repeat calls served from local SQLite. SHA-256 key derivation, stampede shield, tag-based invalidation. **100% cost saved on hit** (input + output tokens).
+- **Semantic Cache** (opt-in) — vCache-powered learned thresholds with SAFE-CACHE centroid defense. Near-duplicate queries served within error bound. CacheAttack 86% hijack class blocked.
+- **Extractive Compression** — structure-preserving compression for JSON, code (AST-aware: Python/JS/Go/Rust/Java/C++), and tool outputs. **60-95% fewer input tokens**, zero accuracy regression.
+- **LLMLingua-2 Prose** (opt-in) — extractive prose summarization for open-ended chat. Safety-warned before enable.
+- **CCR (Compressed Context Retrieval)** — pre-compression originals stored for byte-exact reversal under UUID. Every compressed block recoverable.
+- **CacheAligner** — detects volatile tokens (UUIDs, timestamps, JWTs) in system prompts. Maximizes native provider prefix-cache discounts (Anthropic 90%, OpenAI 50%).
+- **Interception Proxy** — HTTP proxy on port 8765 serving Anthropic, OpenAI, and Gemini surfaces. Zero-code integration — just set `base_url`.
+- **Agent Wrapping** — `slm wrap claude` — one command starts proxy + sets environment + launches agent. 10 supported agents.
+- **Savings Dashboard** — live USD/INR/tokens saved, hit rate, compression ratio, cache size. CLI + UI.
+- **Hot-Reload Config** — UI/CLI writes `optimize.json`; daemon reloads in 2 seconds. No restart.
+- **Fail-open** — any cache/compress/proxy error passes through. Your calls never break.
+- **Data isolation** — separate `llmcache.db` with AES-256-GCM encryption. Never touches `memory.db`.
+
 ### Retrieval
 - 5-channel hybrid: Semantic (Fisher-Rao) + BM25 + Entity Graph + Temporal + Hopfield (associative / partial-query completion)
 - RRF fusion + cross-encoder reranking
@@ -671,6 +770,14 @@ All 8 mesh tools work seamlessly across machines:
 
 | Command | What It Does |
 |:--------|:-------------|
+| `slm optimize status` | Show all Optimize settings (cache, compress, proxy, config version) |
+| `slm optimize on\|off` | Enable/disable all Optimize features (hot-reload, no restart) |
+| `slm optimize savings [--since N] [--provider P] [--json]` | Token/cost savings report — live USD/INR |
+| `slm cache status\|clear\|invalidate\|ttl\|semantic` | Cache sub-control — exact + semantic tiers, TTL management |
+| `slm compress status\|mode\|code\|prose\|ccr\|align` | Compression control — per-channel toggle, safe/aggressive mode |
+| `slm proxy [--port] [--provider] [--no-compress] [--semantic]` | Start interception proxy (port 8765) |
+| `slm wrap <agent> [options]` | Proxy-activate an agent — one command to start saving |
+| `slm help-optimize [topic]` | Full developer reference + per-agent setup recipes |
 | `slm remember "..."` | Store a memory |
 | `slm recall "..."` | Search memories |
 | `slm forget "..."` | Delete matching memories |