ags-cli 0.1.0__py3-none-any.whl

harness/memory/ranking.py

@@ -0,0 +1,31 @@
+"""Recency + relevance fusion for retrieval ranking.
+
+Final score = relevance_weight * cosine_similarity + recency_weight * recency,
+where recency decays exponentially with item age. Weights come from
+``config.yaml`` (``memory.retrieval``)."""
+
+from __future__ import annotations
+
+import math
+from datetime import UTC, datetime
+
+
+def recency_score(created_at: datetime, *, half_life_hours: float = 168.0) -> float:
+    """Exponential decay; 1.0 now, 0.5 at one half-life (default 7 days)."""
+    now = datetime.now(UTC)
+    if created_at.tzinfo is None:
+        created_at = created_at.replace(tzinfo=UTC)
+    age_hours = max((now - created_at).total_seconds() / 3600.0, 0.0)
+    return math.pow(0.5, age_hours / half_life_hours)
+
+
+def fuse(
+    similarity: float,
+    created_at: datetime,
+    *,
+    relevance_weight: float = 0.7,
+    recency_weight: float = 0.3,
+    half_life_hours: float = 168.0,
+) -> float:
+    rec = recency_score(created_at, half_life_hours=half_life_hours)
+    return relevance_weight * similarity + recency_weight * rec

harness/memory/redact.py

@@ -0,0 +1,37 @@
+"""Secret redaction. Runs BEFORE storage and BEFORE embedding so raw secrets
+never enter canonical memory or the vector index. Pattern-based and conservative:
+prefers over-redaction to leakage."""
+
+from __future__ import annotations
+
+import re
+
+_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("aws_access_key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    ("aws_secret", re.compile(r"\b(?i:aws_secret_access_key)\s*[=:]\s*\S+")),
+    ("github_token", re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b")),
+    ("openai_key", re.compile(r"\bsk-[A-Za-z0-9]{20,}\b")),
+    ("anthropic_key", re.compile(r"\bsk-ant-[A-Za-z0-9_\-]{20,}\b")),
+    ("slack_token", re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b")),
+    ("bearer", re.compile(r"(?i:bearer)\s+[A-Za-z0-9._\-]{20,}")),
+    ("jwt", re.compile(r"\beyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\b")),
+    ("private_key", re.compile(
+        r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]+?-----END[^-]+-----"
+    )),
+    ("password_kv", re.compile(r"(?i:password|passwd|secret|api[_-]?key)\s*[=:]\s*\S+")),
+    ("email", re.compile(r"\b[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}\b")),
+]
+
+
+def redact(text: str) -> tuple[str, bool]:
+    """Return (redacted_text, was_redacted)."""
+    redacted = text
+    hit = False
+    for label, pat in _PATTERNS:
+        redacted, n = pat.subn(f"[REDACTED:{label}]", redacted)
+        hit = hit or n > 0
+    return redacted, hit
+
+
+def contains_secret(text: str) -> bool:
+    return redact(text)[1]

harness/memory/service.py

@@ -0,0 +1,320 @@
+"""Memory retrieval service — the unified, provider-agnostic retrieval API.
+
+``retrieve`` runs a namespace-bounded vector search, re-ranks by recency+relevance
+fusion, drops TTL-expired items, and returns a compact normalized context block any
+adapter can prepend to its prompt. This is the single seam through which shared
+memory reaches every provider.
+
+Similarity has two backends behind one query shape: sqlite-vec's ANN KNN search when
+the extension is loaded, and a namespace-scoped brute-force cosine in Python otherwise
+— fine for a single developer's memory, and dependency-free.
+
+``reindex_memory`` iterates workspace items whose embeddings are stale (wrong model),
+deletes them, and re-embeds with the active embedder in batches of 64."""
+
+from __future__ import annotations
+
+import logging
+import math
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from sqlalchemy import and_, delete, or_, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from harness.memory.embed import Embedder, get_embedder
+# _chunk is private to ingest but lives in the same package; imported here to
+# avoid duplicating the chunking logic — same function reused for reindex fidelity.
+from harness.memory.ingest import _chunk
+from harness.memory.namespaces import session_ns, workspace_ns
+from harness.memory.ranking import fuse
+from harness.memory.sqlite_vec_backend import SqliteVecIndex
+from harness.models.enums import MemoryScope
+from harness.models.memory import MemoryEmbedding, MemoryItem
+from harness.observability.metrics import MEMORY_HITS, MEMORY_QUERIES
+from harness.settings import get_settings
+
+log = logging.getLogger(__name__)
+
+# Upper bound on candidate embeddings scanned in the SQLite brute-force path. A single
+# developer's namespace holds far fewer; the cap is a safety valve, logged if hit.
+_LOCAL_SCAN_LIMIT = 5000
+
+
+def _cosine_similarity(a: list[float], b: list[float]) -> float:
+    dot = sum(x * y for x, y in zip(a, b, strict=False))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    if na == 0.0 or nb == 0.0:
+        return 0.0
+    return dot / (na * nb)
+
+
+@dataclass
+class RetrievedItem:
+    item_id: str
+    namespace: str
+    type: str
+    content: str
+    similarity: float
+    score: float
+    created_at: datetime
+
+
+@dataclass
+class RetrievalResult:
+    query: str
+    items: list[RetrievedItem]
+
+    def as_context_block(self, max_chars: int = 4000) -> str:
+        """Compact, normalized context for prompt injection."""
+        if not self.items:
+            return ""
+        lines = ["# Relevant memory (shared, vendor-neutral)"]
+        used = len(lines[0])
+        for it in self.items:
+            entry = f"- ({it.type}) {it.content.strip()}"
+            if used + len(entry) > max_chars:
+                break
+            lines.append(entry)
+            used += len(entry)
+        return "\n".join(lines)
+
+
+class MemoryService:
+    def __init__(self, session: AsyncSession, embedder: Embedder | None = None) -> None:
+        self._session = session
+        self._embedder = embedder or get_embedder()
+        cfg = get_settings().config().get("memory", {}).get("retrieval", {})
+        self._top_k = int(cfg.get("top_k", 8))
+        self._relevance_w = float(cfg.get("relevance_weight", 0.7))
+        self._recency_w = float(cfg.get("recency_weight", 0.3))
+
+    async def retrieve(
+        self,
+        *,
+        workspace_slug: str,
+        query: str,
+        session_id: str | None = None,
+        project: str | None = None,
+        top_k: int | None = None,
+    ) -> RetrievalResult:
+        MEMORY_QUERIES.inc()
+        top_k = top_k or self._top_k
+        [qvec] = await self._embedder.embed([query])
+        now = datetime.now(UTC)
+
+        # Scope-aware, isolation-preserving filter:
+        #  - workspace-scoped items anywhere under ws/<slug>[/project] (incl. the
+        #    provider/* sub-namespaces written by memory extraction);
+        #  - session-scoped items ONLY for the session being queried.
+        ws_prefix = workspace_ns(workspace_slug, project=project)
+        ns_filter = and_(
+            MemoryItem.scope == MemoryScope.workspace,
+            or_(MemoryItem.namespace == ws_prefix,
+                MemoryItem.namespace.like(f"{ws_prefix}/%")),
+        )
+        if session_id:
+            sess_prefix = session_ns(workspace_slug, session_id, project=project)
+            ns_filter = or_(ns_filter, MemoryItem.namespace == sess_prefix)
+        ttl_ok = (MemoryItem.ttl_expires_at.is_(None)) | (MemoryItem.ttl_expires_at > now)
+
+        # Only consider embeddings produced by the active embedder model to avoid
+        # silent corruption from mixed-model vectors in the cosine distance space.
+        model_filter = MemoryEmbedding.model == self._embedder.model
+
+        if await SqliteVecIndex.loaded_for_session(self._session):
+            # SQLite + sqlite-vec ANN path: KNN via vec0 virtual table, then
+            # join back to MemoryItem for namespace/TTL/model filters.
+            # We over-fetch (top_k * 4) candidate item_ids from the vec table
+            # (which holds ALL embeddings regardless of namespace/TTL/model),
+            # then filter via a normal ORM query so namespace isolation,
+            # TTL expiry, and model consistency are strictly enforced.
+            # This is correct because vec_memory rows are only written when
+            # the active embedder is used (see ingest_memory / reindex_memory),
+            # so model drift is handled at write time, not query time.
+            await SqliteVecIndex.ensure_table(self._session, self._embedder.dim)
+            ann_hits = await SqliteVecIndex.search(
+                self._session, qvec, k=top_k * 4
+            )
+            if not ann_hits:
+                rows = []
+            else:
+                ann_item_ids = [item_id for item_id, _ in ann_hits]
+                sim_map = {item_id: sim for item_id, sim in ann_hits}
+                # Resolve item_ids to MemoryItem rows with full filters applied.
+                # item_id in vec_memory is str(item.id) — cast to UUID for the IN clause.
+                try:
+                    ann_uuids = [uuid.UUID(iid) for iid in ann_item_ids]
+                except ValueError:
+                    ann_uuids = []
+                if ann_uuids:
+                    item_stmt = (
+                        select(MemoryItem)
+                        .where(
+                            MemoryItem.id.in_(ann_uuids),
+                            ns_filter,
+                            ttl_ok,
+                        )
+                    )
+                    items_by_id = {
+                        str(item.id): item
+                        for item in (await self._session.execute(item_stmt)).scalars().all()
+                    }
+                    rows = [
+                        (items_by_id[iid], sim_map[iid])
+                        for iid in ann_item_ids
+                        if iid in items_by_id
+                    ]
+                else:
+                    rows = []
+        else:
+            # SQLite (local): embeddings are JSON lists; compute cosine in Python over
+            # the namespace-scoped candidate set.
+            stmt = (
+                select(MemoryItem, MemoryEmbedding.embedding)
+                .join(MemoryEmbedding, MemoryEmbedding.memory_item_id == MemoryItem.id)
+                .where(ns_filter, ttl_ok, model_filter)
+                .limit(_LOCAL_SCAN_LIMIT)
+            )
+            rows = [
+                (item, _cosine_similarity(qvec, emb))
+                for item, emb in (await self._session.execute(stmt)).all()
+                if emb is not None
+            ]
+
+        best: dict[str, RetrievedItem] = {}
+        for item, similarity in rows:
+            score = fuse(
+                similarity,
+                item.created_at,
+                relevance_weight=self._relevance_w,
+                recency_weight=self._recency_w,
+            )
+            key = str(item.id)
+            if key not in best or score > best[key].score:
+                best[key] = RetrievedItem(
+                    item_id=key,
+                    namespace=item.namespace,
+                    type=item.type.value,
+                    content=item.content,
+                    similarity=similarity,
+                    score=score,
+                    created_at=item.created_at,
+                )
+
+        ranked = sorted(best.values(), key=lambda r: r.score, reverse=True)[:top_k]
+        if ranked:
+            MEMORY_HITS.inc()
+        return RetrievalResult(query=query, items=ranked)
+
+
+_REINDEX_BATCH = 64
+
+
+async def reindex_memory(
+    db: AsyncSession,
+    *,
+    workspace_slug: str | None = None,
+    embedder: Embedder | None = None,
+) -> int:
+    """Re-embed all items whose embeddings don't match the active model.
+
+    Iterates MemoryItem rows (optionally namespace-filtered by ``ws/<slug>``
+    prefix), deletes stale-model embeddings, re-embeds content in batches of
+    64 with the active embedder, inserts new MemoryEmbedding rows.  Items that
+    already have an active-model embedding are skipped entirely.
+
+    Returns the count of items actually re-embedded.
+    """
+    embedder = embedder or get_embedder()
+    active_model = embedder.model
+
+    # Build namespace filter when a workspace is specified.
+    if workspace_slug is not None:
+        ns_prefix = workspace_ns(workspace_slug)
+        ns_filter = or_(
+            MemoryItem.namespace == ns_prefix,
+            MemoryItem.namespace.like(f"{ns_prefix}/%"),
+        )
+    else:
+        ns_filter = None  # type: ignore[assignment]
+
+    # Load all candidate items (no TTL filter — reindex is a maintenance op).
+    item_stmt = select(MemoryItem)
+    if ns_filter is not None:
+        item_stmt = item_stmt.where(ns_filter)
+    items: list[MemoryItem] = list(
+        (await db.execute(item_stmt)).scalars().all()
+    )
+
+    # Determine which items already have an active-model embedding so we can skip them.
+    if not items:
+        return 0
+
+    item_ids = [i.id for i in items]
+    active_emb_stmt = select(MemoryEmbedding.memory_item_id).where(
+        MemoryEmbedding.memory_item_id.in_(item_ids),
+        MemoryEmbedding.model == active_model,
+    )
+    already_current: set[uuid.UUID] = set(
+        (await db.execute(active_emb_stmt)).scalars().all()
+    )
+
+    stale_items = [i for i in items if i.id not in already_current]
+    if not stale_items:
+        return 0
+
+    # Delete all embeddings for stale items (regardless of model — a clean slate
+    # avoids having multiple embedding rows for the same chunk if the batch
+    # were ever to be run twice).
+    stale_ids = [i.id for i in stale_items]
+    await db.execute(
+        delete(MemoryEmbedding).where(
+            MemoryEmbedding.memory_item_id.in_(stale_ids)
+        )
+    )
+
+    # Also purge stale items from the vec0 ANN table so it stays consistent.
+    # Drop and recreate the table to handle dim/model transitions: a stale-dim
+    # table would error forever on first upsert after an embedder switch.
+    vec_loaded = await SqliteVecIndex.loaded_for_session(db)
+    if vec_loaded:
+        await SqliteVecIndex.drop_table(db)
+        await SqliteVecIndex.ensure_table(db, embedder.dim)
+
+    # Re-embed in batches of up to _REINDEX_BATCH chunks (batched across items).
+    # Mirror ingest's _chunk() so long items retain the same chunk granularity
+    # they had at ingest time — avoids recall regression and embedder truncation.
+    reindexed = 0
+    # Build a flat list of (item, chunk_idx, chunk_text) triples to batch efficiently.
+    all_chunks: list[tuple[MemoryItem, int, str]] = []
+    for item in stale_items:
+        for idx, chunk_text in enumerate(_chunk(item.content)):
+            all_chunks.append((item, idx, chunk_text))
+
+    for batch_start in range(0, len(all_chunks), _REINDEX_BATCH):
+        batch = all_chunks[batch_start : batch_start + _REINDEX_BATCH]
+        texts = [chunk_text for _, _, chunk_text in batch]
+        vectors = await embedder.embed(texts)
+        for (item, chunk_idx, chunk_text), vec in zip(batch, vectors, strict=True):
+            db.add(
+                MemoryEmbedding(
+                    memory_item_id=item.id,
+                    chunk_idx=chunk_idx,
+                    model=active_model,
+                    embedding=vec,
+                    meta={"chars": len(chunk_text), "reindexed": True},
+                )
+            )
+            if vec_loaded:
+                # Mirror re-embedded vector back into the ANN table.
+                await SqliteVecIndex.upsert(db, str(item.id), chunk_idx, vec)
+        log.debug("reindex_memory: re-embedded %d chunks (batch)", len(batch))
+
+    reindexed = len(stale_items)
+
+    await db.flush()
+    log.info("reindex_memory: re-embedded %d items total (model=%s)", reindexed, active_model)
+    return reindexed

harness/memory/sqlite_vec_backend.py

@@ -0,0 +1,266 @@
+"""Optional sqlite-vec ANN index backend for memory search.
+
+This module provides ``SqliteVecIndex``, an optional accelerator for the SQLite
+retrieval path.  When the ``sqlite-vec`` package is installed, the vec0 virtual
+table gives sub-millisecond ANN search even for thousands of memory embeddings
+— a large improvement over the O(N) brute-force cosine in Python that the base
+path uses.
+
+DDL that was empirically verified to work with sqlite-vec 0.1.9::
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS vec_memory
+        USING vec0(
+            embedding float[{dim}] distance_metric=cosine,
+            +item_id text,
+            +chunk_idx integer
+        )
+
+The ``+`` prefix marks ``item_id`` and ``chunk_idx`` as *auxiliary* (non-indexed)
+payload columns.  Without the prefix vec0 rejects non-embedding columns.
+
+KNN query syntax (verified)::
+
+    SELECT item_id, chunk_idx, distance
+    FROM vec_memory
+    WHERE embedding MATCH ?
+    AND k = ?
+    ORDER BY distance
+
+Vectors must be passed as ``struct.pack("{dim}f", *vec)`` bytes blobs (float32).
+Distance is cosine distance (0 = identical, 2 = opposite); similarity = 1 - distance.
+
+Model-filter design: the vec_memory virtual table intentionally does NOT store
+the embedding model name — vec0 auxiliary columns add overhead and we want the
+table lean.  Correctness is maintained by only writing to vec_memory when the
+embedding model matches the active embedder (callers pass vectors already produced
+by the active model), and by the reindex operation truncating + rebuilding all
+rows whenever a model change is detected (see ``reindex_memory`` in service.py).
+The ANN search therefore has an implicit invariant: all rows in vec_memory were
+produced by the currently-active embedder.  Divergence can only occur during a
+model transition, which is handled by ``reindex_memory`` clearing and rebuilding
+the vec table as part of the same operation.
+
+Public API (async, for production use):
+    SqliteVecIndex.available() -> bool
+    SqliteVecIndex.ensure_table(db: AsyncSession, dim: int) -> None
+    SqliteVecIndex.upsert(db: AsyncSession, item_id: str, chunk_idx: int, vec: list[float]) -> None
+    SqliteVecIndex.search(db: AsyncSession, vec: list[float], k: int) -> list[tuple[str, float]]
+
+Sync API (for tests and sync contexts):
+    SqliteVecIndex.ensure_table_sync(conn, dim)
+    SqliteVecIndex.upsert_sync(conn, item_id, chunk_idx, vec)
+    SqliteVecIndex.search_sync(conn, vec, k) -> list[tuple[str, float]]
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import TYPE_CHECKING
+
+from sqlalchemy import text
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+try:
+    import sqlite_vec as _sqlite_vec  # type: ignore[import]
+except ImportError:
+    _sqlite_vec = None  # type: ignore[assignment]
+
+# Engine-level cache: maps engine id() → bool so we only probe once per engine.
+_engine_vec_loaded: dict[int, bool] = {}
+
+# Module-level memoized result for available() — opening a :memory: connection on
+# every call is unnecessary overhead; the result cannot change within a process.
+_available_cached: bool | None = None
+
+
+def _pack(vec: list[float]) -> bytes:
+    """Pack a Python float list into the float32 blob sqlite-vec expects."""
+    return struct.pack(f"{len(vec)}f", *vec)
+
+
+_CREATE_DDL = """
+CREATE VIRTUAL TABLE IF NOT EXISTS vec_memory
+    USING vec0(
+        embedding float[{dim}] distance_metric=cosine,
+        +item_id text,
+        +chunk_idx integer
+    )
+"""
+
+_SEARCH_SQL = """
+    SELECT item_id, distance
+    FROM vec_memory
+    WHERE embedding MATCH ?
+    AND k = ?
+    ORDER BY distance
+"""
+
+
+class SqliteVecIndex:
+    """Thin façade over the vec0 virtual table.
+
+    All public methods are async (for production use with AsyncSession) and
+    have ``_sync`` equivalents for use in tests with a raw sqlite3.Connection.
+    """
+
+    @staticmethod
+    def available() -> bool:
+        """Return True when sqlite-vec is importable AND loadable.
+
+        The result is memoized at module level — opening a :memory: connection on
+        every call is wasteful; the answer cannot change within a process lifetime.
+        """
+        global _available_cached
+        if _available_cached is not None:
+            return _available_cached
+        if _sqlite_vec is None:
+            _available_cached = False
+            return False
+        try:
+            import sqlite3
+            conn = sqlite3.connect(":memory:")
+            conn.enable_load_extension(True)
+            _sqlite_vec.load(conn)
+            conn.enable_load_extension(False)
+            conn.close()
+            _available_cached = True
+            return True
+        except Exception:  # noqa: BLE001
+            _available_cached = False
+            return False
+
+    @staticmethod
+    async def loaded_for_session(db: AsyncSession) -> bool:  # type: ignore[name-defined]
+        """Return True if the sqlite-vec extension is loaded on this session's connection.
+
+        Probes once per engine (cached in ``_engine_vec_loaded``).  Uses a
+        savepoint so a failed probe does not invalidate the enclosing transaction.
+        Cache is consulted before calling available() to avoid the overhead of the
+        package-level import check on hot paths.
+        """
+        # Fast path: per-engine cache is checked first (avoids available() overhead).
+        engine_key = id(db.get_bind())
+        cached = _engine_vec_loaded.get(engine_key)
+        if cached is not None:
+            return cached
+        # Package-level gate: if sqlite-vec is not importable/loadable, bail out.
+        if not SqliteVecIndex.available():
+            _engine_vec_loaded[engine_key] = False
+            return False
+        try:
+            async with db.begin_nested():
+                await db.execute(text("SELECT vec_version()"))
+            _engine_vec_loaded[engine_key] = True
+            return True
+        except Exception:  # noqa: BLE001
+            _engine_vec_loaded[engine_key] = False
+            return False
+
+    # ------------------------------------------------------------------
+    # Sync helpers — used in tests and by the async wrappers below
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def drop_table_sync(conn) -> None:  # noqa: ANN001
+        """Drop the vec_memory virtual table (used before a dim/model transition)."""
+        conn.execute("DROP TABLE IF EXISTS vec_memory")
+        conn.commit()
+
+    @staticmethod
+    def ensure_table_sync(conn, dim: int) -> None:  # noqa: ANN001
+        """Create the vec_memory virtual table if it doesn't exist."""
+        conn.execute(_CREATE_DDL.format(dim=dim))
+        conn.commit()
+
+    @staticmethod
+    def upsert_sync(conn, item_id: str, chunk_idx: int, vec: list[float]) -> None:  # noqa: ANN001
+        """Insert or replace a vector row.
+
+        vec0 doesn't support ON CONFLICT natively, so we emulate upsert by
+        deleting any existing row for (item_id, chunk_idx) then inserting.
+        """
+        conn.execute(
+            "DELETE FROM vec_memory WHERE item_id = ? AND chunk_idx = ?",
+            (item_id, chunk_idx),
+        )
+        # Use MAX(rowid)+1 to assign a fresh rowid
+        row = conn.execute("SELECT COALESCE(MAX(rowid), 0) FROM vec_memory").fetchone()
+        new_rowid = (row[0] or 0) + 1
+        conn.execute(
+            "INSERT INTO vec_memory (rowid, embedding, item_id, chunk_idx) VALUES (?, ?, ?, ?)",
+            (new_rowid, _pack(vec), item_id, chunk_idx),
+        )
+        conn.commit()
+
+    @staticmethod
+    def search_sync(conn, vec: list[float], k: int) -> list[tuple[str, float]]:  # noqa: ANN001
+        """Return up to ``k`` (item_id, similarity) pairs ordered by similarity desc."""
+        rows = conn.execute(_SEARCH_SQL, (_pack(vec), k)).fetchall()
+        return [(item_id, 1.0 - distance) for item_id, distance in rows]
+
+    # ------------------------------------------------------------------
+    # Async API — uses db.execute(text(...)) for compatibility with
+    # aiosqlite + SQLAlchemy AsyncSession (the session's sync_engine
+    # connect event loads the sqlite-vec extension on every connection).
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    async def drop_table(db: AsyncSession) -> None:
+        """Drop the vec_memory virtual table (used before a dim/model transition)."""
+        await db.execute(text("DROP TABLE IF EXISTS vec_memory"))
+
+    @staticmethod
+    async def ensure_table(db: AsyncSession, dim: int) -> None:
+        """Create the vec_memory virtual table if it doesn't exist (async)."""
+        await db.execute(text(_CREATE_DDL.format(dim=dim)))
+
+    @staticmethod
+    async def upsert(
+        db: AsyncSession, item_id: str, chunk_idx: int, vec: list[float]
+    ) -> None:
+        """Insert or replace a vector row (async)."""
+        blob = _pack(vec)
+        await db.execute(
+            text("DELETE FROM vec_memory WHERE item_id = :iid AND chunk_idx = :ci"),
+            {"iid": item_id, "ci": chunk_idx},
+        )
+        row = (
+            await db.execute(text("SELECT COALESCE(MAX(rowid), 0) FROM vec_memory"))
+        ).fetchone()
+        new_rowid = (row[0] if row else 0) + 1
+        await db.execute(
+            text(
+                "INSERT INTO vec_memory (rowid, embedding, item_id, chunk_idx)"
+                " VALUES (:r, :e, :iid, :ci)"
+            ),
+            {"r": new_rowid, "e": blob, "iid": item_id, "ci": chunk_idx},
+        )
+
+    @staticmethod
+    async def search(
+        db: AsyncSession, vec: list[float], k: int
+    ) -> list[tuple[str, float]]:
+        """Return up to ``k`` (item_id, similarity) pairs, ordered by similarity desc (async)."""
+        blob = _pack(vec)
+        rows = (
+            await db.execute(
+                text(
+                    "SELECT item_id, distance"
+                    " FROM vec_memory"
+                    " WHERE embedding MATCH :q AND k = :k"
+                    " ORDER BY distance"
+                ),
+                {"q": blob, "k": k},
+            )
+        ).fetchall()
+        return [(item_id, 1.0 - dist) for item_id, dist in rows]
+
+    @staticmethod
+    async def delete_item(db: AsyncSession, item_id: str) -> None:
+        """Delete all vec rows for a given item_id (called from reindex)."""
+        await db.execute(
+            text("DELETE FROM vec_memory WHERE item_id = :iid"),
+            {"iid": item_id},
+        )