@wrongstack/vector-memory 0.320.1 → 1.0.2

package/dist/index.js

@@ -249,6 +249,11 @@ function encodeVector(vec) {
   return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
 }
 function decodeVector(buf) {
+  if (buf.byteLength % 4 !== 0) {
+    throw new Error(
+      `decodeVector: invalid vector byteLength ${buf.byteLength} (must be a multiple of 4)`
+    );
+  }
   const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
   const copy = new Float32Array(buf.byteLength / 4);
   for (let i = 0; i < copy.length; i++) {
@@ -264,6 +269,12 @@ import * as path from "node:path";
 import { withFileLock } from "@wrongstack/core/utils";
 import { loadRuntimeDatabaseSync } from "@wrongstack/persistence";
 import { cosineSimilarity, HashingEmbeddingProvider } from "@wrongstack/sage";
+var DEFAULT_SEARCH_LIMIT = 10;
+function normalizeLimit(limit) {
+  if (limit === void 0 || !Number.isFinite(limit)) return DEFAULT_SEARCH_LIMIT;
+  const floored = Math.floor(limit);
+  return floored < 1 ? DEFAULT_SEARCH_LIMIT : floored;
+}
 var DEFAULT_DIRECTORY = ".wrongstack/vector-memory";
 var DEFAULT_FILENAME = "vector-memory.db";
 var DEFAULT_LOCK_TIMEOUT_MS = 5e3;
@@ -525,7 +536,7 @@ var VectorMemoryStore = class _VectorMemoryStore {
   }
   async search(query, opts = {}) {
     this.assertOpen();
-    const limit = opts.limit ?? 10;
+    const limit = normalizeLimit(opts.limit);
     const threshold = opts.threshold ?? 0;
     const includeVectors = opts.includeVectors === true;
     if (typeof query !== "string" || query.trim().length === 0) return [];
@@ -554,7 +565,7 @@ var VectorMemoryStore = class _VectorMemoryStore {
       const vec = decodeVector(row.vec_blob);
       const raw = cosineSimilarity(queryVec, vec);
       const score = Math.max(0, Math.min(1, raw));
-      if (score < threshold) continue;
+      if (!Number.isFinite(score) || score < threshold) continue;
       if (top.length >= limit && score <= (top[top.length - 1]?.score ?? 0)) continue;
       let at = top.length;
       while (at > 0 && (top[at - 1]?.score ?? 0) < score) at--;
@@ -1214,30 +1225,26 @@ async function fuseWithVectorMemory(query, lexical, options = {}) {
   }
   const sageById = /* @__PURE__ */ new Map();
   for (const memory of lexical) sageById.set(memory.id, memory);
-  for (const hit of vectorHits) {
-    const sageId = hit.entry.metadata?.["sageId"];
-    if (typeof sageId === "string" && !sageById.has(sageId)) {
-      continue;
-    }
-  }
   const lexicalRanked = lexical.map((memory, index) => ({
     memory,
     rankScore: lexicalRankScore(index, lexical.length),
     lexicalScore: lexicalRankScore(index, lexical.length)
   }));
   const vectorRanked = [];
+  const seenVectorSageIds = /* @__PURE__ */ new Set();
   for (let i = 0; i < vectorHits.length; i++) {
     const hit = vectorHits[i];
     const sageId = hit.entry.metadata?.["sageId"];
-    if (typeof sageId !== "string") continue;
+    if (typeof sageId !== "string" || seenVectorSageIds.has(sageId)) continue;
     const memory = sageById.get(sageId);
     if (!memory) continue;
+    seenVectorSageIds.add(sageId);
     vectorRanked.push({ memory, vectorScore: hit.score });
   }
   const fused = /* @__PURE__ */ new Map();
   for (let i = 0; i < lexicalRanked.length; i++) {
     const c = lexicalRanked[i];
-    const rrf = weight * 0 + (1 - weight) * (1 / (k + i + 1));
+    const rrf = (1 - weight) * (1 / (k + i + 1));
     fused.set(c.memory.id, {
       memory: c.memory,
       vectorScore: null,
@@ -1581,12 +1588,16 @@ async function runSearchRace(query, lexical, vectorStore, options = {}) {
       preview: previewText(mem.text, 140)
     });
   }
+  const overlapById = /* @__PURE__ */ new Map();
+  for (const row of overlap) overlapById.set(row.id, row);
   for (const hit of vectorHits) {
     const sageId = hit.entry.metadata?.["sageId"];
     if (typeof sageId !== "string") continue;
-    const existing = overlap.find((row) => row.id === sageId);
+    const existing = overlapById.get(sageId);
     if (existing) {
-      existing.vectorScore = hit.score;
+      if (existing.vectorScore === null) {
+        existing.vectorScore = hit.score;
+      }
       continue;
     }
     if (seenIds.has(sageId)) continue;
@@ -1598,8 +1609,8 @@ async function runSearchRace(query, lexical, vectorStore, options = {}) {
       preview: previewText(hit.entry.text, 140)
     });
   }
-  for (let i = overlap.length - 1; i >= 0; i--) {
-    const row = overlap[i];
+  const finalOverlap = [];
+  for (const row of overlap) {
     if (row.vectorScore === null) {
       lexicalOnly.push({
         id: row.id,
@@ -1607,26 +1618,25 @@ async function runSearchRace(query, lexical, vectorStore, options = {}) {
         vectorScore: null,
         preview: row.preview
       });
-      overlap.splice(i, 1);
+    } else {
+      finalOverlap.push(row);
     }
   }
-  const lexicalCount = lexicalOnly.length + overlap.length;
-  const vectorCount = vectorOnly.length + overlap.length;
+  const lexicalCount = lexicalOnly.length + finalOverlap.length;
+  const vectorCount = vectorOnly.length + finalOverlap.length;
   const denom = Math.max(lexicalCount, vectorCount, 1);
   return {
     query,
     lexicalOnly,
     vectorOnly,
-    // The sweep above removed every row still carrying a null vectorScore,
-    // so every remaining row holds a real number here.
-    overlap,
+    overlap: finalOverlap,
     metrics: {
       lexicalCount,
       vectorCount,
-      overlapCount: overlap.length,
+      overlapCount: finalOverlap.length,
       lexicalOnlyRatio: lexicalCount === 0 ? 0 : lexicalOnly.length / lexicalCount,
       vectorOnlyRatio: vectorCount === 0 ? 0 : vectorOnly.length / vectorCount,
-      agreementRatio: overlap.length / denom
+      agreementRatio: finalOverlap.length / denom
     }
   };
 }

package/dist/sage-fusion.d.ts

@@ -6,8 +6,15 @@
  *
  * The fusion is a Reciprocal Rank Fusion (RRF)-style blend rather than a
  * raw cosine-blend, so it stays robust when one side returns nothing
- * (e.g. embedding provider unavailable). All inputs are optional:
- *   - `lexical` may be `[]` → fusion falls back to pure vector ranking.
+ * (e.g. embedding provider unavailable).
+ *
+ * IMPORTANT — the vector channel can only RE-RANK the lexical list, never
+ * extend it. A vector hit is kept only when its `metadata.sageId` resolves to
+ * a memory already present in `lexical`, because the caller's lexical list is
+ * the authoritative source of `Sage` objects and this function will not
+ * fabricate one (pinned by tests/sage-fusion.test.ts). Therefore:
+ *   - `lexical` may be `[]` → the result is `[]`, whatever the vector channel
+ *     found. This is NOT a fallback to pure vector ranking.
  *   - `vector` may be `[]` → fusion falls back to pure lexical ranking.
  *   - either may be `undefined` → fusion silently drops that channel.
  *
@@ -40,6 +47,10 @@ export interface SageFusionOptions {
     /**
      * Cosine threshold below which a vector-only hit is dropped (no lexical
      * counterpart to lift it). Default 0 — keep all, let RRF decide.
+     *
+     * Currently inert: vector-only hits cannot occur (see the module docstring),
+     * so nothing ever reaches this threshold. Kept for API stability and for
+     * the day the vector channel is allowed to extend the candidate set.
      */
     vectorOnlyThreshold?: number | undefined;
 }
@@ -51,7 +62,11 @@ export interface SageFusionHit {
     lexicalScore: number | null;
     /** 0..1, monotonically higher = better. */
     finalScore: number;
-    /** Where the candidate came from. */
+    /**
+     * Where the candidate came from. `'vector'` is currently unreachable —
+     * every candidate originates in the lexical list (see the module
+     * docstring); the vector channel only upgrades one to `'both'`.
+     */
     source: 'lexical' | 'vector' | 'both';
 }
 declare function lexicalRankScore(index: number, total: number): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/vector-memory",
-  "version": "0.320.1",
+  "version": "1.0.2",
   "license": "MIT",
   "description": "WrongStack Vector Memory — an additional vector-search memory store powered by @huggingface/transformers (local ONNX embeddings), alongside the SAGE lexical memory system.",
   "repository": {
@@ -27,9 +27,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@wrongstack/core": "0.320.1",
-    "@wrongstack/persistence": "0.320.1",
-    "@wrongstack/sage": "0.320.1"
+    "@wrongstack/core": "1.0.2",
+    "@wrongstack/persistence": "1.0.2",
+    "@wrongstack/sage": "1.0.2"
   },
   "optionalDependencies": {
     "@huggingface/transformers": "^4.2.0"