@sentry/junior-memory 0.122.1 → 0.123.0

package/dist/store.d.ts

@@ -123,7 +123,11 @@ export type CreateMemoryInput = z.output<typeof createMemoryInputSchema>;
 /** Result of a memory write after idempotency checks. */
 export interface CreateMemoryResult {
     created: boolean;
+    /** True when this call found the memory previously written for the same input identity. */
+    idempotent?: true;
     memory: MemoryRecord;
+    /** Memory ids made inactive by this write. */
+    supersededIds?: string[];
 }
 export type ListMemoriesInput = z.output<typeof listMemoriesInputSchema>;
 export type SearchMemoriesInput = z.output<typeof searchMemoriesInputSchema>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-memory",
-  "version": "0.122.1",
+  "version": "0.123.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.122.1"
+    "@sentry/junior-plugin-api": "0.123.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",

package/src/events.ts

@@ -0,0 +1,59 @@
+import { defineConversationEvent } from "@sentry/junior-plugin-api";
+import { z } from "zod";
+import { MEMORY_KINDS, MEMORY_SCOPES } from "./types";
+import type { MemoryRecord } from "./store";
+
+const MAX_EVENT_PREVIEW_CHARS = 500;
+
+const capturedMemorySchema = z
+  .object({
+    content: z.string().min(1),
+    id: z.string().min(1),
+    kind: z.enum(MEMORY_KINDS),
+    observedAtMs: z.number().finite(),
+    scope: z.enum(MEMORY_SCOPES),
+  })
+  .strict();
+
+function eventPreview(content: string): string {
+  const trimmed = content.trim();
+  if (trimmed.length <= MAX_EVENT_PREVIEW_CHARS) return trimmed;
+  return `${trimmed.slice(0, MAX_EVENT_PREVIEW_CHARS - 3).trimEnd()}...`;
+}
+
+/** Durable transcript event emitted after background memory capture. */
+export const memoriesCapturedEvent = defineConversationEvent({
+  name: "memories_captured",
+  version: 1,
+  schema: z
+    .object({
+      memories: z.array(capturedMemorySchema).min(1).max(100),
+    })
+    .strict(),
+  renderEvent(event) {
+    const count = event.memories.length;
+    return {
+      icon: "brain",
+      title: count === 1 ? "Memory captured" : "Memories captured",
+      preview:
+        count === 1
+          ? eventPreview(event.memories[0]!.content)
+          : `${count} memories`,
+      details: event.memories.map((memory) => ({
+        title: memory.content,
+        metadata: [memory.kind, memory.scope],
+      })),
+    };
+  },
+});
+
+/** Select the stable, safe memory fields retained in conversation history. */
+export function capturedMemory(memory: MemoryRecord) {
+  return {
+    content: memory.content,
+    id: memory.id,
+    kind: memory.kind,
+    observedAtMs: memory.observedAtMs,
+    scope: memory.scope,
+  };
+}

package/src/plugin.ts

@@ -14,6 +14,7 @@ import {
 import { processMemorySession } from "./process-session";
 import { createMemoryPromptContributions } from "./recall";
 import { buildMemoryOperationalReport } from "./operational-report";
+import { memoriesCapturedEvent } from "./events";
 import type { MemoryDb } from "./store";
 import { createMemoryUserPage } from "./user-pages";
 
@@ -100,6 +101,7 @@ export function memoryPlugin(options: MemoryPluginOptions = {}) {
       ? { structuredModelId: modelId }
       : { structuredModel: "default" },
     packageName: "@sentry/junior-memory",
+    conversationEvents: [memoriesCapturedEvent],
     cli: {
       commands: [createMemoryCliCommand()],
     },

package/src/process-session.ts

@@ -10,6 +10,7 @@ import { z } from "zod";
 import {
   createMemoryStore,
   type CreateMemoryInput,
+  type CreateMemoryResult,
   type MemoryDb,
 } from "./store";
 import {
@@ -18,6 +19,7 @@ import {
   type ExtractedMemory,
 } from "./agent";
 import { MEMORY_KINDS, memoryRuntimeContextSchema } from "./types";
+import { capturedMemory, memoriesCapturedEvent } from "./events";
 
 const MEMORY_TOOL_NAMES = new Set([
   "createMemory",
@@ -44,6 +46,21 @@ const extractedMemoryCacheSchema = z.array(
 /** Where a passively extracted memory may be stored, or dropped when unproven. */
 type MemoryRouteTarget = "drop" | "personal" | "conversation";
 
+function recordCapturedMemory(
+  captured: ReturnType<typeof capturedMemory>[],
+  result: CreateMemoryResult,
+): void {
+  const supersededIds = new Set(result.supersededIds ?? []);
+  for (let index = captured.length - 1; index >= 0; index -= 1) {
+    if (supersededIds.has(captured[index]!.id)) {
+      captured.splice(index, 1);
+    }
+  }
+  if (result.created || result.idempotent) {
+    captured.push(capturedMemory(result.memory));
+  }
+}
+
 /** A cited entry is a run-actor durable instruction evidence entry. */
 function isRunActorInstruction(entry: PluginRunTranscriptEntry): boolean {
   return (
@@ -252,6 +269,7 @@ export async function processMemorySession(
     return;
   }
 
+  const captured: ReturnType<typeof capturedMemory>[] = [];
   for (const memory of memories) {
     // The routing gate stays even though extraction is also actor-gated:
     // getTaskMemories caches extraction output for 7 days, so a retry can replay
@@ -262,9 +280,14 @@ export async function processMemorySession(
     }
     const input = passiveInput(run.runId, memory, sourceKey, target);
     if (target === "conversation") {
-      await store.createConversationMemory(input);
+      const result = await store.createConversationMemory(input);
+      recordCapturedMemory(captured, result);
       continue;
     }
-    await store.createMemory(input);
+    const result = await store.createMemory(input);
+    recordCapturedMemory(captured, result);
+  }
+  if (captured.length > 0) {
+    await context.events.emit(memoriesCapturedEvent({ memories: captured }));
   }
 }

package/src/store.ts

@@ -248,7 +248,11 @@ export type CreateMemoryInput = z.output<typeof createMemoryInputSchema>;
 /** Result of a memory write after idempotency checks. */
 export interface CreateMemoryResult {
   created: boolean;
+  /** True when this call found the memory previously written for the same input identity. */
+  idempotent?: true;
   memory: MemoryRecord;
+  /** Memory ids made inactive by this write. */
+  supersededIds?: string[];
 }
 
 export type ListMemoriesInput = z.output<typeof listMemoriesInputSchema>;
@@ -441,12 +445,17 @@ export function activeVisiblePredicate(args: {
 }
 
 /** Resolve retry attempts for the same scoped write idempotency key. */
+interface IdempotencyMatch {
+  memory: MemoryRecord;
+  outcome: "created" | "duplicate";
+}
+
 async function findByIdempotencyKey(args: {
   db: MemoryDb;
   idempotencyKey: string;
   nowMs: number;
   scope: ResolvedMemoryScope;
-}): Promise<MemoryRecord | undefined> {
+}): Promise<IdempotencyMatch | undefined> {
   const activeRows = await args.db
     .select()
     .from(juniorMemoryMemories)
@@ -466,7 +475,7 @@ async function findByIdempotencyKey(args: {
     )
     .limit(1);
   if (activeRows[0]) {
-    return parseMemoryRow(activeRows[0]);
+    return { memory: parseMemoryRow(activeRows[0]), outcome: "created" };
   }
 
   const aliasRows = await args.db
@@ -513,7 +522,7 @@ async function findByIdempotencyKey(args: {
       )
       .limit(1);
     if (rows[0]) {
-      return parseMemoryRow(rows[0]);
+      return { memory: parseMemoryRow(rows[0]), outcome: "duplicate" };
     }
   }
   return undefined;
@@ -1183,13 +1192,15 @@ export function createMemoryStore(
       });
       if (idempotent) {
         await storeEmbedding({
-          content: idempotent.content,
+          content: idempotent.memory.content,
           db,
           embedder,
-          memoryId: idempotent.id,
+          memoryId: idempotent.memory.id,
           nowMs,
         });
-        return { created: false, memory: idempotent };
+        return idempotent.outcome === "created"
+          ? { created: false, idempotent: true, memory: idempotent.memory }
+          : { created: false, memory: idempotent.memory };
       }
     }
 
@@ -1256,7 +1267,7 @@ export function createMemoryStore(
     }
 
     const id = randomUUID();
-    const rows = await db.transaction(async (tx) => {
+    const write = await db.transaction(async (tx) => {
       const inserted = await tx
         .insert(juniorMemoryMemories)
         .values({
@@ -1285,7 +1296,7 @@ export function createMemoryStore(
         .returning();
       const insertedMemory = inserted[0];
       if (!insertedMemory || supersededIds.length === 0) {
-        return inserted;
+        return { inserted, supersededIds: [] };
       }
       const superseded = await tx
         .update(juniorMemoryMemories)
@@ -1311,10 +1322,10 @@ export function createMemoryStore(
           .delete(juniorMemoryEmbeddings)
           .where(inArray(juniorMemoryEmbeddings.memoryId, idsToClean));
       }
-      return inserted;
+      return { inserted, supersededIds: idsToClean };
     });
-    if (rows[0]) {
-      const memory = parseMemoryRow(rows[0]);
+    if (write.inserted[0]) {
+      const memory = parseMemoryRow(write.inserted[0]);
       await storeEmbedding({
         content: memory.content,
         db,
@@ -1323,7 +1334,13 @@ export function createMemoryStore(
         memoryId: memory.id,
         nowMs,
       });
-      return { created: true, memory };
+      return {
+        created: true,
+        memory,
+        ...(write.supersededIds.length > 0
+          ? { supersededIds: write.supersededIds }
+          : {}),
+      };
     }
 
     const idempotent = await findByIdempotencyKey({
@@ -1336,13 +1353,15 @@ export function createMemoryStore(
       throw new Error("Memory idempotency conflict did not resolve.");
     }
     await storeEmbedding({
-      content: idempotent.content,
+      content: idempotent.memory.content,
       db,
       embedder,
-      memoryId: idempotent.id,
+      memoryId: idempotent.memory.id,
       nowMs,
     });
-    return { created: false, memory: idempotent };
+    return idempotent.outcome === "created"
+      ? { created: false, idempotent: true, memory: idempotent.memory }
+      : { created: false, memory: idempotent.memory };
   }
 
   async function retrieveVisibleMemories(

package/src/tools.ts

@@ -420,6 +420,12 @@ function memoryToolResult<TData extends Record<string, unknown>>(
 /** Create a tool that submits an explicit memory candidate for storage. */
 export function createMemoryCreateTool(context: MemoryCreateToolContext) {
   return definePluginTool({
+    annotations: {
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+      readOnlyHint: false,
+    },
     description:
       "Explicit memory-write tool. Use only when the latest user message directly asks Junior to remember, store, save, or forget-and-replace a public/shareable fact. Do not use for ordinary statements like 'I prefer X', 'I use Y', or 'X goes before Y' unless the user also asks you to remember/store/save it; passive memory learning handles those after the visible reply. Pass one self-contained natural-language candidate preserving the user's explicit memory intent. Do not ask the user to rephrase ordinary first-person facts, and do not rewrite them into display-name or third-person wording. Do not include secrets, private personal details, medical/legal/financial/sensitive facts, or another person's personal preference, opinion, habit, identity, relationship, workflow, or private life. Runtime context derives actor, scope, source, and subject ids; the memory agent decides canonical stored content and memory kind, then the plugin derives storage target from kind.",
     executionMode: "sequential",
@@ -506,6 +512,12 @@ export function createMemoryCreateTool(context: MemoryCreateToolContext) {
 /** Create a tool that archives a visible memory in the active context. */
 export function createMemoryRemoveTool(context: MemoryToolContext) {
   return definePluginTool({
+    annotations: {
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false,
+      readOnlyHint: false,
+    },
     description:
       "Forget one memory visible in the active context. Use only ids or short id prefixes returned by listMemories or searchMemories. Never remove memories by hidden actor, Slack, scope, or subject identifiers.",
     executionMode: "sequential",
@@ -535,7 +547,12 @@ export function createMemoryListTool(context: MemoryToolContext) {
   return definePluginTool({
     description:
       "List active memories visible in the current context. Use when the user asks what Junior remembers or when memory ids are needed before removing a memory.",
-    annotations: { readOnlyHint: true, destructiveHint: false },
+    annotations: {
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+      readOnlyHint: true,
+    },
     inputSchema: listMemoriesInputSchema,
     outputSchema: memoryManyOutputSchema,
     execute: async (input) => {
@@ -555,7 +572,12 @@ export function createMemorySearchTool(context: MemoryToolContext) {
   return definePluginTool({
     description:
       "Search active memories visible in the current context. Use when the model needs targeted memory recall. The tool searches only the current actor and active conversation scopes.",
-    annotations: { readOnlyHint: true, destructiveHint: false },
+    annotations: {
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+      readOnlyHint: true,
+    },
     inputSchema: searchMemoriesInputSchema,
     outputSchema: memoryManyOutputSchema,
     execute: async (input) => {