@sentry/junior-memory 0.80.1 → 0.82.0

package/dist/plugin.d.ts

@@ -1,5 +1,7 @@
 export interface MemoryPluginOptions {
     modelId?: string;
+    /** Maximum cosine distance for vector recall candidates. Defaults to MEMORY_RECALL_MAX_VECTOR_DISTANCE env or 0.45. */
+    recallMaxVectorDistance?: number;
 }
 /** Create Junior's long-term memory plugin registration. */
 export declare function createMemoryPlugin(options?: MemoryPluginOptions): import("@sentry/junior-plugin-api").PluginRegistration;

package/dist/recall.d.ts

@@ -4,6 +4,8 @@ export interface MemoryRecallContext {
     conversationId?: string;
     db: MemoryDb;
     embedder?: MemoryEmbeddingProvider;
+    /** Maximum cosine distance for vector recall. Passed through to the memory store. */
+    maxVectorDistance?: number;
     requester?: Requester;
     source: Source;
     text: string;

package/dist/store.d.ts

@@ -78,9 +78,39 @@ export interface MemoryEmbeddingProvider {
         vectors: number[][];
     }>;
 }
+export interface MemorySupersessionInput {
+    candidate: {
+        content: string;
+        kind: "preference";
+    };
+    existingMemories: [
+        {
+            content: string;
+            id: string;
+        },
+        ...Array<{
+            content: string;
+            id: string;
+        }>
+    ];
+    runtimeContext: MemoryRuntimeContext;
+}
+export type MemorySupersessionDecision = {
+    decision: "supersedes_old";
+    supersededIds: [string, ...string[]];
+} | {
+    decision: "distinct" | "uncertain";
+};
+export interface MemorySupersessionDecider {
+    /** Decide whether a new preference clearly replaces active old preferences. */
+    adjudicateSupersession(input: MemorySupersessionInput): Promise<MemorySupersessionDecision> | MemorySupersessionDecision;
+}
 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;
 }
 /** Context-bound storage operations for visible long-term memories. */
 export interface MemoryStore {

package/dist/tools.d.ts

@@ -1,5 +1,5 @@
 import { type Source, type Requester } from "@sentry/junior-plugin-api";
-import { type MemoryEmbeddingProvider, type MemoryDb } from "./store";
+import { type MemoryEmbeddingProvider, type MemoryDb, type MemorySupersessionDecider } from "./store";
 import { type MemoryAgent } from "./agent";
 export type MemoryReviewer = Pick<MemoryAgent, "reviewCreateRequest">;
 /** Runtime-owned context used to bind memory tools to visible scopes. */
@@ -12,12 +12,15 @@ export interface MemoryToolContext {
     source: Source;
     userText?: string;
 }
+export interface MemoryCreateToolContext extends MemoryToolContext {
+    supersessionDecider?: MemorySupersessionDecider;
+}
 type MemoryWriteToolInput = {
     content: string;
     expires_at?: string;
 };
 /** Create a tool that submits an explicit memory candidate for storage. */
-export declare function createMemoryCreateTool(context: MemoryToolContext): {
+export declare function createMemoryCreateTool(context: MemoryCreateToolContext): {
     description: string;
     executionMode: string;
     inputSchema: import("@sinclair/typebox").TObject<{
@@ -31,6 +34,7 @@ export declare function createMemoryCreateTool(context: MemoryToolContext): {
             expiresAtMs?: number | undefined;
             id: string;
             content: string;
+            observedAtMs: number;
             createdAtMs: number;
         };
     }>;
@@ -50,6 +54,7 @@ export declare function createMemoryRemoveTool(context: MemoryToolContext): {
             expiresAtMs?: number | undefined;
             id: string;
             content: string;
+            observedAtMs: number;
             createdAtMs: number;
         };
     }>;
@@ -72,6 +77,7 @@ export declare function createMemoryListTool(context: MemoryToolContext): {
             expiresAtMs?: number | undefined;
             id: string;
             content: string;
+            observedAtMs: number;
             createdAtMs: number;
         }[];
     }>;
@@ -96,6 +102,7 @@ export declare function createMemorySearchTool(context: MemoryToolContext): {
             expiresAtMs?: number | undefined;
             id: string;
             content: string;
+            observedAtMs: number;
             createdAtMs: number;
         }[];
     }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-memory",
-  "version": "0.80.1",
+  "version": "0.82.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -27,7 +27,7 @@
     "commander": "^14.0.3",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@sentry/junior-plugin-api": "0.80.1"
+    "@sentry/junior-plugin-api": "0.82.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",

package/src/agent.ts

@@ -1,5 +1,9 @@
 import type { PluginModel } from "@sentry/junior-plugin-api";
 import { z } from "zod";
+import type {
+  MemorySupersessionDecision,
+  MemorySupersessionInput,
+} from "./store";
 import { MEMORY_KINDS, memoryRuntimeContextSchema } from "./types";
 
 const memoryKindSchema = z.enum(MEMORY_KINDS);
@@ -62,6 +66,28 @@ const extractSessionRequestSchema = z
       .min(1),
   })
   .strict();
+const supersessionRequestSchema = z
+  .object({
+    candidate: z
+      .object({
+        content: z.string().min(1),
+        kind: z.literal("preference"),
+      })
+      .strict(),
+    existingMemories: z
+      .array(
+        z
+          .object({
+            content: z.string().min(1),
+            id: z.string().min(1),
+          })
+          .strict(),
+      )
+      .min(1)
+      .max(10),
+    runtimeContext: memoryRuntimeContextSchema,
+  })
+  .strict();
 
 const expiresAtMsSchema = z
   .number()
@@ -140,6 +166,19 @@ const extractMemoriesResponseSchema = z
       ),
   })
   .strict();
+const supersessionDecisionResponseSchema = z.discriminatedUnion("decision", [
+  z
+    .object({
+      decision: z.literal("supersedes_old"),
+      supersededIds: z.array(z.string().min(1)).min(1).max(10),
+    })
+    .strict(),
+  z
+    .object({
+      decision: z.enum(["distinct", "uncertain"]),
+    })
+    .strict(),
+]);
 
 type MemoryReviewResponse = z.output<typeof memoryReviewResponseSchema>;
 type ExtractMemoriesResponse = z.output<typeof extractMemoriesResponseSchema>;
@@ -153,6 +192,10 @@ export type ExtractSessionRequest = z.output<
 export type ExtractedMemory = z.output<typeof extractedMemoryResultSchema>;
 
 export interface MemoryAgent {
+  /** Decide whether a new preference safely replaces active old preferences. */
+  adjudicateSupersession(
+    request: MemorySupersessionInput,
+  ): Promise<MemorySupersessionDecision> | MemorySupersessionDecision;
   extractSessionMemories(
     request: ExtractSessionRequest,
   ): Promise<ExtractedMemory[]> | ExtractedMemory[];
@@ -175,6 +218,12 @@ const MEMORY_EXTRACTION_SYSTEM = [
   "Reject secrets, credentials, private or sensitive personal details, gossip, speculative claims about other people, assistant/system implementation details, vague references, and low-durability chatter.",
   "If no public, durable, self-contained memory remains after rewriting, return an empty memories array.",
 ].join("\n");
+const MEMORY_SUPERSESSION_SYSTEM = [
+  "You are Junior's memory supersession agent.",
+  "Decide whether a new requester preference clearly replaces existing active requester preferences.",
+  "Return supersedes_old only for obvious changed preferences about the same mutable slot.",
+  "If the facts are additive, different topics, duplicate, broader/narrower without direct replacement, or uncertain, do not supersede.",
+].join("\n");
 const CANONICAL_CONTENT_RULES = [
   "- Stored memory text must be a rewritten fact, not copied user wording or a sentence about who said it.",
   "- Store the minimum useful assertion supported by source evidence; do not add adjacent steps, caveats, or generalized advice.",
@@ -355,9 +404,52 @@ function sessionExtractionPrompt(request: ExtractSessionRequest): string {
   ].join("\n");
 }
 
+function supersessionPrompt(request: MemorySupersessionInput): string {
+  return [
+    "<memory-supersession-input>",
+    "Decide whether the candidate preference clearly replaces one or more existing active preferences.",
+    "",
+    runtimeDescription({
+      runtimeContext: request.runtimeContext,
+    }),
+    "",
+    "<candidate>",
+    escapeXml(JSON.stringify(request.candidate)),
+    "</candidate>",
+    "",
+    "<existing-memories>",
+    escapeXml(JSON.stringify(request.existingMemories)),
+    "</existing-memories>",
+    "",
+    "<rules>",
+    "- Return supersedes_old only when the candidate and old memory describe the same mutable preference slot and the candidate is the newer value.",
+    "- Examples of same mutable slot: preferred programming language, preferred review style, preferred notification cadence, preferred tool for a task.",
+    "- Do not supersede when the candidate is just more specific, an additional preference, a different task/context, or the same value phrased differently.",
+    "- Do not supersede memories from different topics even if they are both preferences.",
+    "- Only return ids that appear in existing-memories.",
+    "- If unsure, return uncertain.",
+    "</rules>",
+    "</memory-supersession-input>",
+  ].join("\n");
+}
+
 /** Create the memory-owned agent that reviews and extracts memory candidates. */
 export function createMemoryAgent(model: PluginModel): MemoryAgent {
   return {
+    async adjudicateSupersession(rawRequest) {
+      const request = supersessionRequestSchema.parse(
+        rawRequest,
+      ) as MemorySupersessionInput;
+      const result = await model.completeObject({
+        schema: supersessionDecisionResponseSchema,
+        system: MEMORY_SUPERSESSION_SYSTEM,
+        prompt: supersessionPrompt(request),
+        maxTokens: 400,
+      });
+      return supersessionDecisionResponseSchema.parse(
+        result.object,
+      ) as MemorySupersessionDecision;
+    },
     async extractSessionMemories(rawRequest) {
       const request = extractSessionRequestSchema.parse(rawRequest);
       const result = await model.completeObject({

package/src/plugin.ts

@@ -6,6 +6,7 @@ import {
   createMemoryListTool,
   createMemoryRemoveTool,
   createMemorySearchTool,
+  type MemoryCreateToolContext,
   type MemoryReviewer,
   type MemoryToolContext,
 } from "./tools";
@@ -14,9 +15,13 @@ import { createMemoryPromptMessages } from "./recall";
 import type { MemoryDb } from "./store";
 
 const MEMORY_MODEL_ENV = "AI_MEMORY_MODEL";
+const MEMORY_RECALL_MAX_VECTOR_DISTANCE_ENV = "MEMORY_RECALL_MAX_VECTOR_DISTANCE";
+const DEFAULT_RECALL_MAX_VECTOR_DISTANCE = 0.45;
 
 export interface MemoryPluginOptions {
   modelId?: string;
+  /** Maximum cosine distance for vector recall candidates. Defaults to MEMORY_RECALL_MAX_VECTOR_DISTANCE env or 0.45. */
+  recallMaxVectorDistance?: number;
 }
 
 function memoryModelId(options: MemoryPluginOptions): string | undefined {
@@ -28,6 +33,20 @@ function memoryModelId(options: MemoryPluginOptions): string | undefined {
   return envModelId || undefined;
 }
 
+function recallMaxVectorDistance(options: MemoryPluginOptions): number {
+  if (options.recallMaxVectorDistance !== undefined) {
+    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: {
   agent: MemoryReviewer;
   conversationId?: string;
@@ -48,6 +67,22 @@ function memoryToolContext(ctx: {
   };
 }
 
+function memoryCreateToolContext(ctx: {
+  agent: MemoryReviewer;
+  conversationId?: string;
+  db: MemoryCreateToolContext["db"];
+  embedder?: MemoryCreateToolContext["embedder"];
+  requester?: MemoryCreateToolContext["requester"];
+  source: MemoryCreateToolContext["source"];
+  supersessionDecider: MemoryCreateToolContext["supersessionDecider"];
+  userText?: string;
+}): MemoryCreateToolContext {
+  return {
+    ...memoryToolContext(ctx),
+    supersessionDecider: ctx.supersessionDecider,
+  };
+}
+
 /** Create Junior's long-term memory plugin registration. */
 export function createMemoryPlugin(options: MemoryPluginOptions = {}) {
   const modelId = memoryModelId(options);
@@ -73,14 +108,23 @@ export function createMemoryPlugin(options: MemoryPluginOptions = {}) {
     },
     hooks: {
       tools(ctx) {
+        const agent = createMemoryAgent(ctx.model);
         const context = memoryToolContext({
           ...ctx,
-          agent: createMemoryAgent(ctx.model),
+          agent,
           db: ctx.db as MemoryDb,
           embedder: ctx.embedder,
         });
         return {
-          createMemory: createMemoryCreateTool(context),
+          createMemory: createMemoryCreateTool(
+            memoryCreateToolContext({
+              ...ctx,
+              agent,
+              db: ctx.db as MemoryDb,
+              embedder: ctx.embedder,
+              supersessionDecider: agent,
+            }),
+          ),
           removeMemory: createMemoryRemoveTool(context),
           listMemories: createMemoryListTool(context),
           searchMemories: createMemorySearchTool(context),
@@ -92,6 +136,7 @@ export function createMemoryPlugin(options: MemoryPluginOptions = {}) {
           ...(ctx.requester ? { requester: ctx.requester } : {}),
           db: ctx.db as MemoryDb,
           embedder: ctx.embedder,
+          maxVectorDistance: recallMaxVectorDistance(options),
           source: ctx.source,
           text: ctx.text,
         });

package/src/process-session.ts

@@ -135,8 +135,10 @@ export async function processMemorySession(
     ...(run.requester ? { requester: run.requester } : {}),
     source: run.source,
   });
+  const agent = createMemoryAgent(context.model);
   const store = createMemoryStore(context.db as MemoryDb, runtimeContext, {
     embedder: context.embedder,
+    supersessionDecider: agent,
   });
   await store.archiveExpiredMemories();
   const memories = await getTaskMemories(context, async () => {
@@ -144,7 +146,6 @@ export async function processMemorySession(
       limit: 10,
       query: evidenceText,
     });
-    const agent = createMemoryAgent(context.model);
     return await agent.extractSessionMemories({
       existingMemories: existingMemories.map((memory) => ({
         content: memory.content,

package/src/recall.ts

@@ -12,13 +12,15 @@ import {
 import { memoryRuntimeContextSchema } from "./types";
 
 const DEFAULT_RECALL_LIMIT = 5;
-const MAX_PROMPT_CHARS = 1_600;
-const MAX_MEMORY_LINE_CHARS = 320;
+const MAX_PROMPT_CHARS = 4_000;
+const MAX_MEMORY_LINE_CHARS = 600;
 
 export interface MemoryRecallContext {
   conversationId?: string;
   db: MemoryDb;
   embedder?: MemoryEmbeddingProvider;
+  /** Maximum cosine distance for vector recall. Passed through to the memory store. */
+  maxVectorDistance?: number;
   requester?: Requester;
   source: Source;
   text: string;
@@ -32,6 +34,10 @@ function trimContent(content: string, maxLength: number): string {
   return `${trimmed.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
 }
 
+function formatObservedDate(observedAtMs: number): string {
+  return new Date(observedAtMs).toISOString().slice(0, 10);
+}
+
 function renderMemoryPrompt(memories: MemoryRecord[]): string | undefined {
   const header = "Relevant memories for this request:";
   const footer =
@@ -40,7 +46,10 @@ function renderMemoryPrompt(memories: MemoryRecord[]): string | undefined {
   let totalChars = header.length + footer.length + 2;
 
   for (const memory of memories) {
-    const line = `- ${trimContent(memory.content, MAX_MEMORY_LINE_CHARS)}`;
+    const line = `- Observed ${formatObservedDate(memory.observedAtMs)}: ${trimContent(
+      memory.content,
+      MAX_MEMORY_LINE_CHARS,
+    )}`;
     if (totalChars + line.length + 1 > MAX_PROMPT_CHARS) {
       break;
     }
@@ -71,7 +80,12 @@ export async function createMemoryPromptMessages(
   const memories = await createMemoryStore(
     context.db,
     runtimeContext,
-    context.embedder ? { embedder: context.embedder } : {},
+    {
+      ...(context.embedder ? { embedder: context.embedder } : {}),
+      ...(context.maxVectorDistance !== undefined
+        ? { maxVectorDistance: context.maxVectorDistance }
+        : {}),
+    },
   ).searchMemories({
     query: context.text,
     limit: DEFAULT_RECALL_LIMIT,