superlocalmemory 3.5.8 → 3.6.1

package/src/superlocalmemory/cli/optimize_cmd.py

@@ -0,0 +1,178 @@
+# 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 optimize status|on|off|savings``."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import sys
+from argparse import Namespace
+
+from superlocalmemory.cli.optimize_constants import (
+    DEFAULT_COST_PER_MILLION_INPUT_TOKENS,
+    OPTIMIZE_DEFAULT_PORT,
+    _PRICING_DATE,
+)
+
+
+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. Call from any handler."""
+    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_optimize(args: Namespace) -> None:
+    """Top-level dispatcher for ``slm optimize <subcommand>``."""
+    sub = getattr(args, "opt_command", None)
+    _dispatch = {
+        "status": cmd_optimize_status,
+        "on": cmd_optimize_on,
+        "off": cmd_optimize_off,
+        "savings": cmd_optimize_savings,
+    }
+    handler = _dispatch.get(sub or "")
+    if handler:
+        handler(args)
+    else:
+        print("Usage: slm optimize status|on|off|savings [--json] [--since N]")
+        sys.exit(0)
+
+
+def cmd_optimize_status(args: Namespace) -> None:
+    """Print current Optimize module status."""
+    cfg = _get_store().get()
+    use_json = getattr(args, "json", False)
+
+    proxy_running = False
+    try:
+        import urllib.request
+        _url = f"http://127.0.0.1:{OPTIMIZE_DEFAULT_PORT}/health"
+        _req = urllib.request.Request(_url, method="GET")
+        with urllib.request.urlopen(_req, timeout=1) as _resp:
+            proxy_running = _resp.status == 200
+    except Exception:
+        pass
+
+    if use_json:
+        data = {
+            "status": "ok",
+            "optimize_enabled": cfg.enabled,
+            "cache_enabled": cfg.cache_enabled,
+            "semantic_enabled": cfg.semantic_enabled,
+            "compress_enabled": cfg.compress_enabled,
+            "compress_mode": cfg.compress_mode,
+            "proxy_running": proxy_running,
+            "proxy_port": OPTIMIZE_DEFAULT_PORT,
+            "config_version": cfg.config_version,
+        }
+        print(json.dumps(data, indent=2))
+        return
+
+    state = "ON" if cfg.enabled else "OFF"
+    print(f"Optimize: {state}")
+    print(f"  Cache:     {'enabled' if cfg.cache_enabled else 'disabled'}"
+          f"  (exact: {cfg.ttl.exact_seconds}s TTL,"
+          f" semantic: {'OFF' if not cfg.semantic_enabled else f'{cfg.ttl.semantic_seconds}s'})")
+    print(f"  Compress:  {'enabled' if cfg.compress_enabled else 'disabled'}"
+          f"  (mode: {cfg.compress_mode},"
+          f" code: {'ON' if cfg.compress_code else 'OFF'},"
+          f" prose: {'ON' if cfg.compress_prose else 'OFF'},"
+          f" CCR: {'ON' if cfg.compress_ccr else 'OFF'})")
+    proxy_status = f"running on :{OPTIMIZE_DEFAULT_PORT}" if proxy_running else "not running"
+    print(f"  Proxy:     {proxy_status}")
+    print(f"  Config:    ~/.superlocalmemory/optimize.json  (version {cfg.config_version})")
+
+
+def cmd_optimize_on(args: Namespace) -> None:
+    """Enable all Optimize features (cache + compress)."""
+    _write_config(enabled=True, cache_enabled=True, compress_enabled=True)
+    use_json = getattr(args, "json", False)
+    if use_json:
+        print(json.dumps({"status": "ok", "optimize_enabled": True}))
+    else:
+        print("Optimize enabled. Run 'slm proxy' to start the proxy."
+              " Daemon hot-reload: active within 2s.")
+
+
+def cmd_optimize_off(args: Namespace) -> None:
+    """Disable all Optimize features. Does NOT stop proxy."""
+    _write_config(
+        enabled=False,
+        cache_enabled=False,
+        semantic_enabled=False,
+        compress_enabled=False,
+    )
+    use_json = getattr(args, "json", False)
+    if use_json:
+        print(json.dumps({"status": "ok", "optimize_enabled": False}))
+    else:
+        print("Optimize disabled. Proxy (if running) will pass through calls unchanged.")
+
+
+def cmd_optimize_savings(args: Namespace) -> None:
+    """Print token/cost savings from CacheDB.metrics_load()."""
+    since = getattr(args, "since", 7)
+    provider = getattr(args, "provider", None)
+    use_json = getattr(args, "json", False)
+
+    if since <= 0:
+        print("Error: --since must be a positive integer.", file=sys.stderr)
+        sys.exit(1)
+
+    snap = _get_cache_db().metrics_load()
+    cfg = _get_store().get()
+
+    tokens_saved = snap.tokens_saved_input + snap.tokens_saved_output + snap.tokens_saved_compress
+    provider_key = provider or "default"
+    rate = DEFAULT_COST_PER_MILLION_INPUT_TOKENS.get(
+        provider_key,
+        DEFAULT_COST_PER_MILLION_INPUT_TOKENS["default"],
+    )
+    # Allow config overrides
+    if cfg.pricing_overrides and provider_key in cfg.pricing_overrides:
+        rate = cfg.pricing_overrides[provider_key].get("input_per_1m_usd", rate)
+
+    estimated_savings_usd = tokens_saved / 1_000_000 * rate
+
+    if use_json:
+        data = {
+            "exact_hits": snap.hits,
+            "semantic_hits": snap.misses,
+            "tokens_saved": tokens_saved,
+            "estimated_savings_usd": round(estimated_savings_usd, 6),
+            "pricing_date": _PRICING_DATE,
+            "tokens_saved_input": snap.tokens_saved_input,
+            "tokens_saved_output": snap.tokens_saved_output,
+            "tokens_saved_compress": snap.tokens_saved_compress,
+        }
+        print(json.dumps(data, indent=2))
+        return
+
+    print(f"Savings (last {since} days):")
+    print(f"  Exact cache hits:    {snap.hits:>5}   ({snap.tokens_saved_input:,} input tokens saved)")
+    print(f"  Semantic cache hits: {snap.misses:>5}")
+    print(f"  Tokens saved (total): {tokens_saved:,}")
+    print(f"  Estimated savings:  ~${estimated_savings_usd:.4f} (at ${rate:.2f}/M tokens)")
+    print(f"  Pricing date: {_PRICING_DATE}")

package/src/superlocalmemory/cli/optimize_constants.py

@@ -0,0 +1,31 @@
+# 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
+
+"""Constants shared by Optimize CLI handlers.
+
+No imports from optimize.* at module load time (lazy import in functions only).
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+OPTIMIZE_DEFAULT_PORT: Final[int] = 8765
+
+# Cache skip saves BOTH input+output tokens (whole call avoided).
+# For CLI display we show the conservative input-price lower bound.
+DEFAULT_COST_PER_MILLION_INPUT_TOKENS: Final[dict[str, float]] = {
+    "anthropic": 3.00,
+    "openai":    2.50,
+    "gemini":    1.25,
+    "default":   3.00,
+}
+_PRICING_DATE: Final[str] = "2026-06-07"
+
+AGGRESSIVE_MODE_WARNING: Final[str] = (
+    "WARNING: Aggressive mode may reduce output fidelity.\n"
+    "  Do NOT use for: code generation, legal text, exact-output tasks, math.\n"
+    "  Safe for: summarization, brainstorming, open-ended chat.\n"
+    "  To revert: slm compress mode safe"
+)

package/src/superlocalmemory/cli/proxy_cmd.py

@@ -0,0 +1,104 @@
+# 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
+
+"""Handler for ``slm proxy``."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import sys
+from argparse import Namespace
+
+_DEFAULT_PORT: int = 8765
+
+
+def _get_store():
+    from superlocalmemory.optimize.config.store import ConfigStore
+    return ConfigStore()
+
+
+def _ensure_running(port: int) -> bool:
+    """Liveness probe: return True if the SLM daemon is responding at *port*.
+
+    Calls GET /health with a 2-second timeout.  The SLM daemon (which also acts
+    as the optimize proxy) is the process that answers on :8765; if it responds
+    the proxy layer is alive. We do NOT call lifecycle.ensure_proxy_running()
+    here because that function reads config via the daemon-internal store
+    (get_optimize_config/_store) which is None in a CLI subprocess context.
+    """
+    try:
+        import urllib.request
+        url = f"http://127.0.0.1:{port}/health"
+        req = urllib.request.Request(url, method="GET")
+        with urllib.request.urlopen(req, timeout=2) as resp:
+            return resp.status == 200
+    except Exception:
+        return False
+
+
+def cmd_proxy(args: Namespace) -> None:
+    """Start the SLM optimization proxy (or report if already running)."""
+    use_json = getattr(args, "json", False)
+    port = getattr(args, "port", _DEFAULT_PORT)
+    provider = getattr(args, "provider", "anthropic")
+    no_compress = getattr(args, "no_compress", False)
+    semantic = getattr(args, "semantic", False)
+
+    # CRIT-3 FIX: validate port before any config write
+    if not (1024 <= port <= 65535):
+        print(f"Error: --port must be 1024–65535, got {port}.", file=sys.stderr)
+        sys.exit(1)
+
+    store = _get_store()
+    cfg = store.get()
+
+    # Build config updates
+    providers = dict(cfg.providers) if cfg.providers else {}
+    from superlocalmemory.optimize.config.schema import ProviderConfig
+    existing = providers.get(provider, ProviderConfig())
+    providers[provider] = ProviderConfig(
+        enabled=existing.enabled,
+        base_url=f"http://localhost:{port}",
+    )
+
+    fields: dict = {"providers": providers, "proxy_enabled": True}
+    if no_compress:
+        fields["compress_enabled"] = False
+    if semantic:
+        fields["semantic_enabled"] = True
+
+    try:
+        cfg = dataclasses.replace(cfg, **fields)
+        store.save(cfg)
+    except (ValueError, OSError) as e:
+        print(f"Error writing config: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    running = _ensure_running(port)
+
+    if use_json:
+        data = {
+            "status": "running" if running else "failed",
+            "port": port,
+            "anthropic_url": f"http://localhost:{port}",
+            "openai_url": f"http://localhost:{port}/v1",
+            "provider": provider,
+            "compress": not no_compress,
+            "semantic": semantic,
+        }
+        print(json.dumps(data, indent=2))
+    else:
+        if running:
+            print(f"SLM proxy starting on :{port}...")
+            print(f"  Anthropic surface:  http://localhost:{port}")
+            print(f"  OpenAI surface:     http://localhost:{port}/v1")
+            print()
+            print(f"Set ANTHROPIC_BASE_URL=http://localhost:{port} before running Claude Code.")
+            print("Or run: slm wrap claude")
+            print()
+            print("Proxy ready.")
+        else:
+            print("Error: proxy failed to start. Check logs.", file=sys.stderr)
+            sys.exit(1)

package/src/superlocalmemory/core/config.py

@@ -691,6 +691,9 @@ class SLMConfig:
         mode = Mode(data.get("mode", "a"))
         llm_data = data.get("llm", {})
         emb_data = data.get("embedding", {})
+        # V3.5.9: read base_dir before constructing config so for_mode() builds
+        # db_path from the user's directory, not DEFAULT_BASE_DIR.
+        raw_base_dir = Path(data.get("base_dir", str(DEFAULT_BASE_DIR)))
         config = cls.for_mode(
             mode,
             llm_provider=llm_data.get("provider", ""),
@@ -703,6 +706,7 @@ class SLMConfig:
             embedding_deployment=emb_data.get("deployment_name", ""),
             embedding_model_name=emb_data.get("model_name", ""),
             embedding_dimension=int(emb_data.get("dimension", 0) or 0),
+            base_dir=raw_base_dir,
         )
         config.active_profile = data.get("active_profile", "default")
 
@@ -813,6 +817,7 @@ class SLMConfig:
         data = {
             "mode": effective_mode,
             "active_profile": self.active_profile,
+            "base_dir": str(self.base_dir),  # V3.5.9: persist so load() can restore custom paths
             "llm": {
                 "provider": self.llm.provider,
                 "model": self.llm.model,

package/src/superlocalmemory/core/engine.py

@@ -126,6 +126,10 @@ class MemoryEngine:
 
         if self._capabilities is Capabilities.FULL:
             self._init_heavy_layer()
+        else:
+            # V3.5.9: LIGHT mode — try to get embedder from running daemon so that
+            # memories stored via MCP have real embeddings (fixes PR #30 NULL embedder).
+            self._try_init_proxy()
 
         self._initialized = True
         logger.info(
@@ -187,6 +191,25 @@ class MemoryEngine:
         from superlocalmemory.learning.adaptive import AdaptiveLearner
         self._adaptive_learner = AdaptiveLearner(self._db)
 
+    def _try_init_proxy(self) -> None:
+        """V3.5.9: Attach McpEmbedderProxy when running in LIGHT mode.
+
+        If the daemon is reachable, the proxy delegates embed calls over HTTP
+        so that MCP-stored facts have real embeddings (fixes PR #30). Silently
+        skips if the daemon is not running — keyword recall still works.
+        """
+        try:
+            from superlocalmemory.core.mcp_embedder_proxy import McpEmbedderProxy
+            port = getattr(self._config, "daemon_port", 8765)
+            proxy = McpEmbedderProxy(port=port)
+            if proxy.is_available():
+                self._embedder = proxy
+                logger.info("MCP embedder proxy attached (daemon port %d)", port)
+            else:
+                logger.debug("Daemon not reachable — MCP will run without embedder")
+        except Exception as exc:
+            logger.debug("McpEmbedderProxy init skipped: %s", exc)
+
     def _init_heavy_layer(self) -> None:
         from superlocalmemory.llm.backbone import LLMBackbone
         from superlocalmemory.core.engine_wiring import (

package/src/superlocalmemory/core/mcp_embedder_proxy.py

@@ -0,0 +1,89 @@
+# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
+# Licensed under AGPL-3.0-or-later - see LICENSE file
+# Part of SuperLocalMemory V3 | https://qualixar.com
+
+"""V3.5.9 — McpEmbedderProxy: lightweight embedder for the MCP (LIGHT) process.
+
+Problem: MemoryEngine(Capabilities.LIGHT) skips _init_heavy_layer(), leaving
+_embedder=None permanently. Any memory stored via MCP tools has NULL embeddings
+→ semantic search silently broken; health() lies, reporting unavailable.
+
+Solution: a thin proxy that delegates embed_batch() to the running daemon via
+its POST /api/embed endpoint over localhost HTTP. The daemon runs a FULL engine
+with one real ONNX/Ollama worker. No second ONNX process is spawned.
+
+Usage (engine.py LIGHT branch):
+    proxy = McpEmbedderProxy(port=8765)
+    if proxy.is_available():
+        engine._embedder = proxy
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_TIMEOUT = 5.0  # seconds — fast enough for inline store() calls
+
+
+class McpEmbedderProxy:
+    """Proxy embedder: MCP process → daemon's /api/embed over localhost HTTP."""
+
+    def __init__(self, port: int = 8765, timeout: float = _DEFAULT_TIMEOUT) -> None:
+        self._base_url = f"http://127.0.0.1:{port}"
+        self._timeout = timeout
+        self._available: bool | None = None  # cached after first is_available() call
+
+    def is_available(self) -> bool:
+        """Ping daemon's embed endpoint. Cached after first success."""
+        if self._available is True:
+            return True
+        try:
+            import httpx
+            resp = httpx.get(f"{self._base_url}/api/v3/embed/ping", timeout=2.0)
+            self._available = resp.status_code == 200
+        except Exception:
+            self._available = False
+        return bool(self._available)
+
+    # -- Embedder interface (matches embeddings.py / ollama_embedder.py) ------
+
+    def embed(self, text: str) -> list[float] | None:
+        """Embed a single text via daemon. Returns None on any error."""
+        results = self.embed_batch([text])
+        return results[0] if results else None
+
+    def embed_batch(self, texts: list[str]) -> list[list[float] | None]:
+        """Embed a batch of texts via daemon's /api/embed endpoint."""
+        if not texts:
+            return []
+        try:
+            import httpx
+            resp = httpx.post(
+                f"{self._base_url}/api/v3/embed",
+                json={"texts": texts},
+                timeout=self._timeout,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            embeddings = data.get("embeddings", [])
+            # Pad with None if daemon returned fewer results than requested
+            while len(embeddings) < len(texts):
+                embeddings.append(None)
+            return embeddings
+        except Exception as exc:
+            logger.debug("McpEmbedderProxy.embed_batch failed: %s", exc)
+            return [None] * len(texts)
+
+    def compute_fisher_params(
+        self, embedding: list[float]
+    ) -> tuple[list[float] | None, list[float] | None]:
+        """Fisher-Rao params stay in daemon's FULL engine; proxy returns None.
+
+        The MCP LIGHT process stores facts with embedding=<vector> but
+        fisher_mean=None, fisher_variance=None. The daemon's consolidation
+        pass fills these in asynchronously — same behaviour as the
+        write-through remember path.
+        """
+        return None, None

package/src/superlocalmemory/llm/backbone.py

@@ -233,17 +233,23 @@ class LLMBackbone:
         self, prompt: str, system: str, max_tokens: int, temperature: float,
     ) -> tuple[str, dict[str, str], dict]:
         messages = self._make_messages(system, prompt)
-        headers = {
-            "Authorization": f"Bearer {self._api_key}",
-            "Content-Type": "application/json",
-        }
+        # V3.5.9: Skip Authorization header when api_key is empty so unauthenticated
+        # local endpoints (llama.cpp, LM Studio, etc.) don't reject with HTTP 401.
+        headers = {"Content-Type": "application/json"}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
         payload = {
             "model": self._model,
             "messages": messages,
             "max_tokens": max_tokens,
             "temperature": temperature,
         }
+        # V3.5.9: If base_url is a bare base (e.g. "http://host:port/v1") without
+        # the /chat/completions path, append it — matching OpenAI SDK behaviour and
+        # fixing the /v1/v1 duplication reported in issue #29.
         url = self._base_url or _OPENAI_URL
+        if self._base_url and not self._base_url.rstrip("/").endswith("chat/completions"):
+            url = f"{self._base_url.rstrip('/')}/chat/completions"
         return url, headers, payload
 
     def _build_ollama(

package/src/superlocalmemory/mcp/server.py

@@ -278,5 +278,39 @@ _watchdog_thread = threading.Thread(target=_parent_watchdog, daemon=True, name="
 _watchdog_thread.start()
 
 
+# V3.5.9: Stdin EOF monitor — complements the parent watchdog for the case where
+# the IDE starts a new MCP session WITHOUT quitting the app. The old stdio pipe
+# is abandoned (write-end closed) but the parent process stays alive, so the
+# watchdog never fires. Without this, each IDE reconnect adds a zombie process
+# (22 seen in production causing 12 GB swap on the M5 Pro).
+#
+# Uses kqueue(2) KQ_EV_EOF on macOS — fires when the write-end of the stdin pipe
+# closes WITHOUT consuming any bytes, so it cannot race with FastMCP's asyncio
+# stdin reader. On Linux (no kqueue), the watchdog alone provides coverage.
+def _stdin_eof_monitor() -> None:
+    """Exit when the IDE closes our stdin pipe (kqueue — macOS only)."""
+    import select as _sel, os as _os_eof
+    _mlog = logging.getLogger(__name__ + ".stdin_monitor")
+    if not hasattr(_sel, "kqueue"):
+        return  # Linux / non-macOS: watchdog covers process death
+    try:
+        fd = sys.stdin.fileno()
+        kq = _sel.kqueue()
+        ke = _sel.kevent(fd, filter=_sel.KQ_FILTER_READ, flags=_sel.KQ_EV_ADD | _sel.KQ_EV_EOF)
+        kq.control([ke], 0)  # register without waiting
+        while True:
+            evs = kq.control(None, 4, 30.0)  # 30 s poll — low cost
+            for ev in evs:
+                if ev.flags & _sel.KQ_EV_EOF:
+                    _mlog.info("stdin write-end closed (kqueue EOF), self-terminating")
+                    _os_eof._exit(0)
+    except Exception as exc:
+        _mlog.debug("stdin EOF monitor error: %s — watchdog will cover", exc)
+
+
+_stdin_monitor_thread = threading.Thread(target=_stdin_eof_monitor, daemon=True, name="stdin-eof-monitor")
+_stdin_monitor_thread.start()
+
+
 if __name__ == "__main__":
     server.run(transport="stdio")

package/src/superlocalmemory/mcp/tools_v3.py

@@ -161,9 +161,13 @@ def register_v3_tools(server, get_engine: Callable) -> None:
                 "fact_count": fact_count,
             }
 
-            # Embedding service
+            # Embedding service — distinguish real embedder from V3.5.9 daemon proxy
+            _emb = engine._embedder
+            from superlocalmemory.core.mcp_embedder_proxy import McpEmbedderProxy
+            _is_proxy = isinstance(_emb, McpEmbedderProxy)
             status["components"]["embedder"] = {
-                "status": "ok" if engine._embedder else "unavailable",
+                "status": "ok" if _emb else "unavailable",
+                "source": "daemon_proxy" if _is_proxy else "local",
                 "model": engine._config.embedding.model_name,
             }
 

package/src/superlocalmemory/optimize/NOTICE

@@ -0,0 +1,11 @@
+Third-party components used by SLM v3.6 Optimize module:
+
+1. Headroom (Apache-2.0)
+   Copyright (c) 2024 Headroom contributors
+   Source: https://github.com/headroom/headroom
+   License: Apache-2.0
+
+2. LLMLingua-2 (MIT)
+   Copyright (c) 2024 Microsoft Corporation
+   Source: https://github.com/microsoft/LLMLingua
+   License: MIT

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

@@ -0,0 +1,68 @@
+"""optimize/adapters — SDK adapters for OpenAI / Anthropic / LangChain.
+
+SECURITY: No pickle anywhere. JSON+pydantic only (SEC-C-04, CWE-502).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger("superlocalmemory.optimize.adapters")
+
+
+def withSLM(client: Any, *, tenant_id: str = "default") -> Any:
+    """Wrap any supported SDK client with SLM cache hooks.
+
+    FAIL-OPEN GUARANTEE:
+      - If Optimize is disabled (config.enabled == False) → return client unchanged.
+      - If cache is unavailable → return client unchanged, log WARNING.
+      - If client type unrecognized → return client unchanged, log WARNING.
+    """
+    try:
+        from superlocalmemory.optimize.config import get_optimize_config
+        from superlocalmemory.optimize.cache.manager import CacheManager
+    except ImportError as exc:
+        logger.warning("SLM Optimize not available (%s) — pass-through active", exc)
+        return client
+
+    config = get_optimize_config()
+    if not config.enabled:
+        return client  # DEFAULT STATE — zero behavioral change
+
+    try:
+        cache_manager = CacheManager.get_instance()
+    except Exception as exc:
+        logger.warning("SLM cache unavailable (%s) — pass-through active", exc)
+        return client
+
+    # Anthropic (.messages.create)
+    if hasattr(client, "messages") and hasattr(client.messages, "create"):
+        try:
+            from superlocalmemory.optimize.adapters.anthropic_adapter import (
+                SLMAnthropicAdapter,
+            )
+            return SLMAnthropicAdapter(client, cache_manager, config, tenant_id)
+        except Exception as exc:
+            logger.warning("SLM Anthropic adapter init failed: %s", exc)
+            return client
+
+    # OpenAI (.chat.completions)
+    if hasattr(client, "chat") and hasattr(client.chat, "completions"):
+        try:
+            from superlocalmemory.optimize.adapters.openai_adapter import (
+                SLMOpenAIAdapter,
+            )
+            return SLMOpenAIAdapter(client, cache_manager, config, tenant_id)
+        except Exception as exc:
+            logger.warning("SLM OpenAI adapter init failed: %s", exc)
+            return client
+
+    logger.warning(
+        "withSLM: unrecognized client type %s — pass-through active",
+        type(client).__name__,
+    )
+    return client
+
+
+__all__ = ["withSLM"]