merge: v2.5.5 — dense-search query-vector cache (perf)

Author: copeus

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers-v",
       "description": "Compound V for Superpowers: triple parallel pre-flight (code archaeology + domain-expert + Context7 library validator), disjoint partitioning, manifest-driven multi-backend dispatch (Claude + Codex + Antigravity + Cursor), git-diff scope enforcement, crash-resumable runs, adaptive tier-based routing, epic mode, V-memory local-first semantic+lexical recall over docs/superpowers (opt-in pure-python embeddings + a deterministic recall→action bridge), and batched parallel dispatch (Opus default, narrow Sonnet exception)",
-      "version": "2.5.4",
+      "version": "2.5.5",
       "source": "./",
       "author": {
         "name": "Oleg",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-v",
   "description": "Compound V for Superpowers: triple parallel pre-flight (code archaeology + domain-expert advisor + library/doc validator via Context7), disjoint file partitioning, manifest-driven multi-backend dispatch (Claude + headless Codex + Antigravity + Cursor workers), git-diff scope enforcement, crash-resumable runs, adaptive tier-based routing, epic mode for multi-feature builds, V-memory local-first semantic+lexical recall over docs/superpowers (opt-in pure-python embeddings + a deterministic recall\u2192action bridge), and batched parallel dispatch (Opus default, Sonnet for narrow junior-task carve-out), plus /v:onboard — a project-onboarding command that builds a citation-verified knowledge base + AGENTS.md/CLAUDE.md bridge behind a human gate. Auto-intercepts brainstorming \u2192 writing-plans \u2192 execution transitions.",
-  "version": "2.5.4",
+  "version": "2.5.5",
   "author": {
     "name": "Oleg",
     "email": "copeus@gmail.com"

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to **superpowers-v (Compound V)** are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses semantic versioning.
 
+## [2.5.5] — 2026-07-05
+
+### Performance
+- **Dense search: repeated queries skip the model load.** Every dense search paid one isolated-venv subprocess = one ONNX model load per query (seconds). A new `query_cache` SQLite table (`sha256(query) + model → vector`, `IF NOT EXISTS` so no migration, bounded to the 500 most-recent rows) lets a repeated query — the common case for `/v:remember` and the recall→action bridge's templated queries — return in milliseconds. A model change misses by key; **identity drift (embedder revision change) clears the cache** alongside the corpus re-embed, so a stale-revision vector is never served; any cache error falls back to embedding (the cache is an optimization, never a failure mode). Selftest proves hit / miss / model-miss / failed-embed-not-cached with a counting fake embedder. Profiled first: the FTS5 lane (rebuild 0.7 s, search 0.28 s, hooks ≤0.25 s) was left untouched — already fast. **Codex cross-model verification caught the stale-vector hazard** — the `(query, model)` key alone can't see an embedder **revision** change (the same drift the corpus re-embed handles), independently confirming the author's own finding — fixed via `_invalidate_query_cache` on the drift branch, plus the extra coverage Codex asked for (different-query miss, cache bound, drift invalidation): 7 cache checks total, all green.
+
 ## [2.5.4] — 2026-07-05
 
 ### Performance

scripts/compound-v-memory.py

@@ -318,6 +318,10 @@ def file_sha(abspath: str) -> str:
   INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
 END;
 CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);
+CREATE TABLE IF NOT EXISTS query_cache (
+  qhash TEXT NOT NULL, model TEXT NOT NULL, vec TEXT NOT NULL, created_at TEXT NOT NULL,
+  PRIMARY KEY (qhash, model)
+);
 """
 
 
@@ -648,6 +652,7 @@ def cmd_refresh(args) -> int:
         if embedder is not None:
             if not identity_matches(conn, model):
                 to_index = list(files)  # identity drift ⇒ re-embed the whole corpus
+                _invalidate_query_cache(conn)  # …and drop stale query vectors (same drift)
             else:
                 missing = {r[0] for r in conn.execute(
                     "SELECT DISTINCT path FROM chunks WHERE embedding IS NULL")}
@@ -704,11 +709,56 @@ def bm25_search(conn, q, limit):
     return [dict(id=r[0], path=r[1], heading=r[2], text=r[3], doc_type=r[4], date=r[5]) for r in rows]
 
 
-def dense_search(conn, paths, model, q, limit):
-    vecs = embed_texts(paths, model, "query", [q])
+QUERY_CACHE_MAX = 500
+
+
+def _invalidate_query_cache(conn):
+    """Drop every cached query vector. Called on embedder IDENTITY DRIFT (embedder_src /
+    fingerprint changed while the model NAME stayed the same): the corpus is re-embedded by the
+    new revision, so query vectors from the old revision must never be compared against it —
+    the (qhash, model) key alone cannot see a revision change (Codex-caught)."""
+    try:
+        conn.execute("DELETE FROM query_cache")
+        conn.commit()
+    except sqlite3.Error:
+        pass
+
+
+def _query_vec(conn, paths, model, q, embed=None):
+    """The query embedding, with a small SQLite cache. A repeated query skips the isolated-venv
+    embedder subprocess entirely — otherwise EVERY dense search pays one ONNX model load
+    (seconds). Keyed by (sha256(query), model), so a model change naturally misses; bounded to
+    QUERY_CACHE_MAX most-recent rows. Degrade-safe: any cache problem falls back to embedding."""
+    qh = hashlib.sha256(q.encode("utf-8")).hexdigest()
+    try:
+        row = conn.execute("SELECT vec FROM query_cache WHERE qhash=? AND model=?",
+                           (qh, model)).fetchone()
+        if row:
+            return json.loads(row[0])
+    except (sqlite3.Error, ValueError, TypeError):
+        pass
+    embed = embed or (lambda texts: embed_texts(paths, model, "query", texts))
+    vecs = embed([q])
     if not vecs:
+        return None
+    if vecs[0] is None:
+        return None
+    try:
+        conn.execute("INSERT OR REPLACE INTO query_cache(qhash,model,vec,created_at) "
+                     "VALUES(?,?,?,?)", (qh, model, json.dumps(vecs[0]), _now()))
+        conn.execute("DELETE FROM query_cache WHERE rowid NOT IN "
+                     "(SELECT rowid FROM query_cache ORDER BY created_at DESC, rowid DESC LIMIT ?)",
+                     (QUERY_CACHE_MAX,))
+        conn.commit()
+    except sqlite3.Error:
+        pass  # cache is an optimization, never a failure mode
+    return vecs[0]
+
+
+def dense_search(conn, paths, model, q, limit):
+    qv = _query_vec(conn, paths, model, q)
+    if not qv:
         return []
-    qv = vecs[0]
     rows = conn.execute(
         "SELECT id,path,heading,text,doc_type,date,embedding FROM chunks WHERE embedding IS NOT NULL"
     ).fetchall()
@@ -1083,6 +1133,31 @@ def _fake_embed(texts):
         check("reindex_batch: failed embed degrades to NULL (FTS5-only), no crash",
               _tot > 0 and _nul == _tot)
 
+        # --- v2.5.5: query-vector cache — a repeated query skips the embedder (model load) ---
+        _qc = {"n": 0}
+
+        def _fake_q(texts):
+            _qc["n"] += 1
+            return [[1.0, 2.0]]
+        v1 = _query_vec(conn, None, "m1", "scope gate", embed=_fake_q)
+        v2 = _query_vec(conn, None, "m1", "scope gate", embed=_fake_q)   # cache HIT
+        check("query cache: repeat query skips the embedder (1 call, same vec)",
+              _qc["n"] == 1 and v1 == v2 == [1.0, 2.0])
+        _query_vec(conn, None, "m2", "scope gate", embed=_fake_q)        # model change -> MISS
+        check("query cache: model change misses (re-embeds)", _qc["n"] == 2)
+        check("query cache: failed embed returns None, nothing cached",
+              _query_vec(conn, None, "m3", "x", embed=lambda t: None) is None
+              and conn.execute("SELECT COUNT(*) FROM query_cache WHERE model='m3'").fetchone()[0] == 0)
+        _query_vec(conn, None, "m1", "different query", embed=_fake_q)  # new query -> MISS
+        check("query cache: different query misses (re-embeds)", _qc["n"] == 3)
+        for i in range(QUERY_CACHE_MAX + 30):                            # bound holds
+            _query_vec(conn, None, "m1", "bulk-%d" % i, embed=_fake_q)
+        check("query cache: bounded to QUERY_CACHE_MAX rows",
+              conn.execute("SELECT COUNT(*) FROM query_cache").fetchone()[0] <= QUERY_CACHE_MAX)
+        _invalidate_query_cache(conn)                                    # identity drift wipe
+        check("query cache: identity drift invalidation empties the cache",
+              conn.execute("SELECT COUNT(*) FROM query_cache").fetchone()[0] == 0)
+
         # lock: a held lock makes a second acquire a no-op (separate open file descriptions)
         fd = acquire_lock(paths["lock"])
         fd2 = acquire_lock(paths["lock"])