superlocalmemory 3.5.9__tar.gz → 3.6.2__tar.gz

{superlocalmemory-3.5.9/src/superlocalmemory.egg-info → superlocalmemory-3.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superlocalmemory
-Version: 3.5.9
+Version: 3.6.2
 Summary: Information-geometric agent memory with mathematical guarantees
 Author-email: Varun Pratap Bhardwaj <admin@superlocalmemory.com>
 License: AGPL-3.0-or-later
@@ -49,6 +49,7 @@ Requires-Dist: watchdog==5.0.3
 Requires-Dist: psutil==7.2.2
 Requires-Dist: structlog==25.5.0
 Requires-Dist: portalocker==3.2.0
+Requires-Dist: cryptography==45.0.2
 Requires-Dist: sentence-transformers==5.3.0
 Requires-Dist: optimum==2.1.0
 Requires-Dist: onnxruntime==1.24.4
@@ -93,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>
@@ -120,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>
 
 ---
 
@@ -239,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.
 
 ---
 
@@ -274,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
@@ -284,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.
@@ -299,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 |
@@ -618,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
@@ -670,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 |

{superlocalmemory-3.5.9 → superlocalmemory-3.6.2}/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 |

{superlocalmemory-3.5.9 → superlocalmemory-3.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.5.9"
+version = "3.6.2"
 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.

{superlocalmemory-3.5.9 → superlocalmemory-3.6.2}/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.2"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.3.0",