lean-memory 0.1.0__py3-none-any.whl

lean_memory/retrieve/retriever.py

@@ -0,0 +1,125 @@
+"""The Retriever — composes the Phase 0 retrieval pipeline (spec section 6):
+
+  dense (two-stage Matryoshka) + sparse (BM25)
+    → RRF fuse (k=10)
+    → over-retrieve top 30-50
+    → mandatory cross-encoder rerank
+    → salience-decay re-score
+    → temporal filter (is_latest by default; as_of=T → interval predicate)
+
+All local, reproducible, no cloud key, no LLM at rank time.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Optional
+
+from ..embed.base import Embedder, matryoshka_truncate
+from ..store.base import Store
+from ..types import RetrievedFact, now_ms
+from .rerank import Reranker
+
+# spec defaults
+RRF_K = 10
+OVER_RETRIEVE = 40  # top 30-50 fused candidates before rerank
+W_REL, W_REC, W_IMP = 0.6, 0.2, 0.2
+DECAY_LAMBDA = 1.0 / (1000 * 60 * 60 * 24 * 30)  # ~1/month in ms; recency=exp(-λ·age)
+
+
+class Retriever:
+    def __init__(self, store: Store, embedder: Embedder, reranker: Reranker) -> None:
+        self.store = store
+        self.embedder = embedder
+        self.reranker = reranker
+
+    def retrieve(
+        self,
+        query: str,
+        k: int = 5,
+        *,
+        as_of: Optional[int] = None,
+        is_latest_only: bool = True,
+        now: Optional[int] = None,
+    ) -> list[RetrievedFact]:
+        now = now if now is not None else now_ms()
+
+        # 1. embed query (full + coarse for the two-stage dense arm)
+        q_full = self.embedder.embed_one(query)
+        q_coarse = matryoshka_truncate(q_full, self.embedder.coarse_dim)
+
+        # 2+3. dense and sparse arms, each over-retrieved
+        dense = self.store.dense_search(
+            q_coarse, q_full, OVER_RETRIEVE,
+            is_latest_only=is_latest_only, as_of=as_of,
+        )
+        sparse = self.store.sparse_search(
+            query, OVER_RETRIEVE, is_latest_only=is_latest_only, as_of=as_of,
+        )
+
+        # 4. RRF fuse (k=10). score(d) = Σ 1/(k + rank_i(d)), rank 1-based.
+        ranks: dict[str, dict[str, int]] = {}
+        for rank, (fid, _) in enumerate(dense, start=1):
+            ranks.setdefault(fid, {})["dense"] = rank
+        for rank, (fid, _) in enumerate(sparse, start=1):
+            ranks.setdefault(fid, {})["sparse"] = rank
+
+        fused: list[tuple[str, float]] = []
+        for fid, r in ranks.items():
+            s = 0.0
+            if "dense" in r:
+                s += 1.0 / (RRF_K + r["dense"])
+            if "sparse" in r:
+                s += 1.0 / (RRF_K + r["sparse"])
+            fused.append((fid, s))
+        fused.sort(key=lambda x: x[1], reverse=True)
+        fused = fused[:OVER_RETRIEVE]
+        if not fused:
+            return []
+
+        # hydrate the fused candidates
+        fact_map = self.store.hydrate([fid for fid, _ in fused])
+
+        # 5. mandatory rerank over the fused candidate texts
+        cand_ids = [fid for fid, _ in fused if fid in fact_map]
+        cand_texts = [fact_map[fid].fact_text for fid in cand_ids]
+        rel_scores = self.reranker.score(query, cand_texts)
+
+        # 6. salience-decay re-score: final = w_rel·rel + w_rec·recency + w_imp·importance
+        rel_norm = _minmax(rel_scores)
+        rrf_lookup = dict(fused)
+        dense_lookup = {fid: i + 1 for i, (fid, _) in enumerate(dense)}
+        sparse_lookup = {fid: i + 1 for i, (fid, _) in enumerate(sparse)}
+
+        results: list[RetrievedFact] = []
+        for fid, rel, rel_n in zip(cand_ids, rel_scores, rel_norm):
+            fact = fact_map[fid]
+            age = max(0, now - (fact.last_access or fact.valid_at))
+            recency = math.exp(-DECAY_LAMBDA * age)
+            importance = fact.salience / 10.0
+            final = W_REL * rel_n + W_REC * recency + W_IMP * importance
+            results.append(
+                RetrievedFact(
+                    fact=fact, final_score=final, relevance=rel,
+                    recency=recency, importance=importance,
+                    dense_rank=dense_lookup.get(fid),
+                    sparse_rank=sparse_lookup.get(fid),
+                    rrf_score=rrf_lookup.get(fid),
+                )
+            )
+
+        results.sort(key=lambda r: r.final_score, reverse=True)
+        top = results[:k]
+        for r in top:
+            self.store.touch(r.fact.id, now)
+        return top
+
+
+def _minmax(xs: list[float]) -> list[float]:
+    """Scale scores to [0,1] so they combine sanely with recency/importance."""
+    if not xs:
+        return []
+    lo, hi = min(xs), max(xs)
+    if hi - lo < 1e-9:
+        return [1.0 for _ in xs]
+    return [(x - lo) / (hi - lo) for x in xs]

lean_memory/store/base.py

@@ -0,0 +1,91 @@
+"""The `Store` interface — the single abstraction every other component talks to.
+
+Two concrete implementations are planned (SqliteStore = default; LanceStore =
+scale tier). Phase 0 ships SqliteStore only. Per BET 4, each namespace is its own
+backing file (per-tenant isolation), so the interface is opened per-namespace.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Optional, Sequence
+
+import numpy as np
+
+from ..types import Entity, Episode, Fact
+
+
+class Store(ABC):
+    """Storage + index abstraction. Implementations own one namespace's data."""
+
+    # ── provenance ──
+    @abstractmethod
+    def add_episode(self, episode: Episode) -> None: ...
+
+    # ── entities ──
+    @abstractmethod
+    def upsert_entity(self, entity: Entity) -> Entity:
+        """Resolve-or-create. If an entity with the same (namespace, name, type)
+        exists, return it; otherwise insert `entity` and return it."""
+
+    @abstractmethod
+    def get_entity(self, entity_id: str) -> Optional[Entity]: ...
+
+    # ── facts ──
+    @abstractmethod
+    def add_fact(self, fact: Fact, embedding: np.ndarray, embedding_256: np.ndarray) -> None:
+        """Insert a fact row + its vec0 vectors + its FTS row, in one transaction."""
+
+    @abstractmethod
+    def supersede_fact(self, old_fact_id: str, new_fact_id: str, valid_to: int) -> None:
+        """ADD-only supersession: point old→new, set old.valid_to, flip old.is_latest=0.
+        Never deletes."""
+
+    @abstractmethod
+    def get_fact(self, fact_id: str) -> Optional[Fact]: ...
+
+    @abstractmethod
+    def find_latest_in_slot(
+        self, subject_id: str, predicate: str
+    ) -> Sequence[Fact]:
+        """All currently-latest facts in a (subject, predicate) slot — for contradiction
+        detection / supersession lookup."""
+
+    # ── retrieval primitives (the Retriever composes these) ──
+    @abstractmethod
+    def dense_search(
+        self,
+        query_256: np.ndarray,
+        query_768: np.ndarray,
+        k: int,
+        *,
+        is_latest_only: bool = True,
+        as_of: Optional[int] = None,
+    ) -> list[tuple[str, float]]:
+        """Two-stage Matryoshka dense search. Returns [(fact_id, distance)] best-first."""
+
+    @abstractmethod
+    def sparse_search(
+        self, query_text: str, k: int, *, is_latest_only: bool = True,
+        as_of: Optional[int] = None,
+    ) -> list[tuple[str, float]]:
+        """BM25 lexical search. Returns [(fact_id, score)] best-first.
+        as_of applies the same interval predicate as the dense arm."""
+
+    @abstractmethod
+    def hydrate(self, fact_ids: Sequence[str]) -> dict[str, Fact]:
+        """Bulk-load Fact rows by id (preserves caller's dedup needs)."""
+
+    @abstractmethod
+    def touch(self, fact_id: str, when_ms: int) -> None:
+        """Record an access (recency/decay bookkeeping)."""
+
+    # ── lifecycle ──
+    @abstractmethod
+    def close(self) -> None: ...
+
+    def __enter__(self) -> "Store":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()

lean_memory/store/schema.py

@@ -0,0 +1,83 @@
+"""SQLite + vec0 + FTS5 schema for Phase 0.
+
+This is the spec's data model translated from its Postgres-flavored DDL to SQLite:
+  - Postgres ENUM / halfvec / pgvector → SQLite TEXT + vec0 INT8[N].
+  - `{dim}`/`{coarse_dim}` are filled at connect time from the embedder.
+The monotemporal spine is always present; bi-temporal audit columns exist but are
+only diverged from ingest time when the audit extra is enabled (deferred past Phase 0).
+"""
+
+SCHEMA_SQL = """
+-- ── PROVENANCE LAYER ────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS episode (
+  id          TEXT PRIMARY KEY,
+  namespace   TEXT NOT NULL,
+  raw         TEXT NOT NULL,
+  source      TEXT,
+  t_ref       INTEGER NOT NULL,
+  created_at  INTEGER NOT NULL
+);
+
+-- ── ENTITY LAYER ────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS entity (
+  id          TEXT PRIMARY KEY,
+  namespace   TEXT NOT NULL,
+  name        TEXT NOT NULL,
+  type        TEXT,
+  summary     TEXT,
+  resolved_id TEXT,
+  created_at  INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS ix_entity_lookup ON entity(namespace, name, type);
+
+-- ── FACT LAYER (monotemporal spine always on; audit axis opt-in) ─────
+CREATE TABLE IF NOT EXISTS fact (
+  id              TEXT PRIMARY KEY,
+  namespace       TEXT NOT NULL,
+  subject_id      TEXT NOT NULL REFERENCES entity(id),
+  predicate       TEXT NOT NULL,
+  object_id       TEXT REFERENCES entity(id),
+  object_literal  TEXT,
+  fact_text       TEXT NOT NULL,
+
+  valid_at        INTEGER NOT NULL,
+  valid_to        INTEGER,
+  superseded_by   TEXT REFERENCES fact(id),
+  is_latest       INTEGER NOT NULL DEFAULT 1,
+
+  ingested_at     INTEGER NOT NULL,
+  expired_at      INTEGER,
+  invalidated_by  TEXT REFERENCES fact(id),
+
+  confidence      REAL NOT NULL DEFAULT 1.0,
+  salience        REAL NOT NULL DEFAULT 0.0,
+  last_access     INTEGER,
+  access_count    INTEGER NOT NULL DEFAULT 0,
+  is_inference    INTEGER NOT NULL DEFAULT 0,
+  tier            TEXT NOT NULL DEFAULT 'hot',
+  episode_id      TEXT NOT NULL REFERENCES episode(id),
+  created_at      INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS ix_fact_ns_latest ON fact(namespace, is_latest);
+CREATE INDEX IF NOT EXISTS ix_fact_slot      ON fact(namespace, subject_id, predicate);
+CREATE INDEX IF NOT EXISTS ix_fact_valid     ON fact(namespace, valid_at, valid_to);
+
+-- ── VECTOR INDEX (sqlite-vec vec0) ──────────────────────────────────
+-- full 768 + 256-dim coarse Matryoshka vector. Stored FLOAT32 in Phase 0:
+-- the spec targets int8 (size win, ~0.2pt quality cost per BET 1) but
+-- sqlite-vec 0.1.9's int8 INSERT path is broken; flip to INT8[N] once fixed.
+CREATE VIRTUAL TABLE IF NOT EXISTS fact_vec USING vec0(
+  fact_id        TEXT PRIMARY KEY,
+  is_latest      INTEGER,
+  tier           TEXT,
+  namespace      TEXT,
+  embedding      FLOAT[{dim}],
+  embedding_256  FLOAT[{coarse_dim}]
+);
+
+-- ── LEXICAL INDEX (FTS5, external-content style holding its own text) ─
+CREATE VIRTUAL TABLE IF NOT EXISTS fact_fts USING fts5(
+  fact_id UNINDEXED,
+  fact_text
+);
+"""

lean_memory/store/sqlite_store.py

@@ -0,0 +1,301 @@
+"""SqliteStore — the default Phase 0 store. One SQLite file per namespace.
+
+Design-spec mapping:
+  - sqlite-vec `vec0` virtual table holds the int8 768-dim + 256-dim coarse vectors
+    (two-stage Matryoshka dense arm).
+  - FTS5 holds `fact_text` for the BM25 sparse arm.
+  - The relational `fact`/`entity`/`episode` tables hold the monotemporal spine.
+  - Per BET 4: this object backs ONE namespace (one file), turning SQLite's
+    single-writer limit into free write-isolation.
+
+Quantization: vectors arrive L2-normalized float32 in [-1, 1]; we map to int8 by
+scaling by 127 and rounding. vec0 does the distance math in int8 space.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Optional, Sequence
+
+import numpy as np
+from sqlite_vec import serialize_float32
+
+from ..types import Entity, Episode, Fact
+from .base import Store
+from .schema import SCHEMA_SQL
+
+
+def _serialize(vec: np.ndarray) -> bytes:
+    """L2-normalized float32 → vec0's float32 wire format.
+
+    NOTE (Phase 0 decision): we store float32, not int8. The schema/spec target int8
+    (size win, ~0.2pt quality cost per BET 1), but sqlite-vec 0.1.9's int8 *insert*
+    path is broken ("expected int8, but float32 provided" even for valid int8 blobs),
+    while the float32 path is solid. int8 is a documented future optimization to flip
+    once the upstream bug is fixed — it does not affect spine correctness.
+    """
+    return serialize_float32(vec.astype(np.float32).tolist())
+
+
+class SqliteStore(Store):
+    def __init__(self, path: str | Path, *, dim: int = 768, coarse_dim: int = 256) -> None:
+        self.path = str(path)
+        self.dim = dim
+        self.coarse_dim = coarse_dim
+        self._db = self._connect()
+        self._init_schema()
+
+    # ── connection / schema ──
+    def _connect(self) -> sqlite3.Connection:
+        import sqlite_vec  # lazy: only needed when a real store is opened
+
+        db = sqlite3.connect(self.path)
+        db.row_factory = sqlite3.Row
+        db.enable_load_extension(True)
+        sqlite_vec.load(db)
+        db.enable_load_extension(False)
+        db.execute("PRAGMA journal_mode=WAL")  # better single-writer concurrency
+        db.execute("PRAGMA foreign_keys=ON")
+        return db
+
+    def _init_schema(self) -> None:
+        sql = SCHEMA_SQL.format(dim=self.dim, coarse_dim=self.coarse_dim)
+        self._db.executescript(sql)
+        self._db.commit()
+
+    # ── provenance ──
+    def add_episode(self, episode: Episode) -> None:
+        self._db.execute(
+            "INSERT INTO episode(id, namespace, raw, source, t_ref, created_at) "
+            "VALUES (?,?,?,?,?,?)",
+            (episode.id, episode.namespace, episode.raw, episode.source,
+             episode.t_ref, episode.created_at),
+        )
+        self._db.commit()
+
+    # ── entities ──
+    def upsert_entity(self, entity: Entity) -> Entity:
+        row = self._db.execute(
+            "SELECT * FROM entity WHERE namespace=? AND name=? AND IFNULL(type,'')=IFNULL(?,'')",
+            (entity.namespace, entity.name, entity.type),
+        ).fetchone()
+        if row:
+            return _row_to_entity(row)
+        self._db.execute(
+            "INSERT INTO entity(id, namespace, name, type, summary, resolved_id, created_at) "
+            "VALUES (?,?,?,?,?,?,?)",
+            (entity.id, entity.namespace, entity.name, entity.type,
+             entity.summary, entity.resolved_id, entity.created_at),
+        )
+        self._db.commit()
+        return entity
+
+    def get_entity(self, entity_id: str) -> Optional[Entity]:
+        row = self._db.execute("SELECT * FROM entity WHERE id=?", (entity_id,)).fetchone()
+        return _row_to_entity(row) if row else None
+
+    # ── facts ──
+    def add_fact(self, fact: Fact, embedding: np.ndarray, embedding_256: np.ndarray) -> None:
+        db = self._db
+        db.execute(
+            """INSERT INTO fact(
+                 id, namespace, subject_id, predicate, object_id, object_literal, fact_text,
+                 valid_at, valid_to, superseded_by, is_latest,
+                 ingested_at, expired_at, invalidated_by,
+                 confidence, salience, last_access, access_count, is_inference, tier,
+                 episode_id, created_at)
+               VALUES (?,?,?,?,?,?,?, ?,?,?,?, ?,?,?, ?,?,?,?,?,?, ?,?)""",
+            (fact.id, fact.namespace, fact.subject_id, fact.predicate, fact.object_id,
+             fact.object_literal, fact.fact_text,
+             fact.valid_at, fact.valid_to, fact.superseded_by, fact.is_latest,
+             fact.ingested_at, fact.expired_at, fact.invalidated_by,
+             fact.confidence, fact.salience, fact.last_access, fact.access_count,
+             fact.is_inference, fact.tier,
+             fact.episode_id, fact.created_at),
+        )
+        db.execute(
+            "INSERT INTO fact_vec(fact_id, namespace, is_latest, tier, embedding, embedding_256) "
+            "VALUES (?,?,?,?,?,?)",
+            (fact.id, fact.namespace, fact.is_latest, fact.tier,
+             _serialize(embedding), _serialize(embedding_256)),
+        )
+        db.execute(
+            "INSERT INTO fact_fts(fact_id, fact_text) VALUES (?,?)",
+            (fact.id, fact.fact_text),
+        )
+        db.commit()
+
+    def supersede_fact(self, old_fact_id: str, new_fact_id: str, valid_to: int) -> None:
+        db = self._db
+        db.execute(
+            "UPDATE fact SET superseded_by=?, valid_to=?, is_latest=0 WHERE id=?",
+            (new_fact_id, valid_to, old_fact_id),
+        )
+        # keep the vec0 metadata filter column in sync so superseded facts drop out
+        db.execute("UPDATE fact_vec SET is_latest=0 WHERE fact_id=?", (old_fact_id,))
+        db.commit()
+
+    def get_fact(self, fact_id: str) -> Optional[Fact]:
+        row = self._db.execute("SELECT * FROM fact WHERE id=?", (fact_id,)).fetchone()
+        return _row_to_fact(row) if row else None
+
+    def find_latest_in_slot(self, subject_id: str, predicate: str) -> Sequence[Fact]:
+        rows = self._db.execute(
+            "SELECT * FROM fact WHERE subject_id=? AND predicate=? AND is_latest=1",
+            (subject_id, predicate),
+        ).fetchall()
+        return [_row_to_fact(r) for r in rows]
+
+    # ── retrieval primitives ──
+    def dense_search(
+        self,
+        query_256: np.ndarray,
+        query_768: np.ndarray,
+        k: int,
+        *,
+        is_latest_only: bool = True,
+        as_of: Optional[int] = None,
+    ) -> list[tuple[str, float]]:
+        """Two-stage Matryoshka: coarse 256-dim KNN over a wider pool, then re-score
+        the survivors at full 768-dim. The coarse pool is k*COARSE_FACTOR wide so the
+        cheaper first stage doesn't drop gold before the precise re-score."""
+        COARSE_FACTOR = 8
+        coarse_k = max(k * COARSE_FACTOR, k)
+
+        latest_clause = "AND is_latest = 1" if is_latest_only else ""
+        # Stage 1: coarse KNN. vec0 KNN must use a single MATCH + LIMIT.
+        coarse_rows = self._db.execute(
+            f"""SELECT fact_id, distance FROM fact_vec
+                WHERE embedding_256 MATCH ? {latest_clause}
+                ORDER BY distance LIMIT ?""",
+            (_serialize(query_256), coarse_k),
+        ).fetchall()
+        if not coarse_rows:
+            return []
+
+        candidate_ids = [r["fact_id"] for r in coarse_rows]
+        # Stage 2: re-score candidates at full 768-dim (exact distance, small set).
+        # vec0 doesn't take an IN-list on KNN, so we read the full vectors back and
+        # compute cosine here — exact, and the candidate set is tiny (coarse_k).
+        placeholders = ",".join("?" * len(candidate_ids))
+        vec_rows = self._db.execute(
+            f"SELECT fact_id, embedding FROM fact_vec WHERE fact_id IN ({placeholders})",
+            candidate_ids,
+        ).fetchall()
+
+        q = query_768.astype(np.float32)
+        q = q / (np.linalg.norm(q) or 1.0)
+        scored: list[tuple[str, float]] = []
+        for vr in vec_rows:
+            stored = np.frombuffer(vr["embedding"], dtype=np.float32)
+            sn = np.linalg.norm(stored) or 1.0
+            cos = float(np.dot(q, stored) / sn)
+            scored.append((vr["fact_id"], 1.0 - cos))  # distance = 1 - cosine
+
+        if as_of is not None:
+            scored = self._apply_as_of(scored, as_of)
+
+        scored.sort(key=lambda x: x[1])
+        return scored[:k]
+
+    def _apply_as_of(self, scored: list[tuple[str, float]], as_of: int) -> list[tuple[str, float]]:
+        ids = [fid for fid, _ in scored]
+        if not ids:
+            return scored
+        placeholders = ",".join("?" * len(ids))
+        valid = {
+            r["id"]
+            for r in self._db.execute(
+                f"""SELECT id FROM fact WHERE id IN ({placeholders})
+                    AND valid_at <= ? AND (valid_to IS NULL OR valid_to > ?)""",
+                (*ids, as_of, as_of),
+            ).fetchall()
+        }
+        return [(fid, d) for fid, d in scored if fid in valid]
+
+    def sparse_search(
+        self, query_text: str, k: int, *, is_latest_only: bool = True,
+        as_of: Optional[int] = None,
+    ) -> list[tuple[str, float]]:
+        # FTS5 BM25: lower bm25() is better, so we negate to "higher is better".
+        needs_row_check = is_latest_only or as_of is not None
+        rows = self._db.execute(
+            """SELECT f.fact_id AS fact_id, bm25(fact_fts) AS score
+               FROM fact_fts f
+               WHERE fact_fts MATCH ?
+               ORDER BY score LIMIT ?""",
+            (_fts_query(query_text), k * (2 if needs_row_check else 1)),
+        ).fetchall()
+        out: list[tuple[str, float]] = []
+        for r in rows:
+            if needs_row_check:
+                row = self._db.execute(
+                    "SELECT is_latest, valid_at, valid_to FROM fact WHERE id=?",
+                    (r["fact_id"],),
+                ).fetchone()
+                if not row:
+                    continue
+                if is_latest_only and not row["is_latest"]:
+                    continue
+                if as_of is not None and not (
+                    row["valid_at"] <= as_of
+                    and (row["valid_to"] is None or row["valid_to"] > as_of)
+                ):
+                    continue
+            out.append((r["fact_id"], -float(r["score"])))
+            if len(out) >= k:
+                break
+        return out
+
+    def hydrate(self, fact_ids: Sequence[str]) -> dict[str, Fact]:
+        if not fact_ids:
+            return {}
+        placeholders = ",".join("?" * len(fact_ids))
+        rows = self._db.execute(
+            f"SELECT * FROM fact WHERE id IN ({placeholders})", list(fact_ids)
+        ).fetchall()
+        return {r["id"]: _row_to_fact(r) for r in rows}
+
+    def touch(self, fact_id: str, when_ms: int) -> None:
+        self._db.execute(
+            "UPDATE fact SET last_access=?, access_count=access_count+1 WHERE id=?",
+            (when_ms, fact_id),
+        )
+        self._db.commit()
+
+    def close(self) -> None:
+        self._db.close()
+
+
+# ── FTS query sanitization ──
+def _fts_query(text: str) -> str:
+    """Turn free text into a safe FTS5 OR-query of bare terms (avoids syntax errors
+    from punctuation/operators in user text)."""
+    terms = [t for t in "".join(c if c.isalnum() else " " for c in text).split() if t]
+    if not terms:
+        return '""'
+    return " OR ".join(terms)
+
+
+# ── row → dataclass ──
+def _row_to_entity(row: sqlite3.Row) -> Entity:
+    return Entity(
+        id=row["id"], namespace=row["namespace"], name=row["name"], type=row["type"],
+        summary=row["summary"], resolved_id=row["resolved_id"], created_at=row["created_at"],
+    )
+
+
+def _row_to_fact(row: sqlite3.Row) -> Fact:
+    return Fact(
+        id=row["id"], namespace=row["namespace"], subject_id=row["subject_id"],
+        predicate=row["predicate"], object_id=row["object_id"],
+        object_literal=row["object_literal"], fact_text=row["fact_text"],
+        valid_at=row["valid_at"], valid_to=row["valid_to"],
+        superseded_by=row["superseded_by"], is_latest=row["is_latest"],
+        ingested_at=row["ingested_at"], expired_at=row["expired_at"],
+        invalidated_by=row["invalidated_by"], confidence=row["confidence"],
+        salience=row["salience"], last_access=row["last_access"],
+        access_count=row["access_count"], is_inference=row["is_inference"],
+        tier=row["tier"], episode_id=row["episode_id"], created_at=row["created_at"],
+    )