@sentry/junior-memory 0.79.0 → 0.80.0

package/src/index.ts

@@ -13,4 +13,5 @@ export type {
   MemoryStoreOptions,
   SearchMemoriesInput,
 } from "./store";
-export type { MemoryRuntimeContext } from "./types";
+export { MEMORY_KINDS } from "./types";
+export type { MemoryKind, MemoryRuntimeContext } from "./types";

package/src/process-session.ts

@@ -10,8 +10,16 @@ import {
   type CreateMemoryInput,
   type MemoryDb,
 } from "./store";
-import { createMemoryAgent, type ExtractedMemory } from "./agent";
-import { memoryRuntimeContextSchema } from "./types";
+import {
+  createMemoryAgent,
+  parseExtractedMemory,
+  type ExtractedMemory,
+} from "./agent";
+import {
+  MEMORY_KINDS,
+  memoryRuntimeContextSchema,
+  type MemoryKind,
+} from "./types";
 
 const MEMORY_TOOL_NAMES = new Set([
   "createMemory",
@@ -25,14 +33,24 @@ const extractedMemoryCacheSchema = z.array(
     .object({
       content: z.string().min(1),
       expiresAtMs: z.number().finite().nullable(),
-      target: z.enum(["requester", "conversation"]),
+      kind: z.enum(MEMORY_KINDS),
     })
-    .strict(),
+    .strict()
+    .transform(parseExtractedMemory),
 );
 
+function targetForKind(kind: MemoryKind): "requester" | "conversation" {
+  if (kind === "preference") {
+    return "requester";
+  }
+  return "conversation";
+}
+
 function memoryIdempotencySuffix(memory: ExtractedMemory): string {
   return createHash("sha256")
-    .update(memory.target)
+    .update(targetForKind(memory.kind))
+    .update("\0")
+    .update(memory.kind)
     .update("\0")
     .update(memory.content)
     .update("\0")
@@ -49,6 +67,7 @@ function passiveInput(
   return {
     content: memory.content,
     idempotencyKey: `session:${sourceKey}:${sessionId}:${memoryIdempotencySuffix(memory)}`,
+    kind: memory.kind,
     ...(memory.expiresAtMs !== null ? { expiresAtMs: memory.expiresAtMs } : {}),
   };
 }
@@ -119,6 +138,7 @@ export async function processMemorySession(
   const store = createMemoryStore(context.db as MemoryDb, runtimeContext, {
     embedder: context.embedder,
   });
+  await store.archiveExpiredMemories();
   const memories = await getTaskMemories(context, async () => {
     const existingMemories = await store.searchMemories({
       limit: 10,
@@ -139,7 +159,7 @@ export async function processMemorySession(
 
   for (const memory of memories) {
     const input = passiveInput(run.runId, memory, sourceKey);
-    if (memory.target === "conversation") {
+    if (targetForKind(memory.kind) === "conversation") {
       await store.createConversationMemory(input);
       continue;
     }

package/src/store.ts

@@ -13,8 +13,10 @@ import {
   eq,
   gt,
   ilike,
+  inArray,
   isNull,
   like,
+  lte,
   or,
   sql,
   type SQL,
@@ -30,7 +32,7 @@ import {
   MEMORY_SCOPES,
   MEMORY_SOURCE_PLATFORMS,
   MEMORY_SUBJECT_TYPES,
-  MEMORY_TYPES,
+  MEMORY_KINDS,
   memoryRuntimeContextSchema,
   type MemoryRuntimeContext,
   type MemoryScope,
@@ -44,6 +46,7 @@ import {
 
 const DEFAULT_LIST_LIMIT = 50;
 const DEFAULT_SEARCH_LIMIT = 10;
+const DEFAULT_EXPIRED_ARCHIVE_LIMIT = 100;
 const VECTOR_SEARCH_OVERFETCH = 4;
 const MAX_MEMORY_CONTENT_CHARS = 4_000;
 const EMBEDDING_METRIC = "cosine";
@@ -67,6 +70,7 @@ const createMemoryInputSchema = z
     content: memoryContentSchema,
     expiresAtMs: numberSchema.optional(),
     idempotencyKey: nonEmptyStringSchema,
+    kind: z.enum(MEMORY_KINDS),
   })
   .strict();
 const listMemoriesInputSchema = z
@@ -86,6 +90,11 @@ const archiveMemoryInputSchema = z
     reason: nonEmptyStringSchema.optional(),
   })
   .strict();
+const archiveExpiredMemoriesInputSchema = z
+  .object({
+    limit: numberSchema.optional(),
+  })
+  .strict();
 const clockSchema = z.function({ input: [], output: numberSchema }).optional();
 const memoryStoreOptionsSchema = z
   .object({
@@ -122,7 +131,7 @@ const memoryRowSchema = z
     subjectType: z.enum(MEMORY_SUBJECT_TYPES),
     supersededAtMs: optionalNumberSchema,
     supersededById: optionalStringSchema,
-    type: z.enum(MEMORY_TYPES),
+    kind: z.enum(MEMORY_KINDS),
   })
   .strict()
   .superRefine((row, ctx) => {
@@ -158,7 +167,7 @@ const memoryRecordSchema = z
     subjectType: z.enum(MEMORY_SUBJECT_TYPES),
     supersededAtMs: numberSchema.optional(),
     supersededById: nonEmptyStringSchema.optional(),
-    type: z.enum(MEMORY_TYPES),
+    kind: z.enum(MEMORY_KINDS),
   })
   .strict();
 const embeddingVectorSchema = z
@@ -188,6 +197,14 @@ export type SearchMemoriesInput = z.output<typeof searchMemoriesInputSchema>;
 
 export type ArchiveMemoryInput = z.output<typeof archiveMemoryInputSchema>;
 
+export type ArchiveExpiredMemoriesInput = z.output<
+  typeof archiveExpiredMemoriesInputSchema
+>;
+
+export interface ArchiveExpiredMemoriesResult {
+  archivedCount: number;
+}
+
 export interface MemoryEmbeddingProvider {
   /** Embed normalized memory text for derived vector retrieval. */
   embedTexts(input: { texts: string[] }): Promise<{
@@ -205,6 +222,10 @@ export interface MemoryStoreOptions {
 
 /** Context-bound storage operations for visible long-term memories. */
 export interface MemoryStore {
+  /** Archive expired memories visible in the current runtime context. */
+  archiveExpiredMemories(
+    input?: ArchiveExpiredMemoriesInput,
+  ): Promise<ArchiveExpiredMemoriesResult>;
   /** Archive a visible memory in the current runtime context. */
   archiveMemory(input: ArchiveMemoryInput): Promise<MemoryRecord>;
   /** Store a personal memory for the current requester. */
@@ -254,7 +275,7 @@ function parseMemoryRow(row: unknown): MemoryRecord {
   return memoryRecordSchema.parse({
     id: parsed.id,
     scope: parsed.scope,
-    type: parsed.type,
+    kind: parsed.kind,
     subjectType: parsed.subjectType,
     content: parsed.content,
     observedAtMs: parsed.observedAtMs,
@@ -312,6 +333,7 @@ function activeVisiblePredicate(args: {
 async function findByIdempotencyKey(args: {
   db: MemoryDb;
   idempotencyKey: string;
+  nowMs: number;
   scope: ResolvedMemoryScope;
 }): Promise<MemoryRecord | undefined> {
   const rows = await args.db
@@ -325,12 +347,77 @@ async function findByIdempotencyKey(args: {
         isNull(juniorMemoryMemories.archivedAtMs),
         isNull(juniorMemoryMemories.supersededAtMs),
         isNull(juniorMemoryMemories.supersededById),
+        or(
+          isNull(juniorMemoryMemories.expiresAtMs),
+          gt(juniorMemoryMemories.expiresAtMs, args.nowMs),
+        ),
       ),
     )
     .limit(1);
   return rows[0] ? parseMemoryRow(rows[0]) : undefined;
 }
 
+/**
+ * Archive a bounded batch of expired active rows and remove their derived vectors.
+ */
+async function archiveExpiredMemoryBatch(args: {
+  db: MemoryDb;
+  idempotencyKey?: string;
+  limit?: number;
+  nowMs: number;
+  scopes: ResolvedMemoryScope[];
+}): Promise<ArchiveExpiredMemoriesResult> {
+  const scopePredicate = visibleScopePredicate(args.scopes);
+  if (!scopePredicate) {
+    return { archivedCount: 0 };
+  }
+  const predicates: SQL[] = [
+    scopePredicate,
+    isNull(juniorMemoryMemories.archivedAtMs),
+    isNull(juniorMemoryMemories.supersededAtMs),
+    isNull(juniorMemoryMemories.supersededById),
+    lte(juniorMemoryMemories.expiresAtMs, args.nowMs),
+  ];
+  if (args.idempotencyKey !== undefined) {
+    predicates.push(
+      eq(juniorMemoryMemories.idempotencyKey, args.idempotencyKey),
+    );
+  }
+
+  const archivedIds = await args.db.transaction(async (tx) => {
+    const expired = await tx
+      .select({ id: juniorMemoryMemories.id })
+      .from(juniorMemoryMemories)
+      .where(and(...predicates))
+      .orderBy(
+        asc(juniorMemoryMemories.expiresAtMs),
+        asc(juniorMemoryMemories.id),
+      )
+      .limit(boundedLimit(args.limit, DEFAULT_EXPIRED_ARCHIVE_LIMIT));
+    const ids = expired.map((row) => row.id);
+    if (ids.length === 0) {
+      return [];
+    }
+
+    const archived = await tx
+      .update(juniorMemoryMemories)
+      .set({
+        archivedAtMs: args.nowMs,
+        archiveReason: "expired",
+      })
+      .where(and(inArray(juniorMemoryMemories.id, ids), ...predicates))
+      .returning({ id: juniorMemoryMemories.id });
+    const idsToClean = archived.map((row) => row.id);
+    if (idsToClean.length > 0) {
+      await tx
+        .delete(juniorMemoryEmbeddings)
+        .where(inArray(juniorMemoryEmbeddings.memoryId, idsToClean));
+    }
+    return idsToClean;
+  });
+  return { archivedCount: archivedIds.length };
+}
+
 function searchScore(memory: MemoryRecord, terms: string[]): number {
   const haystack = memory.content.toLowerCase();
   // Lexical score is a retrieval fallback signal, not a memory policy decision.
@@ -591,6 +678,19 @@ export function createMemoryStore(
   const embedder = options.embedder;
   const getNowMs = parsedOptions.now ?? Date.now;
 
+  async function archiveExpiredVisibleMemories(
+    input: ArchiveExpiredMemoriesInput | undefined,
+    nowMs: number,
+  ): Promise<ArchiveExpiredMemoriesResult> {
+    input = archiveExpiredMemoriesInputSchema.parse(input ?? {});
+    return await archiveExpiredMemoryBatch({
+      db,
+      limit: input.limit,
+      nowMs,
+      scopes: deriveVisibleMemoryScopes(runtimeContext),
+    });
+  }
+
   /** Persist a memory under the plugin-derived scope and subject. */
   async function createScopedMemory(
     rawInput: CreateMemoryInput,
@@ -604,6 +704,18 @@ export function createMemoryStore(
     if (content.length > MAX_MEMORY_CONTENT_CHARS) {
       throw new Error("Memory content exceeds the maximum length.");
     }
+    await archiveExpiredMemoryBatch({
+      db,
+      nowMs,
+      scopes: [scope],
+    });
+    await archiveExpiredMemoryBatch({
+      db,
+      idempotencyKey: input.idempotencyKey,
+      limit: 1,
+      nowMs,
+      scopes: [scope],
+    });
 
     const id = randomUUID();
     const rows = await db
@@ -621,7 +733,7 @@ export function createMemoryStore(
         sourcePlatform: runtimeContext.source.platform,
         subjectKey: subject.subjectKey,
         subjectType: subject.subjectType,
-        type: "knowledge",
+        kind: input.kind,
       })
       .onConflictDoNothing({
         target: [
@@ -647,6 +759,7 @@ export function createMemoryStore(
     const idempotent = await findByIdempotencyKey({
       db,
       idempotencyKey: input.idempotencyKey,
+      nowMs,
       scope,
     });
     if (!idempotent) {
@@ -663,6 +776,10 @@ export function createMemoryStore(
   }
 
   return {
+    async archiveExpiredMemories(input) {
+      return await archiveExpiredVisibleMemories(input, getNowMs());
+    },
+
     async createMemory(input) {
       return await createScopedMemory(input, "personal");
     },
@@ -675,6 +792,11 @@ export function createMemoryStore(
       input = listMemoriesInputSchema.parse(input);
       const nowMs = getNowMs();
       const scopes = deriveVisibleMemoryScopes(runtimeContext);
+      await archiveExpiredMemoryBatch({
+        db,
+        nowMs,
+        scopes,
+      });
       return await listVisibleMemories({
         db,
         limit: input.limit,
@@ -687,6 +809,11 @@ export function createMemoryStore(
       input = searchMemoriesInputSchema.parse(input);
       const nowMs = getNowMs();
       const scopes = deriveVisibleMemoryScopes(runtimeContext);
+      await archiveExpiredMemoryBatch({
+        db,
+        nowMs,
+        scopes,
+      });
       const limit = boundedLimit(input.limit, DEFAULT_SEARCH_LIMIT);
       const vectorCandidates = await searchVisibleVectorMemories({
         db,

package/src/tools.ts

@@ -19,7 +19,11 @@ import {
   parseMemoryReview,
   type MemoryAgent,
 } from "./agent";
-import { memoryRuntimeContextSchema, type MemoryRuntimeContext } from "./types";
+import {
+  memoryRuntimeContextSchema,
+  type MemoryKind,
+  type MemoryRuntimeContext,
+} from "./types";
 
 export type MemoryReviewer = Pick<MemoryAgent, "reviewCreateRequest">;
 
@@ -299,18 +303,26 @@ function sourceIdempotencyKey(context: MemoryToolContext): string {
 
 function createInput(
   context: MemoryToolContext,
-  input: { content: string; expiresAtMs?: number },
+  input: { content: string; expiresAtMs?: number; kind: MemoryKind },
   toolCallId: string,
 ) {
   return {
     content: requireMemoryContent(input.content),
     idempotencyKey: `tool:${sourceIdempotencyKey(context)}:${toolCallId}`,
+    kind: input.kind,
     ...(input.expiresAtMs !== undefined
       ? { expiresAtMs: input.expiresAtMs }
       : {}),
   } satisfies CreateMemoryInput;
 }
 
+function targetForKind(kind: MemoryKind): "requester" | "conversation" {
+  if (kind === "preference") {
+    return "requester";
+  }
+  return "conversation";
+}
+
 /** Return the model-visible projection without hidden ownership/source fields. */
 function compactMemory(memory: MemoryRecord) {
   return {
@@ -327,7 +339,7 @@ function compactMemory(memory: MemoryRecord) {
 export function createMemoryCreateTool(context: MemoryToolContext) {
   return {
     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 the canonical stored content, subject, and target.",
+      "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",
     inputSchema: createMemoryInputSchema,
     execute: async (input, options) => {
@@ -382,6 +394,7 @@ export function createMemoryCreateTool(context: MemoryToolContext) {
         context,
         {
           content: review.content,
+          kind: review.kind,
           ...(review.expiresAtMs !== undefined
             ? { expiresAtMs: review.expiresAtMs }
             : requestedExpiresAtMs !== undefined
@@ -392,7 +405,7 @@ export function createMemoryCreateTool(context: MemoryToolContext) {
       );
       const result = await (async () => {
         try {
-          if (review.target === "conversation") {
+          if (targetForKind(review.kind) === "conversation") {
             return await store.createConversationMemory(memoryInput);
           }
           return await store.createMemory(memoryInput);

package/src/types.ts

@@ -7,16 +7,7 @@ import {
 } from "@sentry/junior-plugin-api";
 import { z } from "zod";
 
-export const MEMORY_TYPES = [
-  "preference",
-  "identity",
-  "relationship",
-  "knowledge",
-  "context",
-  "event",
-  "task",
-  "observation",
-] as const;
+export const MEMORY_KINDS = ["preference", "procedure", "knowledge"] as const;
 
 export const MEMORY_SCOPES = ["personal", "conversation"] as const;
 export const MEMORY_SUBJECT_TYPES = [
@@ -31,7 +22,7 @@ export const MEMORY_SOURCE_PLATFORMS = [
 export const MEMORY_EMBEDDING_METRICS = ["cosine"] as const;
 export const MEMORY_EMBEDDING_DIMENSIONS = 1536;
 
-export type MemoryType = (typeof MEMORY_TYPES)[number];
+export type MemoryKind = (typeof MEMORY_KINDS)[number];
 export type MemoryScope = (typeof MEMORY_SCOPES)[number];
 export type MemorySubjectType = (typeof MEMORY_SUBJECT_TYPES)[number];
 export type MemorySourcePlatform = (typeof MEMORY_SOURCE_PLATFORMS)[number];