superlocalmemory 3.6.10 → 3.6.12

package/CHANGELOG.md

@@ -5,6 +5,71 @@ 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.12] - 2026-06-14 — Distributed-ready + stability fixes
+
+Makes SuperLocalMemory work correctly across a LAN / distributed deployment (issues #39, #40) and fixes a set of stability and security defects. Default single-machine behavior is unchanged.
+
+### Added
+
+- **`SLM_REMOTE=1` — one-switch LAN mode** (default OFF). When enabled, SLM serves the dashboard install token to allowlisted LAN clients, runs the MCP transport statelessly so a gateway/hub can forward tool calls, allows trusted LAN dashboard origins, and exempts the trusted LAN dashboard from rate limiting. LAN access stays gated by `SLM_MCP_ALLOWED_HOSTS`. Granular flags: `SLM_MCP_STATELESS=1`, and tunable rate limits `SLM_RATE_LIMIT_WRITE` / `SLM_RATE_LIMIT_READ` / `SLM_RATE_LIMIT_WINDOW`. See `docs/distributed-deployment.md`.
+- **`slm search`** CLI command (parity with the MCP `search` tool).
+
+### Fixed — Distributed / LAN (#39, #40)
+
+- **The Brain page now loads from a remote browser** on the LAN (the install-token endpoint serves allowlisted LAN clients in remote mode instead of being loopback-only).
+- **Mesh tools no longer fail with `-32600 Session not found`** when called through an MCP gateway/hub (the transport can now run stateless so the session id need not be replayed).
+- **Custom LLM endpoints (llama.cpp / LM Studio / Azure) can now be configured from the dashboard** — the Settings page shows, sends, and saves the endpoint, and switching mode actually persists.
+- **The dashboard rate limit (`429 Too Many Requests`) is now configurable** and trusted LAN clients are exempt in remote mode.
+
+### Fixed — Stability & security
+
+- **Authentication now fails closed.** A failure to install the auth gate could previously leave write endpoints unauthenticated; it now logs and denies non-loopback writes instead.
+- **Mesh peer registration fixed** — sessions now register with the correct peer id, so heartbeat, direct messages, and inbox work reliably (previously they could silently target a non-existent peer).
+- **`SLM_MESH_SHARED_SECRET` is now enforced** on inbound mesh requests from non-loopback callers.
+- **The cache no longer raises on a corrupted or wrong-key entry** — it degrades to a cache miss.
+- **SSRF protection** added to the provider connection test (cloud-metadata and internal addresses are blocked for remote callers; the local dashboard can still test local/LAN endpoints).
+- **Mode B no longer silently falls back to Mode A** when using a keyless local LLM endpoint.
+- **Memory search no longer errors on punctuation** (`?`, `-`, quotes, etc.).
+- **Mode B honors the configured LLM endpoint and timeout** in summarization and consolidation (previously hardcoded to localhost).
+- **Math-health dashboard reports real status** instead of always showing green.
+- Mesh lock release and inbox now behave correctly (no false success, no re-listing of already-read messages); switching profile takes effect immediately for recall.
+
+### Removed
+
+- Removed legacy dead code (an unused in-process daemon handler and superseded duplicate API routes) for a cleaner, more maintainable codebase. No functional change. — Optimize Everywhere: three surfaces (proxy · MCP tools · skill)
+
+Cache + compress across **every setup** — proxy, MCP tools, or skill. Five new MCP tools land directly inside `slm mcp` (no proxy, full 1M context window preserved). A new `slm-optimize` skill makes compression and routed-result caching zero-config for Claude Code users. Overclaim in prior docs fixed; three-surfaces table added.
+
+### Added — Surface B: MCP Optimize Tools (proxy-free)
+
+Five new tools registered in `slm mcp` from v3.6.11+:
+
+- **`slm_compress`** — compress text or tool output. `mode=normalize` is lossless whitespace normalization; `mode=auto`/`aggressive` delegates to the existing CompressRouter engine. Lossy + reversible stores the original in CCR and returns a `ccr_id`. Content >1 MB is stored unreversed. All fail-open.
+- **`slm_retrieve`** — recover the exact original bytes from a `ccr_id` UUID4 returned by `slm_compress`. Validates UUID format before lookup.
+- **`slm_cache_set`** — cache any string result the agent routes through SLM (file reads, bash output, search results, sub-model calls). Key is SHA-256 namespaced `mcpkv:{agent_id}:{key}` — no cross-agent collisions. TTL default 24 h.
+- **`slm_cache_get`** — retrieve a cached result by key. Returns `hit:True/False`. Increments in-module `_kv_hits`/`_kv_misses` counters for stats.
+- **`slm_optimize_stats`** — session compression + cache statistics. Proxy counters read from `CacheDB.metrics_load()` (daemon-persisted, accurate across restarts); KV counters are in-module for this MCP process session.
+
+All five are **fail-open**: any internal error returns `{ok: False, note: <error>}` with the original content unchanged — never raises to the agent.
+
+### Added — Surface C: slm-optimize Skill (zero-config)
+
+- **`skills/slm-optimize/SKILL.md`** and **`ide/skills/slm-optimize/SKILL.md`** — agent-behavior instruction file. Eight behavioral rules: compress CLAUDE.md at session start, compress large tool outputs via `slm_compress`, KV-cache repeated file reads and bash/search results, recover originals with `slm_retrieve`, never-compress list (secrets, JSON, code/Edit/Write outputs), emit stats on request, fail-open on `ok:False`. Compatible with Claude Code, Cursor, Antigravity, Codex, and any IDE that supports MCP tool calls.
+- **`skills/slm-optimize/README.md`** — human install guide: prerequisites, install steps, activation options, feature table, and explicit "what it does NOT do" section.
+
+### Changed — `CacheDB` (new public method)
+
+- **`CacheDB.get_value(cache_key, tenant_id)`** added to `optimize/storage/db.py` — pure `SELECT` lookup with no `hit_count` side-effect (unlike `get()`). Used by `slm_cache_get` to avoid inflating proxy cache counters when agents read KV entries. Fail-open: returns `None` on any SQLite/decryption/zlib error.
+
+### Changed — MCP server registration
+
+- Five optimize tool names added to `_ESSENTIAL_TOOLS` frozenset in `mcp/server.py` (v3.6.11 Surface B). Without this the `_FilteredServer` wrapper silently drops tools whose names are not in the set.
+- `register_optimize_tools(_target)` call added after other `register_*` calls.
+
+### Fixed — Overclaim in README / docs
+
+- Replaced "Save up to 90% on every LLM API call" headline with accurate three-surfaces framing: proxy (full-turn caching on metered API), MCP tools (routed-result caching + compression), skill (auto-applied compression). Hard constraint documented: primary Claude conversation turn cannot be cached without a proxy — never implied otherwise.
+
 ## [3.6.10] - 2026-06-14 — Optimize correctness (cache + lossless compression) · MCP per-agent identity · runtime toggles · benchmark + shadow-capture · Issue #38
 
 This release makes the **Optimize** subsystem (the HTTP proxy that caches and compresses LLM API calls) correct, observable, and **independently controllable at runtime**, adds **per-agent identity** to the HTTP MCP transport, ships a **benchmark + shadow-capture** harness that proves the cache and compression behaviour, and fixes GitHub issue #38. Cache and compression remain **default-OFF** and are now separately toggleable from the dashboard.

package/README.md

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

package/package.json

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

package/pyproject.toml

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

package/skills/slm-optimize/README.md

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

package/skills/slm-optimize/SKILL.md

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

package/src/superlocalmemory/cli/commands.py

@@ -114,6 +114,7 @@ def dispatch(args: Namespace) -> None:
         "list": cmd_list,
         "remember": cmd_remember,
         "recall": cmd_recall,
+        "search": cmd_recall,  # v3.6.12 (parity-3): MCP exposes a `search` verb; give the CLI parity (recall is multi-channel incl. BM25/keyword).
         "forget": cmd_forget,
         "delete": cmd_delete,
         "update": cmd_update,