lean-memory 0.1.0__py3-none-any.whl

lean_memory/extract/taxonomy.py

@@ -0,0 +1,244 @@
+"""Relation taxonomy + the pre-typing extraction `Candidate` — shared by Pass 2-4.
+
+This module is the small, dependency-light vocabulary that the Phase 1 hybrid
+extractor speaks. It pins down two things the spec (section 5) leans on:
+
+1. The **four-relation taxonomy** — `asserts | supersedes | extends | derives` —
+   our improvement over supermemory's `updates|extends|derives`. These are
+   *structural* edge types (how a new fact relates to an existing `(subject,
+   predicate)` slot), NOT domain predicates like `works_at`. The domain predicate
+   lives on `Fact.predicate`; the taxonomy relation governs *versioning behaviour*.
+
+     - `asserts`    — a new fact about a slot (no prior fact, or unrelated). Default.
+     - `supersedes` — new fact contradicts/replaces the object of an existing slot.
+                      Triggers versioning: old.valid_to / superseded_by / is_latest=0.
+     - `extends`    — new fact adds detail to the same slot WITHOUT contradiction
+                      (co-valid; both rows stay is_latest=1).
+     - `derives`    — inferential, cross-utterance. `is_inference=1`, and per the
+                      spec it is **LLM-only**: rules/GLiNER2 surface-form passes can
+                      never emit it, only the Pass 4 constrained-typing step can.
+
+2. The **`Candidate`** — the over-generated extraction unit BEFORE routing/typing.
+   It is the shared currency between Pass 2 (GLiNER2 generates many at high recall),
+   Pass 3 (the recall-biased router flags `needs_typing`), and Pass 4 (the LLM
+   assigns a taxonomy relation + `is_inference` + resolves coreference). It is
+   deliberately looser than `ExtractedFact`/`Fact`: predicate and object may be
+   missing/guessed, and `needs_typing` records the router's escalation decision.
+
+Kept to stdlib + dataclasses on purpose: this is imported by the rules pass (no
+heavy deps), the GLiNER2 pass, the router, and the LLM-typing pass, so it must stay
+import-clean and offline-testable — no torch, no ollama, no model download here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class Relation(str, Enum):
+    """The four structural relations a candidate can hold against an existing slot.
+
+    Subclasses `str` so the value round-trips through SQLite / JSON as a plain
+    string (e.g. stored as a column, or emitted by the LLM-typing schema) while
+    still giving us a closed enum to validate against. `Relation("supersedes")`
+    and `Relation.SUPERSEDES == "supersedes"` both work.
+    """
+
+    ASSERTS = "asserts"
+    SUPERSEDES = "supersedes"
+    EXTENDS = "extends"
+    DERIVES = "derives"
+
+
+#: The relation assigned when nothing else applies (new fact, fresh slot). Used as
+#: the deterministic default so the rules/GLiNER2 passes can label candidates
+#: without an LLM, and the router only escalates the genuinely ambiguous ones.
+DEFAULT_RELATION = Relation.ASSERTS
+
+#: Relations the surface-form (deterministic) passes are allowed to emit on their
+#: own. `derives` is excluded: it is inferential and, per spec section 5, only the
+#: LLM-typing pass may produce it. The router uses this to force escalation of any
+#: candidate that looks like a possible `derives`.
+DETERMINISTIC_RELATIONS: frozenset[Relation] = frozenset(
+    {Relation.ASSERTS, Relation.SUPERSEDES, Relation.EXTENDS}
+)
+
+#: Relations that the LLM-typing pass (Pass 4) may assign. It is the full taxonomy:
+#: the LLM both validates the cheap deterministic verdicts AND is the *only* source
+#: of `derives`.
+LLM_TYPED_RELATIONS: frozenset[Relation] = frozenset(Relation)
+
+# ── compatibility aliases (single source of truth for sibling passes) ──
+# llm_typer.py imports these names; export them here so there is ONE taxonomy and
+# the relation list cannot drift between modules.
+#: Tuple of relation string values, in taxonomy order.
+RELATIONS: tuple[str, ...] = tuple(r.value for r in Relation)
+
+#: Word-boundary inference cue tokens shared by the router (Pass 3) and the
+#: StubTyper (Pass 4) so the two deterministic passes AGREE on what looks
+#: inferential. Used with a \\b...\\b regex, never bare substring membership
+#: (substring matching gave false positives like 'so' inside 'also').
+INFERENCE_CUES: tuple[str, ...] = (
+    "so", "therefore", "thus", "hence", "because", "since", "must",
+    "probably", "likely", "means", "consequently", "implies", "suggests",
+)
+
+
+def is_inference_relation(value) -> bool:
+    """True if the (string or Relation) names the inferential `derives` relation.
+
+    Compatibility helper imported by llm_typer.py; defers to `relation_from_str`
+    so messy LLM output ('Derives', ' derives ') still resolves correctly.
+    """
+    return relation_from_str(value) is Relation.DERIVES
+
+
+def relation_from_str(value: Optional[str], *, default: Relation = DEFAULT_RELATION) -> Relation:
+    """Coerce a (possibly None / LLM-emitted / messy) string into a `Relation`.
+
+    Forgiving on input so the LLM-typing pass can hand us whatever its constrained
+    schema produced without crashing the pipeline; falls back to `default` on
+    anything unrecognized. Case- and whitespace-insensitive.
+    """
+    if isinstance(value, Relation):
+        return value
+    if value is None:
+        return default
+    key = value.strip().lower()
+    for rel in Relation:
+        if rel.value == key:
+            return rel
+    return default
+
+
+def is_inference_flag(relation: Relation) -> int:
+    """Map a taxonomy relation → the `Fact.is_inference` column value (0/1).
+
+    Only `derives` is inferential. Returns an int (not bool) to match the schema's
+    `is_inference INTEGER` column and `Fact.is_inference: int` field exactly.
+    """
+    return 1 if relation is Relation.DERIVES else 0
+
+
+def is_llm_only(relation: Relation) -> bool:
+    """True if only the LLM-typing pass may emit this relation (currently `derives`).
+
+    The router consults this (via `DETERMINISTIC_RELATIONS`) to guarantee a
+    deterministic pass never ships an inferential edge unreviewed.
+    """
+    return relation not in DETERMINISTIC_RELATIONS
+
+
+def triggers_versioning(relation: Relation) -> bool:
+    """True if assigning this relation must run the supersession path (Pass 5).
+
+    Only `supersedes` flips the old slot fact's `valid_to`/`superseded_by`/
+    `is_latest`. `asserts`/`extends` are co-valid (nothing retired); `derives` adds
+    a new inferential row but does not retire the surface facts it was derived from.
+    """
+    return relation is Relation.SUPERSEDES
+
+
+# ── predicate-slot helpers ──
+# The versioning "slot" is the (subject_id, predicate) pair — the same key the
+# store indexes (ix_fact_slot) and `find_latest_in_slot` looks up. Centralizing the
+# slot construction here keeps the router, the contradiction check, and the store
+# call agreeing on exactly one canonical key shape.
+
+#: Canonical placeholder predicate for a candidate whose relation slot the
+#: deterministic passes could not guess (GLiNER2 gives head/tail spans but the
+#: predicate may be unknown until LLM typing). Router treats this as needs_typing.
+UNTYPED_PREDICATE = "_untyped"
+
+
+def normalize_predicate(predicate: Optional[str]) -> str:
+    """Normalize a raw predicate string into a stable slot token.
+
+    Lowercase, collapse internal whitespace to single underscores, strip surrounding
+    punctuation. Mirrors the rules-pass convention (`works_at`, `lives_in`) so a
+    GLiNER2 relation name and a rules predicate collapse to the same slot when they
+    mean the same thing. Empty/None → `UNTYPED_PREDICATE`.
+    """
+    if not predicate:
+        return UNTYPED_PREDICATE
+    cleaned = predicate.strip().lower().strip("\"'.,!?;:")
+    if not cleaned:
+        return UNTYPED_PREDICATE
+    return "_".join(cleaned.split())
+
+
+def slot_key(subject_id: str, predicate: Optional[str]) -> tuple[str, str]:
+    """The canonical `(subject_id, predicate)` versioning slot key.
+
+    This is the key for supersession lookup (`store.find_latest_in_slot`) and the
+    contradiction → supersession flow. The predicate is normalized so callers never
+    have to remember to do it themselves.
+    """
+    return (subject_id, normalize_predicate(predicate))
+
+
+@dataclass
+class Candidate:
+    """An over-generated extraction candidate BEFORE routing/typing (Pass 2-4 currency).
+
+    Emitted at high recall by the deterministic passes (rules + GLiNER2). The fields
+    are intentionally loose — `predicate`/`object_*` may be absent or only guessed —
+    because the whole point of Pass 2 is to over-generate and let Pass 3 (router) and
+    Pass 4 (LLM typing) decide which candidates are real and how to type them.
+
+    Fields:
+      subject_name   — resolved later to a `subject_id`; the head span / subject text.
+      predicate      — guessed relation slot, or None if GLiNER2 gave only spans.
+      object_name    — entity-valued object span (tail), if any (resolved to object_id).
+      object_literal — literal-valued object (date/price/string), if any.
+      fact_text      — the standalone sentence (what eventually gets embedded).
+      valid_at       — world/event time (epoch ms), resolved against episode.t_ref.
+      confidence     — generator confidence in [0,1] (GLiNER2 span/relation score, or
+                       the rules-pass default). The router escalates low-confidence ones.
+      source         — which generator emitted it: 'rules' | 'gliner2' | 'stub'.
+      subject_span   — (start, end) char offsets of the head/subject span, if known
+                       (GLiNER2 reports these; rules may not) — for coref/provenance.
+      object_span    — (start, end) char offsets of the tail/object span, if known.
+      object_id      — resolved entity id for the object, once the resolver runs.
+      needs_typing   — the router's verdict (Pass 3). False until the router sets it;
+                       True means "escalate to the Pass-4 LLM-typing batch". This is
+                       the field the escalation-rate metric is computed over.
+      escalation_reasons — the router's recorded reasons for escalating (for the
+                       first-class escalation-rate-by-reason metric and debugging).
+    """
+
+    subject_name: str
+    fact_text: str
+    valid_at: int
+    predicate: Optional[str] = None
+    object_name: Optional[str] = None
+    object_literal: Optional[str] = None
+    object_id: Optional[str] = None
+    confidence: float = 0.6
+    source: str = "gliner2"  # 'rules' | 'gliner2' | 'stub'
+    subject_span: Optional[tuple[int, int]] = None
+    object_span: Optional[tuple[int, int]] = None
+    needs_typing: bool = False
+    escalation_reasons: list[str] = field(default_factory=list)
+
+    # The taxonomy relation, if/when assigned. None until typed (deterministic
+    # passes may set a tentative ASSERTS/EXTENDS/SUPERSEDES; Pass 4 may overwrite,
+    # and is the only writer of DERIVES). Kept here so the candidate carries the
+    # routing result through to the supersession/persistence step.
+    relation: Optional[Relation] = None
+
+    def slot(self, subject_id: str) -> tuple[str, str]:
+        """Canonical `(subject_id, predicate)` versioning slot for this candidate."""
+        return slot_key(subject_id, self.predicate)
+
+    @property
+    def normalized_predicate(self) -> str:
+        """The slot-token form of `predicate` (`UNTYPED_PREDICATE` if unset)."""
+        return normalize_predicate(self.predicate)
+
+    @property
+    def is_inference(self) -> int:
+        """`Fact.is_inference` value implied by the assigned relation (0 if untyped)."""
+        return is_inference_flag(self.relation) if self.relation is not None else 0

lean_memory/mcp_server.py

@@ -0,0 +1,150 @@
+"""MCP server exposing lean-memory as agent-memory tools.
+
+Run it:
+    python -m lean_memory.mcp_server          # stdio transport
+    lean-memory-mcp                            # console-script equivalent
+
+Wire it into an MCP client (Claude Desktop / Claude Code) with examples/mcp_config.json.
+
+Backends: if the `models` extra is installed (sentence-transformers importable), the
+server uses the real SentenceTransformerEmbedder + CrossEncoderReranker for quality;
+otherwise it falls back to lean-memory's offline stub defaults so it always runs.
+
+Data root: LM_DATA_ROOT env var (default ~/.lean_memory). Each namespace is an
+isolated SQLite file under that root (BET 4).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from .memory import _SAFE_NS, Memory
+
+
+def _data_root() -> Path:
+    root = os.environ.get("LM_DATA_ROOT", "~/.lean_memory")
+    return Path(root).expanduser()
+
+
+def _build_memory(root: Path) -> Memory:
+    """Opportunistically upgrade each backend when its optional extra is present.
+
+    Two INDEPENDENT upgrades, each guarded by its own import so either can succeed
+    without the other (`[models]` without `[extract]`, or vice versa):
+      * `models`  (sentence_transformers) → real embedder + reranker for retrieval.
+      * `extract` (gliner2)               → Gliner2Generator for real extraction.
+    Anything not installed falls back to lean-memory's deterministic offline stubs,
+    so the server always runs. GLiNER matters especially here: the frozen escalation/
+    granularity constants were calibrated ON the GLiNER path, so shipping it aligns
+    the canonical install with what the engine was tuned against.
+
+    Each successful upgrade logs ONE line to stderr (stdout is the MCP protocol
+    channel — NEVER print to stdout here) so cold-cache users, who wait through a
+    ~2 GB download on first tool call, see progress in their client's server logs.
+    """
+    kwargs: dict = {}
+
+    try:
+        import sentence_transformers  # noqa: F401
+
+        from .embed.sentence_transformer import SentenceTransformerEmbedder
+        from .retrieve.rerank import CrossEncoderReranker
+
+        kwargs["embedder"] = SentenceTransformerEmbedder()
+        kwargs["reranker"] = CrossEncoderReranker()
+        print("[lean-memory] models extra active: real embedder + reranker", file=sys.stderr)
+    except ImportError:
+        # `models` extra not installed — keep the deterministic offline stub backends.
+        pass
+
+    try:
+        import gliner2  # noqa: F401
+
+        from .extract.gliner_extractor import Gliner2Generator
+
+        kwargs["generator"] = Gliner2Generator()
+        print("[lean-memory] extract extra active: GLiNER2 extraction", file=sys.stderr)
+    except ImportError:
+        # `extract` extra not installed — keep the stub candidate generator.
+        pass
+
+    return Memory(root=root, **kwargs)
+
+
+mcp = FastMCP("lean-memory")
+
+# Lazy, build-once Memory. Import-time construction would block an MCP client's
+# server spawn through a ~2 GB cold-cache model download with no handshake; the
+# first tool call pays that cost instead, so the handshake is immediate. A plain
+# check-and-build is thread-safe enough for MCP's single-process stdio transport
+# (tool calls are serialized on one event loop; no concurrent _mem() races).
+_MEM: Optional[Memory] = None
+
+
+def _mem() -> Memory:
+    """Return the module-level Memory, building it (once) on first use."""
+    global _MEM
+    if _MEM is None:
+        _MEM = _build_memory(_data_root())
+    return _MEM
+
+
+def _namespace_path(namespace: str) -> Path:
+    """The SQLite file backing a namespace (mirrors Memory._store's naming)."""
+    safe = _SAFE_NS.sub("_", namespace) or "default"
+    return _mem().root / f"{safe}.db"
+
+
+@mcp.tool()
+def memory_add(namespace: str, text: str) -> str:
+    """Ingest text into the namespace's memory. Returns how many facts were written."""
+    written = _mem().add(namespace, text)
+    n = len(written)
+    return f"wrote {n} fact{'s' if n != 1 else ''}"
+
+
+@mcp.tool()
+def memory_search(namespace: str, query: str, k: int = 5) -> str:
+    """Search a namespace's memory and return the top-k facts as a bulleted list."""
+    hits = _mem().search(namespace, query, k=k)
+    if not hits:
+        return "No facts found."
+    # De-duplicate by exact fact_text, keeping the highest-ranked instance and
+    # preserving order: GLiNER over-generation can surface the same sentence
+    # multiple times in top-k, which would print duplicate bullets.
+    seen: set[str] = set()
+    bullets = []
+    for h in hits:
+        text = h.fact.fact_text
+        if text in seen:
+            continue
+        seen.add(text)
+        bullets.append(f"- {text}")
+    return "\n".join(bullets)
+
+
+@mcp.tool()
+def memory_clear(namespace: str) -> str:
+    """Delete all memory for a namespace by removing its SQLite file. Irreversible."""
+    # Release any cached open connection so the file handle is freed before unlink.
+    store = _mem()._stores.pop(namespace, None)
+    if store is not None:
+        store.close()
+    path = _namespace_path(namespace)
+    for p in (path, path.with_suffix(".db-wal"), path.with_suffix(".db-shm")):
+        p.unlink(missing_ok=True)
+    return f"cleared namespace '{namespace}'"
+
+
+def main() -> None:
+    """Console-script / module entry point: serve over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

lean_memory/memory.py

@@ -0,0 +1,203 @@
+"""`Memory` — the top-level facade. This is the public API for Phase 0.
+
+    mem = Memory(root="./data")              # per-tenant files live under root/
+    mem.add("ns1", "I work at Acme.", t_ref=...)
+    hits = mem.search("ns1", "where does the user work?")
+
+Per BET 4, each namespace gets its own SQLite file (write-isolation + brute-force
+comfort). The Memory object owns a small cache of open per-namespace stores.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+
+from .embed.base import Embedder
+from .embed.fake import FakeEmbedder
+from .extract.contradiction import EXTENDS, SUPERSEDES, ContradictionResolver
+from .extract.gliner_extractor import CandidateGenerator, StubCandidateGenerator
+from .extract.llm_typer import StubTyper, TypedFact, Typer
+from .extract.router import RecallBiasedRouter
+from .extract.salience import score_salience
+from .retrieve.rerank import IdentityReranker, Reranker
+from .retrieve.retriever import Retriever
+from .store.sqlite_store import SqliteStore
+from .types import Entity, Episode, Fact, RetrievedFact, new_id, now_ms
+
+# domain predicate the rules/stub passes use when none is guessed
+_DEFAULT_PREDICATE = "about"
+
+# Cap on the known-entity names handed to the router/typer per add(). The set
+# otherwise grows unboundedly with namespace age (conversational data creates
+# entities every turn), inflating — and eventually silently truncating — the
+# constrained-typing prompt. Most recent names win.
+_KNOWN_ENTITIES_CAP = 100
+
+_SAFE_NS = re.compile(r"[^A-Za-z0-9_.-]")
+
+
+class Memory:
+    def __init__(
+        self,
+        root: str | Path = "./lm_data",
+        *,
+        embedder: Optional[Embedder] = None,
+        reranker: Optional[Reranker] = None,
+        generator: Optional[CandidateGenerator] = None,
+        router: Optional[RecallBiasedRouter] = None,
+        typer: Optional[Typer] = None,
+        contradiction: Optional[ContradictionResolver] = None,
+    ) -> None:
+        self.root = Path(root)
+        self.root.mkdir(parents=True, exist_ok=True)
+        # Every backend defaults to the OFFLINE stub so the engine runs with zero
+        # downloads/servers. Swap in the real ones (SentenceTransformerEmbedder,
+        # CrossEncoderReranker, Gliner2Generator, OllamaTyper) for production quality.
+        self.embedder = embedder or FakeEmbedder()
+        self.reranker = reranker or IdentityReranker()
+        # Phase 1 hybrid-extraction pipeline (Pass 2 → 3 → 4 + contradiction):
+        self.generator = generator or StubCandidateGenerator()
+        self.router = router or RecallBiasedRouter()
+        self.typer = typer or StubTyper()
+        self.contradiction = contradiction or ContradictionResolver()
+        self._stores: dict[str, SqliteStore] = {}
+
+    # ── per-tenant store management (BET 4: one file per namespace) ──
+    def _store(self, namespace: str) -> SqliteStore:
+        if namespace not in self._stores:
+            safe = _SAFE_NS.sub("_", namespace) or "default"
+            path = self.root / f"{safe}.db"
+            self._stores[namespace] = SqliteStore(
+                path, dim=self.embedder.dim, coarse_dim=self.embedder.coarse_dim
+            )
+        return self._stores[namespace]
+
+    # ── ingest (the Phase 1 hybrid pipeline) ──
+    def add(
+        self, namespace: str, text: str, *, t_ref: Optional[int] = None, source: str = "user"
+    ) -> list[str]:
+        """Ingest one message through the full hybrid pipeline (spec §5):
+
+          Pass 2  generate over-generated candidates (rules/GLiNER2, high recall)
+          Pass 3  recall-biased router → escalate the hard ones (logs escalation rate)
+          Pass 4  LLM constrained typing of the residual; cheap-type the rest
+          Pass 5  per fact: resolve entity → contradiction check → ADD-only persist
+
+        Returns the ids of the facts written. Nothing is ever deleted.
+        """
+        t_ref = t_ref if t_ref is not None else now_ms()
+        store = self._store(namespace)
+
+        episode = Episode(namespace=namespace, raw=text, t_ref=t_ref, source=source)
+        store.add_episode(episode)
+
+        # Pass 2 — candidate generation (offline default: StubCandidateGenerator).
+        candidates = self.generator.generate(episode)
+        if not candidates:
+            return []
+
+        # Pass 3 — recall-biased router. known_entities is passed to the router/typer
+        # as context only; it no longer drives escalation (the prior_entity trigger was
+        # retired 2026-07 — see bench/results/calibration/README.md).
+        known = self._known_entity_names(store, namespace)
+        to_type, direct = self.router.route(candidates, known_entities=known)
+
+        # Pass 4 — type the escalated residual with the LLM (stub offline); the direct
+        # set is trivially explicit and typed cheaply (asserts, unless an inference cue).
+        typed: list[TypedFact] = []
+        if to_type:
+            typed += self.typer.type_candidates(episode.raw, to_type, known_entities=list(known))
+        if direct:
+            typed += StubTyper().type_candidates(episode.raw, direct, known_entities=list(known))
+
+        # Pass 5 — resolve, contradiction-check, persist (ADD-only).
+        written: list[str] = []
+        for tf in typed:
+            fact = self._build_fact(tf, namespace=namespace, episode_id=episode.id, store=store)
+
+            # Contradiction → supersession over the (subject, predicate) slot.
+            slot_latest = store.find_latest_in_slot(fact.subject_id, fact.predicate)
+            decision = self.contradiction.classify(
+                fact, slot_latest, self.embedder,
+                # ambiguous cases can escalate to the same typer; offline stub is fine.
+                llm_typer=None,
+            )
+
+            full, coarse = self.embedder.embed_with_coarse(fact.fact_text)
+            store.add_fact(fact, full, coarse)
+            # SUPERSEDES retires the matched fact; EXTENDS keeps both co-valid; ASSERTS
+            # touches nothing else. Insert-new-first so the FK target exists.
+            if decision.label == SUPERSEDES and decision.target is not None:
+                store.supersede_fact(decision.target.id, fact.id, valid_to=fact.valid_at)
+            written.append(fact.id)
+        return written
+
+    def _build_fact(
+        self, tf: TypedFact, *, namespace: str, episode_id: str, store: SqliteStore
+    ) -> Fact:
+        """Bind a TypedFact → a persistable Fact: resolve the subject entity, rate
+        salience once (cached), carry the relation's is_inference flag."""
+        subject = store.upsert_entity(Entity(namespace=namespace, name=tf.subject_name, type=None))
+        salience = score_salience(
+            tf.fact_text, source="extract", is_inference=bool(tf.is_inference)
+        )
+        ts = now_ms()
+        return Fact(
+            id=new_id(),
+            namespace=namespace,
+            subject_id=subject.id,
+            predicate=tf.predicate or _DEFAULT_PREDICATE,
+            object_literal=tf.object_literal,
+            fact_text=tf.fact_text,
+            valid_at=tf.valid_at,
+            episode_id=episode_id,
+            confidence=tf.confidence,
+            salience=salience,
+            is_inference=int(tf.is_inference),
+            ingested_at=ts,
+            created_at=ts,
+        )
+
+    def _known_entity_names(self, store: SqliteStore, namespace: str) -> set[str]:
+        """Names of entities already seen in this namespace — passed to the router/typer
+        as context only; they no longer drive escalation (the prior_entity trigger was
+        retired 2026-07 — see bench/results/calibration/README.md).
+        Capped to the most recent _KNOWN_ENTITIES_CAP names (ids are time-sortable)."""
+        rows = store._db.execute(
+            "SELECT name FROM entity WHERE namespace=? ORDER BY created_at DESC, id DESC LIMIT ?",
+            (namespace, _KNOWN_ENTITIES_CAP),
+        ).fetchall()
+        return {r["name"] for r in rows}
+
+    # ── retrieve ──
+    def search(
+        self,
+        namespace: str,
+        query: str,
+        k: int = 5,
+        *,
+        as_of: Optional[int] = None,
+        is_latest_only: bool = True,
+        now: Optional[int] = None,
+    ) -> list[RetrievedFact]:
+        """`now` (epoch ms) anchors the recency-decay term — pass the corpus's
+        present when querying historical data, else the wall clock is used and
+        recency is ≈0 for everything old (the term de-ranks nothing)."""
+        store = self._store(namespace)
+        retriever = Retriever(store, self.embedder, self.reranker)
+        return retriever.retrieve(
+            query, k, as_of=as_of, is_latest_only=is_latest_only, now=now
+        )
+
+    def close(self) -> None:
+        for s in self._stores.values():
+            s.close()
+        self._stores.clear()
+
+    def __enter__(self) -> "Memory":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()

lean_memory/retrieve/rerank.py

@@ -0,0 +1,59 @@
+"""Reranker interface + default backends.
+
+Per BET 1, the reranker is the single largest accuracy lever and is MANDATORY in the
+default pipeline. But the production model is harness-decided (the sub-150M field —
+Ettin-32M / mxbai-base / Qwen3-Reranker-0.6B — is within noise; do NOT assume
+superiority). Phase 0 ships:
+  - IdentityReranker: passes fused order through (keeps tests offline/deterministic).
+  - CrossEncoderReranker: lazy sentence-transformers CrossEncoder, default Ettin-32M.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class Reranker(ABC):
+    @abstractmethod
+    def score(self, query: str, docs: list[str]) -> list[float]:
+        """Return one relevance score per doc (higher = better)."""
+
+
+class IdentityReranker(Reranker):
+    """No-op reranker: preserves incoming order via a descending score ramp.
+
+    Used as the offline test default so the pipeline runs with zero model deps.
+    NOTE: this is explicitly NOT spec-compliant for production — the spec requires a
+    real cross-encoder. It exists only to make Phase 0 runnable without downloads.
+    """
+
+    def score(self, query: str, docs: list[str]) -> list[float]:
+        n = len(docs)
+        return [float(n - i) for i in range(n)]
+
+
+class CrossEncoderReranker(Reranker):
+    """Lazy cross-encoder. Default = Ettin-32M (a verified, real sub-150M option)."""
+
+    def __init__(self, model_name: str = "cross-encoder/ettin-reranker-32m-v1") -> None:
+        self.model_name = model_name
+        self._model = None
+
+    def _ensure(self):
+        if self._model is None:
+            try:
+                from sentence_transformers import CrossEncoder
+            except ImportError as e:  # pragma: no cover
+                raise ImportError(
+                    "CrossEncoderReranker needs the 'models' extra: "
+                    "pip install 'lean-memory[models]'"
+                ) from e
+            self._model = CrossEncoder(self.model_name)
+        return self._model
+
+    def score(self, query: str, docs: list[str]) -> list[float]:
+        if not docs:
+            return []
+        model = self._ensure()
+        pairs = [[query, d] for d in docs]
+        return [float(s) for s in model.predict(pairs)]