flurryx-code-memory 0.4.0__py3-none-any.whl

code_memory/config.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+
+# Config file name (project-local and global). KEY=VALUE per line, '#'
+# starts a comment. Real shell env always wins; project file beats
+# global file. Layering exists so users can pin defaults once
+# (~/.config/code-memory/config) and override per repo
+# (./.code-memoryrc) without polluting the shell rc.
+_RC_BASENAME = ".code-memoryrc"
+_GLOBAL_RC = (
+    Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config")))
+    / "code-memory"
+    / "config"
+)
+
+
+def _parse_rc(path: Path) -> dict[str, str]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    out: dict[str, str] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].lstrip()
+        key, sep, val = line.partition("=")
+        if not sep:
+            continue
+        key = key.strip()
+        val = val.strip()
+        # Strip matching surrounding quotes if any.
+        if len(val) >= 2 and val[0] == val[-1] and val[0] in ("'", '"'):
+            val = val[1:-1]
+        if key:
+            out[key] = val
+    return out
+
+
+def _project_rc() -> Path | None:
+    """Locate project rc: cwd, then walk up to git toplevel."""
+    cwd = Path.cwd()
+    candidate = cwd / _RC_BASENAME
+    if candidate.is_file():
+        return candidate
+    top = _git_toplevel(cwd)
+    if top is not None:
+        candidate = top / _RC_BASENAME
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _load_rc_into_environ() -> None:
+    """Populate os.environ with rc-file values without overriding the
+    real shell. Project rc beats global rc.
+
+    Precedence (highest → lowest):
+        real shell env > ./.code-memoryrc > ~/.config/code-memory/config
+    """
+    # Apply global first so the project pass can shadow it. Neither
+    # pass overrides anything already in the shell environment.
+    for source in (_GLOBAL_RC, _project_rc()):
+        if source is None:
+            continue
+        for k, v in _parse_rc(source).items():
+            if k not in os.environ:
+                os.environ[k] = v
+
+
+def _env(key: str, default: str) -> str:
+    return os.environ.get(key, default)
+
+
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+# Sentinel values for ``CODE_MEMORY_PROJECT`` that mean "infer from cwd"
+# rather than "use a project literally named this". Recognising these
+# avoids the silent footgun of indexing into a namespace called ``auto``.
+_AUTO_SENTINELS = frozenset({"", "auto", "default"})
+
+
+def slugify(name: str) -> str:
+    s = _SLUG_RE.sub("-", name.lower()).strip("-")
+    return s or "default"
+
+
+def _git_toplevel(start: Path) -> Path | None:
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(start), "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=2,
+        )
+    except (FileNotFoundError, subprocess.SubprocessError):
+        return None
+    if out.returncode != 0:
+        return None
+    top = out.stdout.strip()
+    return Path(top) if top else None
+
+
+# Populate os.environ from rc files *before* the ``Config`` dataclass
+# defaults are evaluated (those are computed at module import via
+# ``_env(...)`` calls in field defaults). Real shell env still wins.
+_load_rc_into_environ()
+
+
+# Vector dimensionality of the embedding models we ship recipes for.
+# Used to default ``EMBED_DIM`` when the operator only sets
+# ``EMBED_MODEL``. Saves the silent-mismatch footgun where the model
+# emits 768-d vectors but the Qdrant collection was created for 1024.
+# Keys are matched case-insensitively against the leading model name
+# (anything before ``:``), so ``bge-m3:latest``, ``bge-m3:567m-fp16``,
+# and ``BAAI/bge-m3`` all resolve to the same dim.
+_KNOWN_MODEL_DIMS: dict[str, int] = {
+    # bge family
+    "bge-m3": 1024,
+    "baai/bge-m3": 1024,
+    "bge-large-en": 1024,
+    "bge-base-en": 768,
+    "bge-small-en": 384,
+    # mixedbread
+    "mxbai-embed-large": 1024,
+    # snowflake
+    "snowflake-arctic-embed:s": 384,
+    "snowflake-arctic-embed:m": 768,
+    "snowflake-arctic-embed:l": 1024,
+}
+
+
+def resolve_embed_dim(model_name: str, override: int = 0) -> int:
+    """Return the vector dim for ``model_name``, honouring ``override``.
+
+    ``override > 0`` wins (operators with a custom model still in
+    control). Otherwise look up the model's base name in the known
+    table. Falls back to ``1024`` (bge-m3 default) with a print to
+    stderr so the operator notices we're guessing.
+    """
+    if override > 0:
+        return override
+    lower = model_name.strip().lower()
+    # Try the full name (so ``snowflake-arctic-embed:s`` matches its
+    # own dim, not the parent family's). Fall back to the bare base
+    # name (so ``bge-m3:latest`` still resolves via ``bge-m3``).
+    if lower in _KNOWN_MODEL_DIMS:
+        return _KNOWN_MODEL_DIMS[lower]
+    base = lower.split(":", 1)[0]
+    if base in _KNOWN_MODEL_DIMS:
+        return _KNOWN_MODEL_DIMS[base]
+    # Unknown model — fall back to the bge-m3 default but warn so the
+    # operator notices a mismatch before it produces broken vectors.
+    import sys as _sys
+    _sys.stderr.write(
+        f"[code-memory] WARNING: embed model {model_name!r} not in "
+        f"known-dim table; defaulting to 1024. Set EMBED_DIM=<n> to silence.\n"
+    )
+    return 1024
+
+
+def detect_project_slug(root: str | Path | None = None) -> str:
+    """Resolve project slug.
+
+    Priority:
+      1. explicit `root` (path) -> git toplevel basename, else dir name
+      2. CODE_MEMORY_PROJECT env var
+      3. cwd -> git toplevel basename, else cwd name
+    """
+    if root is not None:
+        p = Path(root).resolve()
+        top = _git_toplevel(p if p.is_dir() else p.parent)
+        return slugify((top or p).name)
+
+    env = os.environ.get("CODE_MEMORY_PROJECT", "").strip()
+    if env and env.lower() not in _AUTO_SENTINELS:
+        return slugify(env)
+
+    cwd = Path.cwd()
+    top = _git_toplevel(cwd)
+    return slugify((top or cwd).name)
+
+
+@dataclass(frozen=True)
+class Config:
+    ollama_url: str = _env("OLLAMA_URL", "http://localhost:11434")
+    # TEI (text-embeddings-inference) server URL. Used only when
+    # ``EMBED_BACKEND=tei``. The enterprise-deploy story: stand TEI up
+    # on a GPU host (Linux + CUDA), point ``TEI_URL`` at it, get a
+    # 5-10× cold-ingest speedup over Ollama with the same bge-m3
+    # weights. On Mac there's no GPU advantage and Ollama's Metal path
+    # is faster — leave on the default backend there.
+    tei_url: str = _env("TEI_URL", "http://localhost:8080")
+    embed_model: str = _env("EMBED_MODEL", "bge-m3")
+    # ``embed_dim`` defaults to the dimension of the configured model
+    # so users don't have to keep two env vars in sync. Override with
+    # ``EMBED_DIM`` when running a model not in the known-dim table.
+    embed_dim: int = int(_env("EMBED_DIM", "0"))
+
+    qdrant_url: str = _env("QDRANT_URL", "http://localhost:6333")
+    qdrant_code: str = _env("QDRANT_COLLECTION_CODE", "code_chunks")
+    qdrant_episodes: str = _env("QDRANT_COLLECTION_EPISODES", "episodes")
+    qdrant_claim_entities: str = _env(
+        "QDRANT_COLLECTION_CLAIM_ENTITIES", "claim_entities"
+    )
+    # Semantic index over user-claim triples (subject + predicate + object
+    # + evidence_span). Distinct from ``qdrant_claim_entities`` — that
+    # one stores canonical entity vectors for resolver dedup; this one
+    # stores per-claim vectors so retrieve can return semantically
+    # matching claims alongside code + episodes. SQLite (``claims.db``)
+    # remains source of truth; this collection is rebuildable.
+    qdrant_claims: str = _env("QDRANT_COLLECTION_CLAIMS", "claims")
+
+    falkor_host: str = _env("FALKOR_HOST", "localhost")
+    falkor_port: int = int(_env("FALKOR_PORT", "6379"))
+    falkor_graph: str = _env("FALKOR_GRAPH", "code_graph")
+
+    # Resolved once at import time. Late-binding against `Path.cwd()` would
+    # diverge whenever a long-lived process (MCP server) shares storage
+    # with shell invocations launched from a different cwd, silently
+    # routing writes and reads to different files.
+    episodic_db: Path = Path(_env("EPISODIC_DB", "./data/episodic.db")).resolve()
+    claims_db: Path = Path(_env("CLAIMS_DB", "./data/claims.db")).resolve()
+    data_dir: Path = Path(_env("DATA_DIR", "./data")).resolve()
+
+    # Claim extraction (Graphiti-style user-prompt facts).
+    # Enabled by default. Set CLAIMS_EXTRACTION=false to disable.
+    claims_enabled: bool = _env("CLAIMS_EXTRACTION", "true").strip().lower() in {
+        "1",
+        "true",
+        "yes",
+        "on",
+    }
+    claims_llm_model: str = _env("CLAIMS_LLM_MODEL", "gemma2:9b")
+    claims_llm_timeout: float = float(_env("CLAIMS_LLM_TIMEOUT", "30"))
+    claims_min_confidence: float = float(_env("CLAIMS_MIN_CONFIDENCE", "0.6"))
+    # Cosine similarity at or above which a freshly embedded
+    # subject/object reuses an existing entity instead of creating a new
+    # one. 0.85 is a conservative default — false-merges hurt more than
+    # extra entities (they propagate to every downstream claim).
+    claims_entity_threshold: float = float(
+        _env("CLAIMS_ENTITY_THRESHOLD", "0.85")
+    )
+
+    def for_project(self, slug: str) -> Config:
+        slug = slugify(slug)
+        return replace(
+            self,
+            qdrant_code=f"{self.qdrant_code}__{slug}",
+            qdrant_episodes=f"{self.qdrant_episodes}__{slug}",
+            qdrant_claim_entities=f"{self.qdrant_claim_entities}__{slug}",
+            qdrant_claims=f"{self.qdrant_claims}__{slug}",
+            falkor_graph=f"{self.falkor_graph}__{slug}",
+            episodic_db=self.data_dir / slug / "episodic.db",
+            claims_db=self.data_dir / slug / "claims.db",
+        )
+
+
+CONFIG = Config()

code_memory/embed/__init__.py

@@ -0,0 +1,224 @@
+"""Embedding backends.
+
+Three backends, same :class:`HybridVec` shape:
+
+* :class:`OllamaEmbedder` (default) — dense-only via the Ollama daemon.
+  Keeps the model warm across short-lived CLI processes (per-save
+  reingest hooks, git hooks). Returns ``sparse`` as an empty vector.
+* :class:`M3Embedder` (opt-in via ``EMBED_BACKEND=flagembed``) — dense
+  + sparse from one in-process FlagEmbedding forward pass. Best for
+  long-lived processes (watcher, MCP server) where the cold-load cost
+  is paid once.
+* :class:`TEIEmbedder` (opt-in via ``EMBED_BACKEND=tei``) — dense-only
+  via HuggingFace's `text-embeddings-inference` GPU server. **5-10×
+  cold-ingest speedup vs Ollama on Linux + NVIDIA**, same weights, no
+  recall loss. Set ``TEI_URL`` to point at the TEI daemon (default
+  ``http://localhost:8080``).
+
+All backends are transparently wrapped in :class:`CachedEmbedder` so
+content-hash cache hits skip the model entirely on re-ingest.
+
+Use :func:`get_embedder` for the process-singleton; it reads
+``EMBED_BACKEND`` and dispatches accordingly.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Protocol
+
+from ..config import CONFIG
+from .cache import EmbedCache, hash_chunk
+from .m3 import HybridVec, M3Embedder, SparseVec
+from .ollama import OllamaEmbedder
+from .tei import TEIEmbedder
+
+log = logging.getLogger(__name__)
+
+ENV_BACKEND = "EMBED_BACKEND"
+ENV_DISABLE_CACHE = "EMBED_CACHE_DISABLED"
+
+
+class Embedder(Protocol):
+    """Common shape: produce :class:`HybridVec` per text."""
+
+    def embed(self, texts):  # type: ignore[no-untyped-def]
+        ...
+
+    def embed_one(self, text: str) -> HybridVec: ...
+
+
+class CachedEmbedder:
+    """Embedder that consults a content-hash cache before the inner backend.
+
+    Same ``embed`` / ``embed_one`` shape as the underlying embedder, so
+    callers don't see the cache. The wrapper:
+
+    1. Hashes every requested chunk.
+    2. Pulls cached vectors in one ``IN (?, ?, …)`` SELECT.
+    3. Forwards the miss list to the inner embedder.
+    4. Writes the new vectors back to the cache before returning.
+    5. Reassembles the output in the original input order.
+
+    On a re-ingest where every chunk is unchanged, the inner embedder
+    sees an empty list and returns instantly — the whole vector
+    pipeline collapses to a SQLite scan + Qdrant upsert.
+    """
+
+    def __init__(
+        self,
+        inner: Embedder,
+        cache: EmbedCache,
+        model_id: str,
+    ) -> None:
+        self._inner = inner
+        self._cache = cache
+        self._model_id = model_id
+
+    @property
+    def cache(self) -> EmbedCache:
+        return self._cache
+
+    @property
+    def model_id(self) -> str:
+        return self._model_id
+
+    def embed(self, texts: Sequence[str]) -> list[HybridVec]:
+        if not texts:
+            return []
+        hashes = [hash_chunk(t) for t in texts]
+        cached = self._cache.get_many(hashes, self._model_id)
+        # Build miss-list + remember positions so we can splice results
+        # back into input order.
+        miss_positions: list[int] = []
+        miss_texts: list[str] = []
+        miss_hashes: list[str] = []
+        for i, h in enumerate(hashes):
+            if h not in cached:
+                miss_positions.append(i)
+                miss_texts.append(texts[i])
+                miss_hashes.append(h)
+
+        new_vecs: list[HybridVec] = (
+            self._inner.embed(miss_texts) if miss_texts else []
+        )
+        if new_vecs:
+            self._cache.put_many(
+                zip(miss_hashes, new_vecs, strict=True),
+                model=self._model_id,
+            )
+
+        # Reassemble in original order.
+        out: list[HybridVec] = [None] * len(texts)  # type: ignore[list-item]
+        for i, h in enumerate(hashes):
+            if h in cached:
+                out[i] = cached[h]
+        for pos, vec in zip(miss_positions, new_vecs, strict=True):
+            out[pos] = vec
+        return out  # type: ignore[return-value]
+
+    def embed_one(self, text: str) -> HybridVec:
+        return self.embed([text])[0]
+
+    def close(self) -> None:
+        inner_close = getattr(self._inner, "close", None)
+        if callable(inner_close):
+            inner_close()
+        self._cache.close()
+
+
+_SINGLETON: Embedder | None = None
+
+
+def _resolve_backend() -> str:
+    raw = os.environ.get(ENV_BACKEND, "ollama").strip().lower()
+    if raw in ("flagembed", "flag", "m3", "fastembed"):
+        return "flagembed"
+    if raw in ("tei", "text-embeddings-inference"):
+        return "tei"
+    return "ollama"
+
+
+def _cache_enabled() -> bool:
+    raw = os.environ.get(ENV_DISABLE_CACHE, "").strip().lower()
+    return raw not in ("1", "true", "yes", "on")
+
+
+def _build_inner_embedder(backend: str) -> tuple[Embedder, str]:
+    """Return (embedder, model_id). model_id namespaces the cache.
+
+    Note: the cache key includes only the embedding model name, not
+    the backend — Ollama and TEI serving the *same* ``bge-m3`` weights
+    yield the same vectors (within floating-point tolerance), so the
+    cache hits are interchangeable across backends. Saves the cache
+    cold-start cost when an operator switches Ollama → TEI.
+    """
+    if backend == "flagembed":
+        log.info("embed: backend=flagembed (in-process m3, dense+sparse)")
+        emb_m3 = M3Embedder()
+        # FlagEmbed carries a sparse vector that Ollama/TEI don't —
+        # keep its cache slot separate so dense-only backends never
+        # see (and silently drop) those sparse rows.
+        return emb_m3, f"flagembed:{getattr(emb_m3, 'model_name', 'bge-m3')}"
+    if backend == "tei":
+        log.info("embed: backend=tei (HTTP @ %s, dense-only)", CONFIG.tei_url)
+        emb_tei = TEIEmbedder()
+        return emb_tei, f"model:{getattr(emb_tei, 'model', 'bge-m3')}"
+    log.info("embed: backend=ollama (HTTP, dense-only)")
+    emb = OllamaEmbedder()
+    return emb, f"model:{getattr(emb, 'model', 'bge-m3')}"
+
+
+def get_embedder() -> Embedder:
+    """Process-singleton embedder. First call wins the backend choice.
+
+    The embedder is always wrapped in :class:`CachedEmbedder` unless
+    ``EMBED_CACHE_DISABLED=1`` is set — content-hash cache hits then
+    bypass the inner model entirely on re-ingest.
+    """
+    global _SINGLETON
+    if _SINGLETON is None:
+        backend = _resolve_backend()
+        inner, model_id = _build_inner_embedder(backend)
+        if not _cache_enabled():
+            log.info("embed: cache disabled via %s", ENV_DISABLE_CACHE)
+            _SINGLETON = inner
+        else:
+            cache_path = _cache_db_path()
+            log.info("embed: cache at %s (model=%s)", cache_path, model_id)
+            cache = EmbedCache(cache_path)
+            _SINGLETON = CachedEmbedder(inner=inner, cache=cache, model_id=model_id)
+    return _SINGLETON
+
+
+def _cache_db_path() -> Path:
+    """Cache file lives in ``CONFIG.data_dir`` so it survives ``code-memory
+    reset`` (which only clears the project namespace) and so the same
+    content embedded twice across projects reuses the cached vector.
+    """
+    base = Path(CONFIG.data_dir)
+    base.mkdir(parents=True, exist_ok=True)
+    return base / "embed_cache.sqlite"
+
+
+def set_embedder_for_tests(embedder: Embedder | None) -> None:
+    global _SINGLETON
+    _SINGLETON = embedder
+
+
+__all__ = [
+    "CachedEmbedder",
+    "EmbedCache",
+    "Embedder",
+    "HybridVec",
+    "M3Embedder",
+    "OllamaEmbedder",
+    "SparseVec",
+    "TEIEmbedder",
+    "get_embedder",
+    "hash_chunk",
+    "set_embedder_for_tests",
+]

code_memory/embed/cache.py

@@ -0,0 +1,204 @@
+"""Persistent content-hash embedding cache.
+
+Most enterprise workflows re-ingest the same repo daily after small
+diffs: a few changed files, the rest stable. Without a cache, every
+ingest re-embeds 100% of the corpus — for a 134k-chunk monorepo on
+``bge-m3``/Ollama that's ~1.5 hours of pure inference each run.
+
+This cache fingerprints each chunk's text (SHA-256) plus the embedding
+model name and keys a dense / sparse vector pair on the result. On
+re-ingest, unchanged chunks short-circuit the embedder entirely. Only
+new or modified chunks pay the model cost.
+
+Design choices:
+
+- **SQLite single-file store** so it shares the same lifecycle as
+  ``EpisodicStore`` (one persistent state directory per project). No
+  separate daemon.
+- **Per-model namespacing.** Switching between ``bge-m3`` and
+  ``bge-small-en`` must not pollute results — they live in different
+  rows. Same hash + different model = different cache entries.
+- **Raw float32 BLOBs.** Lighter than JSON; deserialises with a single
+  ``struct.unpack`` call.
+- **Insert-only by default.** Cache is treated as monotonic; a separate
+  ``vacuum`` clears stale entries that haven't been read in N days.
+- **No locking beyond SQLite's default.** Concurrent watch + manual
+  ingest are rare and the upsert path uses ``INSERT OR REPLACE`` so
+  the latest write wins without explicit serialisation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import sqlite3
+import struct
+import time
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+
+from .m3 import HybridVec, SparseVec
+
+log = logging.getLogger(__name__)
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS embed_cache (
+    chunk_hash TEXT NOT NULL,
+    model TEXT NOT NULL,
+    dense BLOB NOT NULL,
+    sparse_idx BLOB,
+    sparse_val BLOB,
+    ts REAL NOT NULL,
+    PRIMARY KEY (chunk_hash, model)
+);
+CREATE INDEX IF NOT EXISTS idx_embed_cache_ts ON embed_cache(ts);
+"""
+
+
+def hash_chunk(text: str) -> str:
+    """SHA-256 of UTF-8 chunk text. Stable, collision-resistant."""
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _pack_floats(values: Sequence[float]) -> bytes:
+    return struct.pack(f"<{len(values)}f", *values)
+
+
+def _unpack_floats(blob: bytes) -> list[float]:
+    n = len(blob) // 4
+    return list(struct.unpack(f"<{n}f", blob))
+
+
+def _pack_ints(values: Sequence[int]) -> bytes:
+    return struct.pack(f"<{len(values)}i", *values)
+
+
+def _unpack_ints(blob: bytes) -> list[int]:
+    n = len(blob) // 4
+    return list(struct.unpack(f"<{n}i", blob))
+
+
+class EmbedCache:
+    """SQLite-backed content-hash cache for embedding vectors.
+
+    Open once per process. Concurrent access is safe but uncoordinated
+    — last write wins. The hot path (``get_many``) issues one
+    parameterised ``SELECT … WHERE chunk_hash IN (…)`` and rebuilds the
+    in-memory mapping; the cold path (``put_many``) batches inserts in
+    one transaction.
+    """
+
+    def __init__(self, path: Path | str) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        # check_same_thread=False so the pipeline + watcher can share
+        # the same instance from different threads. SQLite serialises
+        # writes internally; reads are concurrent.
+        self.conn = sqlite3.connect(self.path, check_same_thread=False)
+        self.conn.executescript(_SCHEMA)
+        self.conn.commit()
+        # Stats so callers can log hit/miss ratios.
+        self.hits = 0
+        self.misses = 0
+
+    # ------------------------------------------------------------ read
+
+    def get_many(
+        self, hashes: Iterable[str], model: str
+    ) -> dict[str, HybridVec]:
+        """Return ``{hash: HybridVec}`` for every cached hash in ``hashes``.
+
+        Missing entries are simply absent from the result dict — the
+        caller decides what to do (typically: build a miss-list and
+        send it to the embedder).
+        """
+        hash_list = list(hashes)
+        if not hash_list:
+            return {}
+        # SQLite's parameter limit is 999 by default; chunk to stay safe.
+        out: dict[str, HybridVec] = {}
+        for i in range(0, len(hash_list), 800):
+            batch = hash_list[i : i + 800]
+            placeholders = ",".join("?" * len(batch))
+            rows = self.conn.execute(
+                f"""
+                SELECT chunk_hash, dense, sparse_idx, sparse_val
+                FROM embed_cache
+                WHERE model = ? AND chunk_hash IN ({placeholders})
+                """,
+                (model, *batch),
+            ).fetchall()
+            for chunk_hash, dense_blob, idx_blob, val_blob in rows:
+                indices = _unpack_ints(idx_blob) if idx_blob else []
+                values = _unpack_floats(val_blob) if val_blob else []
+                out[chunk_hash] = HybridVec(
+                    dense=_unpack_floats(dense_blob),
+                    sparse=SparseVec(indices=indices, values=values),
+                )
+        self.hits += len(out)
+        self.misses += len(hash_list) - len(out)
+        return out
+
+    # ------------------------------------------------------------ write
+
+    def put_many(
+        self,
+        items: Iterable[tuple[str, HybridVec]],
+        model: str,
+    ) -> int:
+        """Insert (hash, vec) pairs for ``model``. Returns count written."""
+        rows = []
+        now = time.time()
+        for chunk_hash, vec in items:
+            rows.append(
+                (
+                    chunk_hash,
+                    model,
+                    _pack_floats(vec.dense),
+                    _pack_ints(vec.sparse.indices) if vec.sparse.indices else None,
+                    _pack_floats(vec.sparse.values) if vec.sparse.values else None,
+                    now,
+                )
+            )
+        if not rows:
+            return 0
+        with self.conn:
+            self.conn.executemany(
+                """
+                INSERT OR REPLACE INTO embed_cache
+                    (chunk_hash, model, dense, sparse_idx, sparse_val, ts)
+                VALUES (?, ?, ?, ?, ?, ?)
+                """,
+                rows,
+            )
+        return len(rows)
+
+    # ----------------------------------------------------------- admin
+
+    def stats(self) -> dict[str, int]:
+        rows = self.conn.execute(
+            "SELECT COUNT(*) FROM embed_cache"
+        ).fetchone()
+        return {
+            "total_entries": int(rows[0]),
+            "hits": self.hits,
+            "misses": self.misses,
+        }
+
+    def vacuum_older_than(self, seconds: float) -> int:
+        """Drop entries last touched before ``now - seconds``."""
+        cutoff = time.time() - seconds
+        cur = self.conn.execute(
+            "DELETE FROM embed_cache WHERE ts < ?", (cutoff,)
+        )
+        self.conn.commit()
+        return cur.rowcount
+
+    def close(self) -> None:
+        self.conn.close()
+
+    def __enter__(self) -> EmbedCache:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()