cortexm 0.3.0__py3-none-any.whl

cortexm/bridge/reader.py

@@ -0,0 +1,1174 @@
+"""Read path — deterministic neuro-symbolic query planner.
+
+Query → intent parse (temporal / ordering / counting / supersession /
+current-state / multi-hop / free recall) → parallel VSA palace search +
+symbolic Trace queries → contradiction-chain & entity-hop expansion →
+weighted fusion → context block with per-fact cryptographic provenance.
+
+Every retrieval returns the full audit chain:
+query → VSA match → symbolic dereference → source hash → source text.
+No LLM calls at query time (edge-capable, offline).
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from cortexm import metrics
+from cortexm.bridge.dates import find_dates
+from cortexm.config import Config
+from cortexm.text.tokenizer import cap_sequences, content_words
+from cortexm.trace.fact import Fact
+from cortexm.trace.store import TraceStore
+from cortexm.util import normalize
+from cortexm.vsa.palace import MemoryPalace
+from cortexm.vsa.slb import SemanticLookasideBuffer
+
+
+def _content_key(f: "Fact | None") -> tuple:
+    """Deterministic ordering key for a fact. Fact ids are uuid4 (random
+    per process); ties broken on id would make rankings — and therefore
+    benchmark scores — vary across identical runs. Content never does."""
+    if f is None:
+        return ("~", "~", "~", "~")
+    return (f.subject, f.relation, f.value, str(f.valid_from))
+
+
+RELATION_HINTS = [
+    # occupation idioms FIRST: "for a living" contains "living", which the
+    # residence hint below would otherwise capture, drowning the `role`
+    # fact under lives_in/moved_to noise.
+    (re.compile(r"\b(for a living|occupation|profession|career|job title|"
+                r"what does .{2,40}? do|works? as)\b", re.I),
+     ["role", "works_at", "studied"]),
+    (re.compile(r"\b(work\w*|employer|company|job)\b", re.I),
+     ["works_at", "role"]),
+    (re.compile(r"\b(live|lives|living|based|city|hometown|resid\w*|mov\w*)\b", re.I),
+     ["lives_in", "moved_to"]),
+    (re.compile(r"\b(prefer\w*|like\w*|favorite|favourite|taste)\b", re.I),
+     ["prefers", "likes", "dislikes"]),
+    (re.compile(r"\b(music|food|coffee|genre|playlist|meal|lunch|dinner|"
+                r"drink|snack|editor|theme|picking|pick|choose|choosing)\b",
+                re.I),
+     ["prefers", "likes", "dislikes"]),
+    (re.compile(r"\b(manag\w*|boss|report\w*|supervis\w*)\b", re.I),
+     ["reports_to", "manages"]),
+    (re.compile(r"\b(team|group|squad)\b", re.I),
+     ["member_of", "manages", "team_uses", "uses"]),
+    (re.compile(r"\b(skill\w*|know\w*|languag\w*|code|coding|program\w*|stack|tool\w*)\b", re.I),
+     ["has_skill", "speaks", "team_uses", "uses"]),
+    (re.compile(r"\b(birthday|born|age|years old)\b", re.I),
+     ["birthday", "age"]),
+    (re.compile(r"\b(sister|brother|mother|father|mom|dad|wife|husband|sibling|spouse|parent|family|daughter|son)\b", re.I),
+     ["sibling", "parent", "spouse", "child"]),
+    (re.compile(r"\b(project\w*|build\w*|ship\w*|launch\w*|develop\w*|releas\w*)\b", re.I),
+     ["works_on", "completed", "event"]),
+    (re.compile(r"\b(happen\w*|events?|did|done)\b", re.I), ["event"]),
+    (re.compile(r"\b(stud\w*|school|degree|major|university|college|educat\w*)\b", re.I),
+     ["studied", "studied_at"]),
+    (re.compile(r"\b(pet|dog|cat|animal)\b", re.I), ["has_pet"]),
+    (re.compile(r"\b(hobby|free time|weekend)\b", re.I), ["hobby"]),
+    (re.compile(r"\b(nickname|alias|called|go by|full name|real name)\b", re.I),
+     ["alias", "name"]),
+    (re.compile(r"\b(goal|plan\w*|want to|hope)\b", re.I), ["goal"]),
+    (re.compile(r"\b(instruction|always|never|respond|format|signature|guideline)\b", re.I),
+     ["instruction"]),
+]
+
+CURRENT_MARKERS = re.compile(
+    r"\b(current\w*|now|these days|nowadays|latest|today|present)\b", re.I)
+SUPERSESSION_MARKERS = re.compile(
+    r"\b(still|no longer|anymore|used to|former\w*|previous\w*|before|always|ever)\b", re.I)
+ORDERING_MARKERS = re.compile(
+    r"\b(which|what)\s+(?:one\s+)?happened\s+(?:first|before|earlier)\b"
+    r"|\bbefore\s+.+?\s+or\b|\border\b|\bsequence\b|\bchronolog\w*\b"
+    r"|\bfirst\s*:\s*.*\s+or\s+", re.I)
+COUNT_MARKERS = re.compile(
+    r"\bhow\s+many\s+(times|jobs|cities|companies|roles|moves|changes)\b"
+    r"|\bhow\s+often\b", re.I)
+LIST_MARKERS = re.compile(
+    r"\b(?:list|name|enumerate|summar\w+)\b.*\b(?:all|every)\b"
+    r"|\ball\s+(?:the\s+)?\w+\s+"
+    r"(?:that|which|she|he|they|i)\b"
+    r"|\b(?:list|name|enumerate)\s+all\b"
+    r"|\b(?:list|name|enumerate)\s+every\b", re.I)
+MULTIHOP_MARKERS = re.compile(
+    r"\b('s\b|of the|of my|of her|of his|of their)\b", re.I)
+# Tier-4 fix: implicit "current" queries — "where does X work?" /
+# "what does X do?" / "what's X's job/employer/city?" — these are
+# asking for the single-valued CURRENT state but contain no explicit
+# "now" marker. Detecting them lets the reader apply the "current"
+# intent (which sets allow_inactive=True so the superseded chain can
+# surface; for ACTIVE facts only it also biases ranking toward the
+# latest valid_from).
+SINGLE_VALUED_QUERY = re.compile(
+    r"\b(?:where\s+(?:does|do|is)\s+\w+\s+(?:work|live|stay|reside)\b"
+    r"|what(?:'?s| is)\s+\w+(?:'?s)?\s+(?:job|role|title|position|employer|"
+    r"company|boss|manager|location|address|city|home)\b"
+    r"|\bwhat\s+does\s+\w+\s+do\b"
+    r"|\bwho\s+is\s+\w+(?:'?s)?\s+(?:manager|boss|lead|supervisor)\b)", re.I)
+# Temporal + LIST fusion: "list all X from 2024" or "what did X do
+# between A and B" should be a temporal-list (return the full matching
+# set within the window, not just top-k). Detected downstream by the
+# planner when both LIST and a temporal window are set.
+
+
+@dataclass
+class QueryPlan:
+    intent: str = "recall"
+    entities: list[str] = field(default_factory=list)
+    relations: list[str] = field(default_factory=list)
+    window_start: str | None = None
+    window_end: str | None = None
+    keywords: list[str] = field(default_factory=list)
+    # Tier-4 fix: sub-intent carries the temporal_list fusion flag
+    # so the reader's filter knows to apply BOTH the temporal window
+    # AND the exhaustive recall semantics (don't truncate to top-k).
+    sub_intent: str | None = None
+
+
+@dataclass
+class RetrievalResult:
+    query: str
+    intent: str
+    facts: list[Fact]
+    context_block: str
+    provenance: dict
+    timing: dict
+    slb_hit: bool = False
+    scores: dict = field(default_factory=dict)
+
+    def memories(self) -> list[dict]:
+        out = []
+        for f in self.facts:
+            out.append({
+                "id": f.id,
+                "memory": f"{f.subject} | {f.relation} | {f.value}",
+                "score": self.scores.get(f.id, 0.0),
+                "event": "ADD",
+                "valid_from": f.valid_from,
+                "valid_to": f.valid_to,
+                "confidence": f.confidence,
+                "hash": f.source_hash,
+            })
+        return out
+
+
+class MemoryReader:
+    def __init__(self, config: Config, store: TraceStore, palace: MemoryPalace,
+                 prefetcher=None) -> None:
+        self.cfg = config
+        self.store = store
+        self.palace = palace
+        self.prefetcher = prefetcher
+        self.slb = SemanticLookasideBuffer(
+            config.slb_entries, config.slb_threshold, config.dims)
+        self._scope_cache: dict[tuple, frozenset] = {}
+        self._queries = 0
+        # NSR-inspired swappable decoder (default = LLM prompt block,
+        # preserving the original reader._context_block behavior).
+        # Override via reader.with_decoder("rdf" | "datalog" | "json").
+        from cortexm.bridge.decoders import get_decoder
+        self._decoder = get_decoder("llm_prompt")
+        # Cross-encoder-style fact reranker (μ=0). Lazily imported so the
+        # rest of the fabric is unaffected. Controlled by the
+        # `enable_rerank` config knob (False by default — the bench must
+        # explicitly enable it via "+rerank" config).
+        self._reranker = None
+        if getattr(config, "enable_rerank", False):
+            try:
+                from cortexm.bridge.rerank import FactReranker
+                self._reranker = FactReranker(
+                    palace.embedder,
+                    alpha=getattr(config, "rerank_alpha", 0.55),
+                    beta=getattr(config, "rerank_beta", 0.45),
+                    prf_alpha=getattr(config, "prf_alpha", 0.6),
+                    prf_beta=getattr(config, "prf_beta", 0.4),
+                    prf_topn=getattr(config, "prf_topn", 3))
+            except Exception:  # noqa: BLE001
+                self._reranker = None
+
+    def with_decoder(self, name: str) -> "MemoryReader":
+        """Swap the output decoder (NSR insight: same palace + Trace,
+        different decoder). Returns self for chaining.
+
+        Known decoders: 'llm_prompt' (default), 'rdf', 'datalog', 'json'.
+        """
+        from cortexm.bridge.decoders import get_decoder
+        self._decoder = get_decoder(name)
+        return self
+
+    # ------------------------------------------------------------- helpers
+    def _scope_ids(self, user_id, agent_id, run_id, branch) -> frozenset:
+        head = self.store.head(branch or self.store.current_branch()) or ""
+        key = (user_id, agent_id, run_id, branch, head)
+        hit = self._scope_cache.get(key)
+        if hit is not None:
+            return hit
+        facts = self.store.query_facts(
+            user_id=user_id, agent_id=None, run_id=run_id,
+            active=True, include_quarantined=False)
+        # InjecMEM scope sandbox:
+        #  * user-scope query (agent_id=None) sees ONLY user-scoped facts;
+        #    agent-written facts stay invisible until explicitly promoted.
+        #  * agent query (agent_id=A) sees A's own facts PLUS the shared
+        #    user scope — agents read the user's memory, never each
+        #    other's.
+        if agent_id is None:
+            if getattr(self.cfg, "sandbox_enabled", True):
+                facts = [f for f in facts if f.agent_id is None]
+        else:
+            facts = [f for f in facts if f.agent_id in (None, agent_id)]
+        ids = frozenset(f.id for f in facts)
+        if branch is not None:
+            active = self.store.active_ids(branch)
+            ids = ids & active
+        if len(self._scope_cache) < 16:
+            self._scope_cache[key] = ids
+        return ids
+
+    def invalidate_caches(self) -> None:
+        self._scope_cache.clear()
+
+    def _canonical_entities(self, query: str, user_id: str) -> list[str]:
+        """cap-sequences + lexicon + alias resolution to canonical names."""
+        cands: list[str] = []
+        for seq in cap_sequences(query):
+            cands.append(seq.strip().rstrip(".,!?;:"))
+        # single capitalized words that are known entities
+        for w in re.findall(r"\b[A-Z][a-z]{2,}\b", query):
+            cands.append(w)
+        name = self.store.kv_get(f"name:{user_id}")
+        if re.search(r"\b(my|i|me)\b", query, re.I) and name:
+            cands.append(name)
+
+        lex_keys = set()
+        import json
+        raw = self.store.kv_get(f"lexicon:{user_id}", "[]")
+        try:
+            lex_keys = set(json.loads(raw))
+        except Exception:
+            pass
+        canonical: list[str] = []
+        seen = set()
+        seen_out: set[str] = set()
+        for c in cands:
+            if not c or c.lower() in seen:
+                continue
+            seen.add(c.lower())
+            resolved = None
+            # alias resolution: (X, alias, c) → X
+            for f in self.store.query_facts(relation="alias", value=c,
+                                            user_id=user_id, active=True,
+                                            limit=8):
+                resolved = f.subject
+                break
+            if resolved is None and c in lex_keys:
+                resolved = c
+            if resolved is None and name and c.lower() == name.split()[0].lower():
+                resolved = name
+            # FALL-THROUGH: if no alias/lexicon/name resolution found,
+            # use the candidate as-is. This is correct for cases where
+            # the user is asking about an entity that's already a fact
+            # subject in the trace — "Where does Alice work?" with
+            # (Alice, works_at, Google) in the trace should resolve
+            # "Alice" → "Alice" without requiring a separate alias
+            # fact. (The previous behavior dropped the candidate,
+            # which silently broke recall.)
+            if resolved is None:
+                # check if the candidate matches a known fact subject
+                # in this user's scope — if so, use it
+                for f in self.store.query_facts(subject=c, user_id=user_id,
+                                                  active=True, limit=1):
+                    resolved = c
+                    break
+            if resolved is None:
+                # last resort: use the candidate as-is. This is the
+                # correct default for capitalized entity mentions in
+                # natural language queries.
+                resolved = c
+            if resolved and resolved.lower() not in seen_out:
+                canonical.append(resolved)
+                seen_out.add(resolved.lower())
+        # order: prefer multi-word (full names) first
+        canonical.sort(key=lambda s: -len(s))
+        return canonical[:4]
+
+    def _plan(self, query: str, user_id: str, ts: datetime | None) -> QueryPlan:
+        plan = QueryPlan()
+        for rx, rels in RELATION_HINTS:
+            if rx.search(query):
+                plan.relations.extend(rels)
+        plan.relations = list(dict.fromkeys(plan.relations))[:5]
+        plan.entities = self._canonical_entities(query, user_id)
+        plan.keywords = content_words(query)
+
+        if ORDERING_MARKERS.search(query):
+            plan.intent = "ordering"
+        elif COUNT_MARKERS.search(query):
+            plan.intent = "count"
+        elif LIST_MARKERS.search(query):
+            plan.intent = "list"      # exhaustive set recall
+        elif SUPERSESSION_MARKERS.search(query) or CURRENT_MARKERS.search(query):
+            plan.intent = "current"
+        # Tier-4 fix: implicit "current" queries — surface the latest
+        # value on single-valued relations ("where does X work?" /
+        # "what does X do?") even without an explicit "now" marker.
+        # This is the #1 LongMemEval knowledge-update failure mode:
+        # the user asks the obvious question and the engine returns
+        # the superseded (now-inactive) fact because it was never
+        # promoted into the "current" intent. Detected here via the
+        # SINGLE_VALUED_QUERY regex; only fires when no higher-
+        # precision intent (ordering/count/list) already matched.
+        if plan.intent == "recall" and SINGLE_VALUED_QUERY.search(query):
+            plan.intent = "current"
+        dates = find_dates(query, ts or datetime.now(timezone.utc))
+        if dates and plan.intent in ("recall", "current"):
+            plan.intent = "temporal"
+            plan.window_start = dates[0]["iso"]
+            plan.window_end = dates[1]["iso"] if len(dates) > 1 else None
+            if dates[0].get("granularity") == "year":
+                y = dates[0]["iso"][:4]
+                plan.window_start = f"{y}-01-01"
+                plan.window_end = f"{y}-12-31"
+            elif dates[0].get("granularity") in ("month", "ym_num"):
+                # "in February 2025" — close the window at end-of-month;
+                # an open-ended start would drag in every later event.
+                y, mo = dates[0]["iso"][:4], int(dates[0]["iso"][5:7])
+                _last = [31, 29 if (int(y) % 4 == 0 and (int(y) % 100 != 0
+                            or int(y) % 400 == 0)) else 28,
+                         31, 30, 31, 30, 31, 31, 30, 31, 30, 31][mo - 1]
+                plan.window_start = f"{y}-{mo:02d}-01"
+                plan.window_end = f"{y}-{mo:02d}-{_last:02d}"
+            elif dates[0].get("granularity") in ("day", "day_r", "iso_day"):
+                plan.window_end = dates[0]["iso"]
+        # Tier-4 fix: temporal + LIST fusion. "List all of Alice's
+        # projects from 2024" should keep the LIST intent (so the
+        # reader returns the exhaustive set) AND attach the temporal
+        # window (so only facts within 2024 are returned). Previously
+        # the date check above was gated on plan.intent in
+        # ("recall","current"), so LIST + date silently dropped the
+        # window. We now set the window independently of intent, and
+        # add a "temporal_list" sub-intent flag for the reader to use.
+        elif dates and plan.intent == "list":
+            # carry the window through unchanged from the date parser
+            plan.window_start = dates[0]["iso"]
+            plan.window_end = dates[1]["iso"] if len(dates) > 1 else None
+            if dates[0].get("granularity") == "year":
+                y = dates[0]["iso"][:4]
+                plan.window_start = f"{y}-01-01"
+                plan.window_end = f"{y}-12-31"
+            elif dates[0].get("granularity") in ("month", "ym_num"):
+                y, mo = dates[0]["iso"][:4], int(dates[0]["iso"][5:7])
+                _last = [31, 29 if (int(y) % 4 == 0 and (int(y) % 100 != 0
+                            or int(y) % 400 == 0)) else 28,
+                         31, 30, 31, 30, 31, 31, 30, 31, 30, 31][mo - 1]
+                plan.window_start = f"{y}-{mo:02d}-01"
+                plan.window_end = f"{y}-{mo:02d}-{_last:02d}"
+            elif dates[0].get("granularity") in ("day", "day_r", "iso_day"):
+                plan.window_end = dates[0]["iso"]
+            plan.sub_intent = "temporal_list"
+        if re.search(r"\bbetween\s+.+\s+and\s+", query, re.I) and len(dates) >= 2:
+            plan.window_start = min(d["iso"] for d in dates)
+            plan.window_end = max(d["iso"] for d in dates)
+        if re.search(r"\b(before)\b", query, re.I) and dates:
+            plan.intent = "temporal"
+            plan.window_end = dates[0]["iso"]
+            plan.window_start = None
+        if re.search(r"\b(after)\b", query, re.I) and dates:
+            plan.intent = "temporal"
+            plan.window_start = dates[0]["iso"]
+            plan.window_end = None
+        # Tier-4 fix: employment-anchored temporal window.
+        # "Where did X live when (he|she|they) was at <ORG>?" — the
+        # window is the validity period of (X, works_at, <ORG>).
+        # Date parsers can't see "Stripe" as a date; this is the
+        # LongMemEval "where did X live when at Y" failure mode.
+        emp_window = self._employment_window(query, user_id)
+        if emp_window:
+            ws, we = emp_window
+            plan.window_start = ws
+            plan.window_end = we
+            if plan.intent == "recall":
+                plan.intent = "temporal"
+        if MULTIHOP_MARKERS.search(query) and len(plan.relations) >= 2:
+            plan.intent = "multihop" if plan.intent == "recall" else plan.intent
+        return plan
+
+    def _employment_window(self, query: str, user_id: str) -> tuple[str, str] | None:
+        """Detect "when (he|she|they|while) was at <ORG>" and return the
+        validity window of the matching works_at fact.
+
+        Returns (valid_from, valid_to) where valid_to defaults to today
+        if the fact is still active (Bob is still at OpenAI). Used to
+        answer "Where did Bob live when he was at Stripe?" — the window
+        is the period Bob's works_at Stripe fact was active.
+        """
+        m = re.search(
+            r"\bwhen\s+(?:he|she|they|i|we)\s+(?:was|were|is|are|"
+            r"worked|employed)\s+(?:at|with|for)\s+"
+            r"(?P<org>[A-Z][\w&.-]+(?:\s+[A-Z][\w&.-]+)*)"
+            r"|\bwhile\s+(?:at|with|at\s+(?:his|her|their)\s+job\s+at)\s+"
+            r"(?P<org2>[A-Z][\w&.-]+(?:\s+[A-Z][\w&.-]+)*)"
+            r"|\bduring\s+(?:his|her|their)?\s*(?:time\s+|stint\s+)?at\s+"
+            r"(?P<org3>[A-Z][\w&.-]+(?:\s+[A-Z][\w&.-]+)*)",
+            query, re.I)
+        if not m:
+            return None
+        org = (m.group("org") or m.group("org2") or m.group("org3") or "").strip()
+        if not org:
+            return None
+        # look up the works_at fact for this user + org
+        facts = self.store.query_facts(user_id=user_id,
+                                       relation="works_at", active=False)
+        # match by value substring (case-insensitive)
+        org_l = org.lower()
+        for f in facts:
+            if org_l in f.value.lower() or f.value.lower() in org_l:
+                end = f.valid_to or "9999-12-31"
+                return (f.valid_from or "1900-01-01", end)
+        return None
+
+    # ------------------------------------------------------------- search
+    def search(self, query: str, *, user_id: str = "default",
+               agent_id: str | None = None, run_id: str | None = None,
+               k: int | None = None, ts: datetime | None = None,
+               branch: str | None = None) -> RetrievalResult:
+        t0 = time.perf_counter()
+        k = k or self.cfg.top_k_default
+        branch = branch or self.store.current_branch()
+        metrics.bump_retrieval()
+        self._queries += 1
+
+        q_vec = self.palace.embedder.embed(query)
+        plan = self._plan(query, user_id, ts)
+        # intents that emit procedural notes (ORDERING: ..., temporal windows,
+        # counts) cannot be served from the SLB: a cache hit would silently
+        # drop the note and return the wrong fact set for the query shape.
+        # LIST intent is also excluded: its SLB hit filter
+        # (`f.is_active and not f.quarantined`) drops the superseded chain,
+        # silently breaking "list all the places Bob has worked". The
+        # full LIST recall must hit the symbolic path so the supersession
+        # chain expansion (in _build_narrative) can pull inactive facts.
+        slb_ok = (plan.intent not in ("ordering", "temporal", "count", "list")
+                  and not getattr(self.cfg, "slb_disabled", False))
+        scope_key = (user_id, agent_id, run_id, branch)
+        cached = self.slb.lookup(q_vec, scope_key) if slb_ok else None
+        if cached is not None:
+            facts = self.store.get_facts([fid for fid, _ in cached])
+            facts = [f for f in facts if f.is_active and not f.quarantined
+                     and f.matches_scope(user_id, agent_id, run_id)
+                     and (agent_id is not None or f.agent_id is None
+                          or not getattr(self.cfg, "sandbox_enabled", True))]
+            facts = facts[:k]
+            t1 = time.perf_counter()
+            self.slb.record_latency(True, t1 - t0)
+            block = self._context_block(query, "recall", facts,
+                                        {f.id: s for f, (fid, s) in zip(facts, cached)})
+            return RetrievalResult(query, "recall", facts, block,
+                                    self._provenance(query, facts),
+                                    {"latency_ms": round((t1 - t0) * 1e3, 3),
+                                     "slb": "hit"}, True,
+                                    {f.id: s for f, (fid, s) in zip(facts, cached)})
+        self.slb.misses += 1
+
+        scope = self._scope_ids(user_id, agent_id, run_id, branch)
+
+        # --- VSA path (neural recall) ------------------------------------
+        # NOTE: an EMPTY scope is a real state (scope sandbox: the user
+        # owns no visible facts, e.g. everything is agent-scoped). It must
+        # filter to nothing — the old `if scope else None` fallback turned
+        # it into an UNRESTRICTED search that leaked agent-scoped (and
+        # cross-user) vectors into the result set.
+        vsa_hits = self.palace.search(q_vec, max(k * self.cfg.search_k_mult, 24),
+                                      candidate_ids=set(scope))
+        vsa_scores = {fid: float(s) for fid, s in vsa_hits}
+
+        # --- symbolic path -------------------------------------------------
+        sym_facts, notes = self._symbolic_query(plan, user_id, agent_id, run_id,
+                                                scope, k, query)
+
+        # --- query-aware triple pre-filter (HippoRAG 2 lineage) ------------
+        # Drop candidate facts that have low lexical+semantic+relation
+        # overlap with the query BEFORE fusion. HippoRAG 2 credits this
+        # for a 7% F1 gain: removing irrelevant triples from the candidate
+        # pool prevents noise from contaminating the VSA holographic
+        # superposition and the PPR graph. μ=0 — deterministic scorer.
+        # Default ON; configurable via Config.prefilter_enabled.
+        if getattr(self.cfg, "prefilter_enabled", True) and (vsa_scores or sym_facts):
+            try:
+                from cortexm.bridge.prefilter import prefilter_triples
+                # merge the union of vsa + symbolic candidates for filtering
+                pf_map = {f.id: f for f in self.store.get_facts(list(vsa_scores))}
+                pf_map.update({f.id: f for f, _ in sym_facts})
+                pf_candidates = list(pf_map.values())
+                filtered, pf_stats = prefilter_triples(
+                    pf_candidates, query,
+                    query_emb=q_vec,
+                    embedder=self.palace.embedder,
+                    relation_hints=list(plan.relations) if plan.relations else None,
+                    threshold=getattr(self.cfg, "prefilter_threshold", 0.08),
+                    min_keep=getattr(self.cfg, "prefilter_min_keep", 3),
+                )
+                # rebuild vsa_scores / sym_facts to exclude dropped facts
+                kept_ids = {f.id for f in filtered}
+                vsa_scores = {fid: s for fid, s in vsa_scores.items()
+                              if fid in kept_ids}
+                sym_facts = [(f, b) for f, b in sym_facts
+                             if f.id in kept_ids]
+                # stash stats on the plan for the result.timing block
+                plan.prefilter_stats = pf_stats
+            except Exception:
+                # prefilter is best-effort; never let it block retrieval
+                pass
+
+        # --- fusion ---------------------------------------------------------
+        # 'mentioned' anchors are retrieval scaffolding, not answers: their
+        # long snippets inflate lexical similarity, so ONLY their VSA
+        # contribution is damped. Symbolic exacts always dominate.
+        vsa_ids = list(vsa_scores.keys())
+        fact_map = {f.id: f for f in self.store.get_facts(vsa_ids)}
+        sym_map = {f.id: f for f, _ in sym_facts}
+        fact_map.update({k: v for k, v in sym_map.items() if k not in fact_map})
+        candidates: dict[str, float] = {}
+        for fid, s in vsa_scores.items():
+            f = fact_map.get(fid)
+            rel = f.relation if f else None
+            damp = 0.45 if rel == "mentioned" else 1.0
+            candidates[fid] = candidates.get(fid, 0.0) + \
+                self.cfg.fusion_vsa_weight * max(0.0, s) * damp
+        for f, boost in sym_facts:
+            hinted = f.relation in plan.relations
+            b = boost + (0.2 if hinted else 0.0)
+            candidates[f.id] = candidates.get(f.id, 0.0) + \
+                self.cfg.fusion_symbolic_weight * b
+
+        # prefetch boost (MBTB) — cache-warming heuristic ONLY for simple
+        # recall/current intents: for precision intents (multihop,
+        # temporal, ordering, count) the co-access boost reorders the
+        # ranking away from graph-relevant evidence.
+        prefetch_boosted = set()
+        if (self.prefetcher is not None
+                and plan.intent in ("recall", "current")):
+            for fid, w in self.prefetcher.predict().items():
+                if fid in candidates:
+                    candidates[fid] += 0.05 * w
+                    prefetch_boosted.add(fid)
+
+        # expansion: contradiction chains + temporal neighbors + hops.
+        # Tie-break on fact CONTENT, never on ids: ids are uuid4 (random per
+        # process), so id-based ties would shuffle results across runs.
+        _f0 = {f.id: f for f in self.store.get_facts(list(candidates))}
+        top = sorted(candidates.items(),
+                     key=lambda kv: (-kv[1], _content_key(_f0.get(kv[0]))))[:k]
+        top_ids = [fid for fid, _ in top]
+        extra = self._expand(top_ids, plan, scope, user_id, query)
+        for fid, w in extra.items():
+            candidates.setdefault(fid, 0.0)
+            candidates[fid] += w
+
+        # Personalized PageRank diffusion (HippoRAG 2 lineage): graph
+        # activation from the current top set spreads to multi-hop
+        # evidence — the entity-hop expansion above is its depth-2
+        # approximation; PPR is the full diffusion.
+        if self.cfg.ppr_enabled and plan.intent in ("multihop", "recall"):
+            ppr_ids = list(candidates.keys())[: self.cfg.ppr_graph_size]
+            ppr_facts = self.store.get_facts(ppr_ids)
+            if len(ppr_facts) >= 2:
+                from cortexm.bridge.ppr import ppr_boost
+                seed_ids = top_ids[: self.cfg.ppr_seeds]
+                edges = self.store.edges_of_many(ppr_ids, "CONTRADICTS")
+                boosts = ppr_boost(ppr_facts, seed_ids, edges,
+                                   damping=self.cfg.ppr_damping,
+                                   iters=self.cfg.ppr_iters)
+                for fid, b in boosts.items():
+                    candidates[fid] += self.cfg.ppr_weight * b
+
+        _f1 = {f.id: f for f in self.store.get_facts(list(candidates))}
+        ranked_ids = self._diversify(
+            sorted(candidates,
+                   key=lambda fid: (-candidates[fid], _content_key(_f1.get(fid)))), k)
+        facts = self.store.get_facts(ranked_ids)
+        # LIST intent surfaces inactive facts too: "list all the places Bob
+        # has worked" must return Bob's superseded works_at facts, not just
+        # his current job. The symbolic path's supersession-chain
+        # expansion (in _build_narrative) pulls them into the candidate
+        # pool; allow_inactive is what lets them survive the filter here.
+        allow_inactive = plan.intent in ("temporal", "current", "count", "list")
+        facts = [f for f in facts if not f.quarantined
+                 and (f.is_active or allow_inactive)]
+        # Tier-4 fix: temporal_list fusion — if LIST + window were both
+        # set, apply the temporal window AS A FILTER on the recalled
+        # set (return only facts whose valid_from falls in the window)
+        # AND skip the top-k truncation so the user gets the full list.
+        if plan.sub_intent == "temporal_list" and plan.window_start:
+            ws = plan.window_start
+            we = plan.window_end or "9999-12-31"
+            facts = [f for f in facts
+                     if f.valid_from and ws <= f.valid_from <= we]
+        facts.sort(key=lambda f: ranked_ids.index(f.id) if f.id in ranked_ids else 999)
+
+        # --- cross-encoder rerank (μ=0) -------------------------------------
+        # If enabled, re-score top-k by embedding each fact's natural-
+        # language rendering and computing cosine sim to the query. The
+        # chunk vectors in the palace are long and fact-dense — a fact-
+        # level embedding is focused and lifts precision@k by 10-20pp on
+        # MS-MARCO-style benchmarks (cross-encoder reranking, web search
+        # 2026-08). The candidate pool is expanded to 3*k for the rerank
+        # pass so we have a deeper top-N to draw from. PRF (Rocchio)
+        # shifts the query embedding toward the mean of the top-3 fact
+        # NL embeddings — a 2-5pp lift on TREC.
+        rerank_used = False
+        if (self._reranker is not None
+                and plan.intent in ("recall", "current", "multihop")
+                and len(facts) >= 2):
+            # expand the candidate pool back to the wider fusion set so
+            # the rerank can find facts the diversifier dropped
+            pool_ids = [fid for fid, _ in
+                        sorted(candidates.items(),
+                               key=lambda kv: (-kv[1],
+                                               _content_key(_f1.get(kv[0]))))
+                        [:max(k * 3, 15)]]
+            pool_facts = [f for f in self.store.get_facts(pool_ids)
+                          if (not f.quarantined
+                              and (f.is_active or allow_inactive))]
+            pool_scores = {f.id: candidates.get(f.id, 0.0) for f in pool_facts}
+            reranked, new_scores = self._reranker.rerank(
+                q_vec, pool_facts, pool_scores, top_k=k, enable_prf=True)
+            if reranked:
+                facts = reranked
+                ranked_ids = [f.id for f in facts]
+                # patch candidates so _context_block and SLB see rerank scores
+                candidates.update(new_scores)
+                rerank_used = True
+
+        if self.prefetcher is not None and facts:
+            self.prefetcher.observe([f.id for f in facts[:6]])
+
+        self.store.bump_access([f.id for f in facts])
+        t1 = time.perf_counter()
+        self.slb.record_latency(False, t1 - t0)
+        if not getattr(self.cfg, "slb_disabled", False):
+            self.slb.store(q_vec, [(f.id, candidates.get(f.id, 0.0)) for f in facts],
+                       query=query, scope=scope_key if slb_ok else ("__no_cache__",))
+
+        block = self._context_block(query, plan.intent, facts, candidates,
+                                    notes)
+        result = RetrievalResult(
+            query, plan.intent, facts, block,
+            self._provenance(query, facts, vsa_scores),
+            {"latency_ms": round((t1 - t0) * 1e3, 3), "slb": "miss",
+             "prefetch_boosted": len(prefetch_boosted),
+             "vsa_candidates": len(vsa_scores),
+             "symbolic_candidates": len(sym_facts),
+             "rerank": rerank_used},
+            False, {f.id: round(candidates.get(f.id, 0.0), 4) for f in facts})
+        # --- MIND diversity check (InjecMEM defense) ----------------------
+        # Stamp the result's provenance with the retrieval diversity score
+        # so downstream audit dashboards can surface flagged retrievals.
+        # μ=0 — pure embedding math, no LLM call. We don't drop flagged
+        # results; the existing InjecMEM/MINJA defenses handle that.
+        if getattr(self.cfg, "mind_diversity_check", True) and len(facts) >= 2:
+            try:
+                from cortexm.security.mind import mind_check, \
+                    augment_provenance as _mind_aug
+                mv = mind_check(
+                    facts, self.palace.embedder,
+                    threshold=getattr(self.cfg, "mind_diversity_threshold", 0.85),
+                    flag_on_low_diversity=getattr(
+                        self.cfg, "mind_flag_on_low_diversity", True))
+                _mind_aug(result.provenance, mv)
+                result.timing["mind_diversity"] = round(mv.diversity, 4)
+                result.timing["mind_flagged"] = mv.flagged
+            except Exception:
+                pass
+        return result
+
+    # ------------------------------------------------------------- reconstruct
+    def reconstruct(self, query: str, *, user_id: str = "default",
+                     agent_id: str | None = None, run_id: str | None = None,
+                     k: int = 10, max_hops: int | None = None,
+                     llm_scorer=None) -> RetrievalResult:
+        """Active memory reconstruction (MRAgent, ICML 2026 arXiv:2606.06036).
+
+        Instead of single-shot retrieval, this method iteratively explores
+        the Trace graph around the seed facts:
+
+          1. Run the standard search() to get the initial seed set (top-k).
+          2. For each seed, do a 2-hop PPR expansion to find connected
+             evidence (CONTRADICTS, PRECEDED_BY, REFERS_TO edges).
+          3. Score each hop's relevance to the query:
+             * If `llm_scorer` is provided (call signature:
+               llm_scorer(query, fact) -> float in [0,1]), use it.
+             * Else: use cosine(query_emb, fact_emb) via the palace
+               embedder (μ=0 fallback — breaks strict MRAgent which
+               requires an LLM judge, but preserves offline capability).
+          4. Prune branches whose score < reconstruct_prune_threshold.
+          5. Re-run PPR from the pruned subgraph.
+          6. Return a synthesized narrative: a RetrievalResult whose
+             context block contains a NARRATIVE note linking the
+             retrieved facts in a coherent order.
+
+        MRAgent reports up to 23% improvement on LoCoMo and LongMemEval
+        while reducing token cost. Our implementation is μ=0 by default
+        (no LLM call); pass an `llm_scorer` to enable the full MRAgent
+        path. The narrative is rule-based (deterministic).
+
+        Parameters
+        ----------
+        query : str
+        user_id, agent_id, run_id : scope filter
+        k : int            — final top-k returned
+        max_hops : int     — PPR exploration depth (default cfg.reconstruct_max_hops)
+        llm_scorer : callable(query, fact) -> float in [0,1]
+                     None = μ=0 fallback (cosine sim to query emb)
+        """
+        if not getattr(self.cfg, "reconstruct_enabled", True):
+            # fall back to plain search if reconstruction is disabled
+            return self.search(query, user_id=user_id, agent_id=agent_id,
+                               run_id=run_id, k=k)
+
+        t0 = time.perf_counter()
+        max_hops = max_hops or getattr(self.cfg, "reconstruct_max_hops", 3)
+        prune_threshold = getattr(self.cfg, "reconstruct_prune_threshold", 0.25)
+
+        # 1. seed: standard search top-k
+        seed = self.search(query, user_id=user_id, agent_id=agent_id,
+                           run_id=run_id, k=k * 2)
+        if not seed.facts:
+            return seed
+
+        # 2. PPR 2-hop expansion from seeds
+        seed_ids = [f.id for f in seed.facts]
+        expanded_ids = set(seed_ids)
+        # gather edges from seeds. edges_of_many returns a list of dicts
+        # with src/dst/kind keys (bi-directional).
+        edge_dicts = self.store.edges_of_many(seed_ids, "CONTRADICTS") \
+            if hasattr(self.store, "edges_of_many") else []
+        try:
+            refers_edges = self.store.edges_of_many(seed_ids, "REFERS_TO")
+            edge_dicts.extend(refers_edges)
+        except Exception:
+            pass
+        # collect neighbor ids from the edge list
+        for e in edge_dicts:
+            src = e.get("src") or e.get("src_id")
+            dst = e.get("dst") or e.get("dst_id")
+            if src:
+                expanded_ids.add(src)
+            if dst:
+                expanded_ids.add(dst)
+
+        # 3. score each candidate
+        candidate_facts = self.store.get_facts(list(expanded_ids))
+        candidate_facts = [f for f in candidate_facts
+                           if f.is_active and not f.quarantined]
+        if llm_scorer is not None:
+            scores = {f.id: float(llm_scorer(query, f))
+                      for f in candidate_facts}
+        else:
+            # μ=0 fallback: cosine sim to query embedding
+            q_vec = self.palace.embedder.embed(query)
+            scores = {}
+            for f in candidate_facts:
+                # use the fact's NL rendering (same as reranker)
+                try:
+                    from cortexm.bridge.rerank import fact_nl
+                    f_vec = self.palace.embedder.embed(fact_nl(f))
+                    s = float(q_vec @ f_vec)
+                    scores[f.id] = s
+                except Exception:
+                    scores[f.id] = 0.0
+
+        # 4. prune low-scoring candidates (but always keep seed facts —
+        # they already passed the standard search relevance gate, so
+        # dropping them because the μ=0 cosine sim is low would lose
+        # the strongest evidence).
+        seed_id_set = set(seed_ids)
+        survivors = {fid: s for fid, s in scores.items()
+                     if s >= prune_threshold or fid in seed_id_set}
+        survivor_facts = [f for f in candidate_facts
+                         if f.id in survivors]
+        survivor_facts.sort(key=lambda f: -survivors[f.id])
+
+        # 5. re-run PPR from pruned subgraph for a refinement pass
+        # (the standard PPR boost from search() already ran; this just
+        # re-sorts the survivors by combined score)
+        final_scores = {f.id: survivors[f.id] for f in survivor_facts}
+        # blend in the original seed scores so seed facts that survived
+        # keep their higher weight
+        for f in survivor_facts:
+            if f.id in seed.scores:
+                final_scores[f.id] = 0.6 * final_scores[f.id] \
+                                     + 0.4 * seed.scores[f.id]
+
+        survivor_facts.sort(key=lambda f: -final_scores[f.id])
+        survivor_facts = survivor_facts[:k]
+
+        # 6. synthesize a narrative note
+        narrative = self._build_narrative(query, survivor_facts, final_scores)
+
+        # build a RetrievalResult compatible with the existing API
+        block = self._context_block(query, "reconstruct", survivor_facts,
+                                    final_scores, [narrative])
+        t1 = time.perf_counter()
+        return RetrievalResult(
+            query, "reconstruct", survivor_facts, block,
+            self._provenance(query, survivor_facts),
+            {"latency_ms": round((t1 - t0) * 1e3, 3),
+             "slb": "bypass",
+             "reconstruct_hops": max_hops,
+             "reconstruct_candidates": len(candidate_facts),
+             "reconstruct_survivors": len(survivor_facts),
+             "reconstruct_llm_scored": llm_scorer is not None},
+            False, {f.id: round(final_scores[f.id], 4) for f in survivor_facts})
+
+    def _build_narrative(self, query: str, facts: list["Fact"],
+                         scores: dict[str, float]) -> str:
+        """Synthesize a coherent narrative from the retrieved facts.
+
+        Rule-based (μ=0): orders facts by score, groups by subject, and
+        emits a multi-clause narrative. For temporal queries, orders by
+        valid_from. For multi-hop, follows the edge chain.
+        """
+        if not facts:
+            return f"RECONSTRUCT: no evidence found for '{query}'."
+        # group by subject
+        by_subj: dict[str, list] = {}
+        for f in facts:
+            by_subj.setdefault(f.subject, []).append(f)
+        clauses = []
+        for subj in sorted(by_subj.keys()):
+            group = by_subj[subj]
+            # sort group by valid_from then by score
+            group.sort(key=lambda f: (f.valid_from or "",
+                                      -scores.get(f.id, 0)))
+            parts = [f"{f.relation}={f.value}" for f in group]
+            clauses.append(f"  {subj}: " + "; ".join(parts))
+        return ("RECONSTRUCT narrative (μ=0, rule-based):\n"
+                + "\n".join(clauses))
+
+    # ------------------------------------------------------------- symbolic
+    def _symbolic_query(self, plan: QueryPlan, user_id, agent_id, run_id,
+                        scope, k, query):
+        out: list[tuple[Fact, float]] = []
+        notes: list[str] = []
+        add = lambda f, w: out.append((f, w))  # noqa: E731
+
+        def in_scope(f: Fact) -> bool:
+            # scope is always a frozenset; an EMPTY scope means "nothing
+            # visible" (scope sandbox) and must not fall through to
+            # unfiltered access the way a falsy check would.
+            return (f.id in scope) and f.is_active and not f.quarantined
+
+        if plan.entities:
+            for ent in plan.entities[:2]:
+                for f in self.store.facts_about(ent, user_id=user_id):
+                    if in_scope(f):
+                        boost = 1.0 if f.relation in plan.relations else 0.7
+                        add(f, boost)
+
+        # ordering intent: resolve two events, emit ORDERING note
+        if plan.intent == "ordering":
+            notes.extend(self._ordering_notes(plan, user_id, query, in_scope))
+
+        # count intent
+        if plan.intent == "count":
+            for ent in plan.entities[:1]:
+                for rel in plan.relations or ["works_at"]:
+                    hist = self.store.history_of(ent, rel, user_id=user_id)
+                    n = max(0, len({f.value for f in hist}) - 1)
+                    if hist:
+                        notes.append(f"COUNT: {ent} has {len({f.value for f in hist})} "
+                                     f"recorded value(s) for '{rel}' "
+                                     f"({n} change(s))")
+                    for f in hist:
+                        if in_scope(f) or not f.is_active:
+                            add(f, 0.6)
+
+        # supersession / current / LIST intent: pull full contradiction chains.
+        # LIST is included so "list all the places Bob has worked" surfaces
+        # the superseded works_at facts (Bob's prior jobs), not just his
+        # current one. history_of() returns both active and inactive facts;
+        # the post-fusion allow_inactive flag (in `query`) is what lets them
+        # survive the final filter.
+        if plan.intent in ("current", "temporal", "recall", "list"):
+            pulled = {f.id for f, _ in out}
+            for ent in plan.entities[:2]:
+                for rel in (plan.relations or [])[:3]:
+                    for f in self.store.history_of(ent, rel, user_id=user_id)[:6]:
+                        # `f.id in scope` alone drops inactive facts
+                        # (scope_ids() filters active=True). The `or not
+                        # f.is_active` clause lets the superseded chain
+                        # through — same pattern as the count-intent
+                        # code above. user_id isolation is already
+                        # enforced by history_of()'s user_id param;
+                        # agent_id / branch isolation is best-effort
+                        # and intentionally relaxed for LIST / current
+                        # / temporal / recall so historical facts
+                        # surface. Mirrors line ~886.
+                        if f.id not in pulled and (f.id in scope or not f.is_active):
+                            if f.value in plan.entities:
+                                b = 0.9
+                            elif f.is_active:
+                                b = 0.55
+                            else:
+                                b = 0.45
+                            add(f, b)
+                            pulled.add(f.id)
+
+        # temporal window
+        if plan.window_start or plan.window_end:
+            for f in self.store.temporal_window(
+                    plan.window_start, plan.window_end, user_id=user_id,
+                    active=False):
+                if (not f.quarantined and f.id in scope
+                        and (not plan.entities or
+                             any(e in (f.subject, f.value)
+                                 for e in plan.entities) or
+                             f.relation in plan.relations)):
+                    hinted = f.relation in plan.relations
+                    # tier 1: the fact BEGAN inside the window — this is what
+                    # "what happened in <window>" asks for. tier 2: still-valid
+                    # background state that merely overlaps the window.
+                    vf = f.valid_from or ""
+                    began_in = ((plan.window_start is None
+                                 or vf >= plan.window_start)
+                                and (plan.window_end is None
+                                     or vf <= plan.window_end))
+                    if began_in:
+                        b = (1.0 if hinted else 0.9) if f.is_active \
+                            else (0.9 if hinted else 0.75)
+                    else:
+                        b = (0.6 if hinted else 0.5) if f.is_active \
+                            else (0.5 if hinted else 0.4)
+                    add(f, b)
+
+        return out, notes
+
+    # ------------------------------------------------------------- ordering
+    def _ordering_notes(self, plan, user_id, query, in_scope):
+        notes = []
+        # find two event-ish keywords (quoted or capitalized)
+        parts = re.split(r"\s+or\s+|\?|,|;", query)
+        kw_sets = [set(content_words(p)) for p in parts if p.strip()]
+        all_events = self.store.query_facts(relation="event", user_id=user_id,
+                                            active=True, order="valid_from")
+        events: list[Fact] = []
+        for ks in kw_sets:
+            best, best_ov = None, 0
+            for f in all_events:
+                words = set(content_words(f.value)) | {f.value.lower()}
+                ov = len(ks & words)
+                if ov > best_ov:
+                    best, best_ov = f, ov
+            need = 2 if len(ks) >= 2 else 1
+            if best is not None and best_ov >= need and best not in events:
+                events.append(best)
+        if len(events) < 2:
+            # fall back to any two dated facts around entities
+            evs = [f for f in self.store.query_facts(
+                relation="event", user_id=user_id, active=True,
+                order="valid_from")][:50]
+            events = evs[:2] if len(evs) >= 2 else events
+        if len(events) >= 2:
+            a, b = sorted(events[:2], key=lambda f: f.valid_from)
+            notes.append(f"ORDERING: {a.value} ({a.valid_from}) happened before "
+                         f"{b.value} ({b.valid_from})")
+            self._pending_ordering = getattr(self, "_pending_ordering", [])
+            self._pending_ordering.extend([a, b])
+        return notes
+
+    def _diversify(self, ranked_ids: list[str], k: int,
+                   per_relation: int = 4) -> list[str]:
+        """Cap slots per relation so one relation cannot flood the block."""
+        if len(ranked_ids) <= k:
+            return ranked_ids
+        facts = self.store.get_facts(ranked_ids[: max(k * 3, 48)])
+        rel_of = {f.id: f.relation for f in facts}
+        counts: dict[str, int] = {}
+        first, rest = [], []
+        for fid in ranked_ids:
+            rel = rel_of.get(fid, "?")
+            if counts.get(rel, 0) < per_relation:
+                counts[rel] = counts.get(rel, 0) + 1
+                first.append(fid)
+            else:
+                rest.append(fid)
+        out = (first + rest)[:k]
+        return out
+
+    # ------------------------------------------------------------- expand
+    def _expand(self, top_ids: list[str], plan: QueryPlan, scope, user_id,
+                query: str) -> dict[str, float]:
+        extra: dict[str, float] = {}
+        facts = self.store.get_facts(top_ids[:4])
+        for f in facts:
+            for e in self.store.edges_of(f.id, "CONTRADICTS", "out"):
+                extra.setdefault(e["dst"], 0.35)
+            # same subject-relation history
+            for h in self.store.history_of(f.subject, f.relation,
+                                           user_id=user_id)[:4]:
+                if h.id not in top_ids:
+                    extra.setdefault(h.id, 0.3)
+        # entity-hop expansion (multi-hop associative recall, 2 rounds
+        # when the query is compositional: manager-of-X-team-uses-Y)
+        if plan.intent in ("multihop", "recall") and facts:
+            rounds = 2 if plan.intent == "multihop" else 1
+            frontier = facts[:4]
+            seen = set(top_ids)
+            for _rd in range(rounds):
+                nxt = []
+                for f in frontier[:6]:
+                    for g in self.store.facts_about(f.value, user_id=user_id)[:6]:
+                        if g.id not in seen and g.is_active:
+                            # value-hop = chain completion (X → value → Z):
+                            # the semantic shape of every multi-hop question.
+                            w = (0.7 if _rd == 0 and plan.intent == "multihop"
+                                 else (0.5 if _rd == 0 else 0.35))
+                            extra.setdefault(g.id, w)
+                            seen.add(g.id)
+                            nxt.append(g)
+                    for g in self.store.facts_about(f.subject, user_id=user_id)[:8]:
+                        if g.id not in seen and g.is_active:
+                            extra.setdefault(g.id, 0.3)
+                            seen.add(g.id)
+                            nxt.append(g)
+                frontier = nxt
+                if len(extra) > 60:
+                    break
+        # ordering events force-included
+        for f in getattr(self, "_pending_ordering", []):
+            extra.setdefault(f.id, 0.9)
+        self._pending_ordering = []
+        if scope:
+            extra = {fid: w for fid, w in extra.items() if fid in scope}
+        return extra
+
+    # ------------------------------------------------------------- hologram
+    def working_memory(self, query: str, *, user_id: str = "default",
+                       agent_id: str | None = None, run_id: str | None = None,
+                       k: int | None = None) -> dict:
+        """Compress top-k retrieved facts into a single HRR superposition.
+
+        Strategic-plan item: "Holographic working memory — compress the
+        top-k retrieved facts into a single HRR superposition injected
+        into the LLM system prompt. The LLM unbinds specific facts on
+        demand. This is a 5-10× token reduction for the context window."
+
+        Returns a dict with:
+          - preamble: short (~30-50 token) LLM-ready description
+          - fact_ids: which facts are in the superposition
+          - hrr_b64: the HRR vector, base64-packed (for round-trip
+                    through the MCP / REST API)
+          - n_facts: how many facts were superposed
+          - roles_present: subset of {S, R, V}
+        """
+        k = k or self.cfg.top_k_default
+        # reuse the standard search pipeline to get top-k facts
+        res = self.search(query, user_id=user_id, agent_id=agent_id,
+                           run_id=run_id, k=k)
+        facts = res.facts
+        if not facts:
+            return {"preamble": "(no facts in memory)",
+                    "fact_ids": [], "hrr_b64": None,
+                    "n_facts": 0, "roles_present": []}
+        try:
+            from cortexm.vsa.working_memory import build_holographic_wm
+            vsa = getattr(self.palace, "vsa", None) or \
+                self._init_vsa_for_wm()
+            hwm = build_holographic_wm(facts, vsa, self.palace.embedder,
+                                         max_facts=k)
+            d = hwm.to_dict_with_vec()
+            d["query"] = query
+            d["user_id"] = user_id
+            return d
+        except Exception as e:
+            # fall back to the textual context block if HRR build fails
+            return {"preamble": res.context_block,
+                    "fact_ids": [f.id for f in facts],
+                    "hrr_b64": None, "n_facts": len(facts),
+                    "roles_present": [], "error": str(e)}
+
+    def _init_vsa_for_wm(self):
+        """Lazy VSA init for working memory if palace doesn't expose one."""
+        from cortexm.vsa.ops import VSA
+        return VSA(dims=self.cfg.dims, mode=self.cfg.vsa_mode,
+                   seed=self.cfg.seed,
+                   lexical_lambda=self.cfg.lexical_lambda)
+
+    def hologram_extract(self, hrr_b64: str, role: str,
+                         *, candidate_ids: list[str],
+                         user_id: str = "default") -> list[dict]:
+        """Unbind a role from a holographic WM vector and return top-k matches.
+
+        Used by agents that received a working-memory hologram and want
+        to recall a specific fact slot. Pure HRR algebra — μ=0.
+        """
+        try:
+            from cortexm.vsa.working_memory import (
+                HolographicWM, extract_from_hologram, _vec_from_b64)
+            import numpy as np
+            hrr = _vec_from_b64(hrr_b64)
+            # fetch candidate facts and compute their embeddings
+            facts = self.store.get_facts(candidate_ids)
+            facts = [f for f in facts if f and f.is_active]
+            if not facts:
+                return []
+            cand_ids = [f.id for f in facts]
+            # embed the role-specific component of each fact
+            texts = []
+            for f in facts:
+                if role == "S":
+                    texts.append(f.subject or "")
+                elif role == "R":
+                    texts.append((f.relation or "").replace("_", " "))
+                elif role == "V":
+                    texts.append(f.value or "")
+                else:
+                    texts.append("")
+            embs = np.stack([self.palace.embedder.embed(t) for t in texts])
+            vsa = getattr(self.palace, "vsa", None) or \
+                self._init_vsa_for_wm()
+            hwm = HolographicWM(hrr=hrr, n_facts=len(cand_ids),
+                                 roles_present={role}, fact_ids=cand_ids,
+                                 preamble="")
+            hits = extract_from_hologram(hwm, role, None, vsa,
+                                          embs, cand_ids, top_k=3)
+            return [{"id": fid, "score": round(s, 4)} for fid, s in hits]
+        except Exception as e:
+            return [{"error": str(e)}]
+
+    # ------------------------------------------------------------- format
+    def _context_block(self, query: str, intent: str, facts: list[Fact],
+                       scores: dict, notes: list[str] | None = None) -> str:
+        # Route through the swappable decoder (default = LLMPromptDecoder
+        # preserves the original "[Memory — Known facts]" block format).
+        # Callers can swap via reader.with_decoder("rdf" | "datalog" | "json")
+        # to serve non-LLM workloads from the SAME retrieval pipeline.
+        return self._decoder.render(
+            query=query, intent=intent, facts=facts,
+            scores=scores or {}, notes=notes, store=self.store)
+
+    def _provenance(self, query: str, facts: list[Fact],
+                    vsa_scores: dict | None = None) -> dict:
+        chain = []
+        for f in facts[:12]:
+            chunk = self.store.get_chunk(f.source_id) if f.source_id else None
+            chain.append({
+                "fact_id": f.id,
+                "triple": f.display(),
+                "vsa_score": round(vsa_scores.get(f.id, 0.0), 4)
+                if vsa_scores else None,
+                "source_hash": f.source_hash,
+                "source_verified": bool(chunk and chunk["hash"] == f.source_hash),
+                "source_text": (chunk["text"][:160] if chunk else None),
+                "valid_from": f.valid_from, "valid_to": f.valid_to,
+                "tx_from": f.tx_from,
+                "confidence": f.confidence,
+            })
+        return {"query": query, "chain": chain,
+                "verification": all(c["source_verified"] for c in chain)}