@sentry/junior-memory 0.80.1 → 0.81.0

package/dist/index.js

@@ -84,6 +84,19 @@ var extractSessionRequestSchema = z2.object({
     ])
   ).min(1)
 }).strict();
+var supersessionRequestSchema = z2.object({
+  candidate: z2.object({
+    content: z2.string().min(1),
+    kind: z2.literal("preference")
+  }).strict(),
+  existingMemories: z2.array(
+    z2.object({
+      content: z2.string().min(1),
+      id: z2.string().min(1)
+    }).strict()
+  ).min(1).max(10),
+  runtimeContext: memoryRuntimeContextSchema
+}).strict();
 var expiresAtMsSchema = z2.number().finite().nullable().describe(
   "Expiration timestamp when the fact should expire, otherwise null."
 );
@@ -134,6 +147,15 @@ var extractMemoriesResponseSchema = z2.object({
     "Accepted public/shareable durable memories from the completed run. Return one object per distinct source assertion and classify it with kind."
   )
 }).strict();
+var supersessionDecisionResponseSchema = z2.discriminatedUnion("decision", [
+  z2.object({
+    decision: z2.literal("supersedes_old"),
+    supersededIds: z2.array(z2.string().min(1)).min(1).max(10)
+  }).strict(),
+  z2.object({
+    decision: z2.enum(["distinct", "uncertain"])
+  }).strict()
+]);
 var MEMORY_REVIEW_SYSTEM = [
   "You are Junior's memory review agent.",
   "Review one memory candidate and return one structured review decision.",
@@ -148,6 +170,12 @@ var 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");
+var 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");
 var 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.",
@@ -302,8 +330,50 @@ function sessionExtractionPrompt(request) {
     "</memory-extraction-input>"
   ].join("\n");
 }
+function supersessionPrompt(request) {
+  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");
+}
 function createMemoryAgent(model) {
   return {
+    async adjudicateSupersession(rawRequest) {
+      const request = supersessionRequestSchema.parse(
+        rawRequest
+      );
+      const result = await model.completeObject({
+        schema: supersessionDecisionResponseSchema,
+        system: MEMORY_SUPERSESSION_SYSTEM,
+        prompt: supersessionPrompt(request),
+        maxTokens: 400
+      });
+      return supersessionDecisionResponseSchema.parse(
+        result.object
+      );
+    },
     async extractSessionMemories(rawRequest) {
       const request = extractSessionRequestSchema.parse(rawRequest);
       const result = await model.completeObject({
@@ -612,6 +682,7 @@ import {
   ilike as ilike2,
   inArray,
   isNull as isNull2,
+  isNotNull,
   like,
   lte,
   or as or2,
@@ -692,9 +763,24 @@ function deriveVisibleMemoryScopes(ctx) {
 var DEFAULT_LIST_LIMIT = 50;
 var DEFAULT_SEARCH_LIMIT = 10;
 var DEFAULT_EXPIRED_ARCHIVE_LIMIT = 100;
+var HIGH_CONFIDENCE_DUPLICATE_DISTANCE = 0.015;
+var SUPERSESSION_CANDIDATE_LIMIT = 10;
 var VECTOR_SEARCH_OVERFETCH = 4;
 var MAX_MEMORY_CONTENT_CHARS = 4e3;
 var EMBEDDING_METRIC = "cosine";
+var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
+var RELEVANCE_NEAR_TIE_DELTA = 0.01;
+var SUPERSESSION_STOP_TERMS = /* @__PURE__ */ new Set([
+  "and",
+  "for",
+  "prefer",
+  "prefers",
+  "preference",
+  "the",
+  "use",
+  "uses",
+  "with"
+]);
 var nonEmptyStringSchema2 = z3.string().min(1);
 var memoryContentSchema = z3.string().refine((content) => content.trim().length > 0, {
   message: "Memory content is required."
@@ -800,6 +886,9 @@ function normalizeContent(content) {
 function hashEmbeddedContent(content) {
   return createHash("sha256").update(content, "utf8").digest("hex");
 }
+function idempotencyAliasId(args) {
+  return `alias:${createHash("sha256").update(args.scope.scope).update("\0").update(args.scope.scopeKey).update("\0").update(args.idempotencyKey).update("\0").update(args.targetId).digest("hex")}`;
+}
 function boundedLimit(value, fallback) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     return fallback;
@@ -865,7 +954,7 @@ function activeVisiblePredicate(args) {
   );
 }
 async function findByIdempotencyKey(args) {
-  const rows = await args.db.select().from(juniorMemoryMemories).where(
+  const activeRows = await args.db.select().from(juniorMemoryMemories).where(
     and2(
       eq3(juniorMemoryMemories.scope, args.scope.scope),
       eq3(juniorMemoryMemories.scopeKey, args.scope.scopeKey),
@@ -879,7 +968,49 @@ async function findByIdempotencyKey(args) {
       )
     )
   ).limit(1);
-  return rows[0] ? parseMemoryRow(rows[0]) : void 0;
+  if (activeRows[0]) {
+    return parseMemoryRow(activeRows[0]);
+  }
+  const aliasRows = await args.db.select({ supersededById: juniorMemoryMemories.supersededById }).from(juniorMemoryMemories).where(
+    and2(
+      eq3(juniorMemoryMemories.scope, args.scope.scope),
+      eq3(juniorMemoryMemories.scopeKey, args.scope.scopeKey),
+      eq3(juniorMemoryMemories.idempotencyKey, args.idempotencyKey),
+      isNull2(juniorMemoryMemories.archivedAtMs),
+      isNotNull(juniorMemoryMemories.supersededAtMs),
+      isNotNull(juniorMemoryMemories.supersededById),
+      or2(
+        isNull2(juniorMemoryMemories.expiresAtMs),
+        gt2(juniorMemoryMemories.expiresAtMs, args.nowMs)
+      )
+    )
+  ).orderBy(
+    desc2(juniorMemoryMemories.createdAtMs),
+    asc(juniorMemoryMemories.id)
+  );
+  for (const alias of aliasRows) {
+    if (!alias.supersededById) {
+      continue;
+    }
+    const rows = await args.db.select().from(juniorMemoryMemories).where(
+      and2(
+        eq3(juniorMemoryMemories.id, alias.supersededById),
+        eq3(juniorMemoryMemories.scope, args.scope.scope),
+        eq3(juniorMemoryMemories.scopeKey, args.scope.scopeKey),
+        isNull2(juniorMemoryMemories.archivedAtMs),
+        isNull2(juniorMemoryMemories.supersededAtMs),
+        isNull2(juniorMemoryMemories.supersededById),
+        or2(
+          isNull2(juniorMemoryMemories.expiresAtMs),
+          gt2(juniorMemoryMemories.expiresAtMs, args.nowMs)
+        )
+      )
+    ).limit(1);
+    if (rows[0]) {
+      return parseMemoryRow(rows[0]);
+    }
+  }
+  return void 0;
 }
 async function archiveExpiredMemoryBatch(args) {
   const scopePredicate = visibleScopePredicate(args.scopes);
@@ -951,7 +1082,7 @@ async function embedOne(embedder, text2) {
   };
 }
 async function storeEmbedding(args) {
-  if (!args.embedder) {
+  if (!args.embedder && !args.embedding) {
     return;
   }
   try {
@@ -963,10 +1094,18 @@ async function storeEmbedding(args) {
     return;
   }
   let embedding;
-  try {
-    embedding = await embedOne(args.embedder, args.content);
-  } catch {
-    return;
+  if (args.embedding) {
+    embedding = args.embedding;
+  } else {
+    const embedder = args.embedder;
+    if (!embedder) {
+      return;
+    }
+    try {
+      embedding = await embedOne(embedder, args.content);
+    } catch {
+      return;
+    }
   }
   try {
     await args.db.insert(juniorMemoryEmbeddings).values({
@@ -983,6 +1122,192 @@ async function storeEmbedding(args) {
     return;
   }
 }
+function activeScopedSubjectPredicate(args) {
+  const predicate = and2(
+    eq3(juniorMemoryMemories.scope, args.scope.scope),
+    eq3(juniorMemoryMemories.scopeKey, args.scope.scopeKey),
+    eq3(juniorMemoryMemories.kind, args.kind),
+    eq3(juniorMemoryMemories.subjectType, args.subject.subjectType),
+    args.subject.subjectKey === void 0 ? isNull2(juniorMemoryMemories.subjectKey) : eq3(juniorMemoryMemories.subjectKey, args.subject.subjectKey),
+    isNull2(juniorMemoryMemories.archivedAtMs),
+    isNull2(juniorMemoryMemories.supersededAtMs),
+    isNull2(juniorMemoryMemories.supersededById),
+    or2(
+      isNull2(juniorMemoryMemories.expiresAtMs),
+      gt2(juniorMemoryMemories.expiresAtMs, args.nowMs)
+    )
+  );
+  if (!predicate) {
+    throw new Error("Memory duplicate predicate is empty.");
+  }
+  return predicate;
+}
+async function findExactDuplicateMemory(args) {
+  const rows = await args.db.select().from(juniorMemoryMemories).where(
+    and2(
+      activeScopedSubjectPredicate(args),
+      eq3(juniorMemoryMemories.content, args.content)
+    )
+  ).orderBy(
+    desc2(juniorMemoryMemories.createdAtMs),
+    asc(juniorMemoryMemories.id)
+  ).limit(1);
+  return rows[0] ? parseMemoryRow(rows[0]) : void 0;
+}
+async function findVectorDuplicateMemory(args) {
+  const distance = cosineDistance(
+    juniorMemoryEmbeddings.embedding,
+    args.embedding.vector
+  );
+  const rows = await args.db.select({
+    contentHash: juniorMemoryEmbeddings.contentHash,
+    distance,
+    memory: juniorMemoryMemories
+  }).from(juniorMemoryMemories).innerJoin(
+    juniorMemoryEmbeddings,
+    eq3(juniorMemoryEmbeddings.memoryId, juniorMemoryMemories.id)
+  ).where(
+    and2(
+      activeScopedSubjectPredicate(args),
+      eq3(juniorMemoryEmbeddings.provider, args.embedding.provider),
+      eq3(juniorMemoryEmbeddings.model, args.embedding.model),
+      eq3(juniorMemoryEmbeddings.dimensions, MEMORY_EMBEDDING_DIMENSIONS),
+      eq3(juniorMemoryEmbeddings.metric, EMBEDDING_METRIC),
+      lte(distance, HIGH_CONFIDENCE_DUPLICATE_DISTANCE)
+    )
+  ).orderBy(
+    distance,
+    desc2(juniorMemoryMemories.createdAtMs),
+    asc(juniorMemoryMemories.id)
+  ).limit(1);
+  const row = rows[0];
+  if (!row || hashEmbeddedContent(row.memory.content) !== row.contentHash) {
+    return void 0;
+  }
+  return parseMemoryRow(row.memory);
+}
+async function rememberDuplicateIdempotency(args) {
+  if (args.idempotencyKey === void 0) {
+    return;
+  }
+  await args.db.insert(juniorMemoryMemories).values({
+    content: args.content,
+    createdAtMs: args.nowMs,
+    expiresAtMs: args.duplicate.expiresAtMs,
+    id: idempotencyAliasId({
+      idempotencyKey: args.idempotencyKey,
+      scope: args.scope,
+      targetId: args.duplicate.id
+    }),
+    idempotencyKey: args.idempotencyKey,
+    observedAtMs: args.nowMs,
+    scope: args.scope.scope,
+    scopeKey: args.scope.scopeKey,
+    sourceKey: sourceKey(args.runtimeContext),
+    sourcePlatform: args.runtimeContext.source.platform,
+    subjectKey: args.subject.subjectKey,
+    subjectType: args.subject.subjectType,
+    supersededAtMs: args.nowMs,
+    supersededById: args.duplicate.id,
+    kind: args.duplicate.kind
+  }).onConflictDoNothing();
+}
+async function listSupersessionCandidates(args) {
+  const predicate = activeScopedSubjectPredicate(args);
+  const terms = searchTerms(args.content).filter(
+    (term) => !SUPERSESSION_STOP_TERMS.has(term)
+  );
+  const lexicalRows = terms.length > 0 ? await args.db.select().from(juniorMemoryMemories).where(
+    and2(
+      predicate,
+      or2(
+        ...terms.map(
+          (term) => ilike2(juniorMemoryMemories.content, `%${term}%`)
+        )
+      )
+    )
+  ) : [];
+  const lexicalCandidates = lexicalRows.map(parseMemoryRow).map((memory) => ({
+    memory,
+    score: searchScore(memory, terms)
+  })).filter((candidate) => candidate.score > 1).sort(
+    (left, right) => right.score - left.score || right.memory.createdAtMs - left.memory.createdAtMs || left.memory.id.localeCompare(right.memory.id)
+  ).map((candidate) => candidate.memory);
+  const vectorCandidates = args.embedding ? await listVectorSupersessionCandidates({
+    db: args.db,
+    embedding: args.embedding,
+    kind: args.kind,
+    nowMs: args.nowMs,
+    scope: args.scope,
+    subject: args.subject
+  }) : [];
+  const byId = /* @__PURE__ */ new Map();
+  for (const memory of [...lexicalCandidates, ...vectorCandidates]) {
+    if (byId.size >= SUPERSESSION_CANDIDATE_LIMIT) {
+      break;
+    }
+    byId.set(memory.id, memory);
+  }
+  return [...byId.values()];
+}
+async function listVectorSupersessionCandidates(args) {
+  const distance = cosineDistance(
+    juniorMemoryEmbeddings.embedding,
+    args.embedding.vector
+  );
+  const rows = await args.db.select({
+    contentHash: juniorMemoryEmbeddings.contentHash,
+    distance,
+    memory: juniorMemoryMemories
+  }).from(juniorMemoryMemories).innerJoin(
+    juniorMemoryEmbeddings,
+    eq3(juniorMemoryEmbeddings.memoryId, juniorMemoryMemories.id)
+  ).where(
+    and2(
+      activeScopedSubjectPredicate(args),
+      eq3(juniorMemoryEmbeddings.provider, args.embedding.provider),
+      eq3(juniorMemoryEmbeddings.model, args.embedding.model),
+      eq3(juniorMemoryEmbeddings.dimensions, MEMORY_EMBEDDING_DIMENSIONS),
+      eq3(juniorMemoryEmbeddings.metric, EMBEDDING_METRIC)
+    )
+  ).orderBy(
+    distance,
+    desc2(juniorMemoryMemories.createdAtMs),
+    asc(juniorMemoryMemories.id)
+  ).limit(SUPERSESSION_CANDIDATE_LIMIT);
+  return rows.flatMap((row) => {
+    if (hashEmbeddedContent(row.memory.content) !== row.contentHash) {
+      return [];
+    }
+    return [parseMemoryRow(row.memory)];
+  });
+}
+async function decideSupersededIds(args) {
+  if (args.kind !== "preference" || !args.decider || args.candidates.length === 0) {
+    return [];
+  }
+  const existingMemories = args.candidates.map((memory) => ({
+    content: memory.content,
+    id: memory.id
+  }));
+  const candidateIds = new Set(args.candidates.map((memory) => memory.id));
+  try {
+    const decision = await args.decider.adjudicateSupersession({
+      candidate: {
+        content: args.content,
+        kind: "preference"
+      },
+      existingMemories,
+      runtimeContext: args.runtimeContext
+    });
+    if (decision.decision !== "supersedes_old") {
+      return [];
+    }
+    return decision.supersededIds.filter((id) => candidateIds.has(id));
+  } catch {
+    return [];
+  }
+}
 async function listVisibleMemories(args) {
   const predicate = activeVisiblePredicate(args);
   if (!predicate) {
@@ -1067,7 +1392,20 @@ async function searchVisibleVectorMemories(args) {
     ];
   });
 }
-function mergeSearchCandidates(candidates) {
+function observedAgeBoost(memory, nowMs) {
+  const ageMs = Math.max(0, nowMs - memory.observedAtMs);
+  if (ageMs <= 7 * ONE_DAY_MS) {
+    return 0.15;
+  }
+  if (ageMs <= 30 * ONE_DAY_MS) {
+    return 0.1;
+  }
+  if (ageMs <= 90 * ONE_DAY_MS) {
+    return 0.05;
+  }
+  return 0;
+}
+function mergeSearchCandidates(candidates, nowMs) {
   const byId = /* @__PURE__ */ new Map();
   for (const candidate of candidates) {
     const existing = byId.get(candidate.memory.id);
@@ -1080,14 +1418,19 @@ function mergeSearchCandidates(candidates) {
       score: candidate.score
     });
   }
-  return [...byId.values()].sort(
-    (left, right) => right.score - left.score || right.memory.createdAtMs - left.memory.createdAtMs || left.memory.id.localeCompare(right.memory.id)
-  ).map((candidate) => candidate.memory);
+  return [...byId.values()].sort((left, right) => {
+    const scoreDelta = right.score - left.score;
+    if (Math.abs(scoreDelta) > RELEVANCE_NEAR_TIE_DELTA) {
+      return scoreDelta;
+    }
+    return observedAgeBoost(right.memory, nowMs) - observedAgeBoost(left.memory, nowMs) || right.memory.observedAtMs - left.memory.observedAtMs || left.memory.id.localeCompare(right.memory.id);
+  }).map((candidate) => candidate.memory);
 }
 function createMemoryStore(db, context, options = {}) {
   const runtimeContext = memoryRuntimeContextSchema.parse(context);
   const parsedOptions = memoryStoreOptionsSchema.parse({ now: options.now });
   const embedder = options.embedder;
+  const supersessionDecider = options.supersessionDecider;
   const getNowMs = parsedOptions.now ?? Date.now;
   async function archiveExpiredVisibleMemories(input, nowMs) {
     input = archiveExpiredMemoriesInputSchema.parse(input ?? {});
@@ -1119,35 +1462,162 @@ function createMemoryStore(db, context, options = {}) {
       nowMs,
       scopes: [scope]
     });
-    const id = randomUUID();
-    const rows = await db.insert(juniorMemoryMemories).values({
+    if (input.idempotencyKey !== void 0) {
+      const idempotent2 = await findByIdempotencyKey({
+        db,
+        idempotencyKey: input.idempotencyKey,
+        nowMs,
+        scope
+      });
+      if (idempotent2) {
+        await storeEmbedding({
+          content: idempotent2.content,
+          db,
+          embedder,
+          memoryId: idempotent2.id,
+          nowMs
+        });
+        return { created: false, memory: idempotent2 };
+      }
+    }
+    const exactDuplicate = await findExactDuplicateMemory({
       content,
-      createdAtMs: nowMs,
-      expiresAtMs: input.expiresAtMs,
-      id,
-      idempotencyKey: input.idempotencyKey,
-      observedAtMs: nowMs,
-      scope: scope.scope,
-      scopeKey: scope.scopeKey,
-      sourceKey: sourceKey(runtimeContext),
-      sourcePlatform: runtimeContext.source.platform,
-      subjectKey: subject.subjectKey,
-      subjectType: subject.subjectType,
-      kind: input.kind
-    }).onConflictDoNothing({
-      target: [
-        juniorMemoryMemories.scope,
-        juniorMemoryMemories.scopeKey,
-        juniorMemoryMemories.idempotencyKey
-      ],
-      where: sql2`${juniorMemoryMemories.idempotencyKey} IS NOT NULL AND ${juniorMemoryMemories.archivedAtMs} IS NULL AND ${juniorMemoryMemories.supersededAtMs} IS NULL AND ${juniorMemoryMemories.supersededById} IS NULL`
-    }).returning();
+      db,
+      kind: input.kind,
+      nowMs,
+      scope,
+      subject
+    });
+    if (exactDuplicate) {
+      await rememberDuplicateIdempotency({
+        content,
+        db,
+        duplicate: exactDuplicate,
+        idempotencyKey: input.idempotencyKey,
+        nowMs,
+        runtimeContext,
+        scope,
+        subject
+      });
+      await storeEmbedding({
+        content: exactDuplicate.content,
+        db,
+        embedder,
+        memoryId: exactDuplicate.id,
+        nowMs
+      });
+      return { created: false, memory: exactDuplicate };
+    }
+    let candidateEmbedding;
+    if (embedder) {
+      try {
+        candidateEmbedding = await embedOne(embedder, content);
+      } catch {
+        candidateEmbedding = void 0;
+      }
+    }
+    const vectorDuplicate = candidateEmbedding ? await findVectorDuplicateMemory({
+      db,
+      embedding: candidateEmbedding,
+      kind: input.kind,
+      nowMs,
+      scope,
+      subject
+    }) : void 0;
+    if (vectorDuplicate) {
+      await rememberDuplicateIdempotency({
+        content,
+        db,
+        duplicate: vectorDuplicate,
+        idempotencyKey: input.idempotencyKey,
+        nowMs,
+        runtimeContext,
+        scope,
+        subject
+      });
+      await storeEmbedding({
+        content: vectorDuplicate.content,
+        db,
+        embedder,
+        memoryId: vectorDuplicate.id,
+        nowMs
+      });
+      return { created: false, memory: vectorDuplicate };
+    }
+    let supersededIds = [];
+    if (scopeKind === "personal" && input.kind === "preference" && supersessionDecider && (input.expiresAtMs === void 0 || input.expiresAtMs > nowMs)) {
+      const supersessionCandidates = await listSupersessionCandidates({
+        content,
+        db,
+        ...candidateEmbedding ? { embedding: candidateEmbedding } : {},
+        kind: input.kind,
+        nowMs,
+        scope,
+        subject
+      });
+      supersededIds = await decideSupersededIds({
+        candidates: supersessionCandidates,
+        content,
+        decider: supersessionDecider,
+        kind: input.kind,
+        runtimeContext
+      });
+    }
+    const id = randomUUID();
+    const rows = await db.transaction(async (tx) => {
+      const inserted = await tx.insert(juniorMemoryMemories).values({
+        content,
+        createdAtMs: nowMs,
+        expiresAtMs: input.expiresAtMs,
+        id,
+        idempotencyKey: input.idempotencyKey,
+        observedAtMs: nowMs,
+        scope: scope.scope,
+        scopeKey: scope.scopeKey,
+        sourceKey: sourceKey(runtimeContext),
+        sourcePlatform: runtimeContext.source.platform,
+        subjectKey: subject.subjectKey,
+        subjectType: subject.subjectType,
+        kind: input.kind
+      }).onConflictDoNothing({
+        target: [
+          juniorMemoryMemories.scope,
+          juniorMemoryMemories.scopeKey,
+          juniorMemoryMemories.idempotencyKey
+        ],
+        where: sql2`${juniorMemoryMemories.idempotencyKey} IS NOT NULL AND ${juniorMemoryMemories.archivedAtMs} IS NULL AND ${juniorMemoryMemories.supersededAtMs} IS NULL AND ${juniorMemoryMemories.supersededById} IS NULL`
+      }).returning();
+      const insertedMemory = inserted[0];
+      if (!insertedMemory || supersededIds.length === 0) {
+        return inserted;
+      }
+      const superseded = await tx.update(juniorMemoryMemories).set({
+        supersededAtMs: nowMs,
+        supersededById: insertedMemory.id
+      }).where(
+        and2(
+          inArray(juniorMemoryMemories.id, supersededIds),
+          activeScopedSubjectPredicate({
+            kind: input.kind,
+            nowMs,
+            scope,
+            subject
+          })
+        )
+      ).returning({ id: juniorMemoryMemories.id });
+      const idsToClean = superseded.map((row) => row.id);
+      if (idsToClean.length > 0) {
+        await tx.delete(juniorMemoryEmbeddings).where(inArray(juniorMemoryEmbeddings.memoryId, idsToClean));
+      }
+      return inserted;
+    });
     if (rows[0]) {
       const memory = parseMemoryRow(rows[0]);
       await storeEmbedding({
         content: memory.content,
         db,
         embedder,
+        embedding: candidateEmbedding,
         memoryId: memory.id,
         nowMs
       });
@@ -1223,10 +1693,10 @@ function createMemoryStore(db, context, options = {}) {
       });
       const terms = searchTerms(input.query);
       const lexicalCandidates = candidates.map((memory) => ({ memory, score: searchScore(memory, terms) })).filter((item) => item.score > 0);
-      return mergeSearchCandidates([
-        ...vectorCandidates,
-        ...lexicalCandidates
-      ]).slice(0, limit);
+      return mergeSearchCandidates(
+        [...vectorCandidates, ...lexicalCandidates],
+        nowMs
+      ).slice(0, limit);
     },
     async archiveMemory(input) {
       input = archiveMemoryInputSchema.parse(input);
@@ -1297,9 +1767,10 @@ function memoryRuntimeContext(context) {
     source: context.source
   });
 }
-function memoryStore(context) {
+function memoryStore(context, options = {}) {
   return createMemoryStore(context.db, memoryRuntimeContext(context), {
-    embedder: context.embedder
+    embedder: context.embedder,
+    ...options.supersessionDecider ? { supersessionDecider: options.supersessionDecider } : {}
   });
 }
 function boundedLimit2(value, fallback) {
@@ -1442,6 +1913,16 @@ var searchMemoriesInputSchema2 = Type.Object(
   },
   { additionalProperties: false }
 );
+var memoryToolProjectionSchema = Type.Object(
+  {
+    id: Type.String({ minLength: 1 }),
+    content: Type.String({ minLength: 1 }),
+    createdAtMs: Type.Number(),
+    observedAtMs: Type.Number(),
+    expiresAtMs: Type.Optional(Type.Number())
+  },
+  { additionalProperties: false }
+);
 function parseToolInput(schema, input) {
   try {
     if (!Value.Check(schema, input)) {
@@ -1476,12 +1957,13 @@ function targetForKind(kind) {
   return "conversation";
 }
 function compactMemory(memory) {
-  return {
+  return Value.Parse(memoryToolProjectionSchema, {
     id: memory.id,
     content: memory.content,
     createdAtMs: memory.createdAtMs,
+    observedAtMs: memory.observedAtMs,
     ...memory.expiresAtMs !== void 0 ? { expiresAtMs: memory.expiresAtMs } : {}
-  };
+  });
 }
 function createMemoryCreateTool(context) {
   return {
@@ -1496,7 +1978,9 @@ function createMemoryCreateTool(context) {
       const toolCallId = requireToolCallId(options.toolCallId);
       const requestedExpiresAtMs = parseExpiresAt(parsedInput.expires_at);
       const runtimeContext = memoryRuntimeContext(context);
-      const store = memoryStore(context);
+      const store = memoryStore(context, {
+        supersessionDecider: context.supersessionDecider
+      });
       const review = await (async () => {
         try {
           return parseMemoryReview(
@@ -1699,8 +2183,10 @@ async function processMemorySession(context) {
     ...run.requester ? { requester: run.requester } : {},
     source: run.source
   });
+  const agent = createMemoryAgent(context.model);
   const store = createMemoryStore(context.db, runtimeContext, {
-    embedder: context.embedder
+    embedder: context.embedder,
+    supersessionDecider: agent
   });
   await store.archiveExpiredMemories();
   const memories = await getTaskMemories(context, async () => {
@@ -1708,7 +2194,6 @@ async function processMemorySession(context) {
       limit: 10,
       query: evidenceText
     });
-    const agent = createMemoryAgent(context.model);
     return await agent.extractSessionMemories({
       existingMemories: existingMemories.map((memory) => ({
         content: memory.content
@@ -1744,13 +2229,19 @@ function trimContent(content, maxLength) {
   }
   return `${trimmed.slice(0, Math.max(0, maxLength - 3)).trimEnd()}...`;
 }
+function formatObservedDate(observedAtMs) {
+  return new Date(observedAtMs).toISOString().slice(0, 10);
+}
 function renderMemoryPrompt(memories) {
   const header = "Relevant memories for this request:";
   const footer = "Treat these as possibly stale context. Current user instructions and repository evidence take priority.";
   const lines = [];
   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;
     }
@@ -1807,6 +2298,12 @@ function memoryToolContext(ctx) {
     ...ctx.userText ? { userText: ctx.userText } : {}
   };
 }
+function memoryCreateToolContext(ctx) {
+  return {
+    ...memoryToolContext(ctx),
+    supersessionDecider: ctx.supersessionDecider
+  };
+}
 function createMemoryPlugin(options = {}) {
   const modelId = memoryModelId(options);
   return defineJuniorPlugin({
@@ -1829,14 +2326,23 @@ function createMemoryPlugin(options = {}) {
     },
     hooks: {
       tools(ctx) {
+        const agent = createMemoryAgent(ctx.model);
         const context = memoryToolContext({
           ...ctx,
-          agent: createMemoryAgent(ctx.model),
+          agent,
           db: ctx.db,
           embedder: ctx.embedder
         });
         return {
-          createMemory: createMemoryCreateTool(context),
+          createMemory: createMemoryCreateTool(
+            memoryCreateToolContext({
+              ...ctx,
+              agent,
+              db: ctx.db,
+              embedder: ctx.embedder,
+              supersessionDecider: agent
+            })
+          ),
           removeMemory: createMemoryRemoveTool(context),
           listMemories: createMemoryListTool(context),
           searchMemories: createMemorySearchTool(context)