superlocalmemory 3.6.8 → 3.6.10

package/src/superlocalmemory/mcp/agent_context.py

@@ -0,0 +1,111 @@
+"""Per-HTTP-request agent ID resolution — ContextVar home.
+
+Kept in a standalone module so both tools_core and tools_active can import
+it without creating circular dependencies (server.py → tools_core → here,
+and unified_daemon.py → here independently).
+
+Priority chain (HTTP-first, stdio-fallback):
+  1. ContextVar set by _AgentIDExtractorASGI middleware from /mcp/{agent_id} URL path.
+  2. SLM_AGENT_ID environment variable (stdio transport legacy).
+  3. Hard-coded "mcp_client" sentinel.
+"""
+from __future__ import annotations
+
+import contextvars
+import os
+import re
+
+_current_agent_id: contextvars.ContextVar[str] = contextvars.ContextVar(
+    "slm_agent_id", default="mcp_client"
+)
+
+# Agent ids arrive from an untrusted URL path segment. They are ATTRIBUTION
+# metadata, never an authenticated principal — but they reach loggers, the
+# agent registry, and SQL-bound attribution columns, so we hard-restrict the
+# charset at the single extraction chokepoint. This neutralises log-injection
+# (CRLF / ANSI), oversized ids, and any path-ish characters in one place.
+_AGENT_ID_SANITIZE = re.compile(r"[^A-Za-z0-9._-]")
+_AGENT_ID_MAX_LEN = 64
+
+
+def sanitize_agent_id(raw: str) -> str:
+    """Coerce an untrusted agent-id segment to a safe, bounded token."""
+    return _AGENT_ID_SANITIZE.sub("_", raw)[:_AGENT_ID_MAX_LEN]
+
+
+def get_current_agent_id(env_fallback: bool = True) -> str:
+    """Return the agent_id for the current asyncio task.
+
+    For HTTP transport the ASGI wrapper sets the ContextVar from the URL path
+    before the request reaches any MCP tool, so this returns the URL-derived id.
+    For stdio transport the ContextVar holds its default ("mcp_client") and we
+    fall through to the SLM_AGENT_ID env var instead.
+    """
+    ctx_id = _current_agent_id.get()
+    if ctx_id != "mcp_client":
+        return ctx_id
+    if env_fallback:
+        return os.environ.get("SLM_AGENT_ID", "mcp_client")
+    return "mcp_client"
+
+
+class AgentIDExtractorASGI:
+    """ASGI wrapper that maps ``/mcp/{agent_id}`` → the agent-id ContextVar.
+
+    Mounted at ``/mcp`` in unified_daemon. IMPORTANT: Starlette's ``Mount``
+    (≥0.35 / 1.x) does NOT strip the mount prefix from ``scope["path"]`` — it
+    records the prefix in ``scope["root_path"]`` and leaves ``path`` as the full
+    request path (e.g. ``/mcp/claude`` with ``root_path == "/mcp"``). So we
+    compute the mount-relative sub-path ourselves as ``path[len(root_path):]``.
+
+    Flow for ``POST /mcp/claude``:
+      sub-path ``/claude`` → agent id ``claude`` → set ContextVar → rewrite the
+      scope path to ``{root_path}/`` so the inner FastMCP app (Starlette, route
+      ``/``) sees the same mount-relative ``/`` it sees for a bare ``/mcp/``.
+
+    Backward compatible: bare ``/mcp/`` has sub-path ``/`` → no agent segment →
+    the request passes through untouched and the ContextVar keeps its
+    ``"mcp_client"`` default.
+
+    Per-request isolation is guaranteed by ContextVar + ``reset(token)`` in a
+    ``finally``, so concurrent HTTP sessions never see each other's agent id.
+    """
+
+    __slots__ = ("_app",)
+
+    def __init__(self, inner) -> None:
+        self._app = inner
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") == "http":
+            root_path: str = scope.get("root_path", "")
+            full_path: str = scope.get("path", "/")
+            # Mount-relative sub-path (what comes AFTER /mcp). When a root_path
+            # is present the request path MUST start with it (Starlette Mount
+            # guarantees this); if it somehow does not, treat it as no-agent and
+            # pass through untouched rather than mis-parsing the full path.
+            if root_path:
+                if not full_path.startswith(root_path):
+                    await self._app(scope, receive, send)
+                    return
+                subpath = full_path[len(root_path):]
+            else:
+                subpath = full_path
+            first = subpath.lstrip("/").split("/")[0]
+            if first:
+                first = sanitize_agent_id(first)
+                token = _current_agent_id.set(first)
+                # Rewrite the path so the inner app sees the bare mount root,
+                # exactly as it would for a no-agent /mcp/ request.
+                new_full = (root_path + "/") if root_path else "/"
+                new_scope = {
+                    **scope,
+                    "path": new_full,
+                    "raw_path": new_full.encode(),
+                }
+                try:
+                    await self._app(new_scope, receive, send)
+                finally:
+                    _current_agent_id.reset(token)
+                return
+        await self._app(scope, receive, send)

package/src/superlocalmemory/mcp/tools_active.py

@@ -16,9 +16,12 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 
 from __future__ import annotations
 
+import asyncio
+import datetime
 import logging
 import os
 import sqlite3
+import uuid
 from pathlib import Path
 from typing import Callable
 
@@ -106,15 +109,14 @@ def _sqlite_emergency_recall(
 def _get_agent_id(default: str = "mcp_client") -> str:
     """Resolve the calling agent's ID for attribution.
 
-    Each MCP client (Claude Code, Codex, Gemini CLI, Kimi, etc.) can set
-    the ``SLM_AGENT_ID`` env var in its MCP server config so that memories,
-    observations, and registry entries are tagged with the actual source
-    agent — not the legacy ``"mcp_client"`` default.
-
-    v3.4.39+: enables proper per-agent attribution in ``session_init``,
-    ``observe``, and event emissions.
+    Priority chain (v3.6.10+):
+    1. ContextVar set by HTTP URL path (/mcp/{agent_id}) — HTTP transport.
+    2. SLM_AGENT_ID env var — stdio transport per-process identity.
+    3. Provided default (legacy "mcp_client").
     """
-    return os.environ.get("SLM_AGENT_ID", default)
+    from superlocalmemory.mcp.agent_context import get_current_agent_id
+    resolved = get_current_agent_id(env_fallback=True)
+    return resolved if resolved != "mcp_client" else default
 
 
 def _emit_event(event_type: str, payload: dict | None = None,
@@ -213,7 +215,13 @@ def register_active_tools(server, get_engine: Callable) -> None:
             from superlocalmemory.mcp._pool_adapter import PoolError
             degraded_mode = False
             try:
-                response = pool_recall(search_query, limit=max_results, fast=False)
+                # v3.6.9-audit: pool_recall uses blocking urllib under the hood
+                # (DaemonPoolProxy.recall → urllib.urlopen). Must run in a
+                # thread so the async MCP event loop is not stalled — same
+                # fix class as #34 mesh tools deadlock.
+                response = await asyncio.to_thread(
+                    pool_recall, search_query, limit=max_results, fast=False,
+                )
             except (PoolError, Exception) as exc:
                 logger.warning(
                     "session_init: daemon recall failed (%s) — using FTS5 emergency fallback. "
@@ -349,6 +357,13 @@ def register_active_tools(server, get_engine: Callable) -> None:
                     "session_init feedback_count read failed: %s", exc,
                 )
 
+            # v3.6.9 (#35): generate a stable session_id so clients can pass it
+            # to remember() and close_session() for proper session aggregation.
+            session_id = (
+                f"slm-{datetime.datetime.now(datetime.timezone.utc):%Y%m%d}"
+                f"-{uuid.uuid4().hex[:8]}"
+            )
+
             # Register agent + emit event (v3.4.39: SLM_AGENT_ID env support)
             agent_id = _get_agent_id()
             _register_agent(agent_id, pid)
@@ -360,6 +375,7 @@ def register_active_tools(server, get_engine: Callable) -> None:
 
             return {
                 "success": True,
+                "session_id": session_id,
                 "context": context,
                 "memories": memories[:max_results],
                 "memory_count": len(memories),
@@ -430,8 +446,11 @@ def register_active_tools(server, get_engine: Callable) -> None:
                     "confidence": round(decision.confidence, 3),
                 }
 
-            # Auto-store via engine
-            stored = auto.capture(
+            # Auto-store via engine.
+            # pool_store uses blocking urllib (DaemonPoolProxy) — run in
+            # thread so the MCP event loop stays unblocked (#34 class).
+            stored = await asyncio.to_thread(
+                auto.capture,
                 content,
                 category=decision.category,
                 metadata={"agent_id": agent_id, "source": "auto-observe"},
@@ -525,8 +544,24 @@ def register_active_tools(server, get_engine: Callable) -> None:
         try:
             engine = get_engine()
             sid = session_id or getattr(engine, '_last_session_id', '')
+            # v3.6.9 (#35): _last_session_id was never assigned — fall back to
+            # querying the DB for the most recent session_id instead of silently
+            # returning summary_events_created: 0.
+            if not sid:
+                try:
+                    db = getattr(engine, '_db', None) or getattr(engine, 'db', None)
+                    if db and hasattr(db, 'execute'):
+                        rows = db.execute(
+                            "SELECT session_id FROM memories "
+                            "WHERE session_id != '' ORDER BY created_at DESC LIMIT 1",
+                            ()
+                        )
+                        if rows:
+                            sid = str(rows[0][0])
+                except Exception:
+                    pass
             if not sid:
-                return {"success": False, "error": "No session_id provided"}
+                return {"success": False, "error": "No session_id provided or found"}
             count = engine.close_session(sid)
             return {
                 "success": True,

package/src/superlocalmemory/mcp/tools_core.py

@@ -110,6 +110,10 @@ def register_core_tools(server, get_engine: Callable) -> None:
         Extracts atomic facts, resolves entities, builds graph edges,
         and indexes for 4-channel retrieval.
         """
+        # v3.6.10: resolve "mcp_client" sentinel → URL path (HTTP) or env var (stdio)
+        if agent_id == "mcp_client":
+            from superlocalmemory.mcp.agent_context import get_current_agent_id
+            agent_id = get_current_agent_id()
         meta = {
             "project": project,
             "importance": importance,
@@ -122,9 +126,13 @@ def register_core_tools(server, get_engine: Callable) -> None:
         # recall window so a parallel/next agent finds memories saved seconds ago.
         # Falls back to pending.db only if the daemon is unreachable.
         try:
+            import asyncio as _asyncio
             from superlocalmemory.cli.daemon import daemon_request, is_daemon_running
-            if is_daemon_running():
-                resp = daemon_request("POST", "/remember", {
+            # is_daemon_running() and daemon_request() both use blocking urllib
+            # against the same uvicorn server — run in threads so the MCP
+            # event loop stays unblocked (#34 class bug).
+            if await _asyncio.to_thread(is_daemon_running):
+                resp = await _asyncio.to_thread(daemon_request, "POST", "/remember", {
                     "content": content, "tags": tags, "metadata": meta,
                 })
                 if resp and (resp.get("fact_ids") is not None or resp.get("ok")):
@@ -167,6 +175,10 @@ def register_core_tools(server, get_engine: Callable) -> None:
         ``CLAUDE_SESSION_ID``. Omitting it degrades to "no closed-loop
         learning for this recall" — the recall itself always works.
         """
+        # v3.6.10: resolve "mcp_client" sentinel → URL path (HTTP) or env var (stdio)
+        if agent_id == "mcp_client":
+            from superlocalmemory.mcp.agent_context import get_current_agent_id
+            agent_id = get_current_agent_id()
         import asyncio
         try:
             from superlocalmemory.mcp._daemon_proxy import choose_pool
@@ -481,6 +493,10 @@ def register_core_tools(server, get_engine: Callable) -> None:
             fact_id: Exact fact ID to delete (from recall or list_recent results).
             agent_id: Identifier of the calling agent (logged for audit).
         """
+        # v3.6.10: resolve "mcp_client" sentinel → URL path (HTTP) or env var (stdio)
+        if agent_id == "mcp_client":
+            from superlocalmemory.mcp.agent_context import get_current_agent_id
+            agent_id = get_current_agent_id()
         try:
             from superlocalmemory.core.worker_pool import WorkerPool
             pool = WorkerPool.shared()
@@ -515,6 +531,10 @@ def register_core_tools(server, get_engine: Callable) -> None:
             content: New content for the memory (cannot be empty).
             agent_id: Identifier of the calling agent (logged for audit).
         """
+        # v3.6.10: resolve "mcp_client" sentinel → URL path (HTTP) or env var (stdio)
+        if agent_id == "mcp_client":
+            from superlocalmemory.mcp.agent_context import get_current_agent_id
+            agent_id = get_current_agent_id()
         try:
             if not content or not content.strip():
                 return {"success": False, "error": "content cannot be empty"}

package/src/superlocalmemory/mcp/tools_mesh.py

@@ -16,6 +16,7 @@ Auto-heartbeat keeps the session alive as long as the MCP server is running.
 
 from __future__ import annotations
 
+import asyncio
 import json
 import logging
 import os
@@ -141,20 +142,20 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
         global _SESSION_SUMMARY
         _SESSION_SUMMARY = summary or "Active session"
 
-        _ensure_registered()
+        await asyncio.to_thread(_ensure_registered)
 
         # Update summary
-        result = _mesh_request("POST", "/summary", {
-            "peer_id": _PEER_ID,
-            "summary": _SESSION_SUMMARY,
-        })
+        result = await asyncio.to_thread(
+            _mesh_request, "POST", "/summary",
+            {"peer_id": _PEER_ID, "summary": _SESSION_SUMMARY},
+        )
 
         return {
             "peer_id": _PEER_ID,
             "summary": _SESSION_SUMMARY,
             "project_path": _PROJECT_PATH,
-            "registered": True,
-            "heartbeat_active": _HEARTBEAT_THREAD is not None,
+            "registered": _REGISTERED,
+            "heartbeat_active": _HEARTBEAT_THREAD is not None and _HEARTBEAT_THREAD.is_alive(),
             "broker_response": result,
         }
 
@@ -165,8 +166,8 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
         Shows other Claude Code, Cursor, or AI agent sessions that are
         connected to the same SLM mesh network.
         """
-        _ensure_registered()
-        result = _mesh_request("GET", "/peers")
+        await asyncio.to_thread(_ensure_registered)
+        result = await asyncio.to_thread(_mesh_request, "GET", "/peers")
         peers = (result or {}).get("peers", [])
         return {
             "peers": peers,
@@ -185,12 +186,11 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
                 - "project:/path/to/dir" (all sessions in that project directory)
             message: The message content (max 4KB — use file paths for large data)
         """
-        _ensure_registered()
-        result = _mesh_request("POST", "/send", {
-            "from_peer": _PEER_ID,
-            "to_peer": to,
-            "content": message,
-        })
+        await asyncio.to_thread(_ensure_registered)
+        result = await asyncio.to_thread(
+            _mesh_request, "POST", "/send",
+            {"from_peer": _PEER_ID, "to_peer": to, "content": message},
+        )
         return result or {"error": "Failed to send message"}
 
     @server.tool()
@@ -201,18 +201,19 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
         Broadcast/project messages are delivered to ALL matching sessions.
         Messages auto-expire after 48 hours.
         """
-        _ensure_registered()
+        await asyncio.to_thread(_ensure_registered)
         project = _PROJECT_PATH or _detect_project_path()
-        messages = _mesh_request(
-            "GET", f"/inbox/{_PEER_ID}?project_path={project}",
+        messages = await asyncio.to_thread(
+            _mesh_request, "GET", f"/inbox/{_PEER_ID}?project_path={project}",
         )
         msg_list = (messages or {}).get("messages", [])
         # Auto-mark unread messages as read
         unread_ids = [m["id"] for m in msg_list if not m.get("read")]
         if unread_ids:
-            _mesh_request("POST", f"/inbox/{_PEER_ID}/read", {
-                "message_ids": unread_ids,
-            })
+            await asyncio.to_thread(
+                _mesh_request, "POST", f"/inbox/{_PEER_ID}/read",
+                {"message_ids": unread_ids},
+            )
         return {
             "messages": msg_list,
             "count": len(msg_list),
@@ -231,21 +232,20 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
             value: Value to set (only for action="set")
             action: "get" (read all or one key), "set" (write a key)
         """
-        _ensure_registered()
+        await asyncio.to_thread(_ensure_registered)
 
         if action == "set" and key:
-            result = _mesh_request("POST", "/state", {
-                "key": key,
-                "value": value,
-                "set_by": _PEER_ID,
-            })
+            result = await asyncio.to_thread(
+                _mesh_request, "POST", "/state",
+                {"key": key, "value": value, "set_by": _PEER_ID},
+            )
             return result or {"error": "Failed to set state"}
 
         if key:
-            result = _mesh_request("GET", f"/state/{key}")
+            result = await asyncio.to_thread(_mesh_request, "GET", f"/state/{key}")
             return result or {"key": key, "value": None}
 
-        result = _mesh_request("GET", "/state")
+        result = await asyncio.to_thread(_mesh_request, "GET", "/state")
         return result or {"state": {}}
 
     @server.tool()
@@ -261,12 +261,11 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
             file_path: Path to the file
             action: "query" (check lock), "acquire" (lock file), "release" (unlock)
         """
-        _ensure_registered()
-        result = _mesh_request("POST", "/lock", {
-            "file_path": file_path,
-            "action": action,
-            "locked_by": _PEER_ID,
-        })
+        await asyncio.to_thread(_ensure_registered)
+        result = await asyncio.to_thread(
+            _mesh_request, "POST", "/lock",
+            {"file_path": file_path, "action": action, "locked_by": _PEER_ID},
+        )
         return result or {"error": "Lock operation failed"}
 
     @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
@@ -275,7 +274,7 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
 
         Shows the activity log of the mesh network.
         """
-        result = _mesh_request("GET", "/events")
+        result = await asyncio.to_thread(_mesh_request, "GET", "/events")
         return result or {"events": []}
 
     @server.tool(annotations=ToolAnnotations(readOnlyHint=True))
@@ -284,10 +283,10 @@ def register_mesh_tools(server, get_engine: Callable) -> None:
 
         Shows broker uptime, peer count, and connection status.
         """
-        result = _mesh_request("GET", "/status")
+        result = await asyncio.to_thread(_mesh_request, "GET", "/status")
         if result:
             result["my_peer_id"] = _PEER_ID
-            result["heartbeat_active"] = _HEARTBEAT_THREAD is not None
+            result["heartbeat_active"] = _HEARTBEAT_THREAD is not None and _HEARTBEAT_THREAD.is_alive()
         return result or {
             "broker_up": False,
             "error": "Cannot reach mesh broker. Is the daemon running? (slm serve start)",

package/src/superlocalmemory/optimize/cache/boundary_store.py

@@ -93,19 +93,23 @@ class PerItemBoundaryRecord:
         query_sim: float,
         delta: float = 0.05,
         epsilon_grid: tuple[float, ...] = (0.01, 0.02, 0.05, 0.10),
+        return_threshold: float = 1.0,
     ) -> float:
         """Compute τ̂ — the vCache exploration probability (Eq. 11).
 
         Args:
-            query_sim: Cosine similarity s(x) ∈ [0, 1] for the incoming query.
-            delta:     δ — user-defined maximum error rate.
-                       Theorem 4.1 guarantee: Pr(correct) ≥ 1 - δ.
-            epsilon_grid: ε values for the Eq. 11 min sweep.
-                          Distinct from δ; controls CI conservativeness.
+            query_sim:        Cosine similarity s(x) ∈ [0, 1] for the incoming query.
+            delta:            δ — user-defined maximum error rate.
+                              Theorem 4.1 guarantee: Pr(correct) ≥ 1 - δ.
+            epsilon_grid:     ε values for the Eq. 11 min sweep.
+                              Distinct from δ; controls CI conservativeness.
+            return_threshold: Semantic return threshold from config (semantic_return_threshold).
+                              C-03 fix: during cold start, exploit directly when
+                              query_sim >= return_threshold instead of always exploring.
 
         Returns:
             τ̂ ∈ [0.0, 1.0]. Lower = more exploitation.
-            Cold start (n < 3): returns 1.0 (always explore).
+            Cold start (n < 3): 0.0 if query_sim >= return_threshold, else 1.0.
 
         Eq. 11 derivation (from the paper):
           1. I_tt = Σ γ̂² · p_i(1 - p_i)            [Fisher info diagonal]
@@ -117,7 +121,12 @@ class PerItemBoundaryRecord:
         """
         n = len(self.samples)
         if n < 3:
-            return 1.0  # cold start — always explore
+            # ARCH-02 note: this function serves dual purpose — (a) warm-phase vCache
+            # Eq. 11 tau computation and (b) cold-start similarity gate. The cold-start
+            # branch (n < 3) is intentionally simple: if the query is already above the
+            # return threshold, serve it (tau=0.0 → exploit); otherwise explore (tau=1.0).
+            # C-03: honor return_threshold — avoids 100% miss until 3 samples are accumulated.
+            return 0.0 if query_sim >= return_threshold else 1.0
 
         # Step 1: Fisher-information SE
         i_tt = 0.0
@@ -144,12 +153,17 @@ class PerItemBoundaryRecord:
 
         return best_tau
 
-    def should_explore(self, query_sim: float, delta: float = 0.05) -> bool:
+    def should_explore(
+        self,
+        query_sim: float,
+        delta: float = 0.05,
+        return_threshold: float = 1.0,
+    ) -> bool:
         """Return True (explore = LLM call) or False (exploit = serve cache).
 
         Source: vCache Algorithm 2: draw u ~ Uniform(0, 1); explore iff u ≤ τ̂.
         """
-        tau = self.compute_tau(query_sim, delta=delta)
+        tau = self.compute_tau(query_sim, delta=delta, return_threshold=return_threshold)
         return _RNG.random() <= tau
 
     def add_sample(

package/src/superlocalmemory/optimize/cache/exact.py

@@ -3,11 +3,13 @@
 from __future__ import annotations
 
 import json
+import logging
 import time
 from typing import Any
 
 from superlocalmemory.optimize.cache.key_builder import CacheConfig
 
+logger = logging.getLogger(__name__)
 
 _NON_CACHEABLE_FINISH_REASONS: frozenset[str] = frozenset({
     "tool_use",
@@ -20,17 +22,21 @@ _NON_CACHEABLE_FINISH_REASONS: frozenset[str] = frozenset({
 def _is_cacheable_response(response: dict) -> bool:
     finish = response.get("stop_reason") or response.get("finish_reason") or ""
     if finish in _NON_CACHEABLE_FINISH_REASONS:
+        logger.debug("exact: skip cache (finish_reason=%r)", finish)
         return False
     choices = response.get("choices") or []
     for choice in choices:
         fr = (choice.get("finish_reason") or "")
         if fr in _NON_CACHEABLE_FINISH_REASONS:
+            logger.debug("exact: skip cache (choice.finish_reason=%r)", fr)
             return False
         msg = choice.get("message") or {}
         if msg.get("tool_calls"):
+            logger.debug("exact: skip cache (choice.message.tool_calls present)")
             return False
     for block in response.get("content") or []:
         if isinstance(block, dict) and block.get("type") == "tool_use":
+            logger.debug("exact: skip cache (tool_use content block)")
             return False
     return True
 
@@ -46,9 +52,6 @@ class ExactCache:
         row = self._db.get(key, tenant_id)
         if row is None:
             return None
-        if row.ttl_expires is not None and row.ttl_expires < time.time():
-            self._db.delete(key, tenant_id)
-            return None
         return json.loads(row.value.decode("utf-8"))
 
     def set(
@@ -74,7 +77,7 @@ class ExactCache:
             value=encoded,
             model=model,
             ttl_expires=expires_at,
-            tags=[],
+            tags=tags,
         )
         return True
 

package/src/superlocalmemory/optimize/cache/key_builder.py

@@ -4,10 +4,13 @@ from __future__ import annotations
 
 import hashlib
 import json
+import logging
 import re
 from dataclasses import dataclass, field
 from typing import Any
 
+logger = logging.getLogger(__name__)
+
 DETERMINISTIC_PARAMS: frozenset[str] = frozenset({
     "max_tokens", "stop", "stop_sequences", "top_p", "top_k",
     "response_format", "tools", "tool_choice",
@@ -62,6 +65,16 @@ class KeyBuilder:
             temperature = 0.0
 
         if temperature != 0 and not self._config.allow_nonzero_temperature_cache:
+            logger.debug(
+                "cache skip: temperature=%.2f allow_nonzero=%s",
+                temperature,
+                self._config.allow_nonzero_temperature_cache,
+            )
+            try:
+                from superlocalmemory.optimize.metrics.counters import MetricsCollector
+                MetricsCollector.get_instance().increment_skipped_temperature()
+            except Exception:
+                pass
             return None
 
         deterministic_params: dict[str, Any] = {}