@sentry/junior-memory 0.80.1 → 0.82.0

package/src/store.ts

@@ -15,6 +15,7 @@ import {
   ilike,
   inArray,
   isNull,
+  isNotNull,
   like,
   lte,
   or,
@@ -40,6 +41,7 @@ import {
 import {
   deriveMemoryScope,
   deriveMemorySubject,
+  type ResolvedMemorySubject,
   deriveVisibleMemoryScopes,
   type ResolvedMemoryScope,
 } from "./scope";
@@ -47,15 +49,38 @@ import {
 const DEFAULT_LIST_LIMIT = 50;
 const DEFAULT_SEARCH_LIMIT = 10;
 const DEFAULT_EXPIRED_ARCHIVE_LIMIT = 100;
+const HIGH_CONFIDENCE_DUPLICATE_DISTANCE = 0.015;
+const SUPERSESSION_CANDIDATE_LIMIT = 10;
 const VECTOR_SEARCH_OVERFETCH = 4;
 const MAX_MEMORY_CONTENT_CHARS = 4_000;
 const EMBEDDING_METRIC = "cosine";
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const RELEVANCE_NEAR_TIE_DELTA = 0.01;
+const SOURCE_CHANNEL_BOOST = 0.05;
+const SUPERSESSION_STOP_TERMS = new Set([
+  "and",
+  "for",
+  "prefer",
+  "prefers",
+  "preference",
+  "the",
+  "use",
+  "uses",
+  "with",
+]);
 
 export type MemoryDb = PgDatabase<PgQueryResultHKT, typeof memorySqlSchema>;
 
 interface SearchCandidate {
   memory: MemoryRecord;
   score: number;
+  sourceKey: string;
+}
+
+interface MemoryEmbedding {
+  model: string;
+  provider: string;
+  vector: number[];
 }
 
 const nonEmptyStringSchema = z.string().min(1);
@@ -215,9 +240,46 @@ export interface MemoryEmbeddingProvider {
   }>;
 }
 
+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. */
@@ -248,6 +310,22 @@ function hashEmbeddedContent(content: string): string {
   return createHash("sha256").update(content, "utf8").digest("hex");
 }
 
+function idempotencyAliasId(args: {
+  idempotencyKey: string;
+  scope: ResolvedMemoryScope;
+  targetId: string;
+}): string {
+  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: number | undefined, fallback: number): number {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     return fallback;
@@ -269,6 +347,14 @@ function sourceKey(ctx: MemoryRuntimeContext): string {
   return `slack:${ctx.source.teamId}:${ctx.source.channelId}:${threadKey}`;
 }
 
+function sourceChannelPrefix(ctx: MemoryRuntimeContext): string | undefined {
+  if (ctx.source.platform !== "slack") {
+    return undefined;
+  }
+  // TODO(v0.82.0): Replace Slack source-key prefix matching with typed source proximity metadata.
+  return `slack:${ctx.source.teamId}:${ctx.source.channelId}:`;
+}
+
 /** Parse one SQL row into the public memory record projection. */
 function parseMemoryRow(row: unknown): MemoryRecord {
   const parsed = memoryRowSchema.parse(row);
@@ -336,7 +422,7 @@ async function findByIdempotencyKey(args: {
   nowMs: number;
   scope: ResolvedMemoryScope;
 }): Promise<MemoryRecord | undefined> {
-  const rows = await args.db
+  const activeRows = await args.db
     .select()
     .from(juniorMemoryMemories)
     .where(
@@ -354,7 +440,58 @@ async function findByIdempotencyKey(args: {
       ),
     )
     .limit(1);
-  return rows[0] ? parseMemoryRow(rows[0]) : undefined;
+  if (activeRows[0]) {
+    return parseMemoryRow(activeRows[0]);
+  }
+
+  const aliasRows = await args.db
+    .select({ supersededById: juniorMemoryMemories.supersededById })
+    .from(juniorMemoryMemories)
+    .where(
+      and(
+        eq(juniorMemoryMemories.scope, args.scope.scope),
+        eq(juniorMemoryMemories.scopeKey, args.scope.scopeKey),
+        eq(juniorMemoryMemories.idempotencyKey, args.idempotencyKey),
+        isNull(juniorMemoryMemories.archivedAtMs),
+        isNotNull(juniorMemoryMemories.supersededAtMs),
+        isNotNull(juniorMemoryMemories.supersededById),
+        or(
+          isNull(juniorMemoryMemories.expiresAtMs),
+          gt(juniorMemoryMemories.expiresAtMs, args.nowMs),
+        ),
+      ),
+    )
+    .orderBy(
+      desc(juniorMemoryMemories.createdAtMs),
+      asc(juniorMemoryMemories.id),
+    );
+  for (const alias of aliasRows) {
+    if (!alias.supersededById) {
+      continue;
+    }
+    const rows = await args.db
+      .select()
+      .from(juniorMemoryMemories)
+      .where(
+        and(
+          eq(juniorMemoryMemories.id, alias.supersededById),
+          eq(juniorMemoryMemories.scope, args.scope.scope),
+          eq(juniorMemoryMemories.scopeKey, args.scope.scopeKey),
+          isNull(juniorMemoryMemories.archivedAtMs),
+          isNull(juniorMemoryMemories.supersededAtMs),
+          isNull(juniorMemoryMemories.supersededById),
+          or(
+            isNull(juniorMemoryMemories.expiresAtMs),
+            gt(juniorMemoryMemories.expiresAtMs, args.nowMs),
+          ),
+        ),
+      )
+      .limit(1);
+    if (rows[0]) {
+      return parseMemoryRow(rows[0]);
+    }
+  }
+  return undefined;
 }
 
 /**
@@ -442,11 +579,7 @@ function searchTerms(query: string): string[] {
 async function embedOne(
   embedder: MemoryEmbeddingProvider,
   text: string,
-): Promise<{
-  model: string;
-  provider: string;
-  vector: number[];
-}> {
+): Promise<MemoryEmbedding> {
   const normalized = normalizeContent(text);
   if (!normalized) {
     throw new Error("Embedding text is required.");
@@ -469,10 +602,11 @@ async function storeEmbedding(args: {
   content: string;
   db: MemoryDb;
   embedder: MemoryEmbeddingProvider | undefined;
+  embedding?: MemoryEmbedding;
   memoryId: string;
   nowMs: number;
 }): Promise<void> {
-  if (!args.embedder) {
+  if (!args.embedder && !args.embedding) {
     return;
   }
   try {
@@ -488,10 +622,18 @@ async function storeEmbedding(args: {
     return;
   }
   let embedding: Awaited<ReturnType<typeof embedOne>>;
-  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
@@ -512,6 +654,293 @@ async function storeEmbedding(args: {
   }
 }
 
+function activeScopedSubjectPredicate(args: {
+  kind: MemoryRecord["kind"];
+  nowMs: number;
+  scope: ResolvedMemoryScope;
+  subject: ResolvedMemorySubject;
+}): SQL {
+  const predicate = and(
+    eq(juniorMemoryMemories.scope, args.scope.scope),
+    eq(juniorMemoryMemories.scopeKey, args.scope.scopeKey),
+    eq(juniorMemoryMemories.kind, args.kind),
+    eq(juniorMemoryMemories.subjectType, args.subject.subjectType),
+    args.subject.subjectKey === undefined
+      ? isNull(juniorMemoryMemories.subjectKey)
+      : eq(juniorMemoryMemories.subjectKey, args.subject.subjectKey),
+    isNull(juniorMemoryMemories.archivedAtMs),
+    isNull(juniorMemoryMemories.supersededAtMs),
+    isNull(juniorMemoryMemories.supersededById),
+    or(
+      isNull(juniorMemoryMemories.expiresAtMs),
+      gt(juniorMemoryMemories.expiresAtMs, args.nowMs),
+    ),
+  );
+  if (!predicate) {
+    throw new Error("Memory duplicate predicate is empty.");
+  }
+  return predicate;
+}
+
+async function findExactDuplicateMemory(args: {
+  content: string;
+  db: MemoryDb;
+  kind: MemoryRecord["kind"];
+  nowMs: number;
+  scope: ResolvedMemoryScope;
+  subject: ResolvedMemorySubject;
+}): Promise<MemoryRecord | undefined> {
+  const rows = await args.db
+    .select()
+    .from(juniorMemoryMemories)
+    .where(
+      and(
+        activeScopedSubjectPredicate(args),
+        eq(juniorMemoryMemories.content, args.content),
+      ),
+    )
+    .orderBy(
+      desc(juniorMemoryMemories.createdAtMs),
+      asc(juniorMemoryMemories.id),
+    )
+    .limit(1);
+  return rows[0] ? parseMemoryRow(rows[0]) : undefined;
+}
+
+async function findVectorDuplicateMemory(args: {
+  db: MemoryDb;
+  embedding: MemoryEmbedding;
+  kind: MemoryRecord["kind"];
+  nowMs: number;
+  scope: ResolvedMemoryScope;
+  subject: ResolvedMemorySubject;
+}): Promise<MemoryRecord | undefined> {
+  const distance = cosineDistance(
+    juniorMemoryEmbeddings.embedding,
+    args.embedding.vector,
+  );
+  const rows = await args.db
+    .select({
+      contentHash: juniorMemoryEmbeddings.contentHash,
+      distance,
+      memory: juniorMemoryMemories,
+    })
+    .from(juniorMemoryMemories)
+    .innerJoin(
+      juniorMemoryEmbeddings,
+      eq(juniorMemoryEmbeddings.memoryId, juniorMemoryMemories.id),
+    )
+    .where(
+      and(
+        activeScopedSubjectPredicate(args),
+        eq(juniorMemoryEmbeddings.provider, args.embedding.provider),
+        eq(juniorMemoryEmbeddings.model, args.embedding.model),
+        eq(juniorMemoryEmbeddings.dimensions, MEMORY_EMBEDDING_DIMENSIONS),
+        eq(juniorMemoryEmbeddings.metric, EMBEDDING_METRIC),
+        lte(distance, HIGH_CONFIDENCE_DUPLICATE_DISTANCE),
+      ),
+    )
+    .orderBy(
+      distance,
+      desc(juniorMemoryMemories.createdAtMs),
+      asc(juniorMemoryMemories.id),
+    )
+    .limit(1);
+  const row = rows[0];
+  if (!row || hashEmbeddedContent(row.memory.content) !== row.contentHash) {
+    return undefined;
+  }
+  return parseMemoryRow(row.memory);
+}
+
+async function rememberDuplicateIdempotency(args: {
+  content: string;
+  db: MemoryDb;
+  duplicate: MemoryRecord;
+  idempotencyKey?: string;
+  nowMs: number;
+  runtimeContext: MemoryRuntimeContext;
+  scope: ResolvedMemoryScope;
+  subject: ResolvedMemorySubject;
+}): Promise<void> {
+  if (args.idempotencyKey === undefined) {
+    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: {
+  content: string;
+  db: MemoryDb;
+  embedding?: MemoryEmbedding;
+  kind: MemoryRecord["kind"];
+  nowMs: number;
+  scope: ResolvedMemoryScope;
+  subject: ResolvedMemorySubject;
+}): Promise<MemoryRecord[]> {
+  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(
+            and(
+              predicate,
+              or(
+                ...terms.map((term) =>
+                  ilike(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 = new Map<string, MemoryRecord>();
+  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: {
+  db: MemoryDb;
+  embedding: MemoryEmbedding;
+  kind: MemoryRecord["kind"];
+  nowMs: number;
+  scope: ResolvedMemoryScope;
+  subject: ResolvedMemorySubject;
+}): Promise<MemoryRecord[]> {
+  const distance = cosineDistance(
+    juniorMemoryEmbeddings.embedding,
+    args.embedding.vector,
+  );
+  const rows = await args.db
+    .select({
+      contentHash: juniorMemoryEmbeddings.contentHash,
+      distance,
+      memory: juniorMemoryMemories,
+    })
+    .from(juniorMemoryMemories)
+    .innerJoin(
+      juniorMemoryEmbeddings,
+      eq(juniorMemoryEmbeddings.memoryId, juniorMemoryMemories.id),
+    )
+    .where(
+      and(
+        activeScopedSubjectPredicate(args),
+        eq(juniorMemoryEmbeddings.provider, args.embedding.provider),
+        eq(juniorMemoryEmbeddings.model, args.embedding.model),
+        eq(juniorMemoryEmbeddings.dimensions, MEMORY_EMBEDDING_DIMENSIONS),
+        eq(juniorMemoryEmbeddings.metric, EMBEDDING_METRIC),
+      ),
+    )
+    .orderBy(
+      distance,
+      desc(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: {
+  candidates: MemoryRecord[];
+  content: string;
+  decider: MemorySupersessionDecider | undefined;
+  kind: MemoryRecord["kind"];
+  runtimeContext: MemoryRuntimeContext;
+}): Promise<string[]> {
+  // Supersession is conservative: model uncertainty or decider failure leaves
+  // both memories active rather than hiding a possibly valid old preference.
+  if (
+    args.kind !== "preference" ||
+    !args.decider ||
+    args.candidates.length === 0
+  ) {
+    return [];
+  }
+  const existingMemories = args.candidates.map((memory) => ({
+    content: memory.content,
+    id: memory.id,
+  })) as MemorySupersessionInput["existingMemories"];
+  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 [];
+  }
+}
+
 /** List active records for the runtime-derived visible scopes. */
 async function listVisibleMemories(args: {
   db: MemoryDb;
@@ -542,7 +971,7 @@ async function searchVisibleMemories(args: {
   nowMs: number;
   query: string;
   scopes: ResolvedMemoryScope[];
-}): Promise<MemoryRecord[]> {
+}): Promise<SearchCandidate[]> {
   const terms = searchTerms(args.query);
   if (terms.length === 0) {
     return [];
@@ -564,7 +993,11 @@ async function searchVisibleMemories(args: {
         ),
       ),
     );
-  return rows.map(parseMemoryRow);
+  return rows.map((row) => ({
+    memory: parseMemoryRow(row),
+    score: 0,
+    sourceKey: row.sourceKey,
+  }));
 }
 
 /** Search active visible records with exact pgvector cosine distance. */
@@ -572,6 +1005,7 @@ async function searchVisibleVectorMemories(args: {
   db: MemoryDb;
   embedder: MemoryEmbeddingProvider | undefined;
   limit: number;
+  maxDistance?: number;
   nowMs: number;
   query: string;
   scopes: ResolvedMemoryScope[];
@@ -628,22 +1062,58 @@ async function searchVisibleVectorMemories(args: {
     ) {
       return [];
     }
+    if (args.maxDistance !== undefined && distanceValue > args.maxDistance) {
+      return [];
+    }
     return [
       {
         memory: parseMemoryRow(row.memory),
         score: 1 / (1 + Math.max(0, distanceValue)),
+        sourceKey: row.memory.sourceKey,
       },
     ];
   });
 }
 
-/** Fuse higher-is-better retrieval candidates before applying the final limit. */
-function mergeSearchCandidates(candidates: SearchCandidate[]): MemoryRecord[] {
+function sourceBoost(
+  candidate: Pick<SearchCandidate, "sourceKey">,
+  currentChannelPrefix: string | undefined,
+): number {
+  if (!currentChannelPrefix) {
+    return 0;
+  }
+  return candidate.sourceKey.startsWith(currentChannelPrefix)
+    ? SOURCE_CHANNEL_BOOST
+    : 0;
+}
+
+/** Score only observation age for near-tie reranking; this is not lifecycle decay. */
+function observedAgeBoost(memory: MemoryRecord, nowMs: number): number {
+  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;
+}
+
+/** Fuse retrieval candidates while keeping observed age to near-tie reranking. */
+function mergeSearchCandidates(
+  candidates: SearchCandidate[],
+  nowMs: number,
+  currentChannelKey?: string,
+): MemoryRecord[] {
   const byId = new Map<
     string,
     {
       memory: MemoryRecord;
       score: number;
+      sourceKey: string;
     }
   >();
   for (const candidate of candidates) {
@@ -655,15 +1125,28 @@ function mergeSearchCandidates(candidates: SearchCandidate[]): MemoryRecord[] {
     byId.set(candidate.memory.id, {
       memory: candidate.memory,
       score: candidate.score,
+      sourceKey: candidate.sourceKey,
     });
   }
   return [...byId.values()]
-    .sort(
-      (left, right) =>
-        right.score - left.score ||
-        right.memory.createdAtMs - left.memory.createdAtMs ||
-        left.memory.id.localeCompare(right.memory.id),
-    )
+    .sort((left, right) => {
+      const scoreDelta = right.score - left.score;
+      if (Math.abs(scoreDelta) > RELEVANCE_NEAR_TIE_DELTA) {
+        return scoreDelta;
+      }
+      const sourceDelta =
+        sourceBoost(right, currentChannelKey) -
+        sourceBoost(left, currentChannelKey);
+      if (sourceDelta !== 0) {
+        return sourceDelta;
+      }
+      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);
 }
 
@@ -676,6 +1159,8 @@ export function createMemoryStore(
   const runtimeContext = memoryRuntimeContextSchema.parse(context);
   const parsedOptions = memoryStoreOptionsSchema.parse({ now: options.now });
   const embedder = options.embedder;
+  const maxVectorDistance = options.maxVectorDistance;
+  const supersessionDecider = options.supersessionDecider;
   const getNowMs = parsedOptions.now ?? Date.now;
 
   async function archiveExpiredVisibleMemories(
@@ -716,40 +1201,183 @@ export function createMemoryStore(
       nowMs,
       scopes: [scope],
     });
+    if (input.idempotencyKey !== undefined) {
+      const idempotent = await findByIdempotencyKey({
+        db,
+        idempotencyKey: input.idempotencyKey,
+        nowMs,
+        scope,
+      });
+      if (idempotent) {
+        await storeEmbedding({
+          content: idempotent.content,
+          db,
+          embedder,
+          memoryId: idempotent.id,
+          nowMs,
+        });
+        return { created: false, memory: idempotent };
+      }
+    }
 
-    const id = randomUUID();
-    const rows = await db
-      .insert(juniorMemoryMemories)
-      .values({
+    const exactDuplicate = await findExactDuplicateMemory({
+      content,
+      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: MemoryEmbedding | undefined;
+    if (embedder) {
+      try {
+        candidateEmbedding = await embedOne(embedder, content);
+      } catch {
+        candidateEmbedding = undefined;
+      }
+    }
+    const vectorDuplicate = candidateEmbedding
+      ? await findVectorDuplicateMemory({
+          db,
+          embedding: candidateEmbedding,
+          kind: input.kind,
+          nowMs,
+          scope,
+          subject,
+        })
+      : undefined;
+    if (vectorDuplicate) {
+      await rememberDuplicateIdempotency({
         content,
-        createdAtMs: nowMs,
-        expiresAtMs: input.expiresAtMs,
-        id,
+        db,
+        duplicate: vectorDuplicate,
         idempotencyKey: input.idempotencyKey,
-        observedAtMs: nowMs,
-        scope: scope.scope,
-        scopeKey: scope.scopeKey,
-        sourceKey: sourceKey(runtimeContext),
-        sourcePlatform: runtimeContext.source.platform,
-        subjectKey: subject.subjectKey,
-        subjectType: subject.subjectType,
+        nowMs,
+        runtimeContext,
+        scope,
+        subject,
+      });
+      await storeEmbedding({
+        content: vectorDuplicate.content,
+        db,
+        embedder,
+        memoryId: vectorDuplicate.id,
+        nowMs,
+      });
+      return { created: false, memory: vectorDuplicate };
+    }
+
+    let supersededIds: string[] = [];
+    if (
+      scopeKind === "personal" &&
+      input.kind === "preference" &&
+      supersessionDecider &&
+      (input.expiresAtMs === undefined || input.expiresAtMs > nowMs)
+    ) {
+      const supersessionCandidates = await listSupersessionCandidates({
+        content,
+        db,
+        ...(candidateEmbedding ? { embedding: candidateEmbedding } : {}),
         kind: input.kind,
-      })
-      .onConflictDoNothing({
-        target: [
-          juniorMemoryMemories.scope,
-          juniorMemoryMemories.scopeKey,
-          juniorMemoryMemories.idempotencyKey,
-        ],
-        where: sql`${juniorMemoryMemories.idempotencyKey} IS NOT NULL AND ${juniorMemoryMemories.archivedAtMs} IS NULL AND ${juniorMemoryMemories.supersededAtMs} IS NULL AND ${juniorMemoryMemories.supersededById} IS NULL`,
-      })
-      .returning();
+        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: sql`${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(
+          and(
+            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,
       });
@@ -819,6 +1447,9 @@ export function createMemoryStore(
         db,
         embedder,
         limit: limit * VECTOR_SEARCH_OVERFETCH,
+        ...(maxVectorDistance !== undefined
+          ? { maxDistance: maxVectorDistance }
+          : {}),
         nowMs,
         query: input.query,
         scopes,
@@ -831,12 +1462,16 @@ export function createMemoryStore(
       });
       const terms = searchTerms(input.query);
       const lexicalCandidates = candidates
-        .map((memory) => ({ memory, score: searchScore(memory, terms) }))
+        .map((candidate) => ({
+          ...candidate,
+          score: searchScore(candidate.memory, terms),
+        }))
         .filter((item) => item.score > 0);
-      return mergeSearchCandidates([
-        ...vectorCandidates,
-        ...lexicalCandidates,
-      ]).slice(0, limit);
+      return mergeSearchCandidates(
+        [...vectorCandidates, ...lexicalCandidates],
+        nowMs,
+        sourceChannelPrefix(runtimeContext),
+      ).slice(0, limit);
     },
 
     async archiveMemory(input) {