@bcmyguest/openmem 0.6.3 → 0.9.0

package/proxy/openmem_context/embed.py

@@ -0,0 +1,212 @@
+"""Background embeddings for session databases, off the request path (docs/context-store.md, "Vectors").
+
+The request path calls Embedder.notify(path, ...) after it stores new rows; one daemon thread embeds rows that have
+no vector for the configured model through an OpenAI-compatible POST <url>/embeddings and stores them. Trimmed rows
+go first, newest first. Batches adapt to the endpoint: they start at START_BATCH, double while a call takes under
+GROW_FRACTION of its timeout, and halve on a failure down to 1. A row that fails alone MAX_FAILURES times is skipped
+and recorded as a dim-0 vector. Errors are logged (type and location only) and an endpoint that keeps failing is
+retried after RETRY_S. Stdlib only; cli/coding-agent/session-db.mjs embeds the same way.
+"""
+
+import json
+import sqlite3
+import sys
+import threading
+import time
+import traceback
+import urllib.parse
+import urllib.request
+
+from .sessiondb import BUSY_TIMEOUT_MS, pack_vector
+from .settings import DEFAULT_EMBEDDING_MAX_CHARS as DEFAULT_MAX_CHARS
+from .settings import DEFAULT_EMBEDDING_TIMEOUT_S as DEFAULT_TIMEOUT_S
+
+START_BATCH = 4
+MAX_BATCH = 32
+# A call finishing under this fraction of its timeout doubles the next batch.
+GROW_FRACTION = 0.25
+# Single-row failures before a row is skipped; also the consecutive single-row failures that end a run.
+MAX_FAILURES = 3
+RETRY_S = 60
+SKIPPED_BLOB = b""
+
+
+def _where(exc):
+    tb = traceback.extract_tb(exc.__traceback__)
+    return f"{tb[-1].filename.rsplit('/', 1)[-1]}:{tb[-1].lineno}" if tb else "?"
+
+
+def _log(message):
+    print(f"openmem-context: {message}", file=sys.stderr, flush=True)
+
+
+def _log_error(exc):
+    _log(f"embedding failed {type(exc).__name__} at {_where(exc)}")
+
+
+def urllib_embed(url, model, api_key, texts, timeout=DEFAULT_TIMEOUT_S):
+    """Vectors for texts from an OpenAI-compatible embeddings endpoint, in input order."""
+    headers = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    body = json.dumps({"model": model, "input": texts}).encode("utf-8")
+    req = urllib.request.Request(url.rstrip("/") + "/embeddings", data=body, headers=headers, method="POST")
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        payload = json.loads(resp.read().decode("utf-8"))
+    data = sorted(payload["data"], key=lambda d: d.get("index", 0))
+    vectors = [[float(x) for x in d["embedding"]] for d in data]
+    if len(vectors) != len(texts):
+        raise ValueError("embedding count mismatch")
+    return vectors
+
+
+def pending_rows(conn, model, limit, exclude=()):
+    """Rows without a `model` vector, trimmed (in_context = 0) first, then newest first; seqs in exclude are left out."""
+    marks = ",".join("?" * len(exclude))
+    skip = f" AND m.seq NOT IN ({marks})" if exclude else ""
+    return conn.execute(
+        "SELECT m.seq, m.text FROM messages m LEFT JOIN vectors v ON v.message_seq = m.seq AND v.model = ? "
+        f"WHERE v.message_seq IS NULL AND length(trim(m.text)) > 0{skip} ORDER BY m.in_context, m.seq DESC LIMIT ?",
+        (model, *sorted(exclude), limit)).fetchall()
+
+
+def embed_pending(path, model, url, api_key="", embed=urllib_embed, *, state=None, timeout_s=DEFAULT_TIMEOUT_S,
+                  max_chars=DEFAULT_MAX_CHARS):
+    """Embed every row of the database at path that lacks a `model` vector; returns the number stored.
+
+    state carries "batch" (the next batch size), "ok" (the endpoint's last call succeeded) and "failures"
+    ({seq: single-row failures}) between runs. A failed size caps growth for the rest of the run.
+    Re-raises the last error once MAX_FAILURES single-row calls fail in a row with nothing stored this run.
+    """
+    state = {} if state is None else state
+    state.setdefault("batch", START_BATCH)
+    state.setdefault("ok", False)
+    failures = state.setdefault("failures", {})
+    # mode=rw: never create a database that TTL cleanup removed meanwhile.
+    uri = "file:" + urllib.parse.quote(str(path)) + "?mode=rw"
+    conn = sqlite3.connect(uri, uri=True, isolation_level=None, timeout=BUSY_TIMEOUT_MS / 1000)
+    stored = 0
+    tried = set()
+    streak = 0
+    ceiling = MAX_BATCH
+    try:
+        conn.execute(f"PRAGMA busy_timeout = {BUSY_TIMEOUT_MS}")
+        while True:
+            batch = state["batch"]
+            # Rows that never failed first; earlier failures get another try once those are done.
+            rows = pending_rows(conn, model, batch, tried | set(failures)) or pending_rows(conn, model, batch, tried)
+            if not rows:
+                return stored
+            timeout = timeout_s * len(rows)
+            start = time.monotonic()
+            try:
+                vectors = embed(url, model, api_key, [text[:max_chars] for _, text in rows], timeout)
+            except Exception as exc:
+                seconds = time.monotonic() - start
+                if len(rows) > 1:
+                    ceiling = max(1, len(rows) // 2)
+                    state["batch"] = max(1, len(rows) // 2)
+                    _log(f"embedding batch failed {type(exc).__name__} rows={len(rows)} seconds={seconds:.1f} "
+                         f"batch={state['batch']}")
+                    continue
+                seq = rows[0][0]
+                tried.add(seq)
+                failures[seq] = failures.get(seq, 0) + 1
+                streak += 1
+                _log(f"embedding row failed {type(exc).__name__} at {_where(exc)} seq={seq} failures={failures[seq]} "
+                     f"seconds={seconds:.1f} batch=1")
+                # Blame the row only while the endpoint works for other rows.
+                if failures[seq] >= MAX_FAILURES and (stored or state["ok"]):
+                    _insert(conn, [(seq, model, 0, SKIPPED_BLOB)])
+                    del failures[seq]
+                    _log(f"embedding skipped seq={seq} after {MAX_FAILURES} failures")
+                # The endpoint looks down: the caller retries the database after RETRY_S.
+                if streak >= MAX_FAILURES and not stored:
+                    state["ok"] = False
+                    raise
+                continue
+            seconds = time.monotonic() - start
+            _insert(conn, [(seq, model, len(vec), pack_vector(vec)) for (seq, _), vec in zip(rows, vectors)])
+            for seq, _ in rows:
+                failures.pop(seq, None)
+            stored += len(rows)
+            streak = 0
+            state["ok"] = True
+            if len(rows) == batch and seconds < GROW_FRACTION * timeout:
+                state["batch"] = min(ceiling, batch * 2)
+            _log(f"embedded rows={len(rows)} seconds={seconds:.1f} batch={state['batch']}")
+    finally:
+        conn.close()
+
+
+def _insert(conn, rows):
+    conn.execute("BEGIN IMMEDIATE")
+    try:
+        conn.executemany("INSERT OR IGNORE INTO vectors (message_seq, model, dim, blob) VALUES (?, ?, ?, ?)", rows)
+        conn.execute("COMMIT")
+    except BaseException:
+        conn.execute("ROLLBACK")
+        raise
+
+
+class Embedder:
+    """One daemon thread; notify() queues a database path and never blocks on the network."""
+
+    def __init__(self, embed=urllib_embed):
+        self._embed = embed
+        self._queue = {}
+        self._retry_at = {}
+        # {"batch", "ok"} per (url, model); single-row failure counts per (path, model).
+        self._endpoint = {}
+        self._failures = {}
+        self._cond = threading.Condition()
+        self._thread = None
+        self._busy = False
+
+    def notify(self, path, model, url, api_key="", timeout_s=DEFAULT_TIMEOUT_S, max_chars=DEFAULT_MAX_CHARS):
+        if not model or not url:
+            return
+        with self._cond:
+            if time.monotonic() < self._retry_at.get(str(path), 0):
+                return
+            self._queue[str(path)] = (model, url, api_key, timeout_s, max_chars)
+            if self._thread is None or not self._thread.is_alive():
+                self._thread = threading.Thread(target=self._run, name="openmem-embed", daemon=True)
+                self._thread.start()
+            self._cond.notify()
+
+    def batch_size(self, url, model):
+        return self._endpoint.get((url, model), {}).get("batch", START_BATCH)
+
+    def drain(self, timeout=10):
+        """Wait until the queue is empty (tests)."""
+        end = time.monotonic() + timeout
+        with self._cond:
+            while (self._queue or self._busy) and time.monotonic() < end:
+                self._cond.wait(0.05)
+
+    def _run(self):
+        while True:
+            with self._cond:
+                while not self._queue:
+                    self._busy = False
+                    self._cond.notify_all()
+                    self._cond.wait()
+                path, job = next(iter(self._queue.items()))
+                del self._queue[path]
+                self._busy = True
+            model, url, api_key, timeout_s, max_chars = job
+            endpoint = self._endpoint.setdefault((url, model), {"batch": START_BATCH, "ok": False})
+            state = {**endpoint, "failures": self._failures.setdefault((path, model), {})}
+            try:
+                embed_pending(path, model, url, api_key, embed=self._embed, state=state, timeout_s=timeout_s,
+                              max_chars=max_chars)
+            except Exception as exc:  # never let the thread die
+                _log_error(exc)
+                with self._cond:
+                    self._retry_at[path] = time.monotonic() + RETRY_S
+            finally:
+                endpoint.update(batch=state["batch"], ok=state["ok"])
+
+
+embedder = Embedder()

package/proxy/openmem_context/recall.py

@@ -0,0 +1,49 @@
+"""Hindsight recall and ingest-status calls (stdlib urllib)."""
+
+import json
+import urllib.parse
+import urllib.request
+
+OPS_TIMEOUT_S = 2.0
+
+
+def urllib_http(method, url, body, timeout):
+    """Default transport: returns (status, parsed JSON or None)."""
+    data = None if body is None else json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(url, data=data, method=method, headers={"content-type": "application/json"})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        raw = resp.read()
+        return resp.status, (json.loads(raw.decode("utf-8")) if raw else None)
+
+
+def _bank_url(base, bank):
+    return f"{base}/v1/default/banks/{urllib.parse.quote(bank, safe='')}"
+
+
+def recall_text(http, base, bank, query, max_chars, timeout):
+    """Recalled memory text, at most max_chars; '' when nothing came back."""
+    body = {"query": query, "budget": "low", "max_tokens": max(256, max_chars // 4)}
+    status, value = http("POST", f"{_bank_url(base, bank)}/memories/recall", body, timeout)
+    if status != 200 or not isinstance(value, dict):
+        return ""
+    hits = value.get("results") or []
+    texts = []
+    for hit in hits:
+        if isinstance(hit, dict):
+            text = hit.get("text") or hit.get("memory") or hit.get("content")
+            if isinstance(text, str) and text.strip():
+                texts.append(text.strip())
+    return "\n\n".join(texts)[:max_chars]
+
+
+def active_operations(http, base, bank):
+    """Pending + processing ingest operations for the bank."""
+    total = 0
+    for status in ("pending", "processing"):
+        code, value = http("GET", f"{_bank_url(base, bank)}/operations?status={status}&limit=1", None, OPS_TIMEOUT_S)
+        if code == 200 and isinstance(value, dict):
+            count = value.get("total")
+            if count is None:
+                count = len(value.get("operations") or [])
+            total += int(count)
+    return total

package/proxy/openmem_context/session.py

@@ -0,0 +1,70 @@
+"""Session id resolution, in contract order."""
+
+import hashlib
+import json
+import re
+
+from .store import InvalidSessionId, sanitize_sid
+
+_LEGACY_USER_ID_RE = re.compile(r"_session_([0-9A-Za-z-]{8,})$")
+_FALLBACK_HEADERS = ("session_id", "x-session-id", "conversation_id")
+
+
+def _headers(data):
+    psr = data.get("proxy_server_request") or {}
+    raw = psr.get("headers") or {}
+    return {str(k).lower(): v for k, v in raw.items()} if isinstance(raw, dict) else {}
+
+
+def _body(data):
+    psr = data.get("proxy_server_request") or {}
+    body = psr.get("body")
+    return body if isinstance(body, dict) else {}
+
+
+def _from_user_id(user_id):
+    if not isinstance(user_id, str) or not user_id:
+        return None
+    try:
+        parsed = json.loads(user_id)
+    except ValueError:
+        parsed = None
+    if isinstance(parsed, dict) and parsed.get("session_id"):
+        return str(parsed["session_id"])
+    m = _LEGACY_USER_ID_RE.search(user_id)
+    return m.group(1) if m else None
+
+
+def _first_user_text(adapter, items):
+    for item in items or ():
+        if isinstance(item, dict) and adapter.is_turn_start(item):
+            return adapter.user_text(item)
+    return ""
+
+
+def _candidates(data, headers, body):
+    """Session id sources in contract order (docs/context-store.md, "Session id")."""
+    yield headers.get("x-openmem-session-id")
+    yield headers.get("x-claude-code-session-id")
+    for meta in (data.get("metadata"), body.get("metadata")):
+        if isinstance(meta, dict):
+            yield _from_user_id(meta.get("user_id"))
+    yield data.get("prompt_cache_key")
+    yield body.get("prompt_cache_key")
+    for name in _FALLBACK_HEADERS:
+        yield headers.get(name)
+
+
+def resolve_session_id(data, adapter, items):
+    """Sanitized session id from the first source that yields a non-empty one, else fp-<hash>."""
+    headers = _headers(data)
+    body = _body(data)
+    for raw in _candidates(data, headers, body):
+        if not raw:
+            continue
+        try:
+            return sanitize_sid(raw)
+        except InvalidSessionId:
+            continue
+    seed = adapter.system_text(data) + _first_user_text(adapter, items)
+    return "fp-" + hashlib.sha256(seed.encode("utf-8")).hexdigest()[:16]

package/proxy/openmem_context/sessiondb.py

@@ -0,0 +1,276 @@
+"""Per-session SQLite store `sessions/<sid>.db` (docs/context-store.md, "Session database"). Stdlib only.
+
+The proxy writes every request's messages here, idempotently; the MCP tools read it. The schema and the row
+rules must match cli/coding-agent/session-db.mjs byte for byte (scripts/tests/test_context_parity.mjs).
+"""
+
+import math
+import os
+import re
+import sqlite3
+import struct
+import threading
+from collections import OrderedDict
+from pathlib import Path
+
+from .tokens import fingerprint
+
+SCHEMA_VERSION = 3
+# Version 1, executed in order on an empty database. Same strings as SCHEMA in cli/coding-agent/session-db.mjs.
+SCHEMA = (
+    "CREATE TABLE messages (seq INTEGER PRIMARY KEY, fingerprint TEXT NOT NULL UNIQUE, thread TEXT NOT NULL, "
+    "role TEXT NOT NULL, kind TEXT NOT NULL, name TEXT, text TEXT NOT NULL, blob_id TEXT, "
+    "in_context INTEGER NOT NULL DEFAULT 1, trimmed_at_seq INTEGER, trimmed_at TEXT, created_at TEXT NOT NULL)",
+    "CREATE INDEX messages_thread ON messages (thread, seq)",
+    "CREATE TABLE lines (id INTEGER PRIMARY KEY, message_seq INTEGER NOT NULL REFERENCES messages (seq), "
+    "line_no INTEGER NOT NULL, role TEXT NOT NULL, text TEXT NOT NULL, UNIQUE (message_seq, line_no))",
+    "CREATE VIRTUAL TABLE messages_fts USING fts5 (text, content='messages', content_rowid='seq')",
+    "CREATE VIRTUAL TABLE lines_fts USING fts5 (text, content='lines', content_rowid='id')",
+    "CREATE TRIGGER messages_fts_insert AFTER INSERT ON messages BEGIN "
+    "INSERT INTO messages_fts (rowid, text) VALUES (new.seq, new.text); END",
+    "CREATE TRIGGER lines_fts_insert AFTER INSERT ON lines BEGIN "
+    "INSERT INTO lines_fts (rowid, text) VALUES (new.id, new.text); END",
+    "CREATE TABLE vectors (message_seq INTEGER NOT NULL REFERENCES messages (seq), model TEXT NOT NULL, "
+    "dim INTEGER NOT NULL, blob BLOB NOT NULL, PRIMARY KEY (message_seq, model))",
+)
+# (version, DDL) run in order after SCHEMA on a new database, or from the stored version up on an older one; then
+# PRAGMA user_version = SCHEMA_VERSION. Same strings as MIGRATIONS in cli/coding-agent/session-db.mjs.
+MIGRATIONS = (
+    # Trims and fail-opens: kind 'trim' | 'fail_open'; version names the writer ("proxy:<hash>", "opencode:<v>").
+    (2, ("CREATE TABLE events (id INTEGER PRIMARY KEY, at TEXT NOT NULL, kind TEXT NOT NULL, version TEXT NOT NULL, "
+         "location TEXT, error TEXT, tokens_before INTEGER, tokens_after INTEGER, dropped INTEGER)",)),
+    # Per-request usage: kind 'usage', with provider-reported token counts, prompt-cache reads and writes, whether
+    # the request carried a cut, and its cache_control breakpoints (Anthropic route).
+    (3, tuple(f"ALTER TABLE events ADD COLUMN {c}" for c in (
+        "model TEXT", "thread_root TEXT", "trimmed INTEGER", "input_tokens INTEGER", "cache_read_tokens INTEGER",
+        "cache_creation_tokens INTEGER", "output_tokens INTEGER", "breakpoints INTEGER", "breakpoint_at TEXT"))),
+)
+EVENT_COLUMNS = ("at", "kind", "version", "location", "error", "tokens_before", "tokens_after", "dropped", "model",
+                 "thread_root", "trimmed", "input_tokens", "cache_read_tokens", "cache_creation_tokens", "output_tokens",
+                 "breakpoints", "breakpoint_at")
+_INSERT_EVENT = f"INSERT INTO events ({', '.join(EVENT_COLUMNS)}) VALUES ({', '.join('?' * len(EVENT_COLUMNS))})"
+DB_SUFFIX = ".db"
+FILE_MODE = 0o600
+DIR_MODE = 0o700
+BUSY_TIMEOUT_MS = 1000
+MAX_OPEN = 16
+_BLOB_REF_RE = re.compile(r"^\[blob:([0-9a-f]{16})\]")
+_open = OrderedDict()
+_open_guard = threading.Lock()
+
+
+class UnsupportedSchema(RuntimeError):
+    """The database has a user_version this code does not know."""
+
+
+def blob_ref(text):
+    """Blob id named by a stored tool-result text ("[blob:<id>]..."), else None."""
+    m = _BLOB_REF_RE.match(text) if isinstance(text, str) else None
+    return m.group(1) if m else None
+
+
+def chain(rows):
+    """Give each row its fingerprint and thread, in order, in place; returns rows.
+
+    A row's fingerprint hashes the previous row's fingerprint with the row's own role, kind, name and text, so it
+    names the row and its position in the conversation: a resent history yields the same keys, and the same text
+    said twice yields two rows. thread is the fingerprint of the conversation's first row.
+    """
+    prev = ""
+    for row in rows:
+        prev = row["fingerprint"] = fingerprint(
+            {"prev": prev, "role": row["role"], "kind": row["kind"], "name": row["name"], "text": row["text"]})
+        row["thread"] = rows[0]["fingerprint"]
+    return rows
+
+
+def _ensure_file(path):
+    path.parent.mkdir(mode=DIR_MODE, parents=True, exist_ok=True)
+    try:
+        os.chmod(path.parent, DIR_MODE)
+    except OSError:
+        pass
+    if not path.exists():
+        os.close(os.open(path, os.O_WRONLY | os.O_CREAT, FILE_MODE))
+
+
+def connect(path, create=True):
+    """Writer connection in WAL mode with the schema in place; raises UnsupportedSchema on a newer database."""
+    path = Path(path)
+    if create:
+        _ensure_file(path)
+    conn = sqlite3.connect(str(path), isolation_level=None, check_same_thread=False, timeout=BUSY_TIMEOUT_MS / 1000)
+    try:
+        conn.execute(f"PRAGMA busy_timeout = {BUSY_TIMEOUT_MS}")
+        conn.execute("PRAGMA journal_mode = WAL")
+        conn.execute("PRAGMA synchronous = NORMAL")
+        if conn.execute("PRAGMA user_version").fetchone()[0] < SCHEMA_VERSION:
+            conn.execute("BEGIN IMMEDIATE")
+            try:
+                version = conn.execute("PRAGMA user_version").fetchone()[0]
+                if version < SCHEMA_VERSION:
+                    if version == 0:
+                        for ddl in SCHEMA:
+                            conn.execute(ddl)
+                    for target, ddls in MIGRATIONS:
+                        if target > max(version, 1):
+                            for ddl in ddls:
+                                conn.execute(ddl)
+                    conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+                conn.execute("COMMIT")
+            except BaseException:
+                conn.execute("ROLLBACK")
+                raise
+        version = conn.execute("PRAGMA user_version").fetchone()[0]
+        if version != SCHEMA_VERSION:
+            raise UnsupportedSchema(f"user_version {version}")
+    except BaseException:
+        conn.close()
+        raise
+    return conn
+
+
+def _identity(path):
+    try:
+        st = os.stat(path)
+    except OSError:
+        return None
+    return st.st_dev, st.st_ino
+
+
+class SessionDB:
+    """One session's database plus an in-memory index of its rows (fingerprint -> [seq, in_context])."""
+
+    def __init__(self, path):
+        self.path = Path(path)
+        self.conn = connect(self.path)
+        self.identity = _identity(self.path)
+        self.known = {}
+        self.data_version = None
+
+    def close(self):
+        try:
+            self.conn.close()
+        except sqlite3.Error:
+            pass
+
+    def _refresh(self):
+        """Reload the index when another connection committed since the last look."""
+        version = self.conn.execute("PRAGMA data_version").fetchone()[0]
+        if version != self.data_version:
+            self.known = {fp: [seq, flag] for fp, seq, flag in
+                          self.conn.execute("SELECT fingerprint, seq, in_context FROM messages")}
+            self.data_version = version
+
+    def sync(self, rows, cut_row, ts):
+        """Store chained rows and their in_context flags; returns the number of new rows.
+
+        rows: dicts with fingerprint, thread, role, kind, name, text, blob_id and keep (in context after this
+        request). cut_row: index into rows of the first row of the cut turn, or None. Rows already stored are left
+        alone except for in_context: a row that leaves context records trimmed_at_seq (the cut row's seq, NULL
+        without one) and trimmed_at; a row that returns clears both.
+        """
+        self._refresh()
+        known = self.known
+        fresh = [r for r in rows if r["fingerprint"] not in known]
+        changes = [r for r in rows if r["fingerprint"] in known and known[r["fingerprint"]][1] != int(r["keep"])]
+        if not fresh and not changes:
+            return 0
+        conn = self.conn
+        conn.execute("BEGIN IMMEDIATE")
+        try:
+            added = 0
+            for r in fresh:
+                cur = conn.execute(
+                    "INSERT INTO messages (fingerprint, thread, role, kind, name, text, blob_id, created_at) "
+                    "VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT (fingerprint) DO NOTHING",
+                    (r["fingerprint"], r["thread"], r["role"], r["kind"], r["name"], r["text"], r["blob_id"], ts))
+                if cur.rowcount == 1:
+                    seq = cur.lastrowid
+                    conn.executemany("INSERT INTO lines (message_seq, line_no, role, text) VALUES (?, ?, ?, ?)",
+                                     [(seq, n, r["role"], line) for n, line in enumerate(r["text"].split("\n"), 1)])
+                    known[r["fingerprint"]] = [seq, 1]
+                    added += 1
+                else:
+                    seq, flag = conn.execute("SELECT seq, in_context FROM messages WHERE fingerprint = ?",
+                                             (r["fingerprint"],)).fetchone()
+                    known[r["fingerprint"]] = [seq, flag]
+            cut_seq = known[rows[cut_row]["fingerprint"]][0] if cut_row is not None else None
+            for r in rows:
+                entry = known[r["fingerprint"]]
+                want = int(r["keep"])
+                if entry[1] == want:
+                    continue
+                if want:
+                    conn.execute("UPDATE messages SET in_context = 1, trimmed_at_seq = NULL, trimmed_at = NULL "
+                                 "WHERE seq = ?", (entry[0],))
+                else:
+                    conn.execute("UPDATE messages SET in_context = 0, trimmed_at_seq = ?, trimmed_at = ? "
+                                 "WHERE seq = ?", (cut_seq, ts, entry[0]))
+                entry[1] = want
+            conn.execute("COMMIT")
+        except BaseException:
+            try:
+                conn.execute("ROLLBACK")
+            except sqlite3.Error:
+                pass
+            self.data_version = None
+            raise
+        self.data_version = conn.execute("PRAGMA data_version").fetchone()[0]
+        return added
+
+
+    def add_event(self, kind, at, version, **fields):
+        """Append one events row; fields are the other EVENT_COLUMNS (location, error, tokens_before, ...)."""
+        values = {"at": at, "kind": kind, "version": version, **fields}
+        self.conn.execute(_INSERT_EVENT, tuple(values.get(c) for c in EVENT_COLUMNS))
+
+
+def open_session(path):
+    """Cached SessionDB for path; reopened when the file was deleted or replaced (TTL cleanup)."""
+    path = Path(path)
+    with _open_guard:
+        db = _open.pop(str(path), None)
+        if db is not None and db.identity != _identity(path):
+            db.close()
+            db = None
+        if db is None:
+            db = SessionDB(path)
+        _open[str(path)] = db
+        while len(_open) > MAX_OPEN:
+            _open.popitem(last=False)[1].close()
+        return db
+
+
+def drop_session(path):
+    """Forget a cached connection, after an error, so the next request reopens it."""
+    with _open_guard:
+        db = _open.pop(str(Path(path)), None)
+    if db is not None:
+        db.close()
+
+
+# Vectors: float32 little-endian, brute-force cosine (sessions hold thousands of rows).
+def pack_vector(values):
+    return struct.pack(f"<{len(values)}f", *values)
+
+
+def unpack_vector(blob, dim):
+    return struct.unpack(f"<{dim}f", blob)
+
+
+def cosine(a, b):
+    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 and nb else 0.0
+
+
+def nearest(conn, query, model, k):
+    """(seq, similarity) of the k stored vectors of `model` closest to query, best first; ties by seq."""
+    scored = []
+    for seq, dim, blob in conn.execute("SELECT message_seq, dim, blob FROM vectors WHERE model = ?", (model,)):
+        if dim == len(query):
+            scored.append((seq, cosine(query, unpack_vector(blob, dim))))
+    scored.sort(key=lambda x: (-x[1], x[0]))
+    return scored[:k]