superlocalmemory 3.6.23 → 3.7.0

package/src/superlocalmemory/core/store_pipeline.py

@@ -12,6 +12,7 @@ Part of Qualixar | Author: Varun Pratap Bhardwaj
 from __future__ import annotations
 
 import logging
+import json
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
@@ -181,6 +182,13 @@ def run_store(
     auto_linker: Any = None,
     context_generator: Any = None,
     consolidation_engine: Any = None,
+    existing_memory_id: str | None = None,
+    queryable_fact_ids: tuple[str, ...] = (),
+    trusted_actor_id: str = "",
+    pre_authorized: bool = False,
+    ingestion_source_type: str = "store",
+    ingestion_operation_id: str = "",
+    derivation_report: dict[str, bool] | None = None,
 ) -> list[str]:
     """Store content and extract structured facts. Returns fact_ids.
 
@@ -190,11 +198,15 @@ def run_store(
     # Pre-operation hooks (trust gate, ABAC, rate limiter)
     hook_ctx = {
         "operation": "store",
-        "agent_id": metadata.get("agent_id", "unknown") if metadata else "unknown",
+        "agent_id": (
+            trusted_actor_id
+            or (metadata.get("agent_id", "unknown") if metadata else "unknown")
+        ),
         "profile_id": profile_id,
         "content_preview": content[:100],
     }
-    hooks.run_pre("store", hook_ctx)
+    if not pre_authorized:
+        hooks.run_pre("store", hook_ctx)
 
     if entropy_gate and not entropy_gate.should_pass(content):
         return []
@@ -216,19 +228,65 @@ def run_store(
     parser = temporal_parser or TemporalParser()
     parsed_date = parser.parse_session_date(session_date) if session_date else None
 
-    record = MemoryRecord(
-        profile_id=profile_id, content=content,
-        session_id=session_id, speaker=speaker, role=role,
-        session_date=parsed_date, metadata=metadata or {},
-        scope=scope, shared_with=shared_with,
-    )
-    db.store_memory(record)
+    queryable_ids = frozenset(queryable_fact_ids)
+    queryable_facts: list[AtomicFact] = []
+    if existing_memory_id:
+        memory_rows = db.execute(
+            "SELECT * FROM memories WHERE memory_id=?",
+            (existing_memory_id,),
+        )
+        if not memory_rows:
+            raise ValueError("queryable ingestion memory does not exist")
+        memory = dict(memory_rows[0])
+        if memory["profile_id"] != profile_id:
+            raise ValueError("queryable ingestion memory profile mismatch")
+        if memory["content"] != content:
+            raise ValueError("queryable ingestion memory content mismatch")
+        stored_shared = json.loads(memory.get("shared_with") or "null")
+        if (memory.get("scope") or "personal") != scope:
+            raise ValueError("queryable ingestion memory scope mismatch")
+        if (stored_shared or None) != (shared_with or None):
+            raise ValueError("queryable ingestion shared scope mismatch")
+        queryable_facts = db.get_facts_by_ids(list(queryable_ids), profile_id)
+        if len(queryable_facts) != len(queryable_ids):
+            raise ValueError("queryable ingestion fact profile mismatch or missing fact")
+        if any(fact.memory_id != existing_memory_id for fact in queryable_facts):
+            raise ValueError("queryable ingestion fact belongs to another memory")
+        record = MemoryRecord(
+            memory_id=existing_memory_id,
+            profile_id=profile_id,
+            content=content,
+            session_id=memory.get("session_id") or session_id,
+            speaker=memory.get("speaker") or speaker,
+            role=memory.get("role") or role,
+            session_date=memory.get("session_date") or parsed_date,
+            created_at=memory["created_at"],
+            metadata=json.loads(memory.get("metadata_json") or "{}"),
+            scope=scope,
+            shared_with=shared_with,
+        )
+    else:
+        record = MemoryRecord(
+            profile_id=profile_id, content=content,
+            session_id=session_id, speaker=speaker, role=role,
+            session_date=parsed_date, metadata=metadata or {},
+            scope=scope, shared_with=shared_with,
+        )
+        db.store_memory(record)
+
+    extraction_complete = False
+    consolidation_complete = consolidator is not None
+    canonicalization_complete = entity_resolver is not None
+    graph_complete = graph_builder is not None
+    temporal_complete = True
+    provenance_complete = provenance is not None
 
     try:
         facts = fact_extractor.extract_facts(
             turns=[content], session_id=session_id,
             session_date=parsed_date, speaker_a=speaker,
         )
+        extraction_complete = facts is not None
     except Exception as _extract_exc:
         # P0-1 (remember-write-04): an extractor EXCEPTION (transient LLM/embed
         # backend error) must NOT orphan the already-committed memory. The None
@@ -256,7 +314,8 @@ def run_store(
     # V3.3.20: Stronger verbatim filter — skip greetings, filler, short phrases.
     # Verbatim facts with just "Hey! How are you?" dilute embeddings and add noise.
     _MIN_VERBATIM_WORDS = 8
-    if (content.strip()
+    if (not queryable_facts
+            and content.strip()
             and len(content.strip()) >= 40
             and len(content.strip().split()) >= _MIN_VERBATIM_WORDS):
         import uuid
@@ -285,6 +344,19 @@ def run_store(
         if verbatim.content.strip().lower() not in extracted_texts:
             facts.append(verbatim)
 
+    if queryable_facts:
+        # Replace any extractor-produced copy of the complete raw turn with the
+        # already-queryable projection, then promote that stable fact ID in
+        # place.  Large inputs may have a clamped queryable projection, so the
+        # projection itself is authoritative for the verbatim retrieval unit.
+        raw_text = content.strip().lower()
+        facts = [
+            fact for fact in facts
+            if fact.content.strip().lower() != raw_text
+            and fact.fact_id not in queryable_ids
+        ]
+        facts.extend(queryable_facts)
+
     # V3.3.21: If fact extraction produced nothing (short input like "this is test"),
     # store the raw content as a minimal fact. User explicitly called `slm remember` —
     # their data should NEVER be silently dropped. The min-length and min-word filters
@@ -319,9 +391,39 @@ def run_store(
             temporal_parser=temporal_parser,
         )
 
+        is_queryable_promotion = fact.fact_id in queryable_ids
+        if is_queryable_promotion:
+            db.update_fact(fact.fact_id, {
+                "content": fact.content,
+                "fact_type": fact.fact_type,
+                "entities_json": fact.entities,
+                "canonical_entities_json": fact.canonical_entities,
+                "observation_date": fact.observation_date,
+                "referenced_date": fact.referenced_date,
+                "interval_start": fact.interval_start,
+                "interval_end": fact.interval_end,
+                "confidence": fact.confidence,
+                "importance": fact.importance,
+                "evidence_count": fact.evidence_count,
+                "access_count": fact.access_count,
+                "source_turn_ids_json": fact.source_turn_ids,
+                "session_id": fact.session_id,
+                "embedding": fact.embedding,
+                "fisher_mean": fact.fisher_mean,
+                "fisher_variance": fact.fisher_variance,
+                "lifecycle": fact.lifecycle,
+                "langevin_position": fact.langevin_position,
+                "emotional_valence": fact.emotional_valence,
+                "emotional_arousal": fact.emotional_arousal,
+                "signal_type": fact.signal_type,
+            })
         if consolidator:
             try:
-                action = consolidator.consolidate(fact, profile_id)
+                action = consolidator.consolidate(
+                    fact,
+                    profile_id,
+                    exclude_fact_ids=queryable_ids,
+                )
             except Exception as _consolidate_exc:
                 # P0-1 (remember-write-03): a consolidate failure (e.g. LLM
                 # timeout) must NOT orphan the already-committed memory. Fall
@@ -331,19 +433,31 @@ def run_store(
                     "consolidate() failed for fact %s — storing raw fact as "
                     "fallback: %s", fact.fact_id, _consolidate_exc,
                 )
+                consolidation_complete = False
                 action = None
 
             if action is not None:
                 if action.action_type.value == "noop":
-                    continue
+                    # A canonical ingestion projection already exists before
+                    # enrichment. Reconcile it against pre-existing facts and
+                    # remove it when consolidation proves it is a duplicate.
+                    target_id = action.existing_fact_id
+                    if is_queryable_promotion and target_id:
+                        db.delete_fact(fact.fact_id)
+                    existing_fact = db.get_fact(target_id) if target_id else None
+                    if existing_fact is None:
+                        continue
+                    fact = existing_fact
 
                 # Opinion confidence tracking: reinforce or decay
                 if fact.fact_type == FactType.OPINION and action.action_type.value == "update":
                     try:
-                        existing = db.get_fact(action.new_fact_id)
+                        existing = db.get_fact(
+                            action.existing_fact_id or action.new_fact_id
+                        )
                         if existing and existing.fact_type == FactType.OPINION:
                             new_conf = min(1.0, existing.confidence + 0.1)
-                            db.update_fact(action.new_fact_id, {"confidence": new_conf})
+                            db.update_fact(existing.fact_id, {"confidence": new_conf})
                     except Exception:
                         pass
                 elif fact.fact_type == FactType.OPINION and action.action_type.value == "supersede":
@@ -358,35 +472,37 @@ def run_store(
                         pass
 
                 if action.action_type.value in ("update", "supersede"):
-                    updated_fact = db.get_fact(action.new_fact_id)
-                    if updated_fact:
-                        # P1-2 (embeddings-vector-01): the merged/superseding
-                        # fact must reach the vector store (embed on-demand if
-                        # it has none) — otherwise it is invisible to the
-                        # semantic channel despite living in atomic_facts.
-                        _upsert_fact_vectors(
-                            updated_fact, profile_id, ann_index, vector_store, embedder,
+                    target_id = (
+                        (action.existing_fact_id or action.new_fact_id)
+                        if action.action_type.value == "update"
+                        else action.new_fact_id
+                    )
+                    if is_queryable_promotion and target_id != fact.fact_id:
+                        db.delete_fact(fact.fact_id)
+                    updated_fact = db.get_fact(target_id)
+                    if updated_fact is None:
+                        raise RuntimeError(
+                            f"consolidation {action.action_type.value} produced "
+                            f"missing fact {target_id}"
                         )
-                        if graph_builder:
-                            graph_builder.build_edges(updated_fact, profile_id)
-                        if observation_builder:
-                            for eid in updated_fact.canonical_entities:
-                                observation_builder.update_profile(
-                                    eid, updated_fact, profile_id,
-                                )
-                    stored_ids.append(action.new_fact_id)
-                    continue
+                    # Continue through the shared index/graph/temporal/
+                    # provenance stages.  The previous early continue made
+                    # UPDATE/SUPERSEDE facts look stored while skipping half of
+                    # canonical materialization.
+                    fact = updated_fact
                 # ADD case: consolidator already stored the fact (F8 fix)
                 # Fall through to post-processing below
             else:
                 # Consolidate failed → store the raw fact ourselves so the
                 # memory is never left without a retrievable fact, then fall
                 # through to post-processing (embeddings, graph, context).
-                db.store_fact(fact)
-        else:
+                if not is_queryable_promotion:
+                    db.store_fact(fact)
+        elif not is_queryable_promotion:
             db.store_fact(fact)
 
-        stored_ids.append(fact.fact_id)
+        if fact.fact_id not in stored_ids:
+            stored_ids.append(fact.fact_id)
 
         # Dual-write embedding to ANN index + vector store (embed on-demand if
         # a consolidated ADD fact arrived without one). See _upsert_fact_vectors.
@@ -461,6 +577,7 @@ def run_store(
                         len(invalidations), fact.fact_id,
                     )
             except Exception as exc:
+                temporal_complete = False
                 logger.debug(
                     "Temporal validation skipped for fact %s: %s",
                     fact.fact_id, exc,
@@ -488,6 +605,8 @@ def run_store(
                 event = TemporalEvent(
                     profile_id=profile_id, entity_id=eid,
                     fact_id=fact.fact_id,
+                    scope=fact.scope,
+                    shared_with=fact.shared_with,
                     observation_date=fact.observation_date,
                     referenced_date=fact.referenced_date,
                     interval_start=fact.interval_start,
@@ -506,6 +625,8 @@ def run_store(
                     profile_id=profile_id,
                     entity_id=sig.get("entity_id", ""),
                     fact_id=fact.fact_id,
+                    scope=fact.scope,
+                    shared_with=fact.shared_with,
                     interval_start=sig.get("start_time"),
                     interval_end=sig.get("end_time"),
                     description=sig.get("description", ""),
@@ -525,12 +646,12 @@ def run_store(
                 provenance.record(
                     fact_id=fact.fact_id,
                     profile_id=profile_id,
-                    source_type="store",
-                    source_id=session_id,
-                    created_by=speaker or "unknown",
+                    source_type=ingestion_source_type,
+                    source_id=ingestion_operation_id or session_id,
+                    created_by=trusted_actor_id or speaker or "unknown",
                 )
             except Exception:
-                pass
+                provenance_complete = False
 
     logger.info("Stored %d facts (session=%s)", len(stored_ids), session_id)
 
@@ -539,6 +660,16 @@ def run_store(
     hook_ctx["fact_count"] = len(stored_ids)
     hooks.run_post("store", hook_ctx)
 
+    if derivation_report is not None:
+        derivation_report.update({
+            "extraction": extraction_complete,
+            "canonicalization": canonicalization_complete,
+            "consolidation": consolidation_complete,
+            "graph": graph_complete,
+            "temporal": temporal_complete,
+            "provenance": provenance_complete,
+        })
+
     # Phase 5: Step-count trigger for lightweight consolidation (L7)
     if consolidation_engine is not None:
         try:
@@ -602,8 +733,6 @@ def run_store_fact_direct(
         )
         fact.canonical_entities = list(canonical.values())
     db.store_fact(fact)
-    # v3.4.5: Incremental sync to CozoDB/LanceDB (F-04)
-    _sync_to_graph_backends(fact)
     if fact.embedding and ann_index:
         ann_index.add(fact.fact_id, fact.embedding)
     # V3.2: VectorStore upsert (dual-write)
@@ -615,6 +744,9 @@ def run_store_fact_direct(
         )
     if graph_builder:
         graph_builder.build_edges(fact, profile_id)
+    # The graph projection must run after GraphBuilder: syncing immediately
+    # after SQLite fact insertion omitted every new fact edge from Cozo.
+    _sync_to_graph_backends(fact)
     # BM25 indexing
     bm25 = getattr(retrieval_engine, '_bm25', None) if retrieval_engine else None
     if bm25:

package/src/superlocalmemory/core/tier_manager.py

@@ -29,6 +29,11 @@ import logging
 from datetime import datetime, timedelta, UTC
 from typing import TYPE_CHECKING
 
+from superlocalmemory.core.lifecycle_state import (
+    reconcile_profile_lifecycle,
+    set_fact_lifecycle_zone,
+)
+
 if TYPE_CHECKING:
     from superlocalmemory.storage.database import DatabaseManager
 
@@ -77,6 +82,10 @@ def evaluate_tiers(
         "total_evaluated": 0,
     }
 
+    # Repair any rows written by pre-V3.7 split lifecycle paths before making
+    # new transition decisions.
+    reconcile_profile_lifecycle(db, profile_id)
+
     now = datetime.now(UTC)
     pinned_ids = _get_pinned_fact_ids(db, profile_id)
 
@@ -126,13 +135,12 @@ def promote_on_access_batch(db: DatabaseManager, fact_ids: list[str]) -> int:
     """
     if not fact_ids:
         return 0
-    placeholders = ",".join("?" * len(fact_ids))
-    db.execute(
-        f"UPDATE atomic_facts SET lifecycle = 'active' "
-        f"WHERE fact_id IN ({placeholders}) AND lifecycle IN ('warm', 'cold')",
-        tuple(fact_ids),
+    return set_fact_lifecycle_zone(
+        db,
+        fact_ids,
+        "active",
+        from_atomic=("warm", "cold"),
     )
-    return len(fact_ids)
 
 
 def promote_on_access(db: DatabaseManager, fact_id: str) -> None:
@@ -140,10 +148,11 @@ def promote_on_access(db: DatabaseManager, fact_id: str) -> None:
 
     Kept for backward compatibility. Prefer promote_on_access_batch.
     """
-    db.execute(
-        "UPDATE atomic_facts SET lifecycle = 'active' "
-        "WHERE fact_id = ? AND lifecycle IN ('warm', 'cold')",
-        (fact_id,),
+    set_fact_lifecycle_zone(
+        db,
+        [fact_id],
+        "active",
+        from_atomic=("warm", "cold"),
     )
 
 
@@ -164,10 +173,8 @@ def pin_fact(
             "(fact_id, profile_id, pinned_at, reason) VALUES (?, ?, ?, ?)",
             (fact_id, profile_id, now, reason),
         )
-        db.execute(
-            "UPDATE atomic_facts SET lifecycle = 'active' "
-            "WHERE fact_id = ? AND profile_id = ?",
-            (fact_id, profile_id),
+        set_fact_lifecycle_zone(
+            db, [fact_id], "active", profile_id=profile_id,
         )
         return True
     except Exception as exc:
@@ -315,11 +322,12 @@ def _demote_tier(
         # Batch UPDATE in chunks of 500
         for i in range(0, len(demoted_ids), 500):
             batch = demoted_ids[i:i + 500]
-            placeholders = ",".join("?" * len(batch))
-            db.execute(
-                f"UPDATE atomic_facts SET lifecycle = ? "
-                f"WHERE fact_id IN ({placeholders}) AND lifecycle = ?",
-                (to_tier, *batch, from_tier),
+            set_fact_lifecycle_zone(
+                db,
+                batch,
+                to_tier,
+                profile_id=profile_id,
+                from_atomic=(from_tier,),
             )
 
     return len(demoted_ids)
@@ -444,6 +452,10 @@ def _sync_tiers_to_backends(
 
     if _lancedb_backend and hasattr(_lancedb_backend, "bulk_update_tiers_from_sqlite"):
         try:
-            _lancedb_backend.bulk_update_tiers_from_sqlite(db.conn)
+            # DatabaseManager intentionally has no public `.conn`; use its
+            # transaction boundary so tier synchronization cannot silently
+            # fail after a scale projection has been promoted.
+            with db.raw_connection() as conn:
+                _lancedb_backend.bulk_update_tiers_from_sqlite(conn)
         except Exception as exc:
             logger.warning("LanceDB tier sync failed: %s", exc)

package/src/superlocalmemory/core/worker_pool.py

@@ -101,12 +101,21 @@ class WorkerPool:
         })
 
     def delete_memory(self, fact_id: str, agent_id: str = "system") -> dict:
-        """Delete a specific memory by fact_id. Logged for audit."""
-        return self._send({"cmd": "delete_memory", "fact_id": fact_id, "agent_id": agent_id})
+        """Delete by fact ID; ``agent_id`` is untrusted audit metadata."""
+        return self._send({
+            "cmd": "delete_memory",
+            "fact_id": fact_id,
+            "source_agent_id": agent_id,
+        })
 
     def update_memory(self, fact_id: str, content: str, agent_id: str = "system") -> dict:
-        """Update content of a specific memory. Logged for audit."""
-        return self._send({"cmd": "update_memory", "fact_id": fact_id, "content": content, "agent_id": agent_id})
+        """Update content; ``agent_id`` is untrusted audit metadata."""
+        return self._send({
+            "cmd": "update_memory",
+            "fact_id": fact_id,
+            "content": content,
+            "source_agent_id": agent_id,
+        })
 
     def get_memory_facts(self, memory_id: str) -> dict:
         """Get original memory text + child atomic facts."""

package/src/superlocalmemory/dynamics/activation_guided_quantization.py

@@ -22,7 +22,7 @@ HR-05: All SQL uses parameterized queries.
 HR-07: No-op when config.enabled=False.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/dynamics/eap_scheduler.py

@@ -22,7 +22,7 @@ HR-03: Original float32 NEVER deleted unless keep_float32_backup=False
 HR-04: Quantization ONLY via EAP scheduler (not ad-hoc).
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations
@@ -96,7 +96,7 @@ class EAPScheduler:
         self._quantized_store = quantized_store
         self._config = config
 
-    def run_eap_cycle(self, profile_id: str) -> dict:
+    def run_eap_cycle(self, profile_id: str, *, dry_run: bool = False) -> dict:
         """Execute one EAP cycle for a profile.
 
         Steps:
@@ -153,12 +153,16 @@ class EAPScheduler:
 
             if target_bw == 0:
                 # Forgotten -- mark as deleted
-                self._handle_deletion(fact_id, profile_id)
+                if not dry_run:
+                    self._handle_deletion(fact_id, profile_id)
                 stats["deleted"] += 1
                 continue
 
             if target_bw < current_bw:
                 # Downgrade -- compress to lower precision
+                if dry_run:
+                    stats["downgrades"] += 1
+                    continue
                 success = self._handle_downgrade(
                     fact_id, profile_id, target_bw,
                 )
@@ -168,6 +172,9 @@ class EAPScheduler:
                     stats["errors"] += 1
             else:
                 # Upgrade -- restore to higher precision (only if float32 exists)
+                if dry_run:
+                    stats["upgrades"] += 1
+                    continue
                 success = self._handle_upgrade(
                     fact_id, profile_id, target_bw,
                 )

package/src/superlocalmemory/dynamics/ebbinghaus_langevin_coupling.py

@@ -21,7 +21,7 @@ Mathematical formulation:
   weight_combined = w_fisher * w_ebbinghaus
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/dynamics/fisher_langevin_coupling.py

@@ -27,7 +27,7 @@ Mathematical formulation:
 Adapted: uses Langevin position radius for lifecycle zone classification.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/encoding/auto_linker.py

@@ -14,7 +14,7 @@ Responsibilities:
 4. decay_unused(): Weight decay for stale edges
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations

package/src/superlocalmemory/encoding/cognitive_consolidator.py

@@ -34,7 +34,7 @@ References:
   TurboQuant (ICLR 2026). Recursive polar quantization.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 IP Novelty: 92% (no prior art for retention-gated consolidation + polar quantization)
 """
 
@@ -741,13 +741,13 @@ class CognitiveConsolidator:
             cluster_id=cluster.cluster_id,
         )
 
-        # Archive source facts (HR-04: soft-archive, never delete)
+        # Archive source facts (HR-04: soft-archive, never delete) through the
+        # lifecycle invariant writer.
+        from superlocalmemory.core.lifecycle_state import set_fact_lifecycle_zone
+        set_fact_lifecycle_zone(
+            self._db, cluster.fact_ids, "archive", profile_id=profile_id,
+        )
         for fact_id in cluster.fact_ids:
-            self._db.execute(
-                "UPDATE atomic_facts SET lifecycle = 'archived' "
-                "WHERE fact_id = ? AND profile_id = ?",
-                (fact_id, profile_id),
-            )
             # Log access event
             self._db.execute(
                 "INSERT INTO fact_access_log "
@@ -756,15 +756,6 @@ class CognitiveConsolidator:
                 "VALUES (?, ?, ?, datetime('now'), 'consolidation', 'ccq')",
                 (_new_id(), fact_id, profile_id),
             )
-            # Update fact_retention zone
-            self._db.execute(
-                "UPDATE fact_retention "
-                "SET lifecycle_zone = 'archive', "
-                "    last_computed_at = datetime('now') "
-                "WHERE fact_id = ? AND profile_id = ?",
-                (fact_id, profile_id),
-            )
-
         return block_id
 
     # ------------------------------------------------------------------

package/src/superlocalmemory/encoding/consolidator.py

@@ -13,7 +13,7 @@ Mode A: keyword-based contradiction detection (zero LLM).
 Mode B/C: LLM-assisted contradiction detection when available.
 
 Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: Elastic-2.0
+License: AGPL-3.0-or-later
 """
 
 from __future__ import annotations
@@ -100,13 +100,26 @@ class MemoryConsolidator:
     # -- Public API ---------------------------------------------------------
 
     def consolidate(
-        self, new_fact: AtomicFact, profile_id: str,
+        self,
+        new_fact: AtomicFact,
+        profile_id: str,
+        *,
+        exclude_fact_ids: set[str] | frozenset[str] | None = None,
     ) -> ConsolidationAction:
         """Consolidate *new_fact* against existing knowledge.
 
         Returns a ``ConsolidationAction`` describing what was done.
+
+        ``exclude_fact_ids`` is reserved for an ingestion operation's own
+        queryable projection.  That projection is evidence being promoted,
+        not pre-existing knowledge, and must not suppress its derived facts as
+        near-duplicates.
         """
-        candidates = self._find_candidates(new_fact, profile_id)
+        candidates = self._find_candidates(
+            new_fact,
+            profile_id,
+            exclude_fact_ids=exclude_fact_ids,
+        )
 
         if not candidates:
             return self._execute_add(new_fact, profile_id, reason="no matching facts")
@@ -168,7 +181,11 @@ class MemoryConsolidator:
     # -- Candidate search ---------------------------------------------------
 
     def _find_candidates(
-        self, new_fact: AtomicFact, profile_id: str,
+        self,
+        new_fact: AtomicFact,
+        profile_id: str,
+        *,
+        exclude_fact_ids: set[str] | frozenset[str] | None = None,
     ) -> list[tuple[AtomicFact, float]]:
         """Find and score candidate matches from existing facts.
 
@@ -178,7 +195,7 @@ class MemoryConsolidator:
 
         Returns sorted list of (fact, combined_score), descending.
         """
-        seen_ids: set[str] = set()
+        seen_ids: set[str] = set(exclude_fact_ids or ())
         candidate_facts: list[AtomicFact] = []
 
         # --- entity-based candidates ---