superlocalmemory 3.4.25 → 3.4.31

package/src/superlocalmemory/cli/version_banner.py

@@ -0,0 +1,183 @@
+# 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
+
+"""Post-upgrade version banner.
+
+Writes ``$SLM_DATA_DIR/.version`` (default ``~/.superlocalmemory/.version``)
+and prints a short factual banner the first time the CLI or daemon is
+invoked after a ``pip install -U`` / ``npm install -g`` that changes the
+installed version. Every subsequent invocation is a no-op.
+
+The banner is best-effort and must never raise — a disk error or a
+corrupt marker makes the banner silent, not the CLI broken.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+# Strict allowlist: semver-ish only. Anything else in the marker is
+# treated as "unknown" so a tampered or binary marker can't leak into
+# banner strings or downstream consumers.
+_VERSION_PATTERN = re.compile(r"^[0-9A-Za-z.\-+_]{1,32}$")
+
+_MAX_MARKER_BYTES = 64  # a semver string is ≤ 32 chars; 64 is plenty
+
+
+def _data_dir() -> Path:
+    return Path(os.environ.get("SLM_DATA_DIR") or Path.home() / ".superlocalmemory")
+
+
+def _marker_path() -> Path:
+    return _data_dir() / ".version"
+
+
+def read_marker_version() -> str | None:
+    """Return the marker string or None if missing / unreadable / invalid."""
+    target = _marker_path()
+    # Refuse to follow symlinks on the marker file — a co-tenant
+    # attacker who can drop a symlink into our data dir must not be
+    # able to redirect us to an arbitrary file.
+    try:
+        st = target.lstat()
+    except (FileNotFoundError, NotADirectoryError, PermissionError, OSError):
+        return None
+    import stat as _stat
+    if _stat.S_ISLNK(st.st_mode) or not _stat.S_ISREG(st.st_mode):
+        return None
+    try:
+        with open(target, "rb") as f:
+            raw = f.read(_MAX_MARKER_BYTES + 1)
+    except (FileNotFoundError, NotADirectoryError, PermissionError, OSError):
+        return None
+    if len(raw) > _MAX_MARKER_BYTES:
+        return None
+    try:
+        text = raw.decode("ascii").strip()
+    except UnicodeDecodeError:
+        return None
+    if not _VERSION_PATTERN.fullmatch(text):
+        return None
+    return text
+
+
+def write_marker_version(version: str) -> bool:
+    """Persist the current version to the marker with 0600 perms.
+
+    Uses a PID-scoped tmp file + ``os.replace`` for atomicity so
+    concurrent CLI / daemon / npm-postinstall invocations can't corrupt
+    each other's write. The final file is mode 0600 so the upgrade
+    timestamp is not a side-channel for co-tenant attackers.
+    """
+    # Validate input — never write garbage, even on a programmer bug.
+    if not _VERSION_PATTERN.fullmatch(version):
+        return False
+    target = _marker_path()
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        # Parent dir 0700 on POSIX (mirrors safe_fs._ensure_parent_0700)
+        if sys.platform != "win32":
+            try:
+                os.chmod(target.parent, 0o700)
+            except OSError:
+                pass
+        tmp = target.parent / f".version.tmp.{os.getpid()}"
+        # Open with 0600 so the tmp is never world-readable either.
+        flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+        if hasattr(os, "O_NOFOLLOW"):
+            flags |= os.O_NOFOLLOW
+        fd = os.open(tmp, flags, 0o600)
+        try:
+            os.write(fd, (version + "\n").encode("ascii"))
+        finally:
+            os.close(fd)
+        os.replace(tmp, target)
+        if sys.platform != "win32":
+            try:
+                os.chmod(target, 0o600)
+            except OSError:
+                pass
+        return True
+    except OSError:
+        return False
+
+
+def _has_existing_db() -> bool:
+    """True if a memory.db already exists — signals a pre-v3.4.26 user
+    upgrading in-place (the marker only began shipping in v3.4.26)."""
+    return (_data_dir() / "memory.db").exists()
+
+
+def _banner(prior: str | None, current: str) -> str:
+    header = (f"SuperLocalMemory upgraded from {prior} to {current}"
+              if prior else
+              f"SuperLocalMemory upgraded to {current} (from an earlier version)")
+    return "\n".join([
+        header,
+        "  - Multi-IDE MCP processes now share a worker — large RAM drop",
+        "  - Feedback and learning signals flow from every IDE to the daemon",
+        "  - Silent data migration complete; no manual steps required",
+        "Run `slm doctor` to verify your setup.",
+        "",
+    ])
+
+
+def check_and_emit_upgrade_banner(current: str) -> bool:
+    """Print the banner once per upgrade boundary. Idempotent.
+
+    Returns True if the banner was emitted on this call, else False.
+    Never raises — swallows I/O errors so a broken data directory cannot
+    take down the CLI.
+
+    Concurrent CLI + daemon + npm-postinstall callers serialize through
+    an O_CREAT|O_EXCL lock file so at most one emits the banner.
+    """
+    try:
+        prior = read_marker_version()
+
+        if prior == current:
+            return False
+
+        # Fresh install: no marker, no DB. Stay quiet — the setup wizard
+        # handles the welcome. Still write the marker so subsequent
+        # invocations are no-ops.
+        if prior is None and not _has_existing_db():
+            write_marker_version(current)
+            return False
+
+        # Serialize concurrent emitters via O_CREAT|O_EXCL lock file.
+        lock = _data_dir() / ".version-banner.lock"
+        lock_fd = None
+        try:
+            lock.parent.mkdir(parents=True, exist_ok=True)
+            lock_fd = os.open(
+                str(lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600,
+            )
+        except FileExistsError:
+            return False
+        except OSError:
+            pass
+
+        try:
+            # Re-check after winning the lock — the loser may have
+            # already written the marker while we raced.
+            if read_marker_version() == current:
+                return False
+
+            sys.stdout.write(_banner(prior, current))
+            sys.stdout.flush()
+            write_marker_version(current)
+            return True
+        finally:
+            if lock_fd is not None:
+                os.close(lock_fd)
+            try:
+                lock.unlink(missing_ok=True)
+            except OSError:
+                pass
+    except Exception:
+        # Banner is advisory. A failure here must never propagate.
+        return False

package/src/superlocalmemory/cli/wizard_v3426_options.py

@@ -0,0 +1,129 @@
+# 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
+
+"""Setup-wizard extensions for v3.4.26.
+
+Keeps the user-facing surface tiny: one yes/no prompt for the queue.
+Everything else defaults; advanced users edit ``v3426_options.json``.
+
+Also validates the chosen data directory at install time so cloud-sync
+folders (iCloud, Dropbox, OneDrive, …) fail loud BEFORE the user stores
+their first memory.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from superlocalmemory.core.safe_fs import SafeFsError, validate_data_dir
+
+logger = logging.getLogger(__name__)
+
+
+# Defaults tuned for a commodity laptop with 4 concurrent IDEs
+# (Claude Code, Cursor, Antigravity, VS Code). See the release notes
+# for the reasoning behind the numbers.
+_DEFAULT_QUEUE_ENABLED = True
+_DEFAULT_RATE_PER_PID = 30
+_DEFAULT_RATE_PER_AGENT = 10
+_DEFAULT_RATE_GLOBAL = 100
+
+
+@dataclass(frozen=True)
+class V3426Options:
+    queue_enabled: bool
+    rate_limit_per_pid: int
+    rate_limit_per_agent: int
+    rate_limit_global: int
+
+
+def _default_options() -> V3426Options:
+    return V3426Options(
+        queue_enabled=_DEFAULT_QUEUE_ENABLED,
+        rate_limit_per_pid=_DEFAULT_RATE_PER_PID,
+        rate_limit_per_agent=_DEFAULT_RATE_PER_AGENT,
+        rate_limit_global=_DEFAULT_RATE_GLOBAL,
+    )
+
+
+def prompt_v3426_options(interactive: bool) -> V3426Options:
+    """Return user-chosen (or default) v3.4.26 options.
+
+    Non-interactive / EOFError (pipe) returns the defaults silently.
+    Ctrl-C propagates so the user can actually abort install.
+    """
+    if not interactive:
+        return _default_options()
+
+    try:
+        answer = input(
+            "Enable SLM's concurrent-recall queue (recommended)? [Y/n]: "
+        ).strip().lower()
+    except EOFError:
+        return _default_options()
+
+    queue_enabled = answer not in ("n", "no")
+    return V3426Options(
+        queue_enabled=queue_enabled,
+        rate_limit_per_pid=_DEFAULT_RATE_PER_PID,
+        rate_limit_per_agent=_DEFAULT_RATE_PER_AGENT,
+        rate_limit_global=_DEFAULT_RATE_GLOBAL,
+    )
+
+
+def validate_install_data_dir(path: Path) -> tuple[bool, str]:
+    """Return (ok, reason). Empty reason on success."""
+    try:
+        validate_data_dir(path)
+    except SafeFsError as exc:
+        return False, str(exc)
+    return True, ""
+
+
+def persist_v3426_options(opts: V3426Options, home_dir: Path) -> Path:
+    """Write the options JSON with 0600 perms and atomic replace.
+
+    Atomic: a crash mid-write leaves either the old file or nothing,
+    never a truncated JSON that the daemon can't parse on boot.
+    0600: rate-limit config is not sensitive per se, but the file
+    also carries future secrets — enforce the tight mode now.
+    """
+    home_dir.mkdir(parents=True, exist_ok=True)
+    if sys.platform != "win32":
+        try:
+            os.chmod(home_dir, 0o700)
+        except OSError as exc:
+            logger.warning("could not tighten %s to 0700: %s", home_dir, exc)
+    target = home_dir / "v3426_options.json"
+    payload = (json.dumps(asdict(opts), indent=2) + "\n").encode("utf-8")
+    tmp = home_dir / f"v3426_options.json.tmp.{os.getpid()}"
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    try:
+        fd = os.open(tmp, flags, 0o600)
+        try:
+            os.write(fd, payload)
+        finally:
+            os.close(fd)
+        os.replace(tmp, target)
+        if sys.platform != "win32":
+            try:
+                os.chmod(target, 0o600)
+            except OSError:
+                pass
+    except OSError:
+        # Fallback for odd filesystems that don't support O_NOFOLLOW
+        # or the perm bits — log + emit something rather than crash.
+        logger.warning(
+            "atomic write of %s failed; falling back to write_text", target,
+        )
+        target.write_text(
+            json.dumps(asdict(opts), indent=2) + "\n", encoding="utf-8",
+        )
+    return target

package/src/superlocalmemory/core/clock_monitor.py

@@ -0,0 +1,45 @@
+# 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
+
+"""Wall-clock jump detector.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+Event = Literal["forward", "backward"]
+
+
+class ClockJumpDetector:
+    """Detects NTP-style jumps by comparing wall-clock and monotonic deltas."""
+
+    def __init__(self, threshold_s: float = 1.0) -> None:
+        self._threshold = threshold_s
+        self._last_wall: Optional[float] = None
+        self._last_mono: Optional[float] = None
+        self.last_drift_s: float = 0.0
+        self.last_event: Optional[Event] = None
+
+    def tick(self, wall: float, monotonic: float) -> Optional[Event]:
+        if self._last_wall is None or self._last_mono is None:
+            self._last_wall = wall
+            self._last_mono = monotonic
+            return None
+        dw = wall - self._last_wall
+        dm = monotonic - self._last_mono
+        drift = dw - dm
+        self._last_wall = wall
+        self._last_mono = monotonic
+        self.last_drift_s = drift
+        if abs(drift) < self._threshold:
+            self.last_event = None
+            return None
+        self.last_event = "forward" if drift > 0 else "backward"
+        return self.last_event
+
+    def drift_magnitude_s(self) -> float:
+        return abs(self.last_drift_s)

package/src/superlocalmemory/core/db_pool.py

@@ -0,0 +1,80 @@
+# 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
+
+"""Simple bounded SQLite connection pool.
+
+Part of Qualixar | Author: Varun Pratap Bhardwaj
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+from contextlib import contextmanager
+from queue import Empty, Queue
+from typing import Callable, Iterator
+
+
+class ConnectionPool:
+    """Bounded pool of SQLite connections created on-demand."""
+
+    def __init__(
+        self,
+        opener: Callable[[], sqlite3.Connection],
+        size: int = 8,
+    ) -> None:
+        if size < 1:
+            raise ValueError("size must be >= 1")
+        self._opener = opener
+        self._size = size
+        self._available: Queue[sqlite3.Connection] = Queue(maxsize=size)
+        self._created = 0
+        self._lock = threading.Lock()
+        self._closed = False
+        self._all: list[sqlite3.Connection] = []
+
+    def _get_or_create(self, timeout: float | None) -> sqlite3.Connection:
+        try:
+            return self._available.get_nowait()
+        except Empty:
+            pass
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("pool is closed")
+            if self._created < self._size:
+                conn = self._opener()
+                self._all.append(conn)
+                self._created += 1
+                return conn
+        # Pool saturated — block for a returned connection
+        try:
+            return self._available.get(timeout=timeout)
+        except Empty as exc:
+            raise TimeoutError("timed out acquiring DB connection") from exc
+
+    @contextmanager
+    def acquire(self, timeout: float | None = 30.0) -> Iterator[sqlite3.Connection]:
+        if self._closed:
+            raise RuntimeError("pool is closed")
+        conn = self._get_or_create(timeout)
+        try:
+            yield conn
+        finally:
+            if not self._closed:
+                self._available.put(conn)
+
+    def close(self) -> None:
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+        for conn in self._all:
+            try:
+                conn.close()
+            except Exception:
+                pass
+        self._all.clear()
+
+    def size(self) -> int:
+        return self._size

package/src/superlocalmemory/core/engine.py

@@ -21,6 +21,7 @@ import logging
 from typing import Any
 
 from superlocalmemory.core.config import SLMConfig
+from superlocalmemory.core.engine_capabilities import Capabilities, CapabilityError
 from superlocalmemory.core.modes import get_capabilities
 from superlocalmemory.storage.models import (
     AtomicFact, MemoryRecord, Mode, RecallResponse,
@@ -46,9 +47,14 @@ class MemoryEngine:
         response = engine.recall("Where did Alice go?")
     """
 
-    def __init__(self, config: SLMConfig) -> None:
+    def __init__(
+        self,
+        config: SLMConfig,
+        capabilities: Capabilities = Capabilities.FULL,
+    ) -> None:
         self._config = config
         self._caps = get_capabilities(config.mode)
+        self._capabilities = capabilities
         self._profile_id = config.active_profile
         self._initialized = False
 
@@ -99,20 +105,42 @@ class MemoryEngine:
         """Embedding service (read-only access for Phase 2+)."""
         return self._embedder
 
+    @property
+    def capabilities(self) -> Capabilities:
+        """Capability level chosen at construction (LIGHT or FULL)."""
+        return self._capabilities
+
     # -- Initialization -----------------------------------------------------
 
     def initialize(self) -> None:
-        """Initialize all components. Call once before use."""
+        """Initialize all components. Call once before use.
+
+        In LIGHT mode only the DB layer is initialized (SQLite + schema
+        migrations + profile bookkeeping). In FULL mode the heavy layer
+        (embedder, LLM, encoding, retrieval, hooks, consolidation) follows.
+        """
         if self._initialized:
             return
 
+        self._init_db_layer()
+
+        if self._capabilities is Capabilities.FULL:
+            self._init_heavy_layer()
+
+        self._initialized = True
+        logger.info(
+            "MemoryEngine initialized: mode=%s profile=%s capabilities=%s",
+            self._config.mode.value, self._profile_id,
+            self._capabilities.value,
+        )
+
+        if self._capabilities is Capabilities.FULL:
+            # Replay pending async writes only when heavy layer is available.
+            self._process_pending_memories()
+
+    def _init_db_layer(self) -> None:
         from superlocalmemory.storage import schema
         from superlocalmemory.storage.database import DatabaseManager
-        from superlocalmemory.llm.backbone import LLMBackbone
-        from superlocalmemory.core.engine_wiring import (
-            init_embedder, init_encoding, init_retrieval, wire_hooks,
-            _init_auto_invoker, _init_consolidation,
-        )
 
         self._db = DatabaseManager(self._config.db_path)
         self._db.initialize(schema)
@@ -123,35 +151,48 @@ class MemoryEngine:
             from superlocalmemory.storage.schema_v343 import apply_v343_schema
             apply_v343_schema(str(self._db.db_path))
         except Exception as exc:
-            logger.debug("V3.4.3 schema migration: %s", exc)
+            logger.warning("V3.4.3 schema migration failed: %s", exc)
 
         # V3.4.6: Apply "Connected Brain" mesh enhancements (broadcast, project routing, offline queue)
         try:
             from superlocalmemory.storage.schema_v343 import apply_v346_schema
             apply_v346_schema(str(self._db.db_path))
         except Exception as exc:
-            logger.debug("V3.4.6 schema migration: %s", exc)
+            logger.warning("V3.4.6 schema migration failed: %s", exc)
 
         # V3.4.7: Apply "Learning Brain" schema (tool_events, behavioral_assertions)
         try:
             from superlocalmemory.storage.schema_v347 import apply_v347_schema
             apply_v347_schema(str(self._db.db_path))
         except Exception as exc:
-            logger.debug("V3.4.7 schema migration: %s", exc)
+            logger.warning("V3.4.7 schema migration failed: %s", exc)
 
         # V3.4.10: Apply "Fortress" schema (backup_destinations, entity_blacklist)
         try:
             from superlocalmemory.storage.schema_v3410 import apply_v3410_schema
             apply_v3410_schema(str(self._db.db_path))
         except Exception as exc:
-            logger.debug("V3.4.10 schema migration: %s", exc)
+            logger.warning("V3.4.10 schema migration failed: %s", exc)
 
         # V3.4.11: Apply "Scale-Ready" schema (pinned_facts, backend_status, fact_consolidations)
         try:
             from superlocalmemory.storage.schema_v3411 import apply_v3411_schema
             apply_v3411_schema(str(self._db.db_path))
         except Exception as exc:
-            logger.debug("V3.4.11 schema migration: %s", exc)
+            logger.warning("V3.4.11 schema migration failed: %s", exc)
+
+        # DB-only learner — no embedder / LLM dependency. Available in
+        # LIGHT so MCP report_feedback and session_init phase counters
+        # work on the MCP process without loading the heavy layer.
+        from superlocalmemory.learning.adaptive import AdaptiveLearner
+        self._adaptive_learner = AdaptiveLearner(self._db)
+
+    def _init_heavy_layer(self) -> None:
+        from superlocalmemory.llm.backbone import LLMBackbone
+        from superlocalmemory.core.engine_wiring import (
+            init_embedder, init_encoding, init_retrieval, wire_hooks,
+            _init_auto_invoker, _init_consolidation,
+        )
 
         self._embedder = init_embedder(self._config)
 
@@ -165,12 +206,10 @@ class MemoryEngine:
 
         from superlocalmemory.trust.scorer import TrustScorer
         from superlocalmemory.trust.provenance import ProvenanceTracker
-        from superlocalmemory.learning.adaptive import AdaptiveLearner
         from superlocalmemory.compliance.eu_ai_act import EUAIActChecker
 
         self._trust_scorer = TrustScorer(self._db)
 
-        # Encoding components
         enc = init_encoding(
             self._config, self._db, self._embedder, self._llm,
         )
@@ -192,7 +231,6 @@ class MemoryEngine:
         self._auto_linker = enc.get("auto_linker")
         self._graph_analyzer = enc.get("graph_analyzer")
 
-        # Retrieval engine
         self._retrieval_engine = init_retrieval(
             self._config, self._db, self._embedder,
             self._entity_resolver, self._trust_scorer,
@@ -200,10 +238,10 @@ class MemoryEngine:
         )
 
         self._provenance = ProvenanceTracker(self._db)
-        self._adaptive_learner = AdaptiveLearner(self._db)
+        # self._adaptive_learner is initialized in _init_db_layer() because
+        # it depends only on the DB (no embedder / LLM); see note there.
         self._compliance_checker = EUAIActChecker()
 
-        # Wire lifecycle hooks
         hook_result = wire_hooks(
             self._hooks, self._config, self._db,
             self._trust_scorer, self._profile_id,
@@ -231,7 +269,6 @@ class MemoryEngine:
             llm=getattr(self, "_llm", None),  # v3.4.7: for CCQ worker
         )
 
-        # V3.3: Check for embedding model migration on mode switch
         self._check_embedding_migration()
 
         # V3.3.13: Background maintenance scheduler (Langevin/Ebbinghaus/Sheaf)
@@ -245,16 +282,6 @@ class MemoryEngine:
             except Exception as exc:
                 logger.debug("Maintenance scheduler init failed: %s", exc)
 
-        self._initialized = True
-        logger.info(
-            "MemoryEngine initialized: mode=%s profile=%s",
-            self._config.mode.value, self._profile_id,
-        )
-
-        # V3.3.21: Process any pending memories from failed async remember.
-        # Zero cost if no pending.db exists. Backward compatible.
-        self._process_pending_memories()
-
     def _process_pending_memories(self) -> None:
         """Process pending memories from store-first async pattern.
 
@@ -295,6 +322,7 @@ class MemoryEngine:
         metadata: dict[str, Any] | None = None,
     ) -> list[str]:
         """Store content and extract structured facts. Returns fact_ids."""
+        self._require_full("store")
         self._ensure_init()
 
         from superlocalmemory.core.store_pipeline import run_store
@@ -327,6 +355,7 @@ class MemoryEngine:
 
     def store_fact_direct(self, fact: AtomicFact) -> str:
         """Store a pre-built fact with full enrichment."""
+        self._require_full("store_fact_direct")
         self._ensure_init()
 
         from superlocalmemory.core.store_pipeline import run_store_fact_direct
@@ -357,6 +386,7 @@ class MemoryEngine:
         ``put_nowait`` and the actual ``pending_outcomes`` INSERT runs
         on a background worker.
         """
+        self._require_full("recall")
         self._ensure_init()
 
         pid = profile_id or self._profile_id
@@ -396,8 +426,14 @@ class MemoryEngine:
                         fact_ids=fact_ids,
                         query_id=getattr(response, "query_id", "") or "",
                     ))
-            except Exception:
-                pass
+            except Exception as _outcome_exc:
+                # Engagement-signal enqueue is non-blocking; recall
+                # correctness does not depend on it. Log so the failure
+                # is visible instead of silently losing learning signals.
+                logger.warning(
+                    "outcome-queue enqueue failed (engagement signal lost): %s",
+                    _outcome_exc,
+                )
 
         return response
 
@@ -407,6 +443,7 @@ class MemoryEngine:
         self, speaker_a: str, speaker_b: str,
     ) -> None:
         """Pre-create canonical entities for conversation speakers."""
+        self._require_full("create_speaker_entities")
         self._ensure_init()
         if self._entity_resolver:
             self._entity_resolver.create_speaker_entities(
@@ -470,3 +507,11 @@ class MemoryEngine:
     def _ensure_init(self) -> None:
         if not self._initialized:
             self.initialize()
+
+    def _require_full(self, operation: str) -> None:
+        if self._capabilities is not Capabilities.FULL:
+            raise CapabilityError(
+                f"{operation} requires a FULL MemoryEngine but this instance "
+                f"is LIGHT; route through WorkerPool (pool.{operation}) or "
+                f"construct MemoryEngine(config, capabilities=Capabilities.FULL)."
+            )