@vellumai/assistant 0.8.3 → 0.8.5

package/src/memory/memory-retrospective-job.ts

@@ -32,7 +32,9 @@
 // conversations left by a mid-run crash are swept by
 // `memory-retrospective-startup-cleanup.ts`.
 
+import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
 import type { AssistantConfig } from "../config/types.js";
+import { extractTurnContextTimestamp } from "../context/compactor.js";
 import { resolveTurnTimezoneContext } from "../daemon/date-context.js";
 import {
   getAssistantName,
@@ -40,13 +42,17 @@ import {
 } from "../daemon/identity-helpers.js";
 import { INTERNAL_GUARDIAN_TRUST_CONTEXT } from "../daemon/trust-context.js";
 import { formatMessageSliceForTranscript } from "../export/transcript-formatter.js";
+import type { Message } from "../providers/types.js";
 import { wakeAgentForOpportunity } from "../runtime/agent-wake.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import { bootstrapConversation } from "./conversation-bootstrap.js";
 import {
+  addMessage,
   deleteConversation,
   findMostRecentRetrospectiveFor,
+  forkConversation,
+  getConversation,
   getMessages,
   getMessagesAfter,
 } from "./conversation-crud.js";
@@ -56,7 +62,9 @@ import {
   type MemoryJobType,
 } from "./jobs-store.js";
 import {
+  MEMORY_RETROSPECTIVE_FORK_SOURCE,
   MEMORY_RETROSPECTIVE_GROUP_ID,
+  MEMORY_RETROSPECTIVE_INSTRUCTION_KIND,
   MEMORY_RETROSPECTIVE_SOURCE,
 } from "./memory-retrospective-constants.js";
 import {
@@ -65,6 +73,17 @@ import {
   upsertRetrospectiveState,
 } from "./memory-retrospective-state.js";
 
+/**
+ * Feature flag that switches the retrospective handler between the legacy
+ * transcript-based path (renders the new-message slice into a `<transcript>`
+ * block and wakes an empty background conversation) and the new fork-based
+ * path (forks the source through its latest message, persists a user-role
+ * instruction, and wakes the fork). The fork path lets the retrospective hit
+ * the provider prompt cache and read compaction summary + tail messages
+ * natively.
+ */
+const MEMORY_RETROSPECTIVE_FORK_FLAG = "memory-retrospective-fork" as const;
+
 const log = getLogger("memory-retrospective-job");
 
 /**
@@ -96,6 +115,24 @@ export async function memoryRetrospectiveJob(
     return { kind: "no_new_messages" };
   }
 
+  const useFork = isAssistantFeatureFlagEnabled(
+    MEMORY_RETROSPECTIVE_FORK_FLAG,
+    config,
+  );
+  return useFork
+    ? runForkBasedRetrospective(sourceConversationId, config)
+    : runLegacyRetrospective(sourceConversationId, config);
+}
+
+// ---------------------------------------------------------------------------
+// Legacy path — transcript-rendered slice + empty background conversation.
+// Kept behind the `memory-retrospective-fork` flag for safe rollback.
+// ---------------------------------------------------------------------------
+
+async function runLegacyRetrospective(
+  sourceConversationId: string,
+  config: AssistantConfig,
+): Promise<MemoryRetrospectiveOutcome> {
   // 1. Load state + compute the message slice.
   const state = getRetrospectiveState(sourceConversationId);
   const lastProcessedMessageId = state?.lastProcessedMessageId ?? null;
@@ -142,7 +179,7 @@ export async function memoryRetrospectiveJob(
     assistantName: getAssistantName(),
     userName: resolveUserName(getWorkspaceDir()),
   });
-  const prompt = buildPrompt({
+  const prompt = buildLegacyPrompt({
     transcript,
     priorRemembers,
     timeZone: timezoneContext.effectiveTimezone,
@@ -171,6 +208,11 @@ export async function memoryRetrospectiveJob(
       source: MEMORY_RETROSPECTIVE_SOURCE,
       trustContext: INTERNAL_GUARDIAN_TRUST_CONTEXT,
       callSite: "memoryRetrospective",
+      // The background conversation's title already reads "Memory
+      // Retrospective", and `hint` is the full retrospective prompt — surfacing
+      // it verbatim as a "Conversation Woke" card body is noisy internal
+      // scaffolding for the user. Suppress it, matching the fork-based path.
+      suppressWakeSurface: true,
     });
     wakeSucceeded = result.invoked;
     failureReason = result.reason;
@@ -191,17 +233,7 @@ export async function memoryRetrospectiveJob(
       lastRunAt: Date.now(),
     });
 
-    const followUpJobIds: string[] = [];
-    for (const jobType of FOLLOW_UP_JOB_TYPES) {
-      try {
-        followUpJobIds.push(enqueueMemoryJob(jobType, {}));
-      } catch (err) {
-        log.warn(
-          { err, jobType },
-          "memory-retrospective: failed to enqueue follow-up job; continuing",
-        );
-      }
-    }
+    const followUpJobIds = enqueueFollowUpJobs();
 
     log.info(
       {
@@ -210,6 +242,7 @@ export async function memoryRetrospectiveJob(
         cutoffMessageId,
         newMessageCount: newMessages.length,
         priorRememberCount: priorRemembers.length,
+        kind: "legacy",
       },
       "memory-retrospective invoked",
     );
@@ -251,6 +284,243 @@ export async function memoryRetrospectiveJob(
   };
 }
 
+// ---------------------------------------------------------------------------
+// Fork-based path — fork the source through its latest message, persist a
+// user-role retrospective instruction at the tail, and wake the fork. The
+// fork inherits compaction state (summary + tail messages) via the existing
+// `forkConversation` machinery, and its prefix matches the source's prefix
+// so provider prompt caching hits.
+// ---------------------------------------------------------------------------
+
+async function runForkBasedRetrospective(
+  sourceConversationId: string,
+  config: AssistantConfig,
+): Promise<MemoryRetrospectiveOutcome> {
+  const sourceConversation = getConversation(sourceConversationId);
+  if (!sourceConversation) {
+    log.warn(
+      { sourceConversationId },
+      "memory-retrospective (fork): source conversation not found; skipping",
+    );
+    return { kind: "no_new_messages" };
+  }
+
+  const state = getRetrospectiveState(sourceConversationId);
+  const lastProcessedMessageId = state?.lastProcessedMessageId ?? null;
+  const newMessages = getMessagesAfter(
+    sourceConversationId,
+    lastProcessedMessageId,
+  );
+
+  if (newMessages.length === 0) {
+    return { kind: "no_new_messages" };
+  }
+
+  const cutoffMessage = newMessages[newMessages.length - 1];
+  if (!cutoffMessage) {
+    return { kind: "no_new_messages" };
+  }
+  const cutoffMessageId = cutoffMessage.id;
+
+  // The fork carries the full conversation, so the agent needs an explicit
+  // anchor telling it where the review window begins. Prefer the user
+  // turn's `<turn_context>` `current_time:` (matches the conversation's
+  // own clock); fall back to ISO-formatted `createdAt` when the slice
+  // begins with an assistant turn or tool_result-only user message.
+  const windowStartTimestamp =
+    findFirstTurnContextTimestamp(newMessages) ??
+    new Date(newMessages[0]!.createdAt).toISOString();
+
+  // Pull prior `remember` calls BEFORE forking — otherwise
+  // `findMostRecentRetrospectiveFor` could locate this run's own fork.
+  const priorRemembers =
+    collectPriorRetrospectiveRemembers(sourceConversationId);
+
+  // Pin the fork to `cutoffMessageId` so messages arriving between the slice
+  // read above and this call don't sneak into the fork. Without
+  // `throughMessageId`, the fork snapshots the latest source message at fork
+  // time and this run would process turns past the cutoff while state only
+  // advances to `cutoffMessageId`, causing the next retrospective to
+  // reprocess (and potentially re-`remember`) those same turns.
+  //
+  // `forkConversation` inherits `contextSummary` /
+  // `contextCompactedMessageCount` / `contextCompactedAt` when the fork
+  // point sits within the visible window. Compacted source ⇒ compacted
+  // fork ⇒ summary + tail visible to the agent natively.
+  let forkConversationRow: ReturnType<typeof forkConversation>;
+  try {
+    forkConversationRow = forkConversation({
+      conversationId: sourceConversationId,
+      throughMessageId: cutoffMessageId,
+      source: MEMORY_RETROSPECTIVE_FORK_SOURCE,
+      title: `${sourceConversation.title ?? "Untitled"} (Retrospective)`,
+      conversationType: "background",
+      groupId: MEMORY_RETROSPECTIVE_GROUP_ID,
+    });
+  } catch (err) {
+    bumpRetrospectiveLastRunAt(sourceConversationId, Date.now());
+    log.error(
+      { err, sourceConversationId },
+      "memory-retrospective (fork): forkConversation failed",
+    );
+    throw err;
+  }
+  const forkId = forkConversationRow.id;
+
+  const timezoneContext = resolveTurnTimezoneContext({
+    configuredUserTimeZone: config.ui.userTimezone ?? null,
+    detectedTimezone: config.ui.detectedTimezone ?? null,
+  });
+  const instruction = buildForkInstruction({
+    windowStartTimestamp,
+    priorRemembers,
+    timeZone: timezoneContext.effectiveTimezone,
+    isFirstPass: lastProcessedMessageId == null,
+  });
+  try {
+    await addMessage(
+      forkId,
+      "user",
+      JSON.stringify([{ type: "text", text: instruction }]),
+      { kind: MEMORY_RETROSPECTIVE_INSTRUCTION_KIND, hidden: true },
+      { skipIndexing: true },
+    );
+  } catch (err) {
+    log.error(
+      { err, forkId, sourceConversationId },
+      "memory-retrospective (fork): failed to persist instruction message",
+    );
+    safeDeleteForkOnFailure(forkId);
+    bumpRetrospectiveLastRunAt(sourceConversationId, Date.now());
+    throw err;
+  }
+
+  // `skipHintInjection: true` because the instruction is already a
+  // persisted message — the wake's hint sandwich would only duplicate it.
+  let wakeSucceeded = false;
+  let failureReason: string | undefined;
+  let threw: unknown;
+  try {
+    const result = await wakeAgentForOpportunity({
+      conversationId: forkId,
+      hint: "",
+      source: MEMORY_RETROSPECTIVE_SOURCE,
+      trustContext: INTERNAL_GUARDIAN_TRUST_CONTEXT,
+      callSite: "memoryRetrospective",
+      hintRole: "user",
+      skipHintInjection: true,
+      suppressAutoCompaction: true,
+      // The fork's title already reads "(Retrospective)", so an empty-body
+      // "Conversation Woke" surface card on top of it would be noise. Suppress
+      // it — clients should display the fork as a normal background conv.
+      suppressWakeSurface: true,
+    });
+    wakeSucceeded = result.invoked;
+    failureReason = result.reason;
+  } catch (err) {
+    threw = err;
+    failureReason = err instanceof Error ? err.message : String(err);
+    log.error(
+      { err, forkId, sourceConversationId },
+      "memory-retrospective (fork): wake threw",
+    );
+  }
+
+  if (wakeSucceeded) {
+    upsertRetrospectiveState({
+      conversationId: sourceConversationId,
+      lastProcessedMessageId: cutoffMessageId,
+      lastRunAt: Date.now(),
+    });
+
+    const followUpJobIds = enqueueFollowUpJobs();
+
+    log.info(
+      {
+        sourceConversationId,
+        backgroundConversationId: forkId,
+        cutoffMessageId,
+        newMessageCount: newMessages.length,
+        priorRememberCount: priorRemembers.length,
+        windowStartTimestamp,
+        kind: "fork",
+      },
+      "memory-retrospective invoked",
+    );
+    return {
+      kind: "invoked",
+      backgroundConversationId: forkId,
+      cutoffMessageId,
+      newMessageCount: newMessages.length,
+      followUpJobIds,
+    };
+  }
+
+  bumpRetrospectiveLastRunAt(sourceConversationId, Date.now());
+  safeDeleteForkOnFailure(forkId);
+
+  if (threw !== undefined) {
+    throw threw;
+  }
+
+  return {
+    kind: "wake_failed",
+    reason: failureReason,
+    conversationId: forkId,
+  };
+}
+
+function enqueueFollowUpJobs(): string[] {
+  const followUpJobIds: string[] = [];
+  for (const jobType of FOLLOW_UP_JOB_TYPES) {
+    try {
+      followUpJobIds.push(enqueueMemoryJob(jobType, {}));
+    } catch (err) {
+      log.warn(
+        { err, jobType },
+        "memory-retrospective: failed to enqueue follow-up job; continuing",
+      );
+    }
+  }
+  return followUpJobIds;
+}
+
+function safeDeleteForkOnFailure(forkId: string): void {
+  try {
+    deleteConversation(forkId);
+  } catch (err) {
+    log.warn(
+      { err, forkId },
+      "memory-retrospective (fork): failed to delete fork on wake failure; continuing",
+    );
+  }
+}
+
+/**
+ * Walk the slice and return the `<turn_context>` `current_time:` value from
+ * the first message that has one (typically the first user message). The
+ * agent uses this as the explicit anchor for the review window inside its
+ * forked history.
+ */
+function findFirstTurnContextTimestamp(
+  messages: Array<{ role: string; content: string }>,
+): string | null {
+  for (const row of messages) {
+    if (row.role !== "user") continue;
+    let blocks: unknown;
+    try {
+      blocks = JSON.parse(row.content);
+    } catch {
+      continue;
+    }
+    if (!Array.isArray(blocks)) continue;
+    const message = { role: "user", content: blocks } as Message;
+    const ts = extractTurnContextTimestamp(message);
+    if (ts) return ts;
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // Prior-retrospective remember extraction
 // ---------------------------------------------------------------------------
@@ -261,9 +531,23 @@ export async function memoryRetrospectiveJob(
  * array on first run (no prior retrospective) or when the prior run had no
  * `remember` calls (it found nothing to save).
  *
- * This is bounded — a single retrospective conversation, however long the
- * source conversation has grown. Older retrospectives' saves are already
- * baked into the most recent one's `<already_remembered>` block transitively.
+ * Two artifact shapes exist depending on which path produced the prior
+ * retrospective:
+ *
+ *   - **Legacy** (`source === MEMORY_RETROSPECTIVE_SOURCE`): empty bg
+ *     conversation containing only the wake's tail (`remember` tool_use
+ *     blocks). Scan everything.
+ *   - **Fork** (`source === MEMORY_RETROSPECTIVE_FORK_SOURCE`): full source
+ *     prefix forked in, followed by the retrospective's post-fork tail.
+ *     The forked prefix contains the source conversation's own inline
+ *     `remember` calls — scanning the whole row would dump source-inline
+ *     saves into the dedup baseline and inflate it dramatically. Restrict
+ *     to messages created **after** `forkParentMessageId` (the last copied
+ *     message); only messages after that boundary came from this
+ *     retrospective's own work.
+ *
+ * Older retrospectives' saves remain reflected transitively because each
+ * retrospective dedups against the one before it.
  */
 function collectPriorRetrospectiveRemembers(
   sourceConversationId: string,
@@ -280,9 +564,67 @@ function collectPriorRetrospectiveRemembers(
     );
     return [];
   }
+
+  const priorConv = getConversation(prior.id);
+  if (priorConv?.source === MEMORY_RETROSPECTIVE_FORK_SOURCE) {
+    // For fork-kind rows, prior `remember` calls live in the post-fork
+    // tail. `cloneForkMessageMetadata` stamps every copied message with
+    // `forkSourceMessageId` (preserving any existing value when the source
+    // was itself a fork), so the LAST message in the fork carrying
+    // `forkSourceMessageId` is the boundary — its value can point to any
+    // ancestor when the source was a nested fork, so we can't match it
+    // against `forkParentMessageId`. Everything strictly past that
+    // timestamp is post-fork.
+    const boundaryCreatedAt = findForkBoundaryCreatedAt(messages);
+    if (boundaryCreatedAt == null) {
+      log.warn(
+        { priorConversationId: prior.id },
+        "memory-retrospective: fork-kind prior has no message with forkSourceMessageId metadata; treating dedup as empty",
+      );
+      return [];
+    }
+    return extractRememberContents(
+      messages.filter((m) => m.createdAt > boundaryCreatedAt),
+    );
+  }
+
   return extractRememberContents(messages);
 }
 
+/**
+ * Locate the boundary timestamp between the fork's prefix and its post-fork
+ * tail. Scans from the end for the last message whose metadata carries a
+ * `forkSourceMessageId` stamp (the last copied source message); its
+ * `createdAt` is the boundary. The stamp's value may point at any ancestor
+ * when the source was itself a fork (`cloneForkMessageMetadata` preserves
+ * pre-existing values), so we only check for presence, not equality.
+ * Returns `null` only if no copied messages remain (corrupted fork metadata
+ * or empty fork — caller logs + degrades).
+ */
+function findForkBoundaryCreatedAt(
+  forkMessages: Array<{
+    id: string;
+    createdAt: number;
+    metadata: string | null;
+  }>,
+): number | null {
+  for (let i = forkMessages.length - 1; i >= 0; i--) {
+    const row = forkMessages[i]!;
+    if (!row.metadata) continue;
+    try {
+      const parsed = JSON.parse(row.metadata) as {
+        forkSourceMessageId?: unknown;
+      };
+      if (typeof parsed.forkSourceMessageId === "string") {
+        return row.createdAt;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
 interface MessageLike {
   role: string;
   content: string;
@@ -339,17 +681,17 @@ function neutralizeSentinels(s: string): string {
     );
 }
 
-interface PromptArgs {
+interface LegacyPromptArgs {
   transcript: string;
   priorRemembers: string[];
   timeZone: string;
 }
 
-function buildPrompt({
+function buildLegacyPrompt({
   transcript,
   priorRemembers,
   timeZone,
-}: PromptArgs): string {
+}: LegacyPromptArgs): string {
   const safeTranscript = neutralizeSentinels(transcript);
   const renderedPrior =
     priorRemembers.length === 0
@@ -376,3 +718,56 @@ Two dedup sources to skip:
 For everything else, use the \`remember\` tool on facts, plans, decisions, preferences, names, dates, felt moments, corrections, commitments, or anything else concrete and worth carrying forward. One \`remember\` call per fact. If nothing new is worth saving, say "Nothing new to save." and stop.
 `;
 }
+
+// ---------------------------------------------------------------------------
+// Fork-based retrospective instruction
+// ---------------------------------------------------------------------------
+
+interface ForkInstructionArgs {
+  windowStartTimestamp: string;
+  priorRemembers: string[];
+  timeZone: string;
+  /** True when this is the first retrospective pass over the source conversation. */
+  isFirstPass: boolean;
+}
+
+/**
+ * Build the user-role instruction message appended to the forked conversation.
+ * The agent reads the conversation natively (including any inherited compaction
+ * summary + tail messages), so the prompt is short — it just anchors the
+ * review window by `<turn_context>` timestamp and lists the prior
+ * retrospective's saves for cross-kind dedup (a legacy-kind prior's
+ * `remember` calls aren't visible inside the forked conversation history).
+ */
+function buildForkInstruction({
+  windowStartTimestamp,
+  priorRemembers,
+  timeZone,
+  isFirstPass,
+}: ForkInstructionArgs): string {
+  const renderedPrior =
+    priorRemembers.length === 0
+      ? "(none — this is your first retrospective over this conversation)"
+      : priorRemembers.map((c) => `- ${neutralizeSentinels(c)}`).join("\n");
+
+  const windowAnchor = isFirstPass
+    ? "Your review window is the full conversation above."
+    : `Your review window starts at the user turn with \`current_time: ${neutralizeSentinels(windowStartTimestamp)}\` (timezone: ${timeZone}) and ends at the most recent message.`;
+
+  return `This is a memory retrospective pass over the conversation above.
+
+${windowAnchor}
+
+Here are the facts you saved in your previous retrospective pass over this conversation (so you don't restate them):
+
+<already_remembered>
+${renderedPrior}
+</already_remembered>
+
+Two dedup sources to skip:
+1. Anything semantically captured in <already_remembered> above (from your prior retrospective pass).
+2. Anything you already called \`remember\` on inline within your review window — those appear as \`tool_use\` blocks with \`name: "remember"\` in your history.
+
+For everything else in your review window, use the \`remember\` tool on facts, plans, decisions, preferences, names, dates, felt moments, corrections, commitments, or anything else concrete and worth carrying forward. One \`remember\` call per fact. If nothing new is worth saving, say "Nothing new to save." and stop.
+`;
+}

package/src/memory/memory-retrospective-startup-cleanup.ts

@@ -45,7 +45,7 @@ import {
 import { getLogger } from "../util/logger.js";
 import { deleteConversation } from "./conversation-crud.js";
 import { getDb } from "./db-connection.js";
-import { MEMORY_RETROSPECTIVE_SOURCE } from "./memory-retrospective-constants.js";
+import { MEMORY_RETROSPECTIVE_SOURCES } from "./memory-retrospective-constants.js";
 import { conversations, memoryJobs } from "./schema.js";
 
 const log = getLogger("memory-retrospective-startup-cleanup");
@@ -103,7 +103,7 @@ export function sweepOrphanMemoryRetrospectiveConversations(
     .from(conversations)
     .where(
       and(
-        eq(conversations.source, MEMORY_RETROSPECTIVE_SOURCE),
+        inArray(conversations.source, MEMORY_RETROSPECTIVE_SOURCES),
         isNotNull(conversations.forkParentConversationId),
       ),
     )
@@ -129,7 +129,7 @@ export function sweepOrphanMemoryRetrospectiveConversations(
     .from(conversations)
     .where(
       and(
-        eq(conversations.source, MEMORY_RETROSPECTIVE_SOURCE),
+        inArray(conversations.source, MEMORY_RETROSPECTIVE_SOURCES),
         // Conservative: only sweep rows that have had at least one message
         // AND haven't seen activity recently. Conversations without a
         // last_message_at value are too fresh to assess.

package/src/memory/memory-v2-activation-log-store.ts

@@ -44,19 +44,37 @@ export interface MemoryV2ConceptRowRecord {
    *   - `prior_state` — carried over from prior turn's activation state.
    *   - `ann_top50`   — entered via ANN top-K candidate pool.
    *   - `both`        — present in both prior state and ANN pool.
-   *   - `router`      — selected by the Sonnet router (memory-v2 router
-   *     mode). Router-mode rows zero out all activation values
-   *     (`finalActivation`, `ownActivation`, `priorActivation`, channel
-   *     similarities, rerank boosts, `spreadContribution`) because the
-   *     router does not compute spreading-activation scores.
+   *   - `router`      — legacy tag for memory-v2 router selections written
+   *     before tier-aware provenance landed. New rows never use this; old
+   *     activation log rows still carry it and the inspector renders it
+   *     as-is for backward compat.
+   *   - `tier1`       — router-mode, selected by the tier-1 (recently
+   *     modified) batch.
+   *   - `tier2`       — router-mode, selected by the tier-2 (highest EMA)
+   *     batch.
+   *   - `tier3:<N>`   — router-mode, selected by tier-3 batch N (0-indexed).
+   *     A single-batch (no-tier carve-out) workspace produces `tier3:0`.
+   *     The bucket index lets inspector queries attribute selections to
+   *     specific hash-bucketed parallel calls.
    *   - `carry_over`  — router-mode row representing a slug carried over
    *     from `priorEverInjected` that the router did NOT re-pick on this
    *     turn. The cached attachment from a prior turn is still present
-   *     on a prior user message; emitting `source: "router"` for these
+   *     on a prior user message; emitting one of the tier tags for these
    *     rows would overcount router selections in inspector queries.
-   *     Same zeroed activation values as `router`.
+   *
+   * All router-mode rows (`tier*`, `router`, `carry_over`) zero out the
+   * activation values (`finalActivation`, `ownActivation`, etc.) because
+   * the router does not compute spreading-activation scores.
    */
-  source: "prior_state" | "ann_top50" | "both" | "router" | "carry_over";
+  source:
+    | "prior_state"
+    | "ann_top50"
+    | "both"
+    | "router"
+    | "carry_over"
+    | "tier1"
+    | "tier2"
+    | `tier3:${number}`;
   /**
    * Per-turn outcome for this slug:
    *   - `in_context`  — already injected on a prior turn; cached attachment
@@ -97,11 +115,15 @@ export interface RecordMemoryV2ActivationLogParams {
    * `per-turn` for normal append injections, `errored` when `injectMemoryV2Block`
    * threw before completing — telemetry is still written so silent failures
    * are observable in the database, with whatever `concepts` rows had been
-   * built so far (possibly empty). `router` indicates the Sonnet
-   * router selected the per-turn page set; router-mode rows carry zeroed
-   * activation values and `source: "router"` on every concept row.
+   * built so far (possibly empty). `router` indicates the LLM router selected
+   * the per-turn page set; router-mode rows carry zeroed activation values and
+   * `source: "router"` on every concept row. `v3_shadow` is written by the
+   * live-shadow v3 retrieval middleware: it records v3's selection set for
+   * comparison without affecting injected context. The harness oracle filters
+   * `mode='router'`, so `v3_shadow` rows never pollute it; the inspector can
+   * still surface them.
    */
-  mode: "context-load" | "per-turn" | "errored" | "router";
+  mode: "context-load" | "per-turn" | "errored" | "router" | "v3_shadow";
   concepts: MemoryV2ConceptRowRecord[];
   config: MemoryV2ConfigSnapshot;
 }
@@ -149,7 +171,7 @@ export function backfillMemoryV2ActivationMessageId(
 export interface MemoryV2ActivationLog {
   conversationId: string;
   turn: number;
-  mode: "context-load" | "per-turn" | "errored" | "router";
+  mode: "context-load" | "per-turn" | "errored" | "router" | "v3_shadow";
   concepts: MemoryV2ConceptRowRecord[];
   config: MemoryV2ConfigSnapshot;
 }
@@ -170,7 +192,12 @@ export function getMemoryV2ActivationLogByMessageIds(
   return {
     conversationId: row.conversationId,
     turn: row.turn,
-    mode: row.mode as "context-load" | "per-turn" | "errored" | "router",
+    mode: row.mode as
+      | "context-load"
+      | "per-turn"
+      | "errored"
+      | "router"
+      | "v3_shadow",
     concepts: JSON.parse(row.conceptsJson) as MemoryV2ConceptRowRecord[],
     config: JSON.parse(row.configJson) as MemoryV2ConfigSnapshot,
   };

package/src/memory/migrations/100-core-tables.ts

@@ -205,6 +205,7 @@ export function createCoreTables(database: DrizzleDb): void {
       conversation_id TEXT NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
       message_id TEXT REFERENCES messages(id) ON DELETE CASCADE,
       delivery_status TEXT NOT NULL DEFAULT 'pending',
+      delivery_attempts INTEGER NOT NULL DEFAULT 0,
       created_at INTEGER NOT NULL,
       updated_at INTEGER NOT NULL,
       UNIQUE (source_channel, external_chat_id, external_message_id)

package/src/memory/migrations/109-external-conversation-bindings.ts

@@ -11,6 +11,7 @@ export function createExternalConversationBindingsTables(
       conversation_id TEXT PRIMARY KEY REFERENCES conversations(id) ON DELETE CASCADE,
       source_channel TEXT NOT NULL,
       external_chat_id TEXT NOT NULL,
+      external_chat_name TEXT,
       external_thread_id TEXT,
       external_user_id TEXT,
       display_name TEXT,

package/src/memory/migrations/253-conversation-last-notified-profile.ts

@@ -0,0 +1,15 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+export function migrateConversationLastNotifiedProfile(
+  database: DrizzleDb,
+): void {
+  const raw = getSqliteFrom(database);
+  try {
+    raw.exec(
+      `ALTER TABLE conversations ADD COLUMN last_notified_inference_profile TEXT DEFAULT NULL`,
+    );
+  } catch {
+    // Column already exists — nothing to do.
+  }
+}