superlocalmemory 3.7.7 → 3.8.0

package/src/superlocalmemory/retrieval/engine.py

@@ -17,6 +17,7 @@ License: AGPL-3.0-or-later
 from __future__ import annotations
 
 import concurrent.futures
+import functools
 import logging
 import math
 import re
@@ -26,6 +27,11 @@ from typing import TYPE_CHECKING, Any, Protocol
 
 from superlocalmemory.core.config import ChannelWeights, RetrievalConfig
 from superlocalmemory.retrieval.fusion import FusionResult, weighted_rrf
+from superlocalmemory.retrieval.time_window import (
+    in_window,
+    infer_window_from_query,
+    parse_window,
+)
 from superlocalmemory.retrieval.strategy import QueryStrategy, QueryStrategyClassifier
 from superlocalmemory.storage.models import (
     AtomicFact,
@@ -97,12 +103,11 @@ class RetrievalEngine:
         self._profile_channel = profile_channel
         self._bridge = bridge_discovery
         self._trust_scorer = trust_scorer
-        # v3.6.15: serialise the per-recall scope-flag set + channel execution.
-        # Channel instances are SHARED across concurrent recalls (the daemon runs
-        # several in parallel); without this, recall B's flags could overwrite
-        # recall A's mid-flight on the shared channels. Uncontended for a single
-        # recall (~0 cost); only the channel phase of concurrent recalls serialises.
-        self._scope_lock = threading.Lock()
+        # v3.7.9: scope flags (include_global / include_shared) are now threaded
+        # as explicit call parameters into every channel's search() method, so
+        # concurrent recalls each carry their own flags — no shared mutable state,
+        # no lock needed. The _scope_lock and per-recall attribute-set loop have
+        # been removed. See defect S01 in the fix/3.7.9 branch notes.
         # One executor belongs to one retrieval engine. Creating/destroying six
         # worker threads on every recall caused allocator/thread-stack RSS churn
         # under sustained sessions. The scope lock already serializes channel
@@ -149,6 +154,7 @@ class RetrievalEngine:
         extra_disabled_channels: set[str] | None = None,
         include_global: bool = False,
         include_shared: bool = False,
+        window: str | tuple[str, str] | None = None,
     ) -> RecallResponse:
         """Full retrieval pipeline: strategy -> channels -> RRF -> rerank.
 
@@ -161,7 +167,11 @@ class RetrievalEngine:
         for the ``--fast`` CLI flag) without mutating shared config.
         """
         t0 = time.monotonic()
-        self._extra_disabled = set(extra_disabled_channels or ())
+        # NOTE: extra_disabled_channels is passed as an explicit local argument
+        # to _run_channels() — it is NOT stored on self.  Storing it as a shared
+        # mutable instance attribute (the old self._extra_disabled = ...) caused
+        # a race condition where two concurrent recalls could overwrite each
+        # other's channel-disable set (v3.4.64 fix).
 
         # v3.5.0 diagnostic: stage timing inside retrieval (SLM_RECALL_TIMING=1).
         import os as _os_e
@@ -195,18 +205,14 @@ class RetrievalEngine:
         # Dynamic top-k for aggregation queries
         effective_limit = 100 if strat.query_type == "aggregation" else limit
 
-        # 3. Run channels. Set the scope flags on the shared channel instances
-        # and execute them under self._scope_lock so a concurrent recall can't
-        # interleave its scope visibility onto these channels mid-flight. The
-        # worker threads spawned inside _run_channels are joined before the lock
-        # releases, so every channel read sees THIS recall's flags.
-        with self._scope_lock:
-            for ch in (self._semantic, self._bm25, self._entity, self._temporal,
-                       self._hopfield, self._spreading_activation):
-                if ch is not None:
-                    ch.include_global = include_global
-                    ch.include_shared = include_shared
-            ch_results = self._run_channels(query, profile_id, strat)
+        # 3. Run channels. Both scope flags AND extra_disabled_channels travel as
+        # explicit call parameters so concurrent recalls with different flags
+        # cannot corrupt each other.  No lock needed — no shared mutable state.
+        ch_results = self._run_channels(
+            query, profile_id, strat,
+            extra_disabled_channels=extra_disabled_channels,
+            include_global=include_global, include_shared=include_shared,
+        )
         _em("run_channels")
         if profile_hits:
             ch_results["profile"] = profile_hits
@@ -318,6 +324,32 @@ class RetrievalEngine:
                 logger.warning("Entity graph signal enhancement: %s", exc)
 
         _em("expand+entity_enh")
+
+        # T-window: prune candidates to the requested event-time range.
+        # Event times are fetched for the bounded candidate set only (indexed),
+        # then in-range facts are kept — before fact load, so out-of-window facts
+        # are never materialized. T3: when the caller passes no explicit window,
+        # infer one from natural-language scope in the query ("last week").
+        # Safety: an EXPLICIT window is authoritative (honoured even if it empties
+        # the set — the user asked for that scope), but an INFERRED window is
+        # additive and never makes recall worse — if it would empty the results,
+        # fall back to the unwindowed set.
+        _explicit_window = window is not None
+        _window = window if _explicit_window else infer_window_from_query(query)
+        if _window is not None and fused:
+            bounds = parse_window(_window)
+            if bounds is not None:
+                etimes = self._db.get_fact_event_times(
+                    [fr.fact_id for fr in fused], profile_id,
+                )
+                windowed = [
+                    fr for fr in fused
+                    if in_window(etimes.get(fr.fact_id), bounds)
+                ]
+                if windowed or _explicit_window:
+                    fused = windowed
+                _em("time_window")
+
         # 4. Load facts for rerank pool
         pool = min(len(fused), max(effective_limit * 3, 30))
         top = fused[:pool]
@@ -411,8 +443,85 @@ class RetrievalEngine:
             no_confident_match=no_match,
             reranker_applied=reranker_applied,
             reranker_status=reranker_status,
+            # Q2b: thematic context when the top results cluster in one
+            # community. Precomputed summary lookup only — no per-query LLM.
+            community_context=self._community_context(results, profile_id),
         )
 
+    # -- Community context (Wave Q2b) --------------------------------------
+
+    def _community_context(
+        self, results: list[Any], profile_id: str, top_k: int = 8,
+    ) -> dict | None:
+        """Attach the precomputed community summary the top results fall into.
+
+        On-device-safe (market CRIT-1): a single read of the ≤N precomputed
+        community_summaries rows + a membership tally — never a per-query LLM
+        fan-out. Gated: fires only when >=2 of the top results AND >=40% of
+        them belong to one community, so precise factual queries are untouched.
+        Fail-open: any error returns None (recall is never affected).
+        """
+        if not results or not getattr(
+            self._config, "enable_community_context", True,
+        ):
+            return None
+        try:
+            import json
+            from collections import Counter
+
+            rows = [
+                dict(r) for r in self._db.execute(
+                    "SELECT community_id, summary, keywords, fact_ids_json, "
+                    "fact_count FROM community_summaries WHERE profile_id = ?",
+                    (profile_id,),
+                )
+            ]
+            if not rows:
+                return None
+
+            fact_to_cid: dict[str, int] = {}
+            summ_by_cid: dict[int, dict] = {}
+            for r in rows:
+                cid = int(r["community_id"])
+                summ_by_cid[cid] = r
+                try:
+                    for fid in json.loads(r.get("fact_ids_json") or "[]"):
+                        fact_to_cid[str(fid)] = cid
+                except (ValueError, TypeError):
+                    continue
+
+            top_ids = [
+                res.fact.fact_id
+                for res in results[:top_k]
+                if getattr(res, "fact", None) is not None
+            ]
+            tally = Counter(
+                fact_to_cid[fid] for fid in top_ids if fid in fact_to_cid
+            )
+            if not tally:
+                return None
+            best_cid, count = tally.most_common(1)[0]
+            coverage = count / len(top_ids) if top_ids else 0.0
+            if count < 2 or coverage < 0.4:
+                return None
+
+            row = summ_by_cid[best_cid]
+            try:
+                members = json.loads(row.get("fact_ids_json") or "[]")
+            except (ValueError, TypeError):
+                members = []
+            return {
+                "community_id": best_cid,
+                "summary": row.get("summary", ""),
+                "keywords": row.get("keywords", ""),
+                "member_fact_ids": members,
+                "coverage": round(coverage, 3),
+                "matched_results": count,
+            }
+        except Exception as exc:
+            logger.debug("community context skipped (fail-open): %s", exc)
+            return None
+
     # -- Evidence floor (v3.6.6) -------------------------------------------
 
     @staticmethod
@@ -628,7 +737,14 @@ class RetrievalEngine:
         return emb
 
     def _run_channels(
-        self, query: str, profile_id: str, strat: QueryStrategy,
+        self,
+        query: str,
+        profile_id: str,
+        strat: QueryStrategy,
+        *,
+        extra_disabled_channels: set[str] | None = None,
+        include_global: bool = False,
+        include_shared: bool = False,
     ) -> dict[str, list[tuple[str, float]]]:
         """Run active retrieval channels.
 
@@ -646,7 +762,9 @@ class RetrievalEngine:
         out: dict[str, list[tuple[str, float]]] = {}
         # Skip channels listed in disabled_channels (ablation support)
         # V3.4.40: union with per-recall extra_disabled set (e.g. --fast skip)
-        disabled = set(self._config.disabled_channels) | getattr(self, "_extra_disabled", set())
+        # V3.4.64: extra_disabled is now a local parameter, not a shared instance
+        # attribute — eliminates the concurrent-recall race condition.
+        disabled = set(self._config.disabled_channels) | set(extra_disabled_channels or ())
 
         # V3.3.4: Embed query ONCE, reuse for semantic + hopfield channels
         q_emb: list[float] | None = None
@@ -688,22 +806,38 @@ class RetrievalEngine:
         if self._semantic is not None and q_emb is not None and "semantic" not in disabled:
             futures["semantic"] = executor.submit(
                 _safe_channel, "semantic",
-                self._semantic.search, q_emb, profile_id, self._config.semantic_top_k,
+                functools.partial(
+                    self._semantic.search,
+                    include_global=include_global, include_shared=include_shared,
+                ),
+                q_emb, profile_id, self._config.semantic_top_k,
             )
         if self._bm25 is not None and "bm25" not in disabled:
             futures["bm25"] = executor.submit(
                 _safe_channel, "bm25",
-                self._bm25.search, query, profile_id, self._config.bm25_top_k,
+                functools.partial(
+                    self._bm25.search,
+                    include_global=include_global, include_shared=include_shared,
+                ),
+                query, profile_id, self._config.bm25_top_k,
             )
         if self._temporal is not None and "temporal" not in disabled:
             futures["temporal"] = executor.submit(
                 _safe_channel, "temporal",
-                self._temporal.search, query, profile_id, self._config.bm25_top_k,
+                functools.partial(
+                    self._temporal.search,
+                    include_global=include_global, include_shared=include_shared,
+                ),
+                query, profile_id, self._config.bm25_top_k,
             )
         if self._hopfield is not None and q_emb is not None and "hopfield" not in disabled:
             futures["hopfield"] = executor.submit(
                 _safe_channel, "hopfield",
-                self._hopfield.search, q_emb, profile_id, self._config.hopfield_top_k,
+                functools.partial(
+                    self._hopfield.search,
+                    include_global=include_global, include_shared=include_shared,
+                ),
+                q_emb, profile_id, self._config.hopfield_top_k,
             )
         if (
             self._spreading_activation is not None
@@ -712,7 +846,11 @@ class RetrievalEngine:
         ):
             futures["spreading_activation"] = executor.submit(
                 _safe_channel, "spreading_activation",
-                self._spreading_activation.search, q_emb, profile_id, self._config.bm25_top_k,
+                functools.partial(
+                    self._spreading_activation.search,
+                    include_global=include_global, include_shared=include_shared,
+                ),
+                q_emb, profile_id, self._config.bm25_top_k,
             )
 
         # Collect results as channels complete.
@@ -981,6 +1119,10 @@ class RetrievalEngine:
 
 _CHANNEL_KEYS: tuple[str, ...] = (
     "semantic", "bm25", "entity_graph", "temporal",
+    # hopfield + spreading_activation are real retrieval channels (score
+    # contract v2) with bandit-chosen weights; omitting them here silently
+    # discarded adaptive reranking for multi-hop relational recall.
+    "spreading_activation", "hopfield",
 )
 
 

package/src/superlocalmemory/retrieval/entity_channel.py

@@ -835,13 +835,15 @@ class EntityGraphChannel:
             )[:top_k]
             # Shadow SQLite before accepting a projected answer.  The graph
             # channel has optional PageRank/community enrichments, so exact
-            # score equality is neither required nor useful; result ordering
-            # and membership are the correctness contract.  Any divergence is
-            # recorded and fails closed to canonical SQLite.
+            # Score equality is neither required nor useful; result *membership*
+            # is the correctness contract. Order within the same fact set is
+            # tolerated — requiring identical ordering would fail closed on
+            # every query with score ties, leaving Cozo permanently unused.
+            # Any membership divergence is recorded and fails closed to SQLite.
             sqlite_results = self._search_without_cozo(query, profile_id, top_k)
-            matches = [fact_id for fact_id, _ in cozo_results] == [
+            matches = {fact_id for fact_id, _ in cozo_results} == {
                 fact_id for fact_id, _ in sqlite_results
-            ]
+            }
             record = getattr(self._cozo, "record_shadow_comparison", None)
             if callable(record):
                 record(matches=matches, projected=cozo_results, canonical=sqlite_results)

package/src/superlocalmemory/retrieval/hopfield_channel.py

@@ -88,6 +88,8 @@ class HopfieldChannel:
         query: Any,
         profile_id: str,
         top_k: int = 50,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
         """Search for facts using Hopfield associative retrieval.
 
@@ -95,6 +97,9 @@ class HopfieldChannel:
             query: Query embedding (list[float] or np.ndarray).
             profile_id: Scope search to this profile.
             top_k: Maximum results to return.
+            include_global: Include global-scope facts. Falls back to the
+                instance attribute when not supplied.
+            include_shared: Include shared-scope facts. Same fallback.
 
         Returns:
             List of (fact_id, score) sorted by score descending.
@@ -104,8 +109,10 @@ class HopfieldChannel:
         if not self._config.enabled:
             return []
 
-        include_global = bool(getattr(self, "include_global", False))
-        include_shared = bool(getattr(self, "include_shared", False))
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         try:
             with self._cache_lock:
                 return self._search_inner(

package/src/superlocalmemory/retrieval/semantic_channel.py

@@ -120,6 +120,8 @@ class SemanticChannel:
         query_embedding: list[float],
         profile_id: str,
         top_k: int = 50,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
         """Search for semantically similar facts.
 
@@ -130,11 +132,23 @@ class SemanticChannel:
             query_embedding: Dense vector for the query.
             profile_id: Scope to this profile.
             top_k: Maximum results to return.
+            include_global: Include global-scope facts. Defaults to the
+                ``include_global`` instance attribute when not supplied,
+                preserving backward compatibility for callers that still
+                set the attribute directly.
+            include_shared: Include shared-scope facts. Same fallback.
 
         Returns:
             List of (fact_id, score) sorted by score descending.
             Score is in [0, 1] range.
         """
+        # Resolve scope flags: explicit param takes priority; fall back to the
+        # legacy attribute-based path so existing callers keep working.
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
+
         if not query_embedding:
             return []
 
@@ -142,16 +156,26 @@ class SemanticChannel:
 
         # Lance is a derived projection.  It is never an authorization source
         # and it never silently replaces the canonical sqlite-vec path: every
-        # promoted query is shadowed and falls back if membership/order differs.
+        # promoted query is shadowed and falls back if the result *membership*
+        # differs. Order differences within the same fact set are tolerated —
+        # float-score ties would otherwise force a fallback on every query,
+        # leaving the promoted backend permanently unused. Once membership
+        # matches, the projected backend's own ranking is authoritative.
         if (
             self._scale_vector_backend is not None
-            and not bool(getattr(self, "include_global", False))
-            and not bool(getattr(self, "include_shared", False))
+            and not include_global
+            and not include_shared
         ):
-            projected = self._search_via_lance(query_embedding, q_vec, profile_id, top_k)
-            canonical = self._search_without_lance(query_embedding, q_vec, profile_id, top_k)
+            projected = self._search_via_lance(
+                query_embedding, q_vec, profile_id, top_k,
+                include_global=include_global, include_shared=include_shared,
+            )
+            canonical = self._search_without_lance(
+                query_embedding, q_vec, profile_id, top_k,
+                include_global=include_global, include_shared=include_shared,
+            )
             self._scale_shadow_checks += 1
-            if [fid for fid, _ in projected] == [fid for fid, _ in canonical]:
+            if {fid for fid, _ in projected} == {fid for fid, _ in canonical}:
                 return projected
             self._scale_shadow_mismatches += 1
             logger.warning("Lance semantic projection diverged from SQLite; using SQLite")
@@ -161,13 +185,17 @@ class SemanticChannel:
         if self._vector_store and self._vector_store.available:
             results = self._search_via_vector_store(
                 query_embedding, q_vec, profile_id, top_k,
+                include_global=include_global, include_shared=include_shared,
             )
             if results:  # If vec0 returned results, use them
                 return results
             # If vec0 is empty (cold start), fall through to full scan
 
         # --- FALLBACK: full-table scan (original code, unchanged) ---
-        return self._search_full_scan(query_embedding, q_vec, profile_id, top_k)
+        return self._search_full_scan(
+            query_embedding, q_vec, profile_id, top_k,
+            include_global=include_global, include_shared=include_shared,
+        )
 
     def set_scale_vector_backend(self, backend: Any | None) -> None:
         """Attach a parity-verified Lance projection without replacing SQLite."""
@@ -180,14 +208,27 @@ class SemanticChannel:
         }
 
     def _search_via_lance(
-        self, query_embedding: list[float], q_vec: np.ndarray, profile_id: str, top_k: int,
+        self,
+        query_embedding: list[float],
+        q_vec: np.ndarray,
+        profile_id: str,
+        top_k: int,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         original_store, original_qas = self._vector_store, self._qas
         try:
             self._vector_store = _LanceCandidateSource(self._scale_vector_backend)
             # QAS indexes SQLite/quantized records and cannot represent Lance.
             self._qas = None
-            return self._search_via_vector_store(query_embedding, q_vec, profile_id, top_k)
+            return self._search_via_vector_store(
+                query_embedding, q_vec, profile_id, top_k,
+                include_global=include_global, include_shared=include_shared,
+            )
         except Exception as exc:
             logger.warning("Lance semantic projection failed closed to SQLite: %s", exc)
             return []
@@ -195,15 +236,31 @@ class SemanticChannel:
             self._vector_store, self._qas = original_store, original_qas
 
     def _search_without_lance(
-        self, query_embedding: list[float], q_vec: np.ndarray, profile_id: str, top_k: int,
+        self,
+        query_embedding: list[float],
+        q_vec: np.ndarray,
+        profile_id: str,
+        top_k: int,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         backend, self._scale_vector_backend = self._scale_vector_backend, None
         try:
             if self._vector_store and self._vector_store.available:
-                results = self._search_via_vector_store(query_embedding, q_vec, profile_id, top_k)
+                results = self._search_via_vector_store(
+                    query_embedding, q_vec, profile_id, top_k,
+                    include_global=include_global, include_shared=include_shared,
+                )
                 if results:
                     return results
-            return self._search_full_scan(query_embedding, q_vec, profile_id, top_k)
+            return self._search_full_scan(
+                query_embedding, q_vec, profile_id, top_k,
+                include_global=include_global, include_shared=include_shared,
+            )
         finally:
             self._scale_vector_backend = backend
 
@@ -213,8 +270,14 @@ class SemanticChannel:
         q_vec: np.ndarray,
         profile_id: str,
         top_k: int,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
         """KNN via VectorStore (or QAS 3-tier), then Fisher-Rao re-scoring."""
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         # V3.3.19: Try TurboQuant 3-tier search first (float32 + int8 + polar)
         if self._qas is not None:
             try:
@@ -235,12 +298,19 @@ class SemanticChannel:
                 query_embedding, top_k=top_k * 2, profile_id=profile_id,
             )
 
+        # M-01: Normalize KNN scores to [0.5, 1.0] via (score + 1.0) / 2.0 so
+        # they are on the same scale as full-scan scores computed from
+        # (_cosine_similarity(q, f) + 1.0) / 2.0 in the external_scores path.
+        # vector_store.search() clips at 0 (max(0, cosine)), which maps [–1,1]
+        # to [0,1]; the canonical formula maps to [0.5, 1.0] for positives.
+        # Both are [0,1] but different scales — without this normalization KNN
+        # scores are systematically lower and external facts always win max().
+        knn_results = [(fid, (score + 1.0) / 2.0) for fid, score in knn_results]
+
         # The vector index is partitioned by owner profile. An opted-in global
         # or authorized shared fact owned by another profile cannot enter the
         # local KNN candidate set, so merge the bounded cross-profile visible
         # supplement using the same canonical DB scope predicate as fallback.
-        include_global = bool(getattr(self, "include_global", False))
-        include_shared = bool(getattr(self, "include_shared", False))
         external_facts = self._db.get_external_visible_facts(
             profile_id,
             include_global=include_global,
@@ -272,8 +342,8 @@ class SemanticChannel:
         knn_scores = {fid: score for fid, score in knn_results}
         facts = self._db.get_facts_by_ids(
             candidate_ids, profile_id,
-            include_global=getattr(self, 'include_global', False),
-            include_shared=getattr(self, 'include_shared', False),
+            include_global=include_global,
+            include_shared=include_shared,
         )
 
         if not facts:
@@ -294,15 +364,32 @@ class SemanticChannel:
 
         scored: list[tuple[str, float]] = []
         for fact in facts:
-            cos_sim = knn_scores.get(fact.fact_id, 0.0)
+            # C2-ret H-01: recompute the final cosine from the canonical
+            # full-precision embedding using the SAME formula as the full-scan
+            # fallback, so the fast path is observationally equivalent — identical
+            # score MAGNITUDES, not merely identical rankings. The KNN/vector-store
+            # score is a candidate-SELECTION signal only (it decides which facts
+            # are Fisher-rescored), never the final magnitude; trusting it here
+            # leaked the vector store's negative-cosine clamp into public scores.
+            # When a candidate carries no usable embedding (index-only rows), fall
+            # back to the normalized KNN score, preserving the M-01 contract.
+            f_vec: np.ndarray | None = None
+            if fact.embedding is not None:
+                candidate = np.array(fact.embedding, dtype=np.float32)
+                if candidate.shape == q_vec.shape:
+                    f_vec = candidate
+
+            if f_vec is not None:
+                cos_sim = (_cosine_similarity(q_vec, f_vec) + 1.0) / 2.0
+            else:
+                cos_sim = knn_scores.get(fact.fact_id, 0.0)
 
             fisher_weight = self._fisher_weight(fact.access_count)
 
             if (fisher_weight > 0.01
                     and fact.fisher_variance is not None
-                    and fact.embedding is not None
+                    and f_vec is not None
                     and len(fact.fisher_variance) == len(q_vec)):
-                f_vec = np.array(fact.embedding, dtype=np.float32)
                 var_vec = np.array(fact.fisher_variance, dtype=np.float32)
                 f_sim = self._compute_fisher_sim(
                     q_vec, f_vec, var_vec, fact, q_mean, q_var,
@@ -323,10 +410,16 @@ class SemanticChannel:
         q_vec: np.ndarray,
         profile_id: str,
         top_k: int,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
         """Original full-table-scan search. Used as fallback when VectorStore
         is unavailable or empty (cold start).
         """
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         # Compute query Fisher params for Bayesian comparison (F45 fix)
         q_mean: np.ndarray | None = None
         q_var: np.ndarray | None = None
@@ -337,8 +430,8 @@ class SemanticChannel:
 
         facts = self._db.get_all_facts(
             profile_id,
-            include_global=getattr(self, 'include_global', False),
-            include_shared=getattr(self, 'include_shared', False),
+            include_global=include_global,
+            include_shared=include_shared,
         )
 
         scored: list[tuple[str, float]] = []

package/src/superlocalmemory/retrieval/spreading_activation.py

@@ -110,16 +110,25 @@ class SpreadingActivation:
         query: Any,
         profile_id: str = "",
         top_k: int = 7,
+        include_global: bool | None = None,
+        include_shared: bool | None = None,
     ) -> list[tuple[str, float]]:
         """Channel-compatible interface: (query, top_k) -> [(fact_id, score)].
 
         Matches ANNSearchable protocol (Rule 07).
+
+        Args:
+            include_global: Include global-scope facts. Falls back to the
+                instance attribute when not supplied.
+            include_shared: Include shared-scope facts. Same fallback.
         """
         if not self._config.enabled:
             return []
 
-        include_global = bool(getattr(self, "include_global", False))
-        include_shared = bool(getattr(self, "include_shared", False))
+        if include_global is None:
+            include_global = bool(getattr(self, "include_global", False))
+        if include_shared is None:
+            include_shared = bool(getattr(self, "include_shared", False))
         try:
             # Step 0: Get seed nodes from VectorStore KNN
             seed_results = self._seed_search(