@sentry/junior-memory 0.119.0 → 0.121.0

package/src/plugin.ts

@@ -1,5 +1,6 @@
 import { defineJuniorPlugin } from "@sentry/junior-plugin-api";
 import { createMemoryAgent } from "./agent";
+import { createMemoryApi } from "./api";
 import { createMemoryCliCommand } from "./cli";
 import {
   createMemoryCreateTool,
@@ -12,6 +13,7 @@ import {
 } from "./tools";
 import { processMemorySession } from "./process-session";
 import { createMemoryPromptContributions } from "./recall";
+import { buildMemoryOperationalReport } from "./operational-report";
 import type { MemoryDb } from "./store";
 import { createMemoryUserPage } from "./user-pages";
 
@@ -110,6 +112,18 @@ export function memoryPlugin(options: MemoryPluginOptions = {}) {
     },
     userPages: [createMemoryUserPage()],
     hooks: {
+      async operationalReport(ctx) {
+        return await buildMemoryOperationalReport({
+          db: ctx.db as MemoryDb,
+          nowMs: ctx.nowMs,
+        });
+      },
+      apiRoutes(ctx) {
+        return createMemoryApi({
+          actors: ctx.viewer.actors,
+          db: ctx.db as MemoryDb,
+        });
+      },
       tools(ctx) {
         const agent = createMemoryAgent(ctx.model);
         const context = memoryToolContext({
@@ -135,10 +149,12 @@ export function memoryPlugin(options: MemoryPluginOptions = {}) {
       },
       async userPrompt(ctx) {
         return await createMemoryPromptContributions({
+          agent: createMemoryAgent(ctx.model),
           ...(ctx.conversationId ? { conversationId: ctx.conversationId } : {}),
           ...(ctx.actor ? { actor: ctx.actor } : {}),
           db: ctx.db as MemoryDb,
           embedder: ctx.embedder,
+          log: ctx.log,
           maxVectorDistance: recallMaxVectorDistance(options),
           source: ctx.source,
           text: ctx.text,

package/src/ranking.ts

@@ -0,0 +1,98 @@
+import type { MemoryRecord } from "./store";
+
+const RECIPROCAL_RANK_FUSION_K = 60;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+
+export interface MemoryMatch {
+  exactIdentifier: boolean;
+  lexical?: {
+    rank: number;
+  };
+  memory: MemoryRecord;
+  sourceKey: string;
+  vector?: {
+    rank: number;
+  };
+}
+
+function reciprocalRank(rank: number): number {
+  return 1 / (RECIPROCAL_RANK_FUSION_K + rank);
+}
+
+function matchScore(match: MemoryMatch): number {
+  return (
+    (match.vector ? reciprocalRank(match.vector.rank) : 0) +
+    (match.lexical ? reciprocalRank(match.lexical.rank) : 0)
+  );
+}
+
+function currentChannel(
+  match: Pick<MemoryMatch, "sourceKey">,
+  channelPrefix: string | undefined,
+): boolean {
+  return channelPrefix ? match.sourceKey.startsWith(channelPrefix) : false;
+}
+
+function observedAgeRank(memory: MemoryRecord, nowMs: number): number {
+  const ageMs = Math.max(0, nowMs - memory.observedAtMs);
+  if (ageMs <= 7 * ONE_DAY_MS) {
+    return 3;
+  }
+  if (ageMs <= 30 * ONE_DAY_MS) {
+    return 2;
+  }
+  if (ageMs <= 90 * ONE_DAY_MS) {
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * Keep exact structured-identifier matches in the strongest relevance tier,
+ * then fuse lexical and vector ranks without comparing provider raw scores.
+ */
+export function rankMemoryMatches(
+  matches: MemoryMatch[],
+  options: {
+    channelPrefix?: string;
+    nowMs: number;
+  },
+): MemoryMatch[] {
+  const byId = new Map<string, MemoryMatch>();
+  for (const match of matches) {
+    const existing = byId.get(match.memory.id);
+    if (!existing) {
+      byId.set(match.memory.id, match);
+      continue;
+    }
+    byId.set(match.memory.id, {
+      ...existing,
+      exactIdentifier: existing.exactIdentifier || match.exactIdentifier,
+      ...(match.lexical ? { lexical: match.lexical } : {}),
+      ...(match.vector ? { vector: match.vector } : {}),
+    });
+  }
+  return [...byId.values()].sort((left, right) => {
+    const identifierDelta =
+      Number(right.exactIdentifier) - Number(left.exactIdentifier);
+    if (identifierDelta !== 0) {
+      return identifierDelta;
+    }
+    const scoreDelta = matchScore(right) - matchScore(left);
+    if (scoreDelta !== 0) {
+      return scoreDelta;
+    }
+    const channelDelta =
+      Number(currentChannel(right, options.channelPrefix)) -
+      Number(currentChannel(left, options.channelPrefix));
+    if (channelDelta !== 0) {
+      return channelDelta;
+    }
+    return (
+      observedAgeRank(right.memory, options.nowMs) -
+        observedAgeRank(left.memory, options.nowMs) ||
+      right.memory.observedAtMs - left.memory.observedAtMs ||
+      left.memory.id.localeCompare(right.memory.id)
+    );
+  });
+}

package/src/recall.ts

@@ -2,9 +2,11 @@ import {
   definePromptContext,
   type UserPromptContribution,
   type Actor,
+  type PluginLogger,
   type Source,
 } from "@sentry/junior-plugin-api";
 import { z } from "zod";
+import type { MemoryAgent } from "./agent";
 import {
   createMemoryStore,
   type MemoryDb,
@@ -14,13 +16,16 @@ import {
 import { memoryRuntimeContextSchema } from "./types";
 
 const DEFAULT_RECALL_LIMIT = 5;
+const RECALL_CANDIDATE_LIMIT = 20;
 const MAX_PROMPT_CHARS = 4_000;
 const MAX_MEMORY_LINE_CHARS = 600;
 
 export interface MemoryRecallContext {
+  agent: Pick<MemoryAgent, "selectRelevantMemories">;
   conversationId?: string;
   db: MemoryDb;
   embedder?: MemoryEmbeddingProvider;
+  log: PluginLogger;
   /** Maximum cosine distance for vector recall. Passed through to the memory store. */
   maxVectorDistance?: number;
   actor?: Actor;
@@ -103,12 +108,7 @@ const memoryRecallContext = definePromptContext({
   renderPrompt: (content) => renderMemoryPrompt(content.memories),
 });
 
-/**
- * Build active memory recall contributions.
- *
- * Personal recall remains prompt-only so conversation reporting cannot widen
- * actor-scoped memory visibility.
- */
+/** Build active memory recall contributions. */
 export async function createMemoryPromptContributions(
   context: MemoryRecallContext,
 ): Promise<UserPromptContribution[] | undefined> {
@@ -122,21 +122,40 @@ export async function createMemoryPromptContributions(
     ...(context.actor ? { actor: context.actor } : {}),
     source: context.source,
   });
-  const memories = await createMemoryStore(context.db, runtimeContext, {
+  const candidates = await createMemoryStore(context.db, runtimeContext, {
     ...(context.embedder ? { embedder: context.embedder } : {}),
     ...(context.maxVectorDistance !== undefined
       ? { maxVectorDistance: context.maxVectorDistance }
       : {}),
-  }).searchMemories({
+  }).recallMemories({
     query: context.text,
-    limit: DEFAULT_RECALL_LIMIT,
+    limit: RECALL_CANDIDATE_LIMIT,
   });
-  const selected = selectPromptMemories(memories);
-  if (selected.length === 0) {
+  if (candidates.length === 0) {
+    return undefined;
+  }
+  let relevantIds: string[];
+  try {
+    relevantIds = await context.agent.selectRelevantMemories({
+      candidates: candidates.map(({ content, id }) => ({ content, id })),
+      userRequest: context.text,
+    });
+  } catch {
+    // Automatic recall is optional context; a relevance-model failure must not
+    // prevent the user's turn from continuing without recalled memory.
+    context.log.warn("memory_recall_selection_failed");
     return undefined;
   }
-  if (selected.some((memory) => memory.scope === "personal")) {
-    return [{ text: renderMemoryPrompt(selected) }];
+  const candidatesById = new Map(
+    candidates.map((memory) => [memory.id, memory]),
+  );
+  const relevant = relevantIds
+    .map((id) => candidatesById.get(id))
+    .filter((memory): memory is MemoryRecord => memory !== undefined)
+    .slice(0, DEFAULT_RECALL_LIMIT);
+  const selected = selectPromptMemories(relevant);
+  if (selected.length === 0) {
+    return undefined;
   }
   return [memoryRecallContext({ memories: selected })];
 }