@sentry/junior-memory 0.133.0 → 0.135.0

package/src/ranking.ts

@@ -2,6 +2,7 @@ import type { MemoryRecord } from "./store";
 
 const RECIPROCAL_RANK_FUSION_K = 60;
 const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_RRF_WEIGHT = 1;
 
 export interface MemoryMatch {
   lexical?: {
@@ -14,14 +15,21 @@ export interface MemoryMatch {
   };
 }
 
-function reciprocalRank(rank: number): number {
-  return 1 / (RECIPROCAL_RANK_FUSION_K + rank);
+function reciprocalRank(rank: number, weight: number): number {
+  return weight / (RECIPROCAL_RANK_FUSION_K + rank);
 }
 
-function matchScore(match: MemoryMatch): number {
+function matchScore(
+  match: MemoryMatch,
+  weights: { lexicalWeight: number; vectorWeight: number },
+): number {
   return (
-    (match.vector ? reciprocalRank(match.vector.rank) : 0) +
-    (match.lexical ? reciprocalRank(match.lexical.rank) : 0)
+    (match.vector
+      ? reciprocalRank(match.vector.rank, weights.vectorWeight)
+      : 0) +
+    (match.lexical
+      ? reciprocalRank(match.lexical.rank, weights.lexicalWeight)
+      : 0)
   );
 }
 
@@ -46,14 +54,28 @@ function observedAgeRank(memory: MemoryRecord, nowMs: number): number {
   return 0;
 }
 
+function positiveWeight(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isFinite(value) && value > 0
+    ? value
+    : fallback;
+}
+
 /** Fuse lexical and vector ranks without comparing provider raw scores. */
 export function rankMemoryMatches(
   matches: MemoryMatch[],
   options: {
     channelPrefix?: string;
+    /** Optional RRF weight for the lexical leg. Defaults to 1. */
+    lexicalWeight?: number;
     nowMs: number;
+    /** Optional RRF weight for the vector leg. Defaults to 1. */
+    vectorWeight?: number;
   },
 ): MemoryMatch[] {
+  const weights = {
+    lexicalWeight: positiveWeight(options.lexicalWeight, DEFAULT_RRF_WEIGHT),
+    vectorWeight: positiveWeight(options.vectorWeight, DEFAULT_RRF_WEIGHT),
+  };
   const byId = new Map<string, MemoryMatch>();
   for (const match of matches) {
     const existing = byId.get(match.memory.id);
@@ -61,17 +83,31 @@ export function rankMemoryMatches(
       byId.set(match.memory.id, match);
       continue;
     }
+    // Keep the first rank per modality. Shared legs are fused before personal
+    // probes, so a smaller personal top-k cannot overwrite a shared dense rank
+    // with an inflated top rank for the same memory.
     byId.set(match.memory.id, {
       ...existing,
-      ...(match.lexical ? { lexical: match.lexical } : {}),
-      ...(match.vector ? { vector: match.vector } : {}),
+      ...(!existing.lexical && match.lexical
+        ? { lexical: match.lexical }
+        : {}),
+      ...(!existing.vector && match.vector ? { vector: match.vector } : {}),
     });
   }
   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;
     }
+    // Prefer actor preferences over workspace knowledge when RRF ties. Shared
+    // lexical legs often assign the same top rank to recent conversation noise
+    // and a personal-scope probe hit for the same common token.
+    const personalDelta =
+      Number(right.memory.scope === "personal") -
+      Number(left.memory.scope === "personal");
+    if (personalDelta !== 0) {
+      return personalDelta;
+    }
     const channelDelta =
       Number(currentChannel(right, options.channelPrefix)) -
       Number(currentChannel(left, options.channelPrefix));

package/src/recall.ts

@@ -29,8 +29,6 @@ export interface MemoryRecallContext {
   embedder?: MemoryEmbeddingProvider;
   events?: PluginConversationEvents;
   log: PluginLogger;
-  /** Maximum cosine distance for vector recall. Passed through to the memory store. */
-  maxVectorDistance?: number;
   actor?: Actor;
   source: Source;
   text: string;
@@ -159,10 +157,7 @@ export async function createMemoryPromptContributions(
       }
     : undefined;
   const candidates = await createMemoryStore(context.db, runtimeContext, {
-    ...(embedder ? { embedder } : {}),
-    ...(context.maxVectorDistance !== undefined
-      ? { maxVectorDistance: context.maxVectorDistance }
-      : {}),
+    embedder,
   }).recallMemories({
     query: context.text,
     limit: RECALL_CANDIDATE_LIMIT,

package/src/store.ts

@@ -51,11 +51,31 @@ const DEFAULT_SEARCH_LIMIT = 10;
 const DEFAULT_EXPIRED_ARCHIVE_LIMIT = 100;
 const PREFERENCE_ADJUDICATION_CANDIDATE_LIMIT = 10;
 const PREFERENCE_ADJUDICATION_VECTOR_LIMIT = 5;
-const VECTOR_SEARCH_OVERFETCH = 4;
-const LEXICAL_RANK_OVERFETCH = 4;
-const MAX_LEXICAL_RANK_CANDIDATES = 1_000;
+/** Explicit search overfetch: keep a wider fusion window for tool/CLI search. */
+const SEARCH_RETRIEVAL_OVERFETCH = 4;
+/**
+ * Automatic recall overfetch. Recall already asks for ~20 candidates before the
+ * relevance gate, so each hybrid leg only needs a small top-k probe.
+ */
+const RECALL_RETRIEVAL_OVERFETCH = 2;
+/**
+ * Absolute ceiling per retrieval leg. Matches the store limit ceiling so a
+ * single healthy leg can still fill the caller's requested result window.
+ */
+const MAX_RETRIEVAL_LEG_CANDIDATES = 200;
+/** Cap ts_rank_cd work after GIN filtering; ranking is not indexable. */
+const MAX_LEXICAL_RANK_CANDIDATES = 200;
+/** Expand the GIN match window before ts_rank_cd, still under the hard cap. */
+const LEXICAL_RANK_WINDOW_MULTIPLIER = 4;
+/** Bound query text before embedding / FTS construction. */
+const MAX_RETRIEVAL_QUERY_CHARS = 1_500;
 const MAX_MEMORY_CONTENT_CHARS = 4_000;
 const EMBEDDING_METRIC = "cosine";
+/**
+ * Cosine distance cutoff for automatic recall only (not explicit search).
+ * Tuned for text-embedding-3-small; retune if the embedding model changes.
+ */
+const RECALL_MAX_VECTOR_DISTANCE = 0.45;
 
 export type MemoryDb = PgDatabase<PgQueryResultHKT, typeof memorySqlSchema>;
 
@@ -301,8 +321,6 @@ export interface MemorySupersessionDecider {
 
 export interface MemoryStoreOptions {
   embedder?: MemoryEmbeddingProvider;
-  /** Maximum cosine distance for vector recall candidates. Model-dependent; tune when changing AI_EMBEDDING_MODEL. */
-  maxVectorDistance?: number;
   now?: () => number;
   supersessionDecider?: MemorySupersessionDecider;
 }
@@ -949,6 +967,25 @@ async function listVisibleMemories(args: {
   return rows.map(parseMemoryRow);
 }
 
+function normalizeRetrievalQuery(query: string): string {
+  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: number, overfetch: number): number {
+  const requested = Math.max(1, limit);
+  const withOverfetch = requested * Math.max(1, overfetch);
+  // Never return fewer candidates than the caller asked for. A hard overfetch
+  // cap below `limit` under-fills when one modality is empty or both overlap.
+  return Math.min(
+    MAX_RETRIEVAL_LEG_CANDIDATES,
+    Math.max(requested, withOverfetch),
+  );
+}
+
 /** Search a bounded active candidate set with PostgreSQL full-text ranking. */
 async function searchVisibleLexicalMemories(args: {
   db: MemoryDb;
@@ -961,7 +998,11 @@ async function searchVisibleLexicalMemories(args: {
   if (!predicate) {
     return [];
   }
-  const queryVector = sql`to_tsvector('english', ${args.query})`;
+  const query = normalizeRetrievalQuery(args.query);
+  if (!query) {
+    return [];
+  }
+  const queryVector = sql`to_tsvector('english', ${query})`;
   const tsquery = sql`(
     SELECT COALESCE(
       string_agg(quote_literal(term), ' | ')::tsquery,
@@ -969,9 +1010,10 @@ async function searchVisibleLexicalMemories(args: {
     )
     FROM unnest(tsvector_to_array(${queryVector})) AS query_terms(term)
   )`;
+  // GIN filter first, then rank only a bounded recent match window.
   const candidateLimit = Math.min(
     MAX_LEXICAL_RANK_CANDIDATES,
-    args.limit * LEXICAL_RANK_OVERFETCH,
+    args.limit * LEXICAL_RANK_WINDOW_MULTIPLIER,
   );
   const candidates = args.db
     .select()
@@ -1021,33 +1063,29 @@ async function searchVisibleLexicalMemories(args: {
   }));
 }
 
-/** Search active visible records with exact pgvector cosine distance. */
+/** Search active visible records with pgvector cosine distance. */
 async function searchVisibleVectorMemories(args: {
   db: MemoryDb;
-  embedder: MemoryEmbeddingProvider | undefined;
+  embedding: MemoryEmbedding;
   limit: number;
   maxDistance?: number;
   nowMs: number;
-  query: string;
   scopes: ResolvedMemoryScope[];
 }): Promise<MemoryMatch[]> {
-  if (!args.embedder) {
-    return [];
-  }
   const predicate = activeVisiblePredicate(args);
   if (!predicate) {
     return [];
   }
-  let embedding: Awaited<ReturnType<typeof embedOne>>;
-  try {
-    embedding = await embedOne(args.embedder, args.query);
-  } catch {
-    return [];
-  }
+  const embedding = args.embedding;
   const distance = cosineDistance(
     juniorMemoryEmbeddings.embedding,
     embedding.vector,
   );
+  // Push distance cutoff into SQL so recall does not overfetch weak neighbors.
+  const distancePredicate =
+    args.maxDistance === undefined
+      ? undefined
+      : sql`${distance} <= ${args.maxDistance}`;
   const rows = await args.db
     .select({
       contentHash: juniorMemoryEmbeddings.contentHash,
@@ -1066,6 +1104,7 @@ async function searchVisibleVectorMemories(args: {
         eq(juniorMemoryEmbeddings.model, embedding.model),
         eq(juniorMemoryEmbeddings.dimensions, MEMORY_EMBEDDING_DIMENSIONS),
         eq(juniorMemoryEmbeddings.metric, EMBEDDING_METRIC),
+        ...(distancePredicate ? [distancePredicate] : []),
       ),
     )
     .orderBy(
@@ -1084,9 +1123,6 @@ async function searchVisibleVectorMemories(args: {
     ) {
       return [];
     }
-    if (args.maxDistance !== undefined && distanceValue > args.maxDistance) {
-      return [];
-    }
     return [
       {
         memory: parseMemoryRow(row.memory),
@@ -1108,7 +1144,6 @@ export function createMemoryStore(
   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;
 
@@ -1354,6 +1389,19 @@ export function createMemoryStore(
       : { created: false, memory: idempotent.memory };
   }
 
+  /**
+   * Hybrid retrieval for both automatic recall and explicit search.
+   *
+   * Keep both legs parallel and fuse ranks with RRF. Never skip lexical when
+   * vectors already hit: that drops exact/token memories and serializes the
+   * miss path. Each leg is a hard-capped top-k probe so Postgres work stays
+   * bounded even on broad queries.
+   *
+   * Automatic recall also runs personal-scope-only probes. Workspace
+   * conversation memories sharing common tokens (for example "time") can fill
+   * the shared lexical recency window before ranking, which buries older actor
+   * preferences that explicit search still finds.
+   */
   async function retrieveVisibleMemories(
     rawInput: SearchMemoriesInput,
     vectorMaxDistance: number | undefined,
@@ -1367,30 +1415,76 @@ export function createMemoryStore(
       scopes,
     });
     const limit = boundedLimit(input.limit, DEFAULT_SEARCH_LIMIT);
-    const candidateLimit = limit * VECTOR_SEARCH_OVERFETCH;
-    const [vectorMatches, lexicalMatches] = await Promise.all([
-      searchVisibleVectorMemories({
-        db,
-        embedder,
-        limit: candidateLimit,
-        ...(vectorMaxDistance !== undefined
-          ? { maxDistance: vectorMaxDistance }
-          : {}),
-        nowMs,
-        query: input.query,
-        scopes,
-      }),
+    const overfetch =
+      vectorMaxDistance === undefined
+        ? SEARCH_RETRIEVAL_OVERFETCH
+        : RECALL_RETRIEVAL_OVERFETCH;
+    const candidateLimit = retrievalLegLimit(limit, overfetch);
+    const personalScopes = scopes.filter((scope) => scope.scope === "personal");
+    // Automatic recall only: keep a personal-scope probe so workspace noise
+    // cannot monopolize the shared lexical recency window.
+    const probePersonal =
+      vectorMaxDistance !== undefined && personalScopes.length > 0;
+    const query = normalizeRetrievalQuery(input.query);
+    let queryEmbedding: MemoryEmbedding | undefined;
+    if (embedder && query) {
+      try {
+        queryEmbedding = await embedOne(embedder, query);
+      } catch {
+        queryEmbedding = undefined;
+      }
+    }
+    const emptyMatches = Promise.resolve([] as MemoryMatch[]);
+    const lexicalArgs = {
+      db,
+      limit: candidateLimit,
+      nowMs,
+      query: input.query,
+    };
+    // Always run both legs in parallel. Conditional lexical skip is unsafe:
+    // one in-threshold vector distractor can hide a stronger lexical hit.
+    // Embed once up front; vector probes only run when that embedding exists.
+    const matches = await Promise.all([
+      queryEmbedding
+        ? searchVisibleVectorMemories({
+            db,
+            embedding: queryEmbedding,
+            limit: candidateLimit,
+            ...(vectorMaxDistance !== undefined
+              ? { maxDistance: vectorMaxDistance }
+              : {}),
+            nowMs,
+            scopes,
+          })
+        : emptyMatches,
       searchVisibleLexicalMemories({
-        db,
-        limit: candidateLimit,
-        nowMs,
-        query: input.query,
+        ...lexicalArgs,
         scopes,
       }),
+      queryEmbedding && probePersonal
+        ? searchVisibleVectorMemories({
+            db,
+            embedding: queryEmbedding,
+            limit: candidateLimit,
+            maxDistance: vectorMaxDistance,
+            nowMs,
+            scopes: personalScopes,
+          })
+        : emptyMatches,
+      probePersonal
+        ? searchVisibleLexicalMemories({
+            ...lexicalArgs,
+            scopes: personalScopes,
+          })
+        : emptyMatches,
     ]);
     const channelPrefix = sourceChannelPrefix(runtimeContext);
-    return rankMemoryMatches([...vectorMatches, ...lexicalMatches], {
+    return rankMemoryMatches(matches.flat(), {
       nowMs,
+      // Slight lexical preference protects exact ids/names/timezones on ties.
+      ...(vectorMaxDistance === undefined
+        ? {}
+        : { lexicalWeight: 1, vectorWeight: 0.85 }),
       ...(channelPrefix ? { channelPrefix } : {}),
     })
       .slice(0, limit)
@@ -1445,7 +1539,7 @@ export function createMemoryStore(
     },
 
     async recallMemories(input) {
-      return await retrieveVisibleMemories(input, maxVectorDistance);
+      return await retrieveVisibleMemories(input, RECALL_MAX_VECTOR_DISTANCE);
     },
 
     async searchMemories(input) {