cortexm 0.6.0__tar.gz → 0.6.1__tar.gz

{cortexm-0.6.0 → cortexm-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexm
-Version: 0.6.0
+Version: 0.6.1
 Summary: Deterministic agent memory. 96 bytes per fact. Zero LLM at ingest.
 Author: Context-M Contributors
 License-Expression: Apache-2.0

{cortexm-0.6.0 → cortexm-0.6.1}/cortexm/__init__.py

@@ -18,7 +18,7 @@ Plugin kernel:            ``from cortexm import Context, mount_default``
 
 from __future__ import annotations
 
-__version__ = "0.6.0"
+__version__ = "0.6.1"
 
 # μ=0 protocol counter: number of LLM invocations used by this process.
 # The BEAM-honest protocol requires this to stay 0 during ingest & retrieval.

{cortexm-0.6.0 → cortexm-0.6.1}/cortexm/api/memory.py

@@ -1030,6 +1030,41 @@ class Memory:
         self.palace.close()
         self.store.close()
 
+    # ------------------------------------------------------------------
+    # v0.6.1: BM25 + index maintenance facade
+    # Exposed on Memory so users can call ``m.tune_bm25(k1=1.2, b=0.5)``
+    # and ``m.optimize_index()`` without reaching into the verbatim
+    # plugin. If the verbatim tier isn't mounted (e.g. disabled in
+    # Config), these are no-ops so callers don't need to defensively
+    # check.
+    def tune_bm25(self, k1: float = 1.2, b: float = 0.75) -> None:
+        """Tune BM25 k1 (term saturation) + b (length normalization).
+
+        Lucene defaults: k1=1.2, b=0.75. Our corpus (short chat chunks,
+        avg ~12 tokens) tends to prefer slightly higher saturation and
+        weaker length norm; the v0.6.0 defaults were k1=1.5, b=0.75.
+        Run ``scripts/tune_bm25_canonical.py`` to grid-search on the
+        canonical LongMemEval sample and pick the best for your data.
+
+        Takes effect on the next ``search()`` call.
+        """
+        if self._verbatim is not None:
+            self._verbatim.tune_bm25(k1=k1, b=b)
+        # Persist on the config too so reopens honor the tuning.
+        self.config.bm25_k1 = k1
+        self.config.bm25_b = b
+
+    def optimize_index(self) -> dict:
+        """VACUUM + FTS5 optimize + WAL checkpoint.
+
+        Run this after large bulk ingests to fold the WAL back into
+        the main .db file, reclaim deleted-page space, and merge the
+        FTS5 b-tree segments. Idempotent; safe to call any time.
+        """
+        if self._verbatim is not None:
+            return self._verbatim.optimize_index()
+        return {"optimized": False, "reason": "verbatim tier not mounted"}
+
     def _reopen(self) -> None:
         """Rebind every component to a freshly-opened store (post-restore)."""
         from cortexm.security.pii import PIIGuard, PIIVault

{cortexm-0.6.0 → cortexm-0.6.1}/cortexm/bridge/patterns.py

@@ -156,7 +156,8 @@ def _works(m, ctx, sp, ts, sent):
 
 
 @pattern("joined_org",
-         rf"\bi\s+(?:joined|started(?:\s+working)?\s+at|got a job at|moved to a job at)\s+{WORK_AT}")
+         rf"\bi\s+(?:(?:just|finally|recently|recently\s+just)?\s+)?"
+         rf"(?:joined|started(?:\s+working)?\s+at|got a job at|moved to a job at)\s+{WORK_AT}")
 def _joined(m, ctx, sp, ts, sent):
     v = clean_value(m.group("val"))
     return [Candidate("SELF", "works_at", v, 0.92, "joined_org",
@@ -389,6 +390,22 @@ def _pet(m, ctx, sp, ts, sent):
                       0.88, "pet")]
 
 
+# v0.6.1: "my dog's name is Charlie" / "my dog is named Charlie" /
+# "my dog is called Charlie" — the apostrophe-s + "name is" surface form
+# (LongMemEval canonical Q). The base _pet pattern above requires the
+# is-named/called verb form; this pattern catches the possessive variant.
+@pattern("pet_named",
+         rf"\bmy\s+(?P<kind>dog|cat|bird|rabbit)"
+         rf"(?:'s\s+(?:name\s+is|is\s+named|is\s+called)"
+         rf"|\s+is\s+(?:named|called))"
+         rf"\s+(?P<val>{NAME})")
+def _pet_named(m, ctx, sp, ts, sent):
+    return [Candidate(
+        "SELF", "has_pet",
+        f"{m.group('kind')} named {clean_value(m.group('val'))}",
+        0.88, "pet_named")]
+
+
 @pattern("hobby", rf"\bmy hobby is\s+(?P<val>[a-z][a-z ]{{2,40}})|\bin my free time\s+i\s+(?P<val2>[a-z][a-z ]{{2,40}})")
 def _hobby(m, ctx, sp, ts, sent):
     v = clean_value(m.group("val") or m.group("val2") or "")

{cortexm-0.6.0 → cortexm-0.6.1}/cortexm/bridge/reader.py

@@ -841,6 +841,19 @@ class MemoryReader:
             if tc_notes:
                 notes = (notes or []) + tc_notes
 
+        # v0.6.1: Negation-aware retrieval. If the user ingested a
+        # negation like "I don't eat meat", the reader surfaces it
+        # here so the judge sees the explicit "No — they stated..."
+        # signal BEFORE any positive fact lookup. μ=0: pure content-
+        # word overlap (cortexm.bridge.negation.is_negation_overlap).
+        if getattr(self.cfg, "negation_indexing_enabled", True):
+            try:
+                neg_notes = self._negation_notes(query, user_id)
+                if neg_notes:
+                    notes = (neg_notes if not notes else notes + neg_notes)
+            except Exception:
+                pass
+
         # --- 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
@@ -1410,6 +1423,35 @@ class MemoryReader:
                 notes.append("\n".join(lines))
         return notes
 
+    # ------------------------------------------------------- negation lookup
+    def _negation_notes(self, query: str, user_id: str) -> list[str]:
+        """Surface ingested negations that overlap the query.
+
+        The writer wrote sentences like ``"I don't eat meat"`` into
+        ``negation_records`` (see writer._store_negations). When the
+        user later asks ``"Do I eat meat?"``, we want the judge to
+        see the explicit "No — they stated..." signal. μ=0: pure
+        content-word overlap (≥2 shared content words) so we never
+        spuriously suppress a real positive answer.
+        """
+        try:
+            from cortexm.bridge.negation import is_negation_overlap
+            records = self.store.query_negation_records(user_id=user_id)
+            if not records:
+                return []
+            notes: list[str] = []
+            for rec in records:
+                if not is_negation_overlap(query, rec):
+                    continue
+                marker = rec.get("marker", "")
+                sentence = rec.get("sentence", "")
+                notes.append(
+                    f"NEGATION: user stated — \"{sentence}\" "
+                    f"(marker={marker!r})")
+            return notes
+        except Exception:
+            return []
+
     # ------------------------------------------------------------- symbolic
     def _symbolic_query(self, plan: QueryPlan, user_id, agent_id, run_id,
                         scope, k, query):

{cortexm-0.6.0 → cortexm-0.6.1}/cortexm/bridge/synonyms.py

@@ -122,6 +122,22 @@ DEFAULT_CLUSTERS: Dict[str, List[str]] = {
         "grandfather", "grandmother", "grandparent",
         "uncle", "aunt", "cousin", "nephew", "niece",
     ],
+    # MEDICAL — surface-form variants of the same "this user has X"
+    # statement. Each phrase means the user carries a diagnosis or
+    # condition. The rewriter emits one expansion per variant so a
+    # query phrased as "Does Alice have diabetes?" surfaces chunks
+    # like "Alice was diagnosed with diabetes" or "Alice has the
+    # condition diabetes". μ=0: pure phrase substitution, no NER.
+    "medical": [
+        "diagnosed with", "diagnosed as", "diagnosed as having",
+        "has condition", "has the condition", "has a condition of",
+        "has been diagnosed with", "was diagnosed with",
+        "received a diagnosis of", "diagnosis of",
+        "suffers from", "suffering from", "afflicted with",
+        "has been treated for", "under treatment for",
+        "on medication for", "prescribed for",
+        "history of", "family history of",  # weak variants — match
+    ],
 }
 
 

{cortexm-0.6.0 → cortexm-0.6.1}/cortexm/bridge/writer.py

@@ -15,6 +15,7 @@ from datetime import datetime, timezone
 from cortexm import metrics
 from cortexm.bridge.extractor import Extractor
 from cortexm.bridge.patterns import ExtractionContext
+from cortexm.bridge.negation import extract_with_negation
 from cortexm.config import Config
 from cortexm.security.injection import scan as injection_scan
 from cortexm.security.injection import contagion_scan
@@ -147,6 +148,57 @@ class MemoryWriter:
         if text not in corpus:
             corpus.append(text)
 
+    # ------------------------------------------------------------------
+    def _store_negations(self, *, text: str, user_id: str,
+                        session_id: str | None,
+                        source_tx_id: str | None,
+                        agent_id: str | None = None,
+                        created_at: datetime | None = None) -> int:
+        """μ=0 negation routing.
+
+        Splits the text into non-negated + negated sentences
+        (cortexm.bridge.negation.extract_with_negation) and writes
+        each negated sentence into the ``negation_records`` table
+        on the trace store. Returns the number of negation rows
+        written (best-effort: never blocks ingest).
+
+        v0.6.1 wiring: this is the follow-up the v0.6.0 detector
+        was waiting for. Before this, the extractor saw
+        ``"I don't eat meat"`` and, if a pattern fired before the
+        negation was checked, mis-extracted ``(+user, eats, meat)``
+        as a positive fact — the reader then hallucinated "Yes"
+        from the very text that denied it.
+        """
+        if not getattr(self.cfg, "negation_indexing_enabled", True):
+            return 0
+        try:
+            split = extract_with_negation(text)
+            negs = split["negations"]
+            if not negs:
+                return 0
+            ts_s = iso(created_at) if created_at else iso(_now())
+            src_hash = self.store.hasher.hash_text(text)
+            n = 0
+            for rec in negs:
+                self.store.insert_negation_record(
+                    user_id=user_id,
+                    sentence=rec.get("sentence", ""),
+                    marker=rec.get("marker", ""),
+                    implied_subject=rec.get("implied_subject", "") or "",
+                    agent_id=agent_id,
+                    session_id=session_id,
+                    source_tx_id=str(source_tx_id) if source_tx_id is not None else None,
+                    source_hash=src_hash,
+                    created_at=ts_s,
+                )
+                n += 1
+            return n
+        except Exception as e:
+            # best-effort — never block the write path
+            import sys as _sys
+            print(f"[negation] store failed: {e}", file=_sys.stderr)
+            return 0
+
     # ------------------------------------------------------------------
     def _unmess_cache(self) -> dict:
         """Lazy-init the unmess (idiolect + dissim) cache on this writer.
@@ -225,6 +277,27 @@ class MemoryWriter:
                 session_id=run_id or agent_id or user_id,
                 source_tx_id=_src_tx_id,
                 agent_id=agent_id)
+            # v0.6.1: split negated sentences out BEFORE the extractor
+            # runs. The negated sentences go into a separate
+            # ``negation_records`` table (so the reader can return
+            # "No — explicitly stated" later); the extractor now sees
+            # only the non-negated portion, which kills the
+            # "I don't eat meat" → (+user, eats, meat) mis-extraction.
+            # Best-effort: on any failure we fall back to the raw text
+            # so the write path is never blocked.
+            try:
+                if getattr(self.cfg, "negation_indexing_enabled", True):
+                    neg_split = extract_with_negation(text)
+                    self._store_negations(
+                        text=text, user_id=user_id,
+                        session_id=run_id or agent_id or user_id,
+                        source_tx_id=str(_src_tx_id) if _src_tx_id is not None else None,
+                        agent_id=agent_id, created_at=msg_time)
+                    extraction_text = neg_split["positive_text"] or text
+                else:
+                    extraction_text = text
+            except Exception:
+                extraction_text = text
             verdict = injection_scan(text, self.cfg.quarantine_injection)
             if not verdict.quarantined and self.cfg.quarantine_contagion:
                 cv = contagion_scan(text, self._tainted_corpus(user_id),
@@ -249,8 +322,8 @@ class MemoryWriter:
             # The extractor's internal Bitap trigger widening handles
             # misspelled trigger words. When unmess is OFF (bench baseline
             # config), we run the raw text through the extractor unchanged.
-            clauses = self._unmess_text(text, user_id) \
-                if self.cfg.unmess_enabled else [text]
+            clauses = self._unmess_text(extraction_text, user_id) \
+                if self.cfg.unmess_enabled else [extraction_text]
 
             candidates = []
             for clause in clauses:
@@ -425,6 +498,56 @@ class MemoryWriter:
         self.store.end_batch()
         return derived
 
+    # ------------------------------------------------------------------
+    def _max_vsa_overlap(self, fact: Fact, user_id: str) -> float:
+        """Shannon tiered storage: compute the max cosine similarity
+        of this fact's VSA hologram vs. existing facts in the user's
+        scope. Returns 0.0 on cold-start (<shannon_min_facts facts)
+        or any failure. μ=0: deterministic cosine over the user's
+        palace vectors; no LLM, no statistics.
+
+        Used to gate ``palace.add()`` in the COMMIT/COEXIST and
+        SUPERSEDE branches of ``_apply_decision``. If the overlap
+        is above ``shannon_overlap_threshold`` (default 0.9), we
+        store the structured fact + chunk + edges (still findable
+        by BM25 + symbolic query) but SKIP the VSA palace.add — the
+        holographic superposition stays clean and retrieval stays
+        fast. Verbatim tier is unchanged; "doesn't forget" holds.
+        """
+        if not getattr(self.cfg, "shannon_tiered_storage", True):
+            return 0.0
+        try:
+            existing = self.store.query_facts(
+                user_id=user_id, active=True, limit=500)
+            if len(existing) < int(getattr(
+                    self.cfg, "shannon_min_facts", 10)):
+                return 0.0  # cold-start: not enough signal yet
+            new_vec = self.palace.encode_fact(fact)
+            best = 0.0
+            # Scan in chunks of 64 to bound memory on the 4GB box.
+            for f in existing:
+                # Skip self (in case fact is already partially committed)
+                if f.id == fact.id:
+                    continue
+                try:
+                    # encode each existing fact once and cosine-compare
+                    ev = self.palace.encode_fact(f)
+                    # cosine via dot product on normalized vectors
+                    a = new_vec.ravel()
+                    b = ev.ravel()
+                    na = float((a @ a) ** 0.5) or 1.0
+                    nb = float((b @ b) ** 0.5) or 1.0
+                    sim = float((a @ b) / (na * nb))
+                    if sim > best:
+                        best = sim
+                        if best >= 0.99:
+                            break  # near-identical — no need to scan more
+                except Exception:
+                    continue
+            return best
+        except Exception:
+            return 0.0
+
     # ------------------------------------------------------------------
     def _apply_decision(self, fact: Fact, decision, commit, chunk_id,
                         results) -> int:
@@ -478,14 +601,47 @@ class MemoryWriter:
                     reason=f"superseded: {decision.note}")
             self.store.insert_fact(fact, commit)
             self.store.add_edge(fact.id, chunk_id, "EXTRACTED_FROM")
-            self.palace.add(fact.id, self.palace.encode_fact(fact))
-            results.append(self._result(fact, "SUPERSEDED", decision.note))
+            # v0.6.1: Shannon tiered storage. For SUPERSEDE we usually
+            # palace.add (the new fact is the canonical value now).
+            # But if the new fact has high VSA overlap to existing
+            # memory, skip the palace.add — the holographic signal
+            # is already there.
+            overlap = self._max_vsa_overlap(fact, fact.user_id or "default")
+            if overlap > float(getattr(self.cfg, "shannon_overlap_threshold", 0.9)):
+                fact.provenance = {
+                    **fact.provenance,
+                    "shannon_tier": "verbatim_only",
+                    "shannon_overlap": round(overlap, 3),
+                }
+                results.append(self._result(
+                    fact, "SUPERSEDED",
+                    f"{decision.note}; shannon_tier=verbatim_only "
+                    f"(overlap={overlap:.3f})"))
+            else:
+                self.palace.add(fact.id, self.palace.encode_fact(fact))
+                results.append(self._result(fact, "SUPERSEDED", decision.note))
             return 1
         # COMMIT / COEXIST
         self.store.insert_fact(fact, commit)
         self.store.add_edge(fact.id, chunk_id, "EXTRACTED_FROM")
-        self.palace.add(fact.id, self.palace.encode_fact(fact))
-        results.append(self._result(fact, "ADD", decision.note))
+        # v0.6.1: Shannon tiered storage. For brand-new COMMIT/COEXIST
+        # facts, check VSA overlap before adding the hologram. High
+        # overlap (≥0.9) → store the fact + chunk + edges but skip
+        # palace.add (verbatim tier still catches exact-match via BM25).
+        overlap = self._max_vsa_overlap(fact, fact.user_id or "default")
+        if overlap > float(getattr(self.cfg, "shannon_overlap_threshold", 0.9)):
+            fact.provenance = {
+                **fact.provenance,
+                "shannon_tier": "verbatim_only",
+                "shannon_overlap": round(overlap, 3),
+            }
+            results.append(self._result(
+                fact, "ADD",
+                f"shannon_tier=verbatim_only "
+                f"(overlap={overlap:.3f}; verbatim tier still findable)"))
+        else:
+            self.palace.add(fact.id, self.palace.encode_fact(fact))
+            results.append(self._result(fact, "ADD", decision.note))
         return 1
 
     # ------------------------------------------------------------------

{cortexm-0.6.0 → cortexm-0.6.1}/cortexm/config.py

@@ -399,6 +399,24 @@ class Config:
     # (Config.labse_enabled) handles the embedding for non-English text.
     multilingual_routing_enabled: bool = True
 
+    # Shannon entropy-weighted storage (tiered precision compromise).
+    # Pure entropy filter — "skip storing redundant facts" — violates
+    # the "doesn't forget" promise: a fact with VSA overlap > 0.9 to
+    # existing memory gets dropped, and later you ask "what's my
+    # dog's name?" and the system has forgotten. The safer compromise
+    # is TIERED PRECISION: store the verbatim chunk + structured fact
+    # (still findable by BM25 + symbolic query) but SKIP the VSA
+    # palace.add for high-overlap facts. This deduplicates the
+    # holographic superposition (smaller palace = faster retrieval)
+    # without losing any information.
+    #
+    # Cold-start guard: skip the overlap check until the user has at
+    # least ``shannon_min_facts`` facts (default 10) so the first few
+    # noisy facts don't get spuriously tiered-down.
+    shannon_tiered_storage: bool = True
+    shannon_overlap_threshold: float = 0.9
+    shannon_min_facts: int = 10
+
     # IR fundamentals (Lucene/Solr-grade primitives). See
     # cortexm/bridge/ir_pro.py for the implementations.
     #   * query_cache: LRU on (query, user_id, k) — invalidated on add()

{cortexm-0.6.0 → cortexm-0.6.1}/cortexm/plugins/verbatim.py

@@ -334,35 +334,44 @@ class VerbatimPlugin:
         # expansion, so the existing BM25 + cosine path is preserved
         # (additive). Expansions run additional BM25 passes; results
         # are unioned by rowid with dedup.
-        queries = [query]
-        if self.query_rewrite_enabled:
-            if self._query_rewriter is None:
-                from cortexm.bridge.query_rewrite import QueryRewriter
-                self._query_rewriter = QueryRewriter(
-                    max_expansions=self.max_expansions)
-            try:
-                queries = self._query_rewriter.rewrite(query)
-            except Exception:
-                queries = [query]  # rewriter failure → fall back to original
-
-        # Run the existing search path on the FIRST query (original).
-        # Then for any additional expansions, run BM25-only and append
-        # new rowids to the result pool. The dense cosine path runs
-        # once on the original query (cheaper, and the fused score is
-        # most meaningful for the original query embedding).
+        #
+        # v0.6.1: LAZY expansion. The QueryRewriter adds ~2–4ms to every
+        # search() call. The 95% of queries that hit on the first try
+        # don't need expansion. So we try the original query FIRST; only
+        # if it returns empty do we fall back to the rewritten variants.
+        # This restores the v0.5.x 1.6ms read p50 for the common case
+        # while keeping the v0.6.0 synonym/FST/slang safety net for the
+        # long-tail paraphrase queries.
         primary = self._search_single(
-            query=queries[0], user_id=user_id, k=k,
+            query=query, user_id=user_id, k=k,
             session_id=session_id, agent_id=agent_id)
-        if len(queries) <= 1:
+        if primary or not self.query_rewrite_enabled:
+            if self.query_cache_enabled:
+                self._query_cache.put(cache_key, primary)
+            return primary
+        # Primary returned empty — fall back to expansions
+        if self._query_rewriter is None:
+            from cortexm.bridge.query_rewrite import QueryRewriter
+            self._query_rewriter = QueryRewriter(
+                max_expansions=self.max_expansions)
+        try:
+            queries = self._query_rewriter.rewrite(query)
+        except Exception:
+            queries = [query]
+        # Drop the original (already tried); expansions only
+        if queries and queries[0] == query:
+            queries = queries[1:]
+        if not queries:
             if self.query_cache_enabled:
                 self._query_cache.put(cache_key, primary)
             return primary
         # Additional expansions: BM25-only, dedup against primary rowids
+        # (primary is empty here, but keep the guard for safety)
         seen_rowids = {h.chunk_id for h in primary}
         extra: list = []
         # Cap total candidates at 2*k so the union stays bounded.
         budget = max(0, 2 * k - len(primary))
-        for q in queries[1:budget + 1]:
+        for q in queries[:budget + 1]:
             if budget <= 0:
                 break
             extra_hits = self._bm25_only(

cortexm-0.6.1/cortexm/trace/contradictions.py

@@ -0,0 +1,126 @@
+"""Deterministic contradiction detection & truth maintenance.
+
+Phase rules from Section 1.1:
+  1. Classification      — relation → semantic category, single/multi valued
+  2. Contradiction       — exact + fuzzy (Jaccard/Levenshtein) match on
+                           subject-relation pairs; latest-value-wins for
+                           single-valued relations, append for multi-valued
+  3. Interference-aware lifecycle — see lifecycle.py
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from cortexm.trace.fact import Fact, SINGLE_VALUED
+from cortexm.trace.store import TraceStore
+from cortexm.util import similarity
+
+
+# v0.6.1: relation-name aliasing. The extractor emits several surface
+# relations that all mean the same semantic thing:
+#   * moved_to / relocated_to / shifted_to — all "where the user lives"
+#   * joined / started_at / got_job_at    — all "where the user works"
+# Without this map, "I moved to Berlin" (moved_to) and "I live in Munich"
+# (lives_in) sit in DIFFERENT relation slots, so find_conflicts treats
+# them as unrelated facts — the bi-temporal SUPERSEDE chain never fires
+# and the reader answers "Berlin AND Munich" instead of "Munich (latest)".
+# μ=0: a static dict. No model, no inference.
+RELATION_ALIASES: dict[str, str] = {
+    # residence cluster
+    "moved_to": "lives_in",
+    "relocated_to": "lives_in",
+    "shifted_to": "lives_in",
+    "based_in": "lives_in",
+    # employment cluster
+    "started_at": "works_at",
+    "joined": "works_at",
+    "got_job_at": "works_at",
+    "hired_at": "works_at",
+    # education cluster (aliasing 'study_at' / 'enrolled_at' to 'studies_at')
+    "study_at": "studies_at",
+    "enrolled_at": "studies_at",
+}
+
+
+def canonical_relation(relation: str) -> str:
+    """Return the canonical relation name. Used by find_conflicts and
+    the reader's symbolic query path so alias-of-alias queries land in
+    the same bucket. Falls through unchanged for relations without an
+    alias."""
+    return RELATION_ALIASES.get(relation, relation)
+
+
+class Action(str, Enum):
+    COMMIT = "commit"          # brand-new fact
+    MERGE = "merge"            # near-duplicate: reinforce existing
+    SUPERSEDE = "supersede"    # contradiction on single-valued relation
+    COEXIST = "coexist"        # contradiction on multi-valued relation
+    SKIP = "skip"              # exact duplicate
+
+
+@dataclass
+class Conflict:
+    action: Action
+    existing: list[Fact]
+    note: str = ""
+
+
+def find_conflicts(store: TraceStore, candidate: Fact) -> Conflict:
+    """Decide how ``candidate`` interacts with active memory.
+
+    v0.6.1: relation aliasing. Before querying for existing facts on
+    the same (subject, relation) we look up the canonical relation
+    so a ``moved_to = Berlin`` candidate sees the prior ``lives_in =
+    Munich`` and fires SUPERSEDE (not COEXIST-unknown).
+    """
+    canon_rel = canonical_relation(candidate.relation)
+    # Look up BOTH the candidate's literal relation AND the canonical
+    # form — older facts may be stored under either name. We union the
+    # two queries so a partial migration (some facts pre-aliasing, some
+    # post-) still resolves correctly.
+    matching: list[Fact] = []
+    for rel in {candidate.relation, canon_rel}:
+        matching.extend(
+            f for f in store.query_facts(
+                subject=candidate.subject, relation=rel,
+                user_id=candidate.user_id, active=True)
+            if f.id != candidate.id)
+    # de-dup by fact id (a fact stored under the canonical rel could
+    # appear in both queries if candidate.relation == canon_rel)
+    seen_ids: set[str] = set()
+    existing: list[Fact] = []
+    for f in matching:
+        if f.id in seen_ids:
+            continue
+        seen_ids.add(f.id)
+        existing.append(f)
+    if not existing:
+        return Conflict(Action.COMMIT, [])
+
+    exact = [f for f in existing if f.value.strip().lower() == candidate.value.strip().lower()]
+    if exact:
+        return Conflict(Action.SKIP, exact, "exact duplicate")
+
+    # low-salience mention anchors: exact-dup semantics only (no fuzzy
+    # quadratic scans — mention streams are high-volume, low-signal)
+    if candidate.relation in ("mentioned", "event", "instruction"):
+        if candidate.relation == "mentioned":
+            return Conflict(Action.COEXIST, existing, "mention anchor recorded")
+
+    near = [f for f in existing
+            if similarity(f.value, candidate.value) >= 0.92]
+    if near:
+        return Conflict(Action.MERGE, near, "near-duplicate merged; reinforcement +1")
+
+    # SINGLE_VALUED is keyed by canonical relation name; check both
+    single = (candidate.relation in SINGLE_VALUED
+              or canon_rel in SINGLE_VALUED)
+    if single:
+        # newest valid_from wins reality; old fact gets valid_to
+        target = max(existing, key=lambda f: (f.valid_from, f.tx_from))
+        return Conflict(Action.SUPERSEDE, [target],
+                        f"contradiction on single-valued '{canon_rel}'")
+    return Conflict(Action.COEXIST, existing,
+                    f"conflicting values on multi-valued '{canon_rel}' coexist")

{cortexm-0.6.0 → cortexm-0.6.1}/cortexm/trace/rules.py

@@ -132,7 +132,18 @@ class RuleEngine:
         Derived facts inherit the USER SCOPE of their premises — without
         this, ``team_uses(X, L) :- member_of(X, T), uses(T, L)`` derives a
         fact under ``default`` that user0's reader can never see (scope
-        filter drops it), silently losing every multi-hop answer."""
+        filter drops it), silently losing every multi-hop answer.
+
+        v0.6.1 fix: the dedup check now looks at ALL facts (active OR
+        retired) with the same (subject, relation, value, scope). Before
+        this, the rule ``lives_in(X, C) :- moved_to(X, C)`` would re-
+        derive ``lives_in=Berlin`` AFTER the candidate ``lives_in=Munich``
+        fired SUPERSEDE on it — because the retired Berlin fact was
+        invisible to ``active=True`` filter and the rule happily re-
+        created it, undoing the supersession. With this fix, once a
+        (subject, relation, value) tuple has been derived (and possibly
+        later retired by a SUPERSEDE), the rule won't re-materialize it.
+        """
         now = now or _dt.datetime.now(_dt.timezone.utc)
         derived_new: list[Fact] = []
         seen: set[tuple] = set()
@@ -149,8 +160,12 @@ class RuleEngine:
                     if key in seen:
                         continue
                     seen.add(key)
-                    if self.store.query_facts(subject=s, relation=rel, value=v,
-                                              user_id=scope, active=True):
+                    # v0.6.1: dedup against ALL facts (active OR retired)
+                    # — re-deriving a fact that was just superseded
+                    # would silently undo the supersession.
+                    if self.store.query_facts(subject=s, relation=rel,
+                                              value=v, user_id=scope,
+                                              active=None):
                         continue
                     f = Fact(
                         id=new_id(), subject=s, relation=rel, value=v,