superlocalmemory 3.4.16 → 3.4.17

package/CHANGELOG.md

@@ -10,6 +10,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [3.4.17] - 2026-04-17
+
+### Fixed
+- Entity Explorer no longer stuck on "No entities found" after switching operating modes.
+- Engine-backed routes (entity, ingest, recall, remember, list) auto-recover after mode changes — no daemon restart required.
+
+### Added
+- Mode change audit log at `~/.superlocalmemory/logs/mode-audit.log`.
+- Mode C now requires an explicit API key via Settings to prevent accidental cloud-mode writes.
+
+---
+
 ## Author
 
 **Varun Pratap Bhardwaj**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.4.16",
+  "version": "3.4.17",
   "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.4.16"
+version = "3.4.17"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}

package/src/superlocalmemory/server/routes/entity.py

@@ -8,6 +8,8 @@ from __future__ import annotations
 
 from fastapi import APIRouter, HTTPException, Request, Query
 
+from .helpers import require_engine
+
 router = APIRouter(prefix="/api/entity", tags=["entity"])
 
 
@@ -19,9 +21,7 @@ async def list_entities(
     offset: int = Query(default=0, ge=0),
 ):
     """List all entities with basic info (canonical name, type, fact count)."""
-    engine = request.app.state.engine
-    if engine is None:
-        raise HTTPException(503, detail="Engine not initialized")
+    engine = require_engine(request)
 
     import sqlite3
     import json
@@ -75,9 +75,7 @@ async def get_entity(
     project: str = Query(default=""),
 ):
     """Get compiled truth + timeline for an entity."""
-    engine = request.app.state.engine
-    if engine is None:
-        raise HTTPException(503, detail="Engine not initialized")
+    engine = require_engine(request)
 
     import sqlite3
     import json
@@ -121,9 +119,7 @@ async def recompile_entity(
     project: str = Query(default=""),
 ):
     """Force immediate recompilation of an entity."""
-    engine = request.app.state.engine
-    if engine is None:
-        raise HTTPException(503, detail="Engine not initialized")
+    engine = require_engine(request)
 
     import sqlite3
     conn = sqlite3.connect(str(engine._config.db_path))

package/src/superlocalmemory/server/routes/helpers.py

@@ -5,18 +5,26 @@
  - AGPL-3.0-or-later
 
 Shared utilities for all route modules: DB connection, dict factory,
-profile helper, validation, Pydantic models, config paths.
+profile helper, validation, Pydantic models, config paths, and the
+shared lazy engine accessor used by every engine-dependent route.
 """
+import logging
 import re
 import json
 import sqlite3
+import threading
+import time
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
-from fastapi import HTTPException
+from fastapi import HTTPException, Request
 from pydantic import BaseModel, Field
 
 
+_engine_logger = logging.getLogger("superlocalmemory.engine")
+
+
 # ---------------------------------------------------------------------------
 # Version detection (shared — avoids circular import between ui.py ↔ v3_api.py)
 # ---------------------------------------------------------------------------
@@ -65,25 +73,122 @@ UI_DIR = Path(__file__).parent.parent / "ui"
 PROFILES_DIR = MEMORY_DIR / "profiles"
 
 
+# ---------------------------------------------------------------------------
+# Engine lifecycle — lazy, thread-safe, recoverable after mode changes.
+# ---------------------------------------------------------------------------
+
+_engine_init_lock = threading.Lock()
+_last_engine_failure: float = 0.0
+_ENGINE_FAILURE_COOLDOWN_S: float = 5.0
+
+
 def get_engine_lazy(app_state):
-    """Get or lazily initialize the V3 engine. Returns engine or None."""
+    """Return ``app_state.engine``, initialising it if None.
+
+    Why this exists
+    ---------------
+    Mode-change endpoints (``PUT`` / ``POST /api/v3/mode[/set]``) set
+    ``app.state.engine = None`` so the next request picks up the new config.
+    Before this helper, no code path re-created the engine until the daemon
+    restarted, breaking every engine-backed route (entity, ingest, tiers,
+    recall, remember, list, status).
+
+    Contract
+    --------
+    * Returns the cached engine if already initialised.
+    * Otherwise acquires a process-wide lock and builds a fresh
+      ``MemoryEngine`` from the latest ``SLMConfig.load()``.
+    * Returns ``None`` if init fails. A brief cooldown prevents hammering
+      init when the underlying cause (e.g., corrupt DB) is persistent.
+    * Never uses a sticky "already attempted" flag — recovery must be
+      automatic after a transient failure.
+    """
+    global _last_engine_failure
+
     engine = getattr(app_state, "engine", None)
     if engine is not None:
         return engine
-    if getattr(app_state, "_engine_init_attempted", False):
+
+    now = time.monotonic()
+    if _last_engine_failure and (now - _last_engine_failure) < _ENGINE_FAILURE_COOLDOWN_S:
         return None
+
+    with _engine_init_lock:
+        # Double-checked: another thread may have initialised while we waited.
+        engine = getattr(app_state, "engine", None)
+        if engine is not None:
+            return engine
+        try:
+            from superlocalmemory.core.config import SLMConfig
+            from superlocalmemory.core.engine import MemoryEngine
+            config = SLMConfig.load()
+            new_engine = MemoryEngine(config)
+            new_engine.initialize()
+            app_state.engine = new_engine
+            app_state.config = config
+            _engine_logger.info(
+                "Engine lazy-initialised (mode=%s, profile=%s)",
+                getattr(getattr(config, "mode", None), "value", "?"),
+                getattr(config, "active_profile", "?"),
+            )
+            _last_engine_failure = 0.0
+            return new_engine
+        except Exception as exc:
+            _engine_logger.warning("Engine lazy init failed: %s", exc)
+            _last_engine_failure = time.monotonic()
+            return None
+
+
+def require_engine(request: Request):
+    """Return the engine or raise ``HTTPException(503)``.
+
+    Use this in every route that touches ``app.state.engine``. Replaces the
+    old ``engine = request.app.state.engine; if engine is None: raise ...``
+    pattern with a single call that also lazily re-initialises after a mode
+    change.
+    """
+    engine = get_engine_lazy(request.app.state)
+    if engine is None:
+        raise HTTPException(
+            status_code=503,
+            detail="Engine not initialized. Retry in a few seconds — it's warming up.",
+        )
+    return engine
+
+
+def log_mode_change(
+    old_mode: str,
+    new_mode: str,
+    *,
+    provider: str = "",
+    model: str = "",
+    source: str = "api",
+) -> None:
+    """Append an audit entry for every mode change.
+
+    Lets us trace phantom writes (e.g., a stray dashboard-card button click
+    silently flipping the system to Mode C with ``anthropic/claude-sonnet-4``
+    as the auto-defaulted model).
+
+    Audit file: ``<base_dir>/logs/mode-audit.log`` (tab-separated).
+    """
+    audit_path = MEMORY_DIR / "logs" / "mode-audit.log"
     try:
-        from superlocalmemory.core.config import SLMConfig
-        from superlocalmemory.core.engine import MemoryEngine
-        config = SLMConfig.load()
-        engine = MemoryEngine(config)
-        engine.initialize()
-        app_state.engine = engine
-        app_state._engine_init_attempted = True
-        return engine
-    except Exception:
-        app_state._engine_init_attempted = True
-        return None
+        audit_path.parent.mkdir(parents=True, exist_ok=True)
+        ts = datetime.now(timezone.utc).isoformat(timespec="seconds")
+        line = (
+            f"{ts}\told={old_mode}\tnew={new_mode}"
+            f"\tprovider={provider}\tmodel={model}\tsource={source}\n"
+        )
+        with open(audit_path, "a", encoding="utf-8") as handle:
+            handle.write(line)
+    except Exception as exc:  # Logging must never break the mode-change path.
+        _engine_logger.warning("mode audit write failed: %s", exc)
+
+    _engine_logger.info(
+        "Mode change: %s→%s provider=%s model=%s (%s)",
+        old_mode, new_mode, provider, model, source,
+    )
 
 
 def get_db_connection() -> sqlite3.Connection:

package/src/superlocalmemory/server/routes/ingest.py

@@ -44,9 +44,8 @@ async def ingest(req: IngestRequest, request: Request):
     """
     global _active_count
 
-    engine = request.app.state.engine
-    if engine is None:
-        raise HTTPException(503, detail="Engine not initialized")
+    from .helpers import require_engine
+    engine = require_engine(request)
 
     if not req.content:
         raise HTTPException(400, detail="content required")

package/src/superlocalmemory/server/routes/v3_api.py

@@ -101,7 +101,28 @@ async def set_mode(request: Request):
 
         from superlocalmemory.core.config import SLMConfig
         from superlocalmemory.storage.models import Mode
+        from superlocalmemory.server.routes.helpers import log_mode_change
         old_config = SLMConfig.load()
+        old_mode = old_config.mode.value
+
+        # Safety: a bare ``{mode:"c"}`` body (e.g., a stray dashboard button
+        # click) used to silently auto-default the model to
+        # ``anthropic/claude-sonnet-4`` with no API key, writing phantom state
+        # into config.json. Refuse that path — Mode C requires explicit
+        # provider+key via POST /api/v3/mode/set.
+        if new_mode == "c" and not old_config.llm.api_key:
+            return JSONResponse(
+                {
+                    "error": (
+                        "Mode C requires a cloud API key. "
+                        "Configure provider + key in Settings → Step 2 "
+                        "(uses POST /api/v3/mode/set)."
+                    ),
+                    "code": "mode_c_requires_api_key",
+                },
+                status_code=400,
+            )
+
         new_config = SLMConfig.for_mode(
             Mode(new_mode),
             llm_provider=old_config.llm.provider,
@@ -112,13 +133,23 @@ async def set_mode(request: Request):
         new_config.active_profile = old_config.active_profile
         new_config.save()
 
+        # Audit the change before we lose context — proves who/when/what.
+        # Captures the phantom-write case where `for_mode(C)` auto-defaults
+        # the model to "anthropic/claude-sonnet-4" (see core/config.py).
+        log_mode_change(
+            old_mode, new_mode,
+            provider=new_config.llm.provider,
+            model=new_config.llm.model,
+            source="PUT /api/v3/mode",
+        )
+
         # V3.3: Check if embedding model changed — flag for re-indexing
         needs_reindex = (
             old_config.embedding.provider != new_config.embedding.provider
             or old_config.embedding.model_name != new_config.embedding.model_name
         )
 
-        # Reset engine to pick up new config
+        # Invalidate engine; next engine-backed request lazy-inits with new config.
         if hasattr(request.app.state, "engine"):
             request.app.state.engine = None
 
@@ -147,6 +178,9 @@ async def set_full_config(request: Request):
 
         from superlocalmemory.core.config import SLMConfig
         from superlocalmemory.storage.models import Mode
+        from superlocalmemory.server.routes.helpers import log_mode_change
+        old = SLMConfig.load()
+        old_mode = old.mode.value
         config = SLMConfig.for_mode(
             Mode(new_mode),
             llm_provider=provider if provider != "none" else "",
@@ -154,10 +188,16 @@ async def set_full_config(request: Request):
             llm_api_key=api_key,
             llm_api_base="http://localhost:11434" if provider == "ollama" else "",
         )
-        old = SLMConfig.load()
         config.active_profile = old.active_profile
         config.save()
 
+        log_mode_change(
+            old_mode, new_mode,
+            provider=config.llm.provider,
+            model=config.llm.model,
+            source="POST /api/v3/mode/set",
+        )
+
         # Kill existing worker so next request uses new config
         try:
             from superlocalmemory.core.worker_pool import WorkerPool

package/src/superlocalmemory/server/unified_daemon.py

@@ -559,10 +559,25 @@ def _register_daemon_routes(application: FastAPI) -> None:
     """Add daemon-specific routes for CLI integration."""
     global _last_activity
 
+    from superlocalmemory.server.routes.helpers import get_engine_lazy
+
+    def _get_engine_or_503():
+        """Lazy-init engine; raise 503 if init fails.
+
+        Shared by every daemon route so a mode switch that nulled
+        ``application.state.engine`` never leaves the daemon stuck in
+        503 until restart.
+        """
+        engine = get_engine_lazy(application.state)
+        if engine is None:
+            raise HTTPException(503, detail="Engine not initialized")
+        return engine
+
     @application.get("/health")
     async def health():
         _update_activity()
-        engine = application.state.engine
+        # Non-blocking peek: report status without forcing a re-init.
+        engine = getattr(application.state, "engine", None)
         return {
             "status": "ok",
             "pid": os.getpid(),
@@ -574,9 +589,7 @@ def _register_daemon_routes(application: FastAPI) -> None:
     async def recall(q: str = "", query: str = "", limit: int = 20):
         _update_activity()
         search_query = q or query  # Accept both ?q= and ?query= for compatibility
-        engine = application.state.engine
-        if engine is None:
-            raise HTTPException(503, detail="Engine not initialized")
+        engine = _get_engine_or_503()
         if not search_query:
             return {"results": [], "count": 0, "query_type": "none", "retrieval_time_ms": 0}
         try:
@@ -605,9 +618,7 @@ def _register_daemon_routes(application: FastAPI) -> None:
     @application.post("/remember")
     async def remember(req: RememberRequest):
         _update_activity()
-        engine = application.state.engine
-        if engine is None:
-            raise HTTPException(503, detail="Engine not initialized")
+        engine = _get_engine_or_503()
         try:
             metadata = {"tags": req.tags} if req.tags else {}
             fact_ids = engine.store(req.content, metadata=metadata)
@@ -624,7 +635,8 @@ def _register_daemon_routes(application: FastAPI) -> None:
     @application.get("/status")
     async def status():
         _update_activity()
-        engine = application.state.engine
+        # Non-blocking peek — status must never force a re-init.
+        engine = getattr(application.state, "engine", None)
         fact_count = engine.fact_count if engine else 0
         mode = engine._config.mode.value if engine and hasattr(engine, '_config') else "unknown"
         return {
@@ -641,9 +653,7 @@ def _register_daemon_routes(application: FastAPI) -> None:
     @application.get("/list")
     async def list_facts(limit: int = 50):
         _update_activity()
-        engine = application.state.engine
-        if engine is None:
-            raise HTTPException(503, detail="Engine not initialized")
+        engine = _get_engine_or_503()
         try:
             facts = engine.list_facts(limit=limit)
             items = [

package/src/superlocalmemory.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superlocalmemory
-Version: 3.4.14
+Version: 3.4.17
 Summary: Information-geometric agent memory with mathematical guarantees
 Author-email: Varun Pratap Bhardwaj <admin@superlocalmemory.com>
 License: AGPL-3.0-or-later
@@ -634,7 +634,7 @@ Qualixar is building the open-source infrastructure for AI agent reliability eng
 | **[SLM Mesh](https://github.com/qualixar/slm-mesh)** | P2P coordination across AI agent sessions | `npm i slm-mesh` | — |
 | **[SLM MCP Hub](https://github.com/qualixar/slm-mcp-hub)** | Federate 430+ MCP tools through one gateway | `pip install slm-mcp-hub` | — |
 | **[AgentAssay](https://github.com/qualixar/agentassay)** | Token-efficient AI agent testing | `pip install agentassay` | [arXiv:2603.02601](https://arxiv.org/abs/2603.02601) |
-| **[AgentAssert](https://github.com/qualixar/agentassert-abc)** | Behavioral contracts + drift detection | `pip install agentassert` | [arXiv:2602.22302](https://arxiv.org/abs/2602.22302) |
+| **[AgentAssert](https://github.com/qualixar/agentassert-abc)** | Behavioral contracts + drift detection |  `pip install agentassert-abc` | [arXiv:2602.22302](https://arxiv.org/abs/2602.22302) |
 | **[SkillFortify](https://github.com/qualixar/skillfortify)** | Formal verification for AI agent skills | `pip install skillfortify` | [arXiv:2603.00195](https://arxiv.org/abs/2603.00195) |
 
 **Zero cloud dependency. Local-first. EU AI Act compliant.**