@wrongstack/vector-memory 0.320.1 → 1.0.0

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 [];
@@ -1214,12 +1225,6 @@ 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),
@@ -1237,7 +1242,7 @@ async function fuseWithVectorMemory(query, lexical, options = {}) {
   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,

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.0",
   "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.0",
+    "@wrongstack/persistence": "1.0.0",
+    "@wrongstack/sage": "1.0.0"
   },
   "optionalDependencies": {
     "@huggingface/transformers": "^4.2.0"