@sentry/junior-memory 0.132.0 → 0.134.0

package/README.md

@@ -65,7 +65,13 @@ exported types, tools, and tests are authoritative.
 - Search combines independently ranked vector and PostgreSQL full-text matches
   with reciprocal rank fusion; provider-specific raw scores are never added
   together.
-- Automatic recall retrieves a broad candidate window, then uses the
+- Both retrieval legs always run in parallel as bounded top-k probes. Each leg
+  fetches at least the caller's requested limit (and never more than the store
+  limit ceiling). Recall keeps a smaller overfetch window than explicit search
+  and slightly prefers lexical ranks so exact tokens survive soft semantic
+  neighbors. Vector recall also applies the cosine distance cutoff in SQL, and
+  embeddings use an HNSW cosine index (`vector_cosine_ops`).
+- Automatic recall retrieves a bounded candidate window, then uses the
   memory-owned relevance model to admit at most five directly useful memories.
   An empty result contributes no filler prompt text.
 - Every completed automatic recall attempt emits an invisible, namespaced
@@ -80,8 +86,12 @@ exported types, tools, and tests are authoritative.
 
 - `AI_MEMORY_MODEL` or `memoryPlugin({ modelId })` selects the structured
   review model.
-- `MEMORY_RECALL_MAX_VECTOR_DISTANCE` or
-  `recallMaxVectorDistance` configures the vector candidate threshold.
+- `memoryPlugin({ disableRecall: true })` disables automatic prompt recall.
+- `memoryPlugin({ disableExtraction: true })` disables passive session
+  extraction. The two flags are independent and do not disable explicit memory
+  tools.
+- Automatic recall uses a fixed cosine distance cutoff of `0.45` (for
+  `text-embedding-3-small`). Explicit search does not apply that cutoff.
 - Generate schema changes with `pnpm --filter @sentry/junior-memory db:generate`.
 
 Follow `../../policies/data-redaction.md`, `../../policies/security.md`, and the

package/dist/index.js

@@ -167,6 +167,9 @@ var juniorMemoryEmbeddings = pgTable(
       table.dimensions,
       table.metric
     ),
+    // Cosine ANN for vector recall/search. Ops must match cosineDistance (<=>).
+    // Keep this unfiltered so planners can use HNSW before scope/status joins.
+    index("junior_memory_embeddings_embedding_hnsw_idx").using("hnsw", table.embedding.op("vector_cosine_ops")).with({ m: 16, ef_construction: 64 }),
     check(
       "junior_memory_embeddings_metric_check",
       sql`${table.metric} IN ('cosine')`
@@ -181,11 +184,12 @@ var juniorMemoryEmbeddings = pgTable(
 // src/ranking.ts
 var RECIPROCAL_RANK_FUSION_K = 60;
 var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
-function reciprocalRank(rank) {
-  return 1 / (RECIPROCAL_RANK_FUSION_K + rank);
+var DEFAULT_RRF_WEIGHT = 1;
+function reciprocalRank(rank, weight) {
+  return weight / (RECIPROCAL_RANK_FUSION_K + rank);
 }
-function matchScore(match) {
-  return (match.vector ? reciprocalRank(match.vector.rank) : 0) + (match.lexical ? reciprocalRank(match.lexical.rank) : 0);
+function matchScore(match, weights) {
+  return (match.vector ? reciprocalRank(match.vector.rank, weights.vectorWeight) : 0) + (match.lexical ? reciprocalRank(match.lexical.rank, weights.lexicalWeight) : 0);
 }
 function currentChannel(match, channelPrefix) {
   return channelPrefix ? match.sourceKey.startsWith(channelPrefix) : false;
@@ -203,7 +207,14 @@ function observedAgeRank(memory, nowMs) {
   }
   return 0;
 }
+function positiveWeight(value, fallback) {
+  return value !== void 0 && Number.isFinite(value) && value > 0 ? value : fallback;
+}
 function rankMemoryMatches(matches, options) {
+  const weights = {
+    lexicalWeight: positiveWeight(options.lexicalWeight, DEFAULT_RRF_WEIGHT),
+    vectorWeight: positiveWeight(options.vectorWeight, DEFAULT_RRF_WEIGHT)
+  };
   const byId = /* @__PURE__ */ new Map();
   for (const match of matches) {
     const existing = byId.get(match.memory.id);
@@ -218,7 +229,7 @@ function rankMemoryMatches(matches, options) {
     });
   }
   return [...byId.values()].sort((left, right) => {
-    const scoreDelta = matchScore(right) - matchScore(left);
+    const scoreDelta = matchScore(right, weights) - matchScore(left, weights);
     if (scoreDelta !== 0) {
       return scoreDelta;
     }
@@ -344,9 +355,15 @@ var DEFAULT_SEARCH_LIMIT = 10;
 var DEFAULT_EXPIRED_ARCHIVE_LIMIT = 100;
 var PREFERENCE_ADJUDICATION_CANDIDATE_LIMIT = 10;
 var PREFERENCE_ADJUDICATION_VECTOR_LIMIT = 5;
-var VECTOR_SEARCH_OVERFETCH = 4;
+var SEARCH_RETRIEVAL_OVERFETCH = 4;
+var RECALL_RETRIEVAL_OVERFETCH = 2;
+var MAX_RETRIEVAL_LEG_CANDIDATES = 200;
+var MAX_LEXICAL_RANK_CANDIDATES = 200;
+var LEXICAL_RANK_WINDOW_MULTIPLIER = 4;
+var MAX_RETRIEVAL_QUERY_CHARS = 1500;
 var MAX_MEMORY_CONTENT_CHARS = 4e3;
 var EMBEDDING_METRIC = "cosine";
+var RECALL_MAX_VECTOR_DISTANCE = 0.45;
 var nonEmptyStringSchema2 = z2.string().min(1);
 var memoryContentSchema = z2.string().refine((content) => content.trim().length > 0, {
   message: "Memory content is required."
@@ -890,12 +907,31 @@ async function listVisibleMemories(args) {
   ).limit(limit);
   return rows.map(parseMemoryRow);
 }
+function normalizeRetrievalQuery(query) {
+  const normalized = query.replace(/\s+/g, " ").trim();
+  if (normalized.length <= MAX_RETRIEVAL_QUERY_CHARS) {
+    return normalized;
+  }
+  return normalized.slice(0, MAX_RETRIEVAL_QUERY_CHARS).trimEnd();
+}
+function retrievalLegLimit(limit, overfetch) {
+  const requested = Math.max(1, limit);
+  const withOverfetch = requested * Math.max(1, overfetch);
+  return Math.min(
+    MAX_RETRIEVAL_LEG_CANDIDATES,
+    Math.max(requested, withOverfetch)
+  );
+}
 async function searchVisibleLexicalMemories(args) {
   const predicate = activeVisiblePredicate(args);
   if (!predicate) {
     return [];
   }
-  const queryVector = sql2`to_tsvector('english', ${args.query})`;
+  const query = normalizeRetrievalQuery(args.query);
+  if (!query) {
+    return [];
+  }
+  const queryVector = sql2`to_tsvector('english', ${query})`;
   const tsquery = sql2`(
     SELECT COALESCE(
       string_agg(quote_literal(term), ' | ')::tsquery,
@@ -903,16 +939,40 @@ async function searchVisibleLexicalMemories(args) {
     )
     FROM unnest(tsvector_to_array(${queryVector})) AS query_terms(term)
   )`;
-  const textsearch = juniorMemoryMemories.searchVector;
-  const textRank = sql2`ts_rank_cd(${textsearch}, ${tsquery})`;
-  const rows = await args.db.select({
-    memory: juniorMemoryMemories,
-    textRank
-  }).from(juniorMemoryMemories).where(and(predicate, sql2`${textsearch} @@ ${tsquery}`)).orderBy(
-    desc(textRank),
+  const candidateLimit = Math.min(
+    MAX_LEXICAL_RANK_CANDIDATES,
+    args.limit * LEXICAL_RANK_WINDOW_MULTIPLIER
+  );
+  const candidates = args.db.select().from(juniorMemoryMemories).where(
+    and(predicate, sql2`${juniorMemoryMemories.searchVector} @@ ${tsquery}`)
+  ).orderBy(
     desc(juniorMemoryMemories.observedAtMs),
     asc(juniorMemoryMemories.id)
-  ).limit(args.limit);
+  ).limit(candidateLimit).as("lexical_candidates");
+  const textRank = sql2`ts_rank_cd(${candidates.searchVector}, ${tsquery})`;
+  const rows = await args.db.select({
+    memory: {
+      archiveReason: candidates.archiveReason,
+      archivedAtMs: candidates.archivedAtMs,
+      content: candidates.content,
+      createdAtMs: candidates.createdAtMs,
+      expiresAtMs: candidates.expiresAtMs,
+      id: candidates.id,
+      idempotencyKey: candidates.idempotencyKey,
+      kind: candidates.kind,
+      observedAtMs: candidates.observedAtMs,
+      scope: candidates.scope,
+      scopeKey: candidates.scopeKey,
+      searchVector: candidates.searchVector,
+      sourceKey: candidates.sourceKey,
+      sourcePlatform: candidates.sourcePlatform,
+      subjectKey: candidates.subjectKey,
+      subjectType: candidates.subjectType,
+      supersededAtMs: candidates.supersededAtMs,
+      supersededById: candidates.supersededById
+    },
+    textRank
+  }).from(candidates).orderBy(desc(textRank), desc(candidates.observedAtMs), asc(candidates.id)).limit(args.limit);
   const ranks = denseRanks(rows, (row) => Number(row.textRank));
   return rows.map((row, index2) => ({
     lexical: { rank: ranks[index2] },
@@ -928,9 +988,13 @@ async function searchVisibleVectorMemories(args) {
   if (!predicate) {
     return [];
   }
+  const query = normalizeRetrievalQuery(args.query);
+  if (!query) {
+    return [];
+  }
   let embedding;
   try {
-    embedding = await embedOne(args.embedder, args.query);
+    embedding = await embedOne(args.embedder, query);
   } catch {
     return [];
   }
@@ -938,6 +1002,7 @@ async function searchVisibleVectorMemories(args) {
     juniorMemoryEmbeddings.embedding,
     embedding.vector
   );
+  const distancePredicate = args.maxDistance === void 0 ? void 0 : sql2`${distance} <= ${args.maxDistance}`;
   const rows = await args.db.select({
     contentHash: juniorMemoryEmbeddings.contentHash,
     distance,
@@ -951,7 +1016,8 @@ async function searchVisibleVectorMemories(args) {
       eq(juniorMemoryEmbeddings.provider, embedding.provider),
       eq(juniorMemoryEmbeddings.model, embedding.model),
       eq(juniorMemoryEmbeddings.dimensions, MEMORY_EMBEDDING_DIMENSIONS),
-      eq(juniorMemoryEmbeddings.metric, EMBEDDING_METRIC)
+      eq(juniorMemoryEmbeddings.metric, EMBEDDING_METRIC),
+      ...distancePredicate ? [distancePredicate] : []
     )
   ).orderBy(
     distance,
@@ -964,9 +1030,6 @@ async function searchVisibleVectorMemories(args) {
     if (row.distance === null || !Number.isFinite(distanceValue) || hashEmbeddedContent(row.memory.content) !== row.contentHash) {
       return [];
     }
-    if (args.maxDistance !== void 0 && distanceValue > args.maxDistance) {
-      return [];
-    }
     return [
       {
         memory: parseMemoryRow(row.memory),
@@ -982,7 +1045,6 @@ function createMemoryStore(db, context, options = {}) {
   const runtimeContext = memoryRuntimeContextSchema.parse(context);
   const parsedOptions = memoryStoreOptionsSchema.parse({ now: options.now });
   const embedder = options.embedder;
-  const maxVectorDistance = options.maxVectorDistance;
   const supersessionDecider = options.supersessionDecider;
   const getNowMs = parsedOptions.now ?? Date.now;
   async function archiveExpiredVisibleMemories(input, nowMs) {
@@ -1195,7 +1257,8 @@ function createMemoryStore(db, context, options = {}) {
       scopes
     });
     const limit = boundedLimit(input.limit, DEFAULT_SEARCH_LIMIT);
-    const candidateLimit = limit * VECTOR_SEARCH_OVERFETCH;
+    const overfetch = vectorMaxDistance === void 0 ? SEARCH_RETRIEVAL_OVERFETCH : RECALL_RETRIEVAL_OVERFETCH;
+    const candidateLimit = retrievalLegLimit(limit, overfetch);
     const [vectorMatches, lexicalMatches] = await Promise.all([
       searchVisibleVectorMemories({
         db,
@@ -1217,6 +1280,8 @@ function createMemoryStore(db, context, options = {}) {
     const channelPrefix = sourceChannelPrefix(runtimeContext);
     return rankMemoryMatches([...vectorMatches, ...lexicalMatches], {
       nowMs,
+      // Slight lexical preference protects exact ids/names/timezones on ties.
+      ...vectorMaxDistance === void 0 ? {} : { lexicalWeight: 1, vectorWeight: 0.85 },
       ...channelPrefix ? { channelPrefix } : {}
     }).slice(0, limit).map(({ memory }) => memory);
   }
@@ -1263,7 +1328,7 @@ function createMemoryStore(db, context, options = {}) {
       });
     },
     async recallMemories(input) {
-      return await retrieveVisibleMemories(input, maxVectorDistance);
+      return await retrieveVisibleMemories(input, RECALL_MAX_VECTOR_DISTANCE);
     },
     async searchMemories(input) {
       return await retrieveVisibleMemories(input, void 0);
@@ -3143,8 +3208,7 @@ async function createMemoryPromptContributions(context) {
     }
   } : void 0;
   const candidates = await createMemoryStore(context.db, runtimeContext, {
-    ...embedder ? { embedder } : {},
-    ...context.maxVectorDistance !== void 0 ? { maxVectorDistance: context.maxVectorDistance } : {}
+    embedder
   }).recallMemories({
     query: context.text,
     limit: RECALL_CANDIDATE_LIMIT
@@ -3456,8 +3520,6 @@ function createMemoryUserPage() {
 
 // src/plugin.ts
 var MEMORY_MODEL_ENV = "AI_MEMORY_MODEL";
-var MEMORY_RECALL_MAX_VECTOR_DISTANCE_ENV = "MEMORY_RECALL_MAX_VECTOR_DISTANCE";
-var DEFAULT_RECALL_MAX_VECTOR_DISTANCE = 0.45;
 function memoryModelId(options) {
   const explicitModelId = options.modelId?.trim();
   if (explicitModelId) {
@@ -3466,19 +3528,6 @@ function memoryModelId(options) {
   const envModelId = process.env[MEMORY_MODEL_ENV]?.trim();
   return envModelId || void 0;
 }
-function recallMaxVectorDistance(options) {
-  if (options.recallMaxVectorDistance !== void 0) {
-    return options.recallMaxVectorDistance;
-  }
-  const raw = process.env[MEMORY_RECALL_MAX_VECTOR_DISTANCE_ENV]?.trim();
-  if (raw) {
-    const parsed = Number(raw);
-    if (Number.isFinite(parsed) && parsed > 0) {
-      return Math.min(parsed, 1);
-    }
-  }
-  return DEFAULT_RECALL_MAX_VECTOR_DISTANCE;
-}
 function memoryToolContext(ctx) {
   return {
     agent: ctx.agent,
@@ -3514,7 +3563,7 @@ function memoryPlugin(options = {}) {
     cli: {
       commands: [createMemoryCliCommand()]
     },
-    tasks: {
+    tasks: options.disableExtraction ? {} : {
       processSession: {
         async run(ctx) {
           await processMemorySession(ctx);
@@ -3564,20 +3613,21 @@ function memoryPlugin(options = {}) {
           searchMemories: createMemorySearchTool(context)
         };
       },
-      async userPrompt(ctx) {
-        return await createMemoryPromptContributions({
-          agent: createMemoryAgent(ctx.model),
-          ...ctx.conversationId ? { conversationId: ctx.conversationId } : {},
-          ...ctx.actor ? { actor: ctx.actor } : {},
-          db: ctx.db,
-          embedder: ctx.embedder,
-          events: ctx.events,
-          log: ctx.log,
-          maxVectorDistance: recallMaxVectorDistance(options),
-          source: ctx.source,
-          text: ctx.text
-        });
-      }
+      ...!options.disableRecall ? {
+        async userPrompt(ctx) {
+          return await createMemoryPromptContributions({
+            agent: createMemoryAgent(ctx.model),
+            ...ctx.conversationId ? { conversationId: ctx.conversationId } : {},
+            ...ctx.actor ? { actor: ctx.actor } : {},
+            db: ctx.db,
+            embedder: ctx.embedder,
+            events: ctx.events,
+            log: ctx.log,
+            source: ctx.source,
+            text: ctx.text
+          });
+        }
+      } : {}
     }
   });
 }