cortexm 0.3.0__py3-none-any.whl

cortexm/bridge/dates.py

@@ -0,0 +1,178 @@
+"""Deterministic date-expression resolution (μ=0 temporal parsing).
+
+Extracts absolute and relative date expressions from text, resolved
+against the conversation timestamp — the substrate for bi-temporal
+valid times and BEAM temporal-reasoning abilities.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta
+
+from cortexm.util import month_name, month_number
+
+MONTH_RE = r"(?:January|February|March|April|May|June|July|August|September|October|November|December)"
+
+ABS_PATTERNS = [
+    # March 3, 2024 / March 3rd 2024 / March 3, 2024
+    (re.compile(rf"\b(?:on\s+)?({MONTH_RE})\.?\s+(\d{{1,2}})(?:st|nd|rd|th)?,?\s+(\d{{4}})\b", re.I), "day"),
+    # 3 March 2024
+    (re.compile(rf"\b(\d{{1,2}})(?:st|nd|rd|th)?\s+(?:of\s+)?({MONTH_RE})\.?,?\s+(\d{{4}})\b", re.I), "day_r"),
+    # March 3 (no year — assume year of context ts, prefer past)
+    (re.compile(rf"\b(?:on\s+)?({MONTH_RE})\.?\s+(\d{{1,2}})(?:st|nd|rd|th)?\b(?!\s*,?\s*\d{{4}})", re.I), "day_noyear"),
+    # March 2024 (month granularity)
+    (re.compile(rf"\bin\s+({MONTH_RE})\.?,?\s+(\d{{4}})\b", re.I), "month"),
+    (re.compile(rf"\b({MONTH_RE})\s+(\d{{4}})\b"), "month"),
+    # 2025-08-15 (ISO day)
+    (re.compile(r"\b(\d{4})-(\d{2})-(\d{2})\b"), "iso_day"),
+    # 2025-08 / 2025/08 / "2025 08" (numeric year-month; before bare year)
+    (re.compile(r"\b(\d{4})[-/ ](\d{1,2})\b"), "ym_num"),
+    (re.compile(r"\bin\s+(\d{4})\b"), "year"),
+]
+
+REL_PATTERNS = [
+    (re.compile(r"\byesterday\b", re.I), "yesterday"),
+    (re.compile(r"\b(today|this morning|right now)\b", re.I), "today"),
+    (re.compile(r"\btomorrow\b", re.I), "tomorrow"),
+    (re.compile(r"\blast\s+night\b", re.I), "yesterday"),
+    (re.compile(rf"\blast\s+({MONTH_RE})\b", re.I), "last_month"),
+    (re.compile(r"\blast\s+week\b", re.I), "last_week"),
+    (re.compile(r"\blast\s+month\b", re.I), "last_month_rel"),
+    (re.compile(r"\blast\s+year\b", re.I), "last_year"),
+    (re.compile(r"\b(\d+|a|an|one|two|three|four|five|six|few|several|couple)\s+(day|week|month|year)s?\s+ago\b", re.I), "ago"),
+    (re.compile(rf"\b(?:in|since)\s+({MONTH_RE})\b(?!\s*,?\s*\d{{4}})", re.I), "this_year_month"),
+    (re.compile(r"\bsince\s+(\d{4})\b"), "year"),
+]
+
+WEEKDAYS = ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"]
+LAST_WEEKDAY = re.compile(rf"\blast\s+({'|'.join(WEEKDAYS)})\b", re.I)
+
+
+def _month_num(name: str) -> int:
+    return month_number(name)
+
+
+def _mk(year: int, month: int, day: int) -> str:
+    return f"{year:04d}-{month:02d}-{day:02d}"
+
+
+def resolve_relative(label: str, m: re.Match, ts: datetime) -> tuple[str, str] | None:
+    """Return (iso_date, surface) for a relative expression."""
+    g = m.group(0).lower()
+    if label == "yesterday":
+        d = ts - timedelta(days=1)
+        return _mk(d.year, d.month, d.day), g
+    if label == "today":
+        return _mk(ts.year, ts.month, ts.day), g
+    if label == "tomorrow":
+        d = ts + timedelta(days=1)
+        return _mk(d.year, d.month, d.day), g
+    if label == "last_week":
+        d = ts - timedelta(days=7)
+        return _mk(d.year, d.month, d.day), g
+    if label == "last_month_rel":
+        d = ts.replace(day=1) - timedelta(days=1)
+        return _mk(d.year, d.month, 1), g
+    if label == "last_year":
+        return _mk(ts.year - 1, 1, 1), g
+    if label == "last_month":
+        mm = _month_num(m.group(1))
+        y = ts.year if mm <= ts.month else ts.year - 1
+        return _mk(y, mm, 1), g
+    if label == "ago":
+        raw = m.group(1).lower()
+        words = {"a": 1, "an": 1, "one": 1, "two": 2, "three": 3,
+                 "four": 4, "five": 5, "six": 6, "few": 3, "several": 4,
+                 "couple": 2}
+        n = words.get(raw, 1) if not raw.isdigit() else int(raw)
+        unit = m.group(2).lower()
+        if unit.startswith("day"):
+            d = ts - timedelta(days=n)
+        elif unit.startswith("week"):
+            d = ts - timedelta(weeks=n)
+        elif unit.startswith("month"):
+            d = ts.replace(day=1)
+            for _ in range(n):
+                d = (d.replace(day=1) - timedelta(days=1)).replace(day=1)
+            return _mk(d.year, d.month, d.day), g
+        else:
+            return _mk(ts.year - n, ts.month, ts.day), g
+        return _mk(d.year, d.month, d.day), g
+    if label == "this_year_month":
+        mm = _month_num(m.group(1))
+        y = ts.year if mm <= ts.month else ts.year - 1
+        return _mk(y, mm, 1), g
+    if label == "year":
+        return f"{m.group(1)}-01-01", g
+    return None
+
+
+def find_dates(text: str, ts: datetime) -> list[dict]:
+    """All date expressions: [{span, iso, surface, granularity}]."""
+    out: list[dict] = []
+    taken: list[tuple[int, int]] = []
+
+    def overlaps(s, e):
+        return any(not (e <= a or s >= b) for a, b in taken)
+
+    for rx, label in ABS_PATTERNS:
+        for m in rx.finditer(text):
+            if overlaps(m.start(), m.end()):
+                continue
+            try:
+                if label == "day":
+                    mo, d, y = _month_num(m.group(1)), int(m.group(2)), int(m.group(3))
+                elif label == "day_r":
+                    d, mo, y = int(m.group(1)), _month_num(m.group(2)), int(m.group(3))
+                elif label == "day_noyear":
+                    mo, d = _month_num(m.group(1)), int(m.group(2))
+                    y = ts.year if (mo, d) <= (ts.month, ts.day) else ts.year - 1
+                elif label == "year":
+                    y = int(m.group(1))
+                    mo, d = 1, 1
+                elif label == "iso_day":
+                    y, mo, d = int(m.group(1)), int(m.group(2)), int(m.group(3))
+                elif label == "ym_num":
+                    y, mo = int(m.group(1)), int(m.group(2))
+                    if not 1 <= mo <= 12:  # not a month — e.g. "2025 30"
+                        continue
+                    d = 1
+                else:  # month
+                    mo, y = _month_num(m.group(1)), int(m.group(2))
+                    d = 1
+                iso = _mk(y, mo, d)
+            except (ValueError, TypeError):
+                continue
+            out.append({"span": (m.start(), m.end()), "iso": iso,
+                        "surface": m.group(0), "granularity": label})
+            taken.append((m.start(), m.end()))
+
+    for rx, label in REL_PATTERNS:
+        for m in rx.finditer(text):
+            if overlaps(m.start(), m.end()):
+                continue
+            r = resolve_relative(label, m, ts)
+            if r:
+                iso, surface = r
+                out.append({"span": (m.start(), m.end()), "iso": iso,
+                            "surface": m.group(0), "granularity": label})
+                taken.append((m.start(), m.end()))
+
+    for m in LAST_WEEKDAY.finditer(text):
+        if overlaps(m.start(), m.end()):
+            continue
+        wd = WEEKDAYS.index(m.group(1).lower())
+        delta = (ts.weekday() - wd) % 7 or 7
+        d = ts - timedelta(days=delta)
+        out.append({"span": (m.start(), m.end()), "iso": _mk(d.year, d.month, d.day),
+                    "surface": m.group(0), "granularity": "weekday"})
+        taken.append((m.start(), m.end()))
+
+    out.sort(key=lambda d: d["span"][0])
+    return out
+
+
+def first_date(text: str, ts: datetime) -> str | None:
+    ds = find_dates(text, ts)
+    return ds[0]["iso"] if ds else None

cortexm/bridge/decoders.py

@@ -0,0 +1,204 @@
+"""Swappable retrieval decoders — NSR-inspired (ESWEEK24).
+
+arXiv insight: the VSA core is task-agnostic; only the decoder
+changes. Context-M's reader was hardcoded to format facts for an LLM
+prompt (the `_context_block` method). This module extracts that
+formatter into a pluggable decoder interface so the SAME palace + Trace
+can serve multiple output formats:
+
+    - LLMPromptDecoder   — current behavior, formats facts as a
+                            "[Memory — Known facts]" block for LLM
+                            context-stuffing
+    - RDFDecoder         — export facts as RDF/N3 triples for external
+                            graph DBs (SPARQL queryable)
+    - DatalogDecoder     — emit facts as Datalog clauses for the
+                            contradiction engine to consume
+    - JSONDecoder        — return facts as plain JSON for API responses
+
+All decoders take the same inputs (query, facts, scores, notes,
+store) and return a string. The reader picks one via
+`reader.with_decoder(decoder)` or by passing `decoder=` to .search().
+The default remains LLMPromptDecoder so existing callers don't break.
+
+Why this matters: the palace / Trace substrate is now reusable for
+non-LLM workloads (RDF export, contradiction proofs, audit JSON)
+without duplicating the retrieval pipeline.
+"""
+from __future__ import annotations
+
+import json
+from typing import Iterable, Protocol
+
+
+class Decoder(Protocol):
+    """Pluggable retrieval-output decoder.
+
+    A decoder takes the post-fusion fact list + scores + procedural
+    notes and renders them in a domain-specific format. The reader
+    pipeline (intent plan → palace search → fusion → notes) is
+    identical across decoders — only the output shape changes.
+    """
+    name: str
+
+    def render(self, *, query: str, intent: str, facts: list,
+               scores: dict, notes: list[str] | None,
+               store=None) -> str: ...
+
+
+# ---------- LLM prompt decoder (current behavior) ----------------------
+
+class LLMPromptDecoder:
+    """Format facts as a context block for LLM context-stuffing.
+
+    This is the original reader._context_block output. Kept verbatim
+    so existing prompts continue to work.
+    """
+    name = "llm_prompt"
+
+    def render(self, *, query, intent, facts, scores, notes, store=None) -> str:
+        lines = ["[Memory — Known facts]"]
+        if not facts and not notes:
+            lines.append("(no verified facts found for this query)")
+        for f in facts:
+            chunk = store.get_chunk(f.source_id) if (
+                store and f.source_id) else None
+            snippet = ""
+            if chunk:
+                snippet = chunk["text"].replace("\n", " ")[:80]
+                if len(chunk["text"]) > 80:
+                    snippet += "..."
+            lines.append(
+                f"- {f.display()} [valid {f.valid_window()}; "
+                f"learned {f.tx_from[:10]}; conf {f.confidence:.2f}; "
+                f"id {f.id[:8]}; src #{f.source_hash[:8]}; \"{snippet}\"]")
+        for n in (notes or []):
+            lines.append(f"- {n}")
+        return "\n".join(lines)
+
+
+# ---------- RDF / N3 decoder ------------------------------------------
+
+class RDFDecoder:
+    """Export facts as RDF/N3 triples.
+
+    Format: <subject> <relation> <value> .
+    Subjects/values are URI-escaped; string literals quoted. Useful
+    for piping Context-M's verified facts into an external graph DB
+    (e.g. Apache Jena, BlazeGraph) for SPARQL queries.
+
+    NOTE: namespaces are bare (no @prefix). Callers can post-process
+    to add prefix declarations if desired.
+    """
+    name = "rdf"
+
+    def render(self, *, query, intent, facts, scores, notes, store=None) -> str:
+        out: list[str] = []
+        for f in facts:
+            out.append(f"{self._term(f.subject)} "
+                       f"{self._term(f.relation)} "
+                       f"{self._term(f.value)} .")
+        if notes:
+            for n in notes:
+                out.append(f"# note: {n}")
+        return "\n".join(out)
+
+    @staticmethod
+    def _term(s: str) -> str:
+        # bare URI if alnum+CWD, else quoted literal
+        if not s:
+            return '""'
+        # treat CamelCase / dotted names as URIs in the local : namespace
+        if all(c.isalnum() or c in "._-:/" for c in s) and not s[0].isdigit():
+            return f":{s}"
+        # quoted literal with N3 escapes
+        return '"' + s.replace('"', '\\"') + '"'
+
+
+# ---------- Datalog decoder -------------------------------------------
+
+class DatalogDecoder:
+    """Emit facts as Datalog clauses for the contradiction engine.
+
+    Format: relation(subject, value).
+    Used by the contradiction / lifecycle engines to reason over
+    verified facts as logic predicates. The current Trace.rules
+    engine already speaks this dialect — this decoder exposes the
+    same format for external callers.
+    """
+    name = "datalog"
+
+    def render(self, *, query, intent, facts, scores, notes, store=None) -> str:
+        out: list[str] = []
+        for f in facts:
+            out.append(f"{f.relation}({self._atom(f.subject)}, "
+                       f"{self._atom(f.value)}).")
+        if notes:
+            for n in notes:
+                out.append(f"% note: {n}")
+        return "\n".join(out)
+
+    @staticmethod
+    def _atom(s: str) -> str:
+        # Datalog atom — lowercase, spaces → underscores
+        if not s:
+            return "_"
+        a = s.lower().replace(" ", "_").replace("-", "_")
+        # quote if starts with digit or contains non-atom chars
+        if a[0].isdigit() or not all(c.isalnum() or c == "_" for c in a):
+            return f'"{s}"'
+        return a
+
+
+# ---------- JSON decoder ----------------------------------------------
+
+class JSONDecoder:
+    """Return facts as a JSON array of triples.
+
+    Each entry: {subject, relation, value, valid_from, valid_to,
+    confidence, id, score}. Used by REST API responses and by
+    audit / federation tools that consume structured facts.
+    """
+    name = "json"
+
+    def render(self, *, query, intent, facts, scores, notes, store=None) -> str:
+        out: list[dict] = []
+        for f in facts:
+            out.append({
+                "subject": f.subject,
+                "relation": f.relation,
+                "value": f.value,
+                "valid_from": f.valid_from,
+                "valid_to": f.valid_to,
+                "tx_from": f.tx_from,
+                "confidence": round(f.confidence, 4),
+                "id": f.id,
+                "score": round(scores.get(f.id, 0.0), 4) if scores else None,
+            })
+        if notes:
+            out.append({"_notes": notes})
+        return json.dumps(out, default=str, indent=2)
+
+
+# ---------- Registry --------------------------------------------------
+
+DECODERS: dict[str, type] = {
+    "llm_prompt": LLMPromptDecoder,
+    "rdf": RDFDecoder,
+    "datalog": DatalogDecoder,
+    "json": JSONDecoder,
+}
+
+
+def get_decoder(name: str = "llm_prompt") -> "Decoder":
+    """Look up a decoder by name; raises ValueError for unknown names."""
+    cls = DECODERS.get(name)
+    if cls is None:
+        raise ValueError(
+            f"unknown decoder '{name}' — known: {list(DECODERS)}")
+    return cls()
+
+
+__all__ = [
+    "Decoder", "LLMPromptDecoder", "RDFDecoder", "DatalogDecoder",
+    "JSONDecoder", "DECODERS", "get_decoder",
+]

cortexm/bridge/enrich.py

@@ -0,0 +1,255 @@
+"""Async LLM enrichment fallback — graceful degradation off the μ=0 path.
+
+The μ=0 protocol guarantees the SYNCHRONOUS ingest path never calls an LLM.
+That determinism is the product's cost/speed moat, but 60 hand-written
+patterns will inevitably miss messy, indirect, or non-English phrasing.
+This module is the plan's acknowledged fallback: AFTER a chunk is stored
+(and its BLAKE3 hash sealed), chunks whose text yielded ZERO pattern
+candidates are queued for a second-pass LLM extraction. Enriched facts:
+
+  * carry provenance {"pattern": "llm_enrichment", "extractor_model": ...}
+    so every enriched fact is auditable and distinguishable from μ=0 facts;
+  * are confidence-capped (default 0.85) so deterministic facts always win
+    conflicts against enriched ones;
+  * still pass the full InjecMEM / MINJA quarantine + lifecycle pipeline;
+  * bump metrics.llm_calls so the μ=0 audit trail stays honest — an auditor
+    sees exactly which phase spent LLM budget.
+
+Usage (explicit, never automatic):
+    report = memory.enrich(user_id="alice")            # sync
+    report = memory.enrich_async(user_id="alice")      # background thread
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tempfile
+import threading
+from dataclasses import dataclass
+
+from cortexm import metrics
+from cortexm.bridge.patterns import Candidate
+from cortexm.bridge.writer import MemoryWriter
+from cortexm.util import normalize
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_REPO_ROOT = os.path.dirname(os.path.dirname(_HERE))  # .../context-m
+DEFAULT_EXTRACTOR_JS = os.path.join(_REPO_ROOT, "benchmarks", "llm",
+                                    "extract_facts.mjs")
+DEFAULT_NODE = os.environ.get("CORTEXM_NODE_BIN", "node")
+SDK_FALLBACKS = [
+    "/home/z/.bun/install/global/node_modules/z-ai-web-dev-sdk/dist/index.js",
+]
+
+ENRICH_CONFIDENCE_CAP = 0.85
+
+
+@dataclass
+class EnrichmentReport:
+    chunks_total: int = 0
+    chunks_eligible: int = 0        # zero pattern candidates
+    llm_calls: int = 0
+    llm_tokens: int = 0
+    facts_extracted: int = 0
+    facts_committed: int = 0
+    quarantined: int = 0
+    seconds: float = 0.0
+    extractor_model: str | None = None
+
+    def to_dict(self) -> dict:
+        return dict(self.__dict__)
+
+
+class NodeLLMExtractor:
+    """Subprocess bridge to benchmarks/llm/extract_facts.mjs (z-ai SDK).
+
+    Injectable and replaceable: tests pass a plain Python callable with the
+    same (texts, subjects) -> list[list[dict]] contract instead.
+    """
+
+    def __init__(self, script: str | None = None, concurrency: int = 4) -> None:
+        self.script = script or DEFAULT_EXTRACTOR_JS
+        self.concurrency = concurrency
+
+    def __call__(self, texts: list[str], subjects: list[str | None]) -> list[list[dict]]:
+        if not texts:
+            return []
+        items = [{"id": i, "text": t, "subject": s or None}
+                 for i, (t, s) in enumerate(zip(texts, subjects))]
+        with tempfile.TemporaryDirectory(prefix="cortexm-enrich-") as td:
+            inp = os.path.join(td, "in.jsonl")
+            outp = os.path.join(td, "out.jsonl")
+            with open(inp, "w", encoding="utf-8") as fh:
+                fh.writelines(json.dumps(it) + "\n" for it in items)
+            env = dict(os.environ)
+            env.setdefault("LLM_CONCURRENCY", str(self.concurrency))
+            env.setdefault("LLM_CACHE_DIR",
+                           os.path.join(_REPO_ROOT, "benchmarks", "llm", ".cache"))
+            proc = subprocess.run(
+                [DEFAULT_NODE, self.script, inp, outp, "--enrich"],
+                capture_output=True, text=True, timeout=1800, env=env)
+            if proc.returncode != 0 or not os.path.exists(outp):
+                raise RuntimeError(f"enrichment extractor failed: "
+                                   f"{proc.stderr[-500:]}")
+            rows = [json.loads(l) for l in open(outp, encoding="utf-8")
+                    if l.strip()]
+        rows.sort(key=lambda r: int(r.get("id", 0)))
+        out: list[list[dict]] = []
+        for r in rows:
+            facts = [f for f in (r.get("facts") or [])
+                     if isinstance(f, dict) and f.get("subject")
+                     and f.get("relation") and f.get("value")]
+            out.append(facts)
+        # keep alignment with input length
+        while len(out) < len(texts):
+            out.append([])
+        return out
+
+
+def _default_extractor():
+    return NodeLLMExtractor()
+
+
+def find_eligible_chunks(writer: MemoryWriter, user_id: str | None,
+                         limit: int | None = None) -> list[dict]:
+    """Chunks where the μ=0 extractor produced no REAL candidates.
+
+    Low-confidence ``mention_fallback`` mentions (pattern="mention_fallback",
+    conf 0.35) fire on almost any capitalized text — they are lexicon noise,
+    not signal. A chunk is enrichment-eligible only when no genuine pattern
+    matched, which is exactly the "pattern confidence dropped" condition the
+    strategic plan describes for the async LLM fallback.
+    """
+    from cortexm.bridge.patterns import ExtractionContext
+    from cortexm.bridge.extractor import Extractor
+
+    extractor = writer.extractor if hasattr(writer, "extractor") else Extractor(writer.cfg)
+    eligible: list[dict] = []
+    for chunk in writer.store.all_chunks(user_id):
+        ctx = ExtractionContext(
+            user_id=chunk.get("user_id") or "default",
+            agent_id=chunk.get("agent_id"), run_id=chunk.get("run_id"),
+            ts=_parse_ts(chunk.get("ts")),
+            speaker="assistant" if chunk.get("source") in ("assistant", "ai", "bot") else "user",
+            subject_name=writer._name_of(chunk.get("user_id") or "default"),
+            lexicon=writer._lexicon(chunk.get("user_id") or "default"))
+        try:
+            cands = extractor.extract(chunk["text"], ctx)
+            real = [c for c in cands if c.pattern != "mention_fallback"]
+        except Exception:
+            real = []
+        if not real and len(chunk["text"].strip()) >= 20:
+            eligible.append(chunk)
+            if limit and len(eligible) >= limit:
+                break
+    return eligible
+
+
+def _parse_ts(v):
+    if not v:
+        return None
+    from datetime import datetime, timezone
+    try:
+        return datetime.fromisoformat(v.replace("Z", "+00:00")) \
+            if isinstance(v, str) else v
+    except ValueError:
+        return None
+
+
+def enrich(writer: MemoryWriter, user_id: str | None = None, *,
+           extractor=None, limit: int | None = None,
+           min_confidence: float | None = None,
+           dry_run: bool = False) -> EnrichmentReport:
+    """Second-pass LLM extraction over zero-signal chunks. Explicit call."""
+    import time
+
+    t0 = time.time()
+    rep = EnrichmentReport()
+    eligible = find_eligible_chunks(writer, user_id, limit)
+    rep.chunks_total = len(writer.store.all_chunks(user_id))
+    rep.chunks_eligible = len(eligible)
+    if dry_run or not eligible:
+        rep.seconds = round(time.time() - t0, 3)
+        return rep
+
+    extractor = extractor or _default_extractor()
+    texts = [c["text"] for c in eligible]
+    subjects = [writer._name_of(c.get("user_id") or "default") for c in eligible]
+    batch = extractor(texts, subjects)
+    rep.llm_calls += 1
+    metrics.bump_llm_call()
+
+    cap = ENRICH_CONFIDENCE_CAP
+    floor = min_confidence if min_confidence is not None \
+        else writer.cfg.min_confidence
+
+    for chunk, facts in zip(eligible, batch):
+        model = None
+        uid = chunk.get("user_id") or "default"
+        # name learning from enriched facts: if the LLM spotted "my name
+        # is X" in text the patterns missed, later facts in this batch can
+        # be re-subjected to X so they align with query entities.
+        learned_name = None
+        for f in facts:
+            if str(f.get("relation", "")).lower() == "name" and f.get("value"):
+                learned_name = str(f["value"]).strip()
+                if writer._name_of(uid) is None and learned_name:
+                    writer._set_name(uid, learned_name)
+                break
+        subj_hint = learned_name or writer._name_of(uid) or uid
+        cands: list[Candidate] = []
+        for f in facts:
+            try:
+                conf = float(f.get("confidence", 0.7))
+            except (TypeError, ValueError):
+                conf = 0.7
+            conf = min(conf, cap)
+            if conf < floor:
+                continue
+            model = f.get("_model") or model
+            subj = str(f.get("subject") or "").strip()
+            # re-subject generic speaker labels to the learned persona name
+            # so enriched facts are findable by entity queries
+            if (not subj or subj.lower() in ("user", "the user", "speaker",
+                                             "i", "me")):
+                subj = subj_hint
+            cands.append(Candidate(
+                subject=subj[:80],
+                relation=_safe_relation(f["relation"]),
+                value=str(f["value"])[:160],
+                confidence=conf,
+                pattern="llm_enrichment"))
+        if not cands:
+            continue
+        n = writer.ingest_candidates(
+            cands, user_id=uid,
+            agent_id=chunk.get("agent_id"), chunk_id=chunk["id"],
+            ts=_parse_ts(chunk.get("ts")), source="llm-enrichment",
+            extractor_model=model)
+        rep.facts_extracted += len(cands)
+        rep.facts_committed += n
+    rep.extractor_model = getattr(extractor, "model_name", None)
+    rep.seconds = round(time.time() - t0, 3)
+    return rep
+
+
+def _safe_relation(rel) -> str:
+    r = normalize(str(rel)).replace(" ", "_").replace("-", "_")
+    return "".join(ch for ch in r if ch.isalnum() or ch == "_")[:40] or "related_to"
+
+
+def enrich_async(writer: MemoryWriter, user_id: str | None = None, **kw):
+    """Fire-and-forget background enrichment. Returns (thread, result holder)."""
+    holder: dict = {}
+
+    def _run():
+        try:
+            holder["report"] = enrich(writer, user_id, **kw)
+        except Exception as e:  # pragma: no cover - background guard
+            holder["error"] = str(e)
+
+    t = threading.Thread(target=_run, daemon=True, name="cortexm-enrich")
+    t.start()
+    return t, holder