abstractnote 0.1.0__py3-none-any.whl

abstractnote/store/archive.py

@@ -0,0 +1,166 @@
+"""The archive as it stood on a date: the third time axis (docs/data-model.md "Time").
+
+``as_received = R`` answers "what did my archive hold on R?": only the notes received by R
+(``notes.received_at <= R``) count, so material imported later is left out even when its own dates are
+older. Everything derived from notes follows them: a revision belongs to the archive at R when the note
+that caused it was received by R, and a user action (no note) when it was recorded by R. Entities exist
+when a revision in the archive created them or a note in the archive mentions them; merges, names,
+aliases, summaries and claim closures count only when their revision belongs; a claim closed by a later
+revision is read as it was before that revision (replayed from the revisions that do belong).
+
+``at`` (history time) composes with it: the graph or card "as of T, from what the archive held on R".
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional, Tuple
+
+from .. import ids
+
+FOREVER = "9999-12-31T23:59:59Z"
+
+NOTES_SQL = "SELECT note_id FROM notes WHERE received_at<=?"
+REVISIONS_SQL = ("SELECT r.revision_id FROM revisions r LEFT JOIN notes n ON n.note_id=r.note_id"
+                 " WHERE r.applied_index=1 AND COALESCE(n.received_at, r.recorded_at)<=?")
+
+
+class Archive:
+    """What the archive held at ``as_received``; reads ask it which rows belong."""
+
+    def __init__(self, store: Any, as_received: str) -> None:
+        self.store = store
+        self.at = ids.normalize_time(as_received, field="as_received")
+        self.revisions = {r[0] for r in store.q(REVISIONS_SQL, (self.at,))}
+        self._merges: Optional[Dict[str, List[Tuple[str, str, Optional[str]]]]] = None
+        self._claim_states: Dict[str, Dict[str, Any]] = {}
+
+    # ---------------------------------------------------------------- SQL filters
+    def notes_in(self, col: str) -> Tuple[str, List[Any]]:
+        """``col IN (notes received by R)``."""
+        return f"{col} IN ({NOTES_SQL})", [self.at]
+
+    def revisions_in(self, col: str) -> Tuple[str, List[Any]]:
+        """``col IN (revisions that belong to the archive at R)``."""
+        return f"{col} IN ({REVISIONS_SQL})", [self.at]
+
+    def has(self, revision_id: Optional[str]) -> bool:
+        return bool(revision_id) and revision_id in self.revisions
+
+    # ---------------------------------------------------------------- merges
+    def merges(self) -> Dict[str, List[Tuple[str, str, Optional[str]]]]:
+        """``from_id -> [(at, into_id, undone_at or None)]`` for the merges in the archive, newest first; an undo
+        counts only when its own revision belongs."""
+        if self._merges is None:
+            out: Dict[str, List[Tuple[str, str, Optional[str]]]] = {}
+            for r in self.store.q("SELECT * FROM merges ORDER BY at DESC, revision_id DESC"):
+                if r["revision_id"] not in self.revisions:
+                    continue
+                undone = r["undone_at"] if self.has(r["undone_revision_id"]) else None
+                out.setdefault(r["from_id"], []).append((r["at"], r["into_id"], undone))
+            self._merges = out
+        return self._merges
+
+    def canonical(self, entity_id: str, at: Optional[str] = None) -> str:
+        """The surviving entity as of history time ``at`` (default: any time), by the merges in the archive."""
+        ref = at or FOREVER
+        merges = self.merges()
+        seen = set()
+        cur = entity_id
+        while cur not in seen:
+            seen.add(cur)
+            nxt = None
+            for m_at, into, undone in merges.get(cur, []):
+                if m_at <= ref and (undone is None or undone > ref):
+                    nxt = into
+                    break
+            if nxt is None:
+                return cur
+            cur = nxt
+        return cur
+
+    def members(self, entity_id: str, at: Optional[str] = None) -> List[str]:
+        """The entity and every entry merged into it (transitively) in the archive as of ``at``."""
+        out = [entity_id]
+        for m in sorted(self.merges()):
+            if m != entity_id and self.canonical(m, at) == entity_id:
+                out.append(m)
+        return out
+
+    # ---------------------------------------------------------------- entities
+    def entity_stats(self) -> Dict[str, Dict[str, Any]]:
+        """``entity_id -> {first_seen, last_seen, notes}`` of each entity in the archive, from its own creation
+        (when the creating revision belongs) and its own notes in the archive (``notes`` is a set of note ids)."""
+        out: Dict[str, Dict[str, Any]] = {}
+        sql, params = self.revisions_in("created_revision_id")
+        for r in self.store.q(f"SELECT entity_id, created_at FROM entities WHERE {sql}", params):
+            out[r[0]] = {"first_seen": r[1], "last_seen": r[1], "notes": set()}
+        sql, params = self.notes_in("note_id")
+        for r in self.store.q(f"SELECT entity_id, note_id, at FROM entity_notes WHERE {sql}", params):
+            st = out.setdefault(r[0], {"first_seen": r[2], "last_seen": r[2], "notes": set()})
+            st["notes"].add(r[1])
+            st["first_seen"] = min(st["first_seen"], r[2])
+            st["last_seen"] = max(st["last_seen"], r[2])
+        return out
+
+    def holds_entity(self, entity_id: str) -> bool:
+        sql, params = self.revisions_in("created_revision_id")
+        if self.store.q1(f"SELECT 1 FROM entities WHERE entity_id=? AND {sql}", [entity_id, *params]):
+            return True
+        sql, params = self.notes_in("note_id")
+        return self.store.q1(f"SELECT 1 FROM entity_notes WHERE entity_id=? AND {sql}", [entity_id, *params]) is not None
+
+    def name(self, entity_id: str, at: Optional[str] = None) -> Optional[str]:
+        sql, params = self.revisions_in("revision_id")
+        r = self.store.q1(f"SELECT name FROM entity_names WHERE entity_id=? AND at<=? AND {sql} ORDER BY at DESC,"
+                          " revision_id DESC LIMIT 1", [entity_id, at or FOREVER, *params])
+        return r[0] if r else None
+
+    def summary(self, entity_id: str, at: Optional[str] = None) -> Optional[str]:
+        sql, params = self.revisions_in("revision_id")
+        r = self.store.q1(f"SELECT summary FROM entity_summaries WHERE entity_id=? AND at<=? AND {sql} ORDER BY at"
+                          " DESC, revision_id DESC LIMIT 1", [entity_id, at or FOREVER, *params])
+        return r[0] if r else None
+
+    # ---------------------------------------------------------------- claims
+    def claim_state(self, row: Any) -> Dict[str, Any]:
+        """``{status, valid_until, superseded_by}`` of a claim as the archive at R held it."""
+        cid = row["claim_id"]
+        if not row["closed_revision_id"] or row["closed_revision_id"] in self.revisions:
+            return {"status": row["status"], "valid_until": row["valid_until"], "superseded_by": row["superseded_by"]}
+        if cid in self._claim_states:
+            return self._claim_states[cid]
+        valid_until = None
+        added = self.store.revision_row(row["revision_id"])
+        for op in json.loads(added["ops_json"]) if added else []:
+            p = op.get("payload") or {}
+            if op.get("op") == "claim.add" and p.get("claim_id") == cid:
+                valid_until = p.get("valid_until")
+        state = {"status": "active", "valid_until": valid_until, "superseded_by": None}
+        for r in self.store.q("SELECT revision_id, at, ops_json FROM revisions WHERE applied_index=1 AND ops_json LIKE ?"
+                              " ORDER BY seq", (f'%"{cid}"%',)):
+            if r["revision_id"] not in self.revisions:
+                continue
+            for op in json.loads(r["ops_json"]):
+                p = op.get("payload") or {}
+                if p.get("claim_id") != cid:
+                    continue
+                if op.get("op") == "claim.supersede" and state["status"] == "active":
+                    state = {"status": "superseded", "valid_until": state["valid_until"] or p.get("valid_until"),
+                             "superseded_by": p.get("by_claim_id")}
+                elif op.get("op") == "claim.retract" and state["status"] != "retracted":
+                    state = {"status": "retracted",
+                             "valid_until": state["valid_until"] or p.get("valid_until") or r["at"],
+                             "superseded_by": state["superseded_by"]}
+        self._claim_states[cid] = state
+        return state
+
+    def claim_dict(self, row: Any) -> Dict[str, Any]:
+        return {**self.store.claim_dict(row), **self.claim_state(row)}
+
+
+def archive_for(store: Any, as_received: Optional[str]) -> Optional[Archive]:
+    """An :class:`Archive` for a non-empty ``as_received``, else None (the archive as it is now)."""
+    if as_received in (None, ""):
+        return None
+    return Archive(store, as_received)

abstractnote/store/embeddings.py

@@ -0,0 +1,275 @@
+"""Embedders and the notebook's embedding cache.
+
+One notebook = one embedding space. The pin ``{model_id, dimension}`` is kept
+in the note index ``meta`` table and given to the AbstractMemory store at
+creation. Every vector is computed once through :class:`VectorCache` (keyed by
+the sha256 of the embedded text and the model id), stored in the note index,
+and handed to the triple store, so a rebuild never re-embeds unless asked.
+
+Adapters:
+
+- :class:`HashingEmbedder` — deterministic feature hashing, offline; the
+  default for headless notebooks and the test suite.
+- :func:`openai_compat_embedder` — any OpenAI-compatible ``/v1/embeddings``.
+- :func:`gateway_embedder` — the gateway embedding route via
+  ``abstractmemory.AbstractGatewayTextEmbedder``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+import sqlite3
+import struct
+import threading
+from typing import Any, Dict, Iterable, List, Optional, Protocol, Sequence, Tuple
+
+try:  # numpy is optional: faster cosine scans when present
+    import numpy as _np
+except Exception:  # pragma: no cover
+    _np = None
+
+HASHING_MODEL_PREFIX = "abstractnote-hashing-v1"
+
+
+class TextEmbedder(Protocol):
+    def embed_texts(self, texts: Sequence[str]) -> List[List[float]]: ...
+
+
+_TOKEN_RE = re.compile(r"\w+", re.UNICODE)
+
+
+class HashingEmbedder:
+    """Deterministic, offline embedder: signed feature hashing of words and
+    character trigrams, L2-normalised. Good enough for exact and near-exact
+    similarity (tests, headless use); not a semantic model."""
+
+    def __init__(self, dimension: int = 256) -> None:
+        if dimension < 8:
+            raise ValueError("The hashing embedder needs at least 8 dimensions.")
+        self.dimension = int(dimension)
+        self.model_id = f"{HASHING_MODEL_PREFIX}-{self.dimension}"
+
+    def _features(self, text: str) -> Iterable[str]:
+        words = _TOKEN_RE.findall(str(text or "").casefold())
+        for w in words:
+            yield "w:" + w
+            padded = f"#{w}#"
+            for i in range(len(padded) - 2):
+                yield "c:" + padded[i : i + 3]
+
+    def embed_texts(self, texts: Sequence[str]) -> List[List[float]]:
+        out: List[List[float]] = []
+        for text in texts:
+            vec = [0.0] * self.dimension
+            for feat in self._features(text):
+                h = hashlib.blake2b(feat.encode("utf-8"), digest_size=8).digest()
+                idx = int.from_bytes(h[:4], "little") % self.dimension
+                sign = 1.0 if h[4] & 1 else -1.0
+                vec[idx] += sign
+            norm = math.sqrt(sum(v * v for v in vec))
+            out.append([v / norm for v in vec] if norm > 0 else vec)
+        return out
+
+
+def openai_compat_embedder(base_url: str, model: str, **kwargs: Any) -> TextEmbedder:
+    from abstractmemory import OpenAICompatTextEmbedder
+
+    return OpenAICompatTextEmbedder(base_url, model, **kwargs)
+
+
+class _PinnedGatewayEmbedder:
+    """Gateway embedder with an explicit model id (the gateway route does not report one)."""
+
+    def __init__(self, inner: Any, model_id: Optional[str]) -> None:
+        self._inner = inner
+        if model_id:
+            self.model_id = model_id
+
+    def embed_texts(self, texts: Sequence[str]) -> List[List[float]]:
+        return self._inner.embed_texts(texts)
+
+
+def gateway_embedder(base_url: str, auth_token: Optional[str] = None, *, model_id: Optional[str] = None,
+                     **kwargs: Any) -> TextEmbedder:
+    from abstractmemory import AbstractGatewayTextEmbedder
+
+    return _PinnedGatewayEmbedder(AbstractGatewayTextEmbedder(base_url=base_url, auth_token=auth_token, **kwargs),
+                                  model_id)
+
+
+def embedder_model_id(embedder: Any) -> Optional[str]:
+    for attr in ("model_id", "model"):
+        v = getattr(embedder, attr, None)
+        if isinstance(v, str) and v.strip():
+            return v.strip()
+    return None
+
+
+def embedder_for_pin(pin: Optional[Dict[str, Any]]) -> Optional[TextEmbedder]:
+    """The embedder a pin can be reopened with without configuration (hashing only)."""
+    if not pin:
+        return None
+    mid = str(pin.get("model_id") or "")
+    if mid.startswith(HASHING_MODEL_PREFIX + "-"):
+        try:
+            return HashingEmbedder(int(mid.rsplit("-", 1)[1]))
+        except ValueError:
+            return None
+    return None
+
+
+# ----------------------------------------------------------------------------- vectors
+
+def pack(vector: Sequence[float]) -> bytes:
+    return struct.pack(f"<{len(vector)}f", *[float(x) for x in vector])
+
+
+def unpack(blob: bytes) -> List[float]:
+    n = len(blob) // 4
+    return list(struct.unpack(f"<{n}f", blob))
+
+
+def cosine(a: Sequence[float], b: Sequence[float]) -> float:
+    if len(a) != len(b) or not a:
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    return dot / (na * nb) if na > 0 and nb > 0 else 0.0
+
+
+def top_k(query: Sequence[float], items: Sequence[Tuple[str, bytes]], k: int,
+          min_score: Optional[float] = None) -> List[Tuple[str, float]]:
+    """Cosine top-k of (key, packed-vector) items, best first."""
+    if not items or k <= 0:
+        return []
+    if _np is not None:
+        q = _np.asarray(query, dtype=_np.float32)
+        qn = float(_np.linalg.norm(q))
+        if qn == 0:
+            return []
+        keys = [key for key, _ in items]
+        mat = _np.frombuffer(b"".join(blob for _, blob in items), dtype="<f4").reshape(len(items), -1)
+        if mat.shape[1] != q.shape[0]:
+            raise ValueError("A stored vector has a different dimension from the query; rebuild with --reembed.")
+        norms = _np.linalg.norm(mat, axis=1)
+        norms[norms == 0] = 1.0
+        scores = (mat @ q) / (norms * qn)
+        order = _np.argsort(-scores)
+        out: List[Tuple[str, float]] = []
+        for idx in order[: max(k, 0) if min_score is None else len(order)]:
+            s = float(scores[idx])
+            if min_score is not None and s < min_score:
+                break
+            out.append((keys[idx], s))
+            if len(out) >= k:
+                break
+        return out
+    scored = [(key, cosine(query, unpack(blob))) for key, blob in items]
+    scored.sort(key=lambda t: -t[1])
+    if min_score is not None:
+        scored = [t for t in scored if t[1] >= min_score]
+    return scored[:k]
+
+
+def vector_key(text: str, model_id: str) -> str:
+    return hashlib.sha256(f"{model_id}\x1f{text}".encode("utf-8")).hexdigest()
+
+
+class VectorCache:
+    """Embeds through the notebook's embedder once per distinct (model, text).
+
+    Vectors live in the note index ``vectors`` table; only misses reach the embedder."""
+
+    def __init__(self, conn: sqlite3.Connection, lock: threading.RLock, embedder: Optional[TextEmbedder],
+                 model_id: Optional[str], dimension: Optional[int]) -> None:
+        self._conn = conn
+        self._lock = lock
+        self.embedder = embedder
+        self.model_id = model_id or (embedder_model_id(embedder) if embedder is not None else None) or "unknown"
+        self.dimension = dimension
+        self.missing_embedder = "This notebook has no embedder, so new text cannot be embedded."
+
+    def keys_for(self, texts: Sequence[str]) -> List[str]:
+        return [vector_key(t, self.model_id) for t in texts]
+
+    def ensure(self, texts: Sequence[str]) -> List[str]:
+        """Make sure every text has a stored vector; return their keys."""
+        keys = self.keys_for(texts)
+        with self._lock:
+            have = set()
+            for i in range(0, len(keys), 500):
+                chunk = keys[i : i + 500]
+                q = ",".join("?" for _ in chunk)
+                have.update(r[0] for r in self._conn.execute(
+                    f"SELECT vector_key FROM vectors WHERE vector_key IN ({q})", chunk))
+        missing: Dict[str, str] = {}
+        for key, text in zip(keys, texts):
+            if key not in have and key not in missing:
+                missing[key] = text
+        if missing:
+            if self.embedder is None:
+                raise ValueError(self.missing_embedder)
+            texts_missing = list(missing.values())
+            vectors = self.embedder.embed_texts(texts_missing)
+            if len(vectors) != len(texts_missing):
+                raise RuntimeError("The embedder returned a different number of vectors than texts.")
+            dims = {len(v) for v in vectors}
+            if len(dims) != 1:
+                raise RuntimeError("The embedder returned vectors of different dimensions.")
+            dim = dims.pop()
+            if self.dimension is not None and dim != self.dimension:
+                raise RuntimeError(
+                    f"The embedder returned {dim}-dimension vectors but this notebook is pinned to "
+                    f"{self.dimension}; rebuild with --reembed after changing the embedding model."
+                )
+            self.dimension = dim
+            with self._lock:
+                self._conn.executemany(
+                    "INSERT OR IGNORE INTO vectors(vector_key, model_id, dimension, vector) VALUES (?,?,?,?)",
+                    [(k, self.model_id, dim, pack(v)) for k, v in zip(missing.keys(), vectors)],
+                )
+        return keys
+
+    def get(self, key: Optional[str]) -> Optional[List[float]]:
+        if not key:
+            return None
+        with self._lock:
+            row = self._conn.execute("SELECT vector FROM vectors WHERE vector_key=?", (key,)).fetchone()
+        return unpack(row[0]) if row else None
+
+    def embed_queries(self, texts: Sequence[str]) -> List[Optional[List[float]]]:
+        """Vectors for several query texts in one embedder call (stored vectors reused; nothing stored)."""
+        out: List[Optional[List[float]]] = [self.get(vector_key(t, self.model_id)) for t in texts]
+        missing = [i for i, v in enumerate(out) if v is None]
+        if missing and self.embedder is not None:
+            vecs = self.embedder.embed_texts([texts[i] for i in missing])
+            for i, v in zip(missing, vecs):
+                v = [float(x) for x in v]
+                if self.dimension is not None and len(v) != self.dimension:
+                    raise RuntimeError(
+                        f"The embedder returned a {len(v)}-dimension vector but this notebook is pinned to "
+                        f"{self.dimension}; rebuild with --reembed after changing the embedding model."
+                    )
+                out[i] = v
+        return out
+
+    def embed_query(self, text: str) -> Optional[List[float]]:
+        """Vector for a query text: a stored vector when the text was embedded
+        before, else one embedder call (queries are not stored). None when the
+        notebook has no embedder."""
+        cached = self.get(vector_key(text, self.model_id))
+        if cached is not None:
+            return cached
+        if self.embedder is None:
+            return None
+        [vec] = self.embedder.embed_texts([text])
+        vec = [float(x) for x in vec]
+        if self.dimension is not None and len(vec) != self.dimension:
+            raise RuntimeError(
+                f"The embedder returned a {len(vec)}-dimension vector but this notebook is pinned to "
+                f"{self.dimension}; rebuild with --reembed after changing the embedding model."
+            )
+        return vec

abstractnote/store/kg.py

@@ -0,0 +1,219 @@
+"""The AbstractMemory projection: ``ClaimStore`` over ``kg.sqlite3``.
+
+Every claim becomes a ``TripleAssertion`` (``assertion_id = claim_id``); entity
+names, aliases and merges become ``schema:name``, ``skos:altLabel`` and
+``schema:sameAs`` assertions. The triple store is append-only: the only
+in-place change is ``close_assertion(assertion_id, valid_until)`` (an additive
+AbstractMemory method), always paired with a journal ``ClosureRecord`` so that
+``TripleQuery(active_at=...)`` and ranked retrieval both agree with the note
+index. Every query passes ``owner_id="abstractnote"``.
+
+Vectors are never computed here: the note index embeds each canonical text
+once (``VectorCache``) and the triple store reads them through
+:class:`_LookupEmbedder`, so a rebuild does not call the embedder.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import warnings
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from abstractmemory import ClosureRecord, SQLiteJournal, SQLiteTripleStore, TripleAssertion, TripleQuery
+from abstractmemory.canonical_text import canonical_text
+
+from .. import ids
+from ..model import CERTAINTY_CONFIDENCE
+from .embeddings import VectorCache, vector_key
+
+OWNER_ID = "abstractnote"
+SCOPE = "global"
+KIND_ATTR = "abstractnote_kind"  # claim | name | alias | same_as
+
+
+class _LookupEmbedder:
+    """Serves vectors the note index already computed; a miss is an error."""
+
+    def __init__(self, cache: VectorCache) -> None:
+        self._cache = cache
+        self.model_id = cache.model_id
+
+    def embed_texts(self, texts: Sequence[str]) -> List[List[float]]:
+        out = []
+        for t in texts:
+            v = self._cache.get(vector_key(t, self._cache.model_id))
+            if v is None:
+                raise KeyError("A triple text has no vector in the note index (embed it first).")
+            out.append(v)
+        return out
+
+
+def claim_assertion(payload: Dict[str, Any], rev: Dict[str, Any], subject_kind: Optional[str],
+                    object_kind: Optional[str], *, run_id: Optional[str] = None) -> TripleAssertion:
+    """The ``TripleAssertion`` of one ``claim.add`` payload (docs/data-model.md, projection table)."""
+    literal = payload.get("object_id") is None
+    attrs: Dict[str, Any] = {
+        KIND_ATTR: "claim", "certainty": payload["certainty"], "stance": payload.get("stance") or "assert",
+    }
+    if subject_kind:
+        attrs["subject_type"] = subject_kind
+    if object_kind and not literal:
+        attrs["object_type"] = object_kind
+    if literal:
+        attrs["literal"] = True
+    if payload.get("evidence"):
+        attrs["evidence_quote"] = payload["evidence"]
+    prov = {
+        "source": "abstractnote", "note_id": payload.get("note_id") or rev.get("note_id"),
+        "revision_id": rev["revision_id"], "run_id": run_id or rev.get("run_id"),
+        "evidence_quote": payload.get("evidence"), "recorded_at": rev["recorded_at"],
+    }
+    return TripleAssertion(
+        subject=payload["subject_id"], predicate=payload["predicate"],
+        object=payload["object_literal"] if literal else payload["object_id"],
+        scope=SCOPE, owner_id=OWNER_ID, observed_at=payload["observed_at"],
+        valid_from=payload.get("valid_from"), valid_until=payload.get("valid_until"),
+        confidence=CERTAINTY_CONFIDENCE.get(payload["certainty"], 0.5),
+        provenance={k: v for k, v in prov.items() if v is not None}, attributes=attrs,
+        assertion_id=payload["claim_id"],
+    )
+
+
+def label_assertion(entity_id: str, predicate: str, value: str, kind: str, rev: Dict[str, Any]) -> TripleAssertion:
+    literal = kind in ("name", "alias")
+    attrs: Dict[str, Any] = {KIND_ATTR: kind}
+    if literal:
+        attrs["literal"] = True
+    return TripleAssertion(
+        subject=entity_id, predicate=predicate, object=value, scope=SCOPE, owner_id=OWNER_ID,
+        observed_at=rev["at"], valid_from=rev["at"] if kind == "same_as" else None,
+        provenance={"source": "abstractnote", "revision_id": rev["revision_id"], "recorded_at": rev["recorded_at"],
+                    **({"note_id": rev["note_id"]} if rev.get("note_id") else {})},
+        attributes=attrs, assertion_id=ids.kg_assertion_id(entity_id, predicate, value),
+    )
+
+
+def _journal_time(ts: str) -> str:
+    return ts[:-1] + "+00:00" if ts.endswith("Z") else ts
+
+
+class ClaimStore:
+    """AbstractMemory ``SQLiteTripleStore`` + ``SQLiteJournal`` for one notebook."""
+
+    def __init__(self, path: Path, cache: VectorCache) -> None:
+        self.path = Path(path)
+        self.cache = cache
+        pin: Dict[str, Any] = {"model_id": cache.model_id, "source": "creation"}
+        if cache.dimension is not None:
+            pin["dimension"] = cache.dimension
+        self._embedder = _LookupEmbedder(cache)
+        self.store = SQLiteTripleStore(self.path, embedder=self._embedder, embedding_pin=pin)
+        self.journal = SQLiteJournal(self.path)
+
+    def close(self) -> None:
+        self.store.close()
+        self.journal.close()
+
+    # ------------------------------------------------------------------ projection
+
+    def plan(self, rev: Dict[str, Any], kinds: Dict[str, str]) -> Tuple[List[TripleAssertion], List[Dict[str, Any]]]:
+        """The assertions to add and the closures to apply for one revision."""
+        adds: List[TripleAssertion] = []
+        closes: List[Dict[str, Any]] = []
+        for op in rev.get("ops") or []:
+            name, p = op["op"], op.get("payload") or {}
+            if name == "entity.create":
+                adds.append(label_assertion(p["entity_id"], "schema:name", p["name"], "name", rev))
+                for alias in p.get("aliases") or []:
+                    if str(alias).strip() and ids.fold(alias) != ids.fold(p["name"]):
+                        adds.append(label_assertion(p["entity_id"], "skos:altLabel", str(alias).strip(), "alias", rev))
+            elif name == "entity.alias":
+                if str(p.get("alias") or "").strip():
+                    adds.append(label_assertion(p["entity_id"], "skos:altLabel", str(p["alias"]).strip(), "alias", rev))
+            elif name == "entity.rename":
+                adds.append(label_assertion(p["entity_id"], "schema:name", p["name"], "name", rev))
+                if p.get("previous"):
+                    adds.append(label_assertion(p["entity_id"], "skos:altLabel", p["previous"], "alias", rev))
+            elif name == "entity.merge":
+                adds.append(label_assertion(p["from_id"], "schema:sameAs", p["into_id"], "same_as", rev))
+            elif name == "entity.unmerge":
+                closes.append({"assertion_id": ids.kg_assertion_id(p["from_id"], "schema:sameAs", p["entity_id"]),
+                               "valid_until": rev["at"], "kind": "retract", "reason": p.get("reason") or "unmerged",
+                               "replacement_ids": ()})
+            elif name == "claim.add":
+                adds.append(claim_assertion(p, rev, kinds.get(p["subject_id"]),
+                                            kinds.get(p.get("object_id") or "")))
+            elif name == "claim.supersede":
+                closes.append({"assertion_id": p["claim_id"], "valid_until": p["valid_until"], "kind": "supersede",
+                               "reason": p.get("reason") or "superseded by a later note",
+                               "replacement_ids": (p["by_claim_id"],) if p.get("by_claim_id") else ()})
+            elif name == "claim.retract":
+                closes.append({"assertion_id": p["claim_id"], "valid_until": p.get("valid_until") or rev["at"],
+                               "kind": "retract", "reason": p.get("reason") or "retracted", "replacement_ids": ()})
+        return adds, closes
+
+    def texts_for(self, adds: Sequence[TripleAssertion]) -> List[str]:
+        return [canonical_text(a) for a in adds]
+
+    def project(self, rev: Dict[str, Any], kinds: Dict[str, str]) -> Dict[str, int]:
+        """Write one revision to AbstractMemory. Idempotent: ids are deterministic,
+        ``add`` ignores known ids, ``close_assertion`` only closes open windows and
+        journal closures with a known id are no-ops."""
+        adds, closes = self.plan(rev, kinds)
+        if adds:
+            self.cache.ensure(self.texts_for(adds))
+            with warnings.catch_warnings():
+                # A vector miss must fail the write, never degrade it to vectorless.
+                warnings.filterwarnings("error", message=r"#FALLBACK: embedder failed", category=RuntimeWarning)
+                self.store.add(adds)
+        closed = 0
+        for c in closes:
+            if c["kind"] == "supersede" and not c["replacement_ids"]:
+                c = dict(c, kind="retract")
+            if self.store.close_assertion(c["assertion_id"], c["valid_until"]):
+                closed += 1
+            self.journal.append_closure(ClosureRecord(
+                assertion_id=c["assertion_id"], kind=c["kind"], reason=c["reason"],
+                replacement_ids=tuple(c["replacement_ids"]), observed_at=_journal_time(rev["recorded_at"]),
+                actor="abstractnote",
+                provenance={"revision_id": rev["revision_id"], "note_id": rev.get("note_id"),
+                            "valid_until": c["valid_until"]},
+                closure_id=ids.closure_id(rev["revision_id"], c["assertion_id"], c["kind"]),
+            ))
+        return {"added": len(adds), "closed": closed}
+
+    # ------------------------------------------------------------------ reads
+
+    def query(self, **kwargs: Any) -> List[TripleAssertion]:
+        kwargs.setdefault("owner_id", OWNER_ID)
+        kwargs.setdefault("scope", SCOPE)
+        kwargs.setdefault("limit", 0)
+        return self.store.query(TripleQuery(**kwargs))
+
+    def active_claim_ids(self, at: str) -> List[str]:
+        """Claim assertion ids AbstractMemory considers active at ``at``."""
+        rows = self.query(active_at=ids.normalize_time(at, field="at"))
+        return sorted(a.assertion_id for a in rows if (a.attributes or {}).get(KIND_ATTR) == "claim")
+
+    def count(self) -> int:
+        return len(self.query())
+
+    def embedding_pin(self) -> Optional[dict]:
+        return self.store.embedding_pin()
+
+
+def kinds_from_index(conn: sqlite3.Connection, rev: Dict[str, Any]) -> Dict[str, str]:
+    """Entity kinds needed to type a revision's claim assertions."""
+    wanted = set()
+    for op in rev.get("ops") or []:
+        if op["op"] == "claim.add":
+            p = op.get("payload") or {}
+            wanted.add(p["subject_id"])
+            if p.get("object_id"):
+                wanted.add(p["object_id"])
+    if not wanted:
+        return {}
+    q = ",".join("?" for _ in wanted)
+    return {r[0]: r[1] for r in conn.execute(f"SELECT entity_id, kind FROM entities WHERE entity_id IN ({q})",
+                                             list(wanted))}