superlocalmemory 3.5.8 → 3.6.1

package/ATTRIBUTION.md

@@ -59,5 +59,29 @@ SuperLocalMemory uses the following open-source libraries:
 - scikit-learn (BSD-3-Clause) — TF-IDF vectorization and similarity search
 - SQLite (Public Domain) — Local database storage
 - NumPy (BSD-3-Clause) — Numerical operations
+- SciPy (BSD-3-Clause) — Numerical optimization (used by vCache MLE logistic refit)
 
 See [requirements.txt](requirements.txt) for the full dependency list.
+
+### Optimize Module — Research Citations (v3.6)
+
+The Optimize module (LLD-03 / LLD-04) builds on peer-reviewed work.
+The Implementer verified each arXiv ID against arxiv.org before citation.
+
+| Component | Source | License / Note |
+|---|---|---|
+| **vCache** (per-item learned thresholds, online MLE) | arXiv:2502.03771 (ICLR 2026, Berkeley/TUM) | Eq. 9 (sigmoid), Eq. 10 (BCE MLE), Eq. 11 (confidence-band τ̂), Algorithm 2, Theorem 4.1 (≥1-δ correctness guarantee) |
+| **CacheAttack** (86% response hijack, 90.6% agentic) | arXiv:2601.23088 | Threat model. The 90.6% figure is [UNVERIFIED — body-only, RA-18]; the 86% figure is verified from the abstract. |
+| **SAFE-CACHE** (centroid-based adversarial defense) | Nature Scientific Reports 2026 | [CITATION-NEEDED-ONLINE — exact paper verified, but exact defense figures are body-only.] Defense reduced attack success from 52.77% to 14.27% per the paper. |
+| **ContextCache** (multi-turn context-aware keys) | arXiv:2506.22791 | §3 — context-aware cache keys prevent false reuse across semantically overlapping but conversationally distinct turns. |
+| **LLMLingua-2** (prose compression) | arXiv:2403.12968 (Microsoft Research) | MIT license. Models: `microsoft/llmlingua-2-bert-base-multilingual-cased-meetingbank` (default) and `microsoft/llmlingua-2-xlm-roberta-large-meetingbank`. Off by default, opt-in via `compress_prose=True` + `compress_mode="aggressive"`. **Originals always stored in CCR before lossy compression — reversible via `headroom_retrieve`.** |
+| **LongLLMLingua** (RAG compression) | arXiv:2310.06839 | Not used in Phase 3. Documented for Phase 4 RAG integration. |
+| **Headroom** (router, JSON handler, code handler, aligner) | github.com/qualixar/headroom (Apache-2.0) | Patterns adapted with attribution: `ContentRouter`, `JSONStructureHandler`, `CodeLanguage` enum, `CacheAligner._classify_token`. |
+| **omnicache-ai** (test fixture patterns) | github.com/qualixar/omnicache-ai (Apache-2.0) | Deterministic hash-to-vector embedding fixture for tests. |
+
+**Two fabricated arXiv IDs were caught and fixed during the LLD-10 audit:**
+`2501.05064` and `2404.12693` (both previously wrong vCache labels). The
+verified ID is **arXiv:2502.03771**.
+
+If you see an arXiv ID in the Optimize module not listed above, treat it
+as suspect.

package/CHANGELOG.md

@@ -5,6 +5,92 @@ 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
+- **MCP zombie processes — stdin EOF monitor (macOS):** `slm mcp` now self-terminates when
+  the IDE closes the stdio pipe without quitting the parent app (e.g. "start new session"
+  in Claude Code or Antigravity). Uses `kqueue` `KQ_EV_EOF` so it detects the hangup without
+  consuming bytes needed by FastMCP's asyncio stdin reader. Complements the existing parent
+  watchdog (which only fires on process death). Previously 22+ orphan MCP sessions were
+  accumulating on the M5 Pro causing 12 GB of swap.
+- **`slm reap --all`** (new flag): kills every `slm mcp` process except the caller, regardless
+  of orphan status. Use this after switching IDEs to clear all stale sessions in one command.
+  `slm reap --force` still kills only confirmed orphans. JSON output now lists this option in
+  `next_actions`.
+- **MCP embedder NULL (PR #30):** `MemoryEngine(Capabilities.LIGHT)` permanently left
+  `_embedder=None`, causing memories stored via MCP tools to have no embeddings — semantic
+  search was silently broken and `health()` reported the embedder as `unavailable`. Root
+  cause correctly diagnosed by @kotys2022 in PR #30. Fix: after LIGHT init, engine now tries
+  to attach a `McpEmbedderProxy` that delegates `embed_batch()` to the daemon's
+  `/api/v3/embed` endpoint over localhost HTTP. One ONNX worker total across all sessions.
+  If the daemon is unreachable, the engine gracefully degrades to keyword-only recall (same
+  behaviour as before, but now honest). `health()` reports `source: daemon_proxy` so users
+  can distinguish proxy from local embedder.
+- **`base_dir` ignored in config (issue #28):** `SLMConfig.load()` no longer ignores a custom
+  `base_dir` in `config.json` — it now passes it to `for_mode()` so `db_path` and all
+  derivative paths are built from the user's directory, not `~/.superlocalmemory`. `save()`
+  now persists `base_dir` so the setting survives daemon restarts.
+- **Local model auth deadlock (issue #29):** Three interlocking fixes for `llama.cpp` / LM
+  Studio / other unauthenticated endpoints under the `openai` provider:
+  1. `LLMBackbone._build_openai()` omits the `Authorization: Bearer` header when `api_key` is
+     empty — unauthenticated local servers no longer reject with HTTP 401.
+  2. `_build_openai()` appends `/chat/completions` when `base_url` does not already end in
+     that path, fixing the `/v1/v1/chat/completions` duplication reported in the issue.
+  3. `POST /api/v3/provider/test` now accepts an empty `api_key` when a custom `base_url` or
+     `endpoint` is provided, and probes the actual endpoint instead of hard-coding OpenAI's URL.
+
 ## [3.5.8] - 2026-06-06 — MCP zombie process fix
 
 ### Fixed

package/README.md

@@ -2,17 +2,18 @@
   <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>
@@ -29,31 +30,89 @@
 
 ---
 
-## 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>
 
 ---
 
@@ -148,21 +207,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.
 
 ---
 
@@ -183,9 +252,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
@@ -193,7 +271,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.
@@ -208,6 +292,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 |
@@ -527,6 +612,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
@@ -579,6 +678,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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.5.8",
+  "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.5.8"
+version = "3.6.1"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}
@@ -55,6 +55,7 @@ dependencies = [
     "psutil==7.2.2",
     "structlog==25.5.0",
     "portalocker==3.2.0",
+    "cryptography==45.0.2",
     # Semantic search + cross-encoder reranker. Do NOT use
     # sentence-transformers[onnx] — its extras pull optimum which
     # overrides the sentence-transformers pin via transitive deps.

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.8"
+__version__ = "3.6.1"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.3.0",

package/src/superlocalmemory/cli/cache_cmd.py

@@ -0,0 +1,198 @@
+# 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
+
+"""Handlers for ``slm cache status|clear|invalidate|ttl|semantic``."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import sys
+from argparse import Namespace
+
+
+def _get_store():
+    from superlocalmemory.optimize.config.store import ConfigStore
+    return ConfigStore()
+
+
+def _get_cache_db():
+    from superlocalmemory.optimize.storage.db import CacheDB
+    return CacheDB()
+
+
+def _write_config(**fields) -> None:
+    """5-step immutable config-write."""
+    store = _get_store()
+    cfg = store.get()
+    try:
+        cfg = dataclasses.replace(cfg, **fields)
+        store.save(cfg)
+    except ValueError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except OSError as e:
+        print(f"Error writing config: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_cache(args: Namespace) -> None:
+    """Top-level dispatcher for ``slm cache <subcommand>``."""
+    sub = getattr(args, "cache_command", None)
+    _dispatch = {
+        "status": cmd_cache_status,
+        "clear": cmd_cache_clear,
+        "invalidate": cmd_cache_invalidate,
+        "ttl": cmd_cache_ttl,
+        "semantic": cmd_cache_semantic,
+    }
+    handler = _dispatch.get(sub or "")
+    if handler:
+        handler(args)
+    else:
+        print("Usage: slm cache status|clear|invalidate|ttl|semantic [options]")
+        sys.exit(0)
+
+
+def cmd_cache_status(args: Namespace) -> None:
+    """Print cache status from CacheDB + ConfigStore."""
+    use_json = getattr(args, "json", False)
+    tenant = getattr(args, "tenant", "default")
+
+    cfg = _get_store().get()
+    db = _get_cache_db()
+    entry_count = db.entry_count(tenant)
+    db_size = db.db_size_bytes()
+    snap = db.metrics_load()
+
+    if use_json:
+        data = {
+            "status": "ok",
+            "entries_exact": entry_count,
+            "db_size_bytes": db_size,
+            "ttl_exact": cfg.ttl.exact_seconds,
+            "ttl_semantic": cfg.ttl.semantic_seconds,
+            "hits": snap.hits,
+            "misses": snap.misses,
+            "hit_rate": snap.hit_rate,
+        }
+        print(json.dumps(data, indent=2))
+        return
+
+    print("Cache status:")
+    print(f"  Entries (exact):   {entry_count}  (not expired)")
+    semantic_state = "OFF" if not cfg.semantic_enabled else "ON"
+    print(f"  Semantic index:    {semantic_state}")
+    size_mb = db_size / (1024 * 1024)
+    print(f"  DB size:           {size_mb:.1f} MB  (~/.superlocalmemory/llmcache.db)")
+    print(f"  TTL (exact):       {cfg.ttl.exact_seconds}s")
+    print(f"  TTL (semantic):    {cfg.ttl.semantic_seconds}s")
+    print(f"  Hits:              {snap.hits}")
+    print(f"  Misses:            {snap.misses}")
+    print(f"  Hit rate:          {snap.hit_rate:.1%}")
+
+
+def cmd_cache_clear(args: Namespace) -> None:
+    """Delete all cache entries for a tenant."""
+    use_json = getattr(args, "json", False)
+    tenant = getattr(args, "tenant", "default")
+
+    db = _get_cache_db()
+    deleted = db.clear_tenant(tenant)
+
+    if use_json:
+        print(json.dumps({"status": "ok", "deleted": deleted}))
+        return
+
+    print(f"Cache cleared: {deleted} entries deleted.")
+    print("Hot-reload: daemon will pick up config change within 2s.")
+
+
+def cmd_cache_invalidate(args: Namespace) -> None:
+    """Delete entries matching a tag."""
+    use_json = getattr(args, "json", False)
+    tag = getattr(args, "tag", None)
+
+    if not tag:
+        print("Error: --tag is required.", file=sys.stderr)
+        sys.exit(1)
+
+    db = _get_cache_db()
+    deleted = db.invalidate_by_tag(tag)
+
+    if use_json:
+        print(json.dumps({"status": "ok", "deleted": deleted, "tag": tag}))
+        return
+
+    print(f"Invalidated: {deleted} entries with tag \"{tag}\".")
+
+
+def cmd_cache_ttl(args: Namespace) -> None:
+    """Set exact-cache and/or semantic-cache TTL."""
+    use_json = getattr(args, "json", False)
+    ttl_set = getattr(args, "ttl_set", None)
+    ttl_semantic = getattr(args, "ttl_semantic", None)
+
+    if ttl_set is not None and ttl_set <= 0:
+        print("Error: --set must be a positive integer.", file=sys.stderr)
+        sys.exit(1)
+    if ttl_semantic is not None and ttl_semantic <= 0:
+        print("Error: --semantic must be a positive integer.", file=sys.stderr)
+        sys.exit(1)
+
+    store = _get_store()
+    cfg = store.get()
+
+    fields: dict = {}
+    if ttl_set is not None:
+        new_ttl = dataclasses.replace(cfg.ttl, exact_seconds=ttl_set)
+        fields["ttl"] = new_ttl
+    if ttl_semantic is not None:
+        new_ttl = dataclasses.replace(cfg.ttl, semantic_seconds=ttl_semantic)
+        fields["ttl"] = new_ttl
+
+    if not fields:
+        print("Error: specify --set and/or --semantic.", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        cfg = dataclasses.replace(cfg, **fields)
+        store.save(cfg)
+    except (ValueError, OSError) as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if use_json:
+        result: dict = {"status": "ok"}
+        if ttl_set is not None:
+            result["ttl_exact"] = ttl_set
+        if ttl_semantic is not None:
+            result["ttl_semantic"] = ttl_semantic
+        print(json.dumps(result, indent=2))
+        return
+
+    if ttl_set is not None:
+        print(f"TTL (exact) set to {ttl_set}s.")
+    if ttl_semantic is not None:
+        print(f"TTL (semantic) set to {ttl_semantic}s.")
+    print("Daemon hot-reload: active within 2s. No restart required.")
+
+
+def cmd_cache_semantic(args: Namespace) -> None:
+    """Enable or disable semantic cache."""
+    use_json = getattr(args, "json", False)
+    value = getattr(args, "semantic_value", "off")
+
+    _write_config(semantic_enabled=(value == "on"))
+
+    if use_json:
+        print(json.dumps({"status": "ok", "semantic_enabled": value == "on"}))
+        return
+
+    if value == "on":
+        print("Semantic cache: ENABLED.")
+        print("Note: requires embedding model (~500MB). Run `slm warmup` if not already done.")
+    else:
+        print("Semantic cache: DISABLED.")
+    print("Daemon hot-reload: active within 2s.")