@vellumai/assistant 0.4.56 → 0.5.0

package/src/memory/conversation-title-service.ts

@@ -146,7 +146,6 @@ export async function generateAndPersistConversationTitle(
       signal: combinedSignal,
     },
   );
-
   const textBlock = response.content.find((b) => b.type === "text");
   if (textBlock && textBlock.type === "text") {
     let title = normalizeTitle(textBlock.text);
@@ -312,7 +311,7 @@ function buildTitlePrompt(
   assistantResponse?: string,
 ): string {
   const parts: string[] = [
-    "Generate a very short title for this conversation. Rules: at most 5 words, at most 40 characters, no quotes, no markdown formatting.",
+    "Generate a very short title summarizing the TOPIC of this conversation. Rules: at most 5 words, at most 40 characters, no quotes, no markdown formatting. IMPORTANT: Summarize what the user is asking about — do NOT respond to the message, do NOT assess feasibility, and do NOT comment on your own capabilities.",
   ];
 
   if (context) {
@@ -369,7 +368,7 @@ function deriveFallbackTitle(context?: TitleContext): string | null {
 
 function buildRegenerationPrompt(recentMessages: MessageRow[]): string {
   const parts: string[] = [
-    "Generate a very short title for this conversation based on the recent messages below. Rules: at most 5 words, at most 40 characters, no quotes, no markdown formatting.",
+    "Generate a very short title summarizing the TOPIC of this conversation based on the recent messages below. Rules: at most 5 words, at most 40 characters, no quotes, no markdown formatting. IMPORTANT: Summarize what the user is asking about — do NOT respond to the messages, do NOT assess feasibility, and do NOT comment on your own capabilities.",
     "",
     "Recent messages:",
   ];

package/src/memory/db-init.ts

@@ -25,6 +25,7 @@ import {
   createCoreTables,
   createExternalConversationBindingsTables,
   createFollowupsTables,
+  createLifecycleEventsTable,
   createMediaAssetsTables,
   createMessagesFts,
   createNotificationTables,
@@ -51,8 +52,10 @@ import {
   migrateContactsRolePrincipal,
   migrateConversationsThreadTypeIndex,
   migrateCreateThreadStartersTable,
+  migrateCreateTraceEventsTable,
   migrateDropAccountsTable,
   migrateDropAssistantIdColumns,
+  migrateDropCapabilityCardState,
   migrateDropConflicts,
   migrateDropContactInteractionColumns,
   migrateDropEntityTables,
@@ -84,6 +87,7 @@ import {
   migrateReminderRoutingIntent,
   migrateRemindersToSchedules,
   migrateRenameConversationTypeColumn,
+  migrateRenameCreatedBySessionIdColumns,
   migrateRenameFollowupsThreadIdColumn,
   migrateRenameGmailProviderKeyToGoogle,
   migrateRenameGuardianVerificationValues,
@@ -91,6 +95,8 @@ import {
   migrateRenameNotificationThreadColumns,
   migrateRenameSequenceEnrollmentsThreadIdColumn,
   migrateRenameSequenceStepsReplyKey,
+  migrateRenameSourceSessionIdColumn,
+  migrateRenameThreadStartersTable,
   migrateRenameVerificationSessionIdColumn,
   migrateRenameVerificationTable,
   migrateRenameVoiceToPhone,
@@ -426,12 +432,30 @@ export function initializeDb(): void {
   // 72. Rename integration:gmail → integration:google across OAuth tables
   migrateRenameGmailProviderKeyToGoogle(database);
 
-  // 73. Create thread_starters table for personalized empty-thread suggestions
+  // 73. Create thread_starters table for personalized empty-thread suggestions (renamed in migration 77)
   migrateCreateThreadStartersTable(database);
 
   // 74. Add capability card columns to thread_starters + category relevance table
   migrateCapabilityCardColumns(database);
 
+  // 75. Rename created_by_session_id → source_conversation_id in verification sessions and invites
+  migrateRenameCreatedBySessionIdColumns(database);
+
+  // 76. Rename source_session_id → source_context_id in notification_events
+  migrateRenameSourceSessionIdColumn(database);
+
+  // 77. Rename thread_starters → conversation_starters table and indexes
+  migrateRenameThreadStartersTable(database);
+
+  // 78. Lifecycle events table for app_open / hatch telemetry
+  createLifecycleEventsTable(database);
+
+  // 79. Remove deleted capability-card state while keeping conversation starter chips
+  migrateDropCapabilityCardState(database);
+
+  // 80. Trace events table for persistent trace/activity storage across sessions
+  migrateCreateTraceEventsTable(database);
+
   validateMigrationState(database);
 
   if (process.env.BUN_TEST === "1") {

package/src/memory/invite-store.ts

@@ -23,7 +23,7 @@ export interface IngressInvite {
   id: string;
   sourceChannel: string;
   tokenHash: string;
-  createdByConversationId: string | null;
+  sourceConversationId: string | null;
   note: string | null;
   maxUses: number;
   useCount: number;
@@ -73,7 +73,7 @@ function rowToInvite(
     id: row.id,
     sourceChannel: row.sourceChannel,
     tokenHash: row.tokenHash,
-    createdByConversationId: row.createdByConversationId,
+    sourceConversationId: row.sourceConversationId,
     note: row.note,
     maxUses: row.maxUses,
     useCount: row.useCount,
@@ -101,7 +101,7 @@ function rowToInvite(
 export function createInvite(params: {
   sourceChannel: string;
   contactId: string;
-  createdByConversationId?: string;
+  sourceConversationId?: string;
   note?: string;
   maxUses?: number;
   expiresInMs?: number;
@@ -124,7 +124,7 @@ export function createInvite(params: {
     id,
     sourceChannel: params.sourceChannel,
     tokenHash: tokenH,
-    createdByConversationId: params.createdByConversationId ?? null,
+    sourceConversationId: params.sourceConversationId ?? null,
     note: params.note ?? null,
     maxUses: params.maxUses ?? 1,
     useCount: 0,

package/src/memory/items-extractor.ts

@@ -12,6 +12,7 @@ import {
 } from "../providers/provider-send-message.js";
 import { getLogger } from "../util/logger.js";
 import { truncate } from "../util/truncate.js";
+import { maybeEnqueueConversationStartersJob } from "./conversation-starters-cadence.js";
 import { getDb } from "./db.js";
 import { computeMemoryFingerprint } from "./fingerprint.js";
 import { enqueueMemoryJob } from "./jobs-store.js";
@@ -20,7 +21,6 @@ import { withQdrantBreaker } from "./qdrant-circuit-breaker.js";
 import { getQdrantClient } from "./qdrant-client.js";
 import { memoryItems, memoryItemSources, messages } from "./schema.js";
 import { isConversationFailed } from "./task-memory-cleanup.js";
-import { maybeEnqueueThreadStartersJob } from "./thread-starters-cadence.js";
 import { clampUnitInterval } from "./validation.js";
 
 const log = getLogger("memory-items-extractor");
@@ -715,14 +715,14 @@ export async function extractAndUpsertMemoryItemsForMessage(
     "Extracted memory items from message",
   );
 
-  // Trigger thread starters generation when new items are upserted
+  // Trigger conversation starters generation when new items are upserted
   if (upserted > 0) {
     try {
-      maybeEnqueueThreadStartersJob(effectiveScopeId);
+      maybeEnqueueConversationStartersJob(effectiveScopeId);
     } catch (err) {
       log.warn(
         { err: err instanceof Error ? err.message : String(err) },
-        "Failed to check thread starters cadence",
+        "Failed to check conversation starters cadence",
       );
     }
   }

package/src/memory/job-handlers/{thread-starters.ts → conversation-starters.ts}

@@ -1,14 +1,15 @@
 /**
- * Job handler for generating thread starters.
+ * Job handler for generating conversation starters.
  *
  * Crosses user memory items with the skill catalog to produce personalized
- * suggestion chips shown on the empty thread page.
+ * suggestion chips shown on the empty conversation page.
  */
 
 import { and, desc, eq } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import { loadSkillCatalog } from "../../config/skills.js";
+import { buildCoreIdentityContext } from "../../prompts/system-prompt.js";
 import {
   createTimeout,
   extractToolUse,
@@ -21,17 +22,21 @@ import { getDb } from "../db.js";
 import { asString } from "../job-utils.js";
 import type { MemoryJob } from "../jobs-store.js";
 import { rawAll, rawGet } from "../raw-query.js";
-import { memoryCheckpoints, memoryItems, threadStarters } from "../schema.js";
+import {
+  conversationStarters,
+  memoryCheckpoints,
+  memoryItems,
+} from "../schema.js";
 
-const log = getLogger("thread-starters-gen");
+const log = getLogger("conversation-starters-gen");
 
 function checkpointKey(base: string, scopeId: string): string {
   return `${base}:${scopeId}`;
 }
 
-const CK_ITEM_COUNT = "thread_starters:item_count_at_last_gen";
-const CK_BATCH = "thread_starters:generation_batch";
-const CK_LAST_GEN_AT = "thread_starters:last_gen_at";
+const CK_ITEM_COUNT = "conversation_starters:item_count_at_last_gen";
+const CK_BATCH = "conversation_starters:generation_batch";
+const CK_LAST_GEN_AT = "conversation_starters:last_gen_at";
 
 // ── Rollup construction ───────────────────────────────────────────
 
@@ -126,7 +131,7 @@ export function buildSkillsSummary(): string {
 // ── LLM generation ────────────────────────────────────────────────
 
 /** Capability categories matching the Intelligence page taxonomy. */
-export const THREAD_STARTER_CATEGORIES = [
+export const CONVERSATION_STARTER_CATEGORIES = [
   "communication",
   "productivity",
   "development",
@@ -137,7 +142,8 @@ export const THREAD_STARTER_CATEGORIES = [
   "integration",
 ] as const;
 
-export type ThreadStarterCategory = (typeof THREAD_STARTER_CATEGORIES)[number];
+export type ConversationStarterCategory =
+  (typeof CONVERSATION_STARTER_CATEGORIES)[number];
 
 interface GeneratedStarter {
   label: string;
@@ -148,48 +154,110 @@ interface GeneratedStarter {
 async function generateStarters(scopeId: string): Promise<GeneratedStarter[]> {
   const provider = await getConfiguredProvider();
   if (!provider) {
-    log.info("No configured provider for thread starters generation");
+    log.info("No configured provider for conversation starters generation");
     return [];
   }
 
   const rollup = buildMemoryRollup(scopeId);
   if (!rollup) {
-    log.info("No memory items to generate thread starters from");
+    log.info("No memory items to generate conversation starters from");
     return [];
   }
   const diff = buildNewItemsDiff(scopeId);
   const skills = buildSkillsSummary();
 
-  const systemPrompt = `You are generating thread starter suggestions for a personal AI assistant's empty conversation page. These are clickable chips that help the user discover what the assistant can do, personalized to their context.
+  const now = new Date();
+  const timeContext = `Current time: ${now.toLocaleString("en-US", { weekday: "long", year: "numeric", month: "long", day: "numeric", hour: "numeric", minute: "2-digit", hour12: true })}`;
+
+  const identityContext = buildCoreIdentityContext();
+
+  const systemPrompt = `You are generating 4 conversation starters for a personal assistant app. These appear as clickable chips on the empty conversation page — the first thing the user sees when they open the app.
+
+${timeContext}
 
-Given the user's accumulated memories and the assistant's available skills, generate 4-6 thread starters. Each starter has:
-- label: Short chip text (max 50 chars). Start with a verb. Be specific and actionable.
-- prompt: The full message that will be sent when clicked (1-2 natural sentences).
-- category: One of: ${THREAD_STARTER_CATEGORIES.join(", ")}. Pick the best-fit capability category.
+Your goal: look at what's going on in this person's life right now and suggest the 4 most useful things they could ask you to do. Think about what a thoughtful chief of staff would proactively bring up in a 30-second check-in.
 
-Rules:
-- Cross user context (who they are, what they work on) with assistant capabilities (skills).
-- Be specific to THIS user — generic suggestions like "Tell me a joke" are not useful.
-- Vary across different skills and memory categories.
-- Labels should be concise and scannable.
-- Prompts should be natural, as if the user typed them.
+${identityContext ? `## Assistant identity & user profile\n\n${identityContext}\n\n` : ""}## What you know
 
 ${rollup}
 ${diff}
-${skills}`;
+${skills}
+
+## How to think about this
+
+Start from the user's situation, not from the skill list. Ask yourself:
+- What is this person likely dealing with right now (given the day/time and their context)?
+- What's active, stuck, or coming up soon?
+- Where could I save them real time or effort right now?
+
+The skills list tells you what the assistant CAN do — use it to filter out suggestions the assistant can't actually help with, not as a menu to generate suggestions from.
+
+## Selection
+
+Generate exactly 4 starters, ranked #1 (best) to #4.
+
+For each, you must be able to clearly answer:
+- Why now? (timing — day of week, recent activity, upcoming deadline)
+- Why this user? (grounded in their specific context, not generic)
+- Why would they be glad I suggested this? (genuine usefulness, not just relevance)
+
+If you can't answer all three strongly, replace it with something better.
+
+Prioritize:
+- Relief: unblock something stuck, reduce drag
+- Momentum: advance work already in motion
+- Confidence: surface what they need to decide or act on
+- Curiosity: something timely they'd want to know about
+
+Favor what is live over what is merely true. Recent changes matter more than old memories. Active work matters more than dormant topics. This week matters more than "someday."
+
+## Output format
+
+Return exactly 4 starters in rank order (best first).
+
+Each starter has:
+- label: 3-6 words, max 40 chars, starts with a verb. Should sound like a smart offer of help, not a feature name or task description. Must sound natural when read aloud.
+- prompt: 1-2 natural sentences, written as the user would actually say them — not templated.
+- category: one of ${CONVERSATION_STARTER_CATEGORIES.join(", ")}
+
+The 4 starters should feel like one coherent set of recommendations for this moment — similar abstraction level, no jarring mix of mundane chores and life strategy. Don't lift raw memory phrases, project names, or jargon into labels unless they already sound natural in conversation.
+
+Never include a chip whose primary meaning is configuration, setup, workflow creation, or "set up X for Y" unless it solves an urgent pain the user is actively feeling right now. Prefer the outcome over the mechanism — "Catch the emails that matter" beats "Set up a playbook for inbox."
+
+## Topic diversity
+
+Each chip should cover a distinct topic or concern. Never have two chips about the same tool, project, or theme — even if there are multiple related issues. Pick the single most impactful angle and give the other slot to something different. Four chips about three topics is too narrow; four chips about four topics is right.
+
+## User-facingness check
+
+If a label sounds like an issue title, project ticket, or implementation task, rewrite it. Prefer the user-visible payoff over the internal object name. The chip should feel inviting and useful, not merely accurate.
+
+Prefer natural, flowing language over mechanical or operational phrasing. "Get Slack messages flowing" is better than "Restore outgoing Slack messages." The label should sound like something a helpful person would say, not a support ticket.
+
+Before finalizing each label, ask yourself: would this feel good to click? Or does it sound like a backlog item? If it sounds like a backlog item, rewrite it.
+
+Examples of bad vs good:
+- BAD: "Fix Slack Socket Mode blocker" → GOOD: "Fix Slack so it just works"
+- BAD: "Rewire messaging for Socket Mode" → GOOD: "Get Socket Mode stable"
+- BAD: "Review this week's calendar" → GOOD: "Protect this week's focus"
+- BAD: "Model the coaching transition" → GOOD: "Plan the coaching transition"
+- BAD: "Restore outgoing Slack messages" → GOOD: "Get Slack messages flowing"
+- BAD: "Set up a playbook for inbox" → GOOD: "Catch the emails that matter"
+
+The good versions emphasize the user's payoff, not the internal mechanism.`;
 
   const { signal, cleanup } = createTimeout(20000);
   try {
     const response = await provider.sendMessage(
       [
         userMessage(
-          "Generate personalized thread starters based on my context.",
+          "Generate personalized conversation starters based on my context.",
         ),
       ],
       [
         {
-          name: "store_thread_starters",
-          description: "Store generated thread starter suggestions",
+          name: "store_conversation_starters",
+          description: "Store generated conversation starter suggestions",
           input_schema: {
             type: "object" as const,
             properties: {
@@ -201,15 +269,16 @@ ${skills}`;
                     label: {
                       type: "string",
                       description:
-                        "Short chip text (max 50 chars, starts with a verb)",
+                        "Concierge-quality chip text (2-7 words, max 40 chars, starts with a verb)",
                     },
                     prompt: {
                       type: "string",
-                      description: "Full message sent on click (1-2 sentences)",
+                      description:
+                        "Full message sent on click (1-2 natural sentences, as the user would say it)",
                     },
                     category: {
                       type: "string",
-                      enum: [...THREAD_STARTER_CATEGORIES],
+                      enum: [...CONVERSATION_STARTER_CATEGORIES],
                       description: "Capability category for grouping",
                     },
                   },
@@ -226,7 +295,10 @@ ${skills}`;
         config: {
           modelIntent: "quality-optimized",
           max_tokens: 1024,
-          tool_choice: { type: "tool" as const, name: "store_thread_starters" },
+          tool_choice: {
+            type: "tool" as const,
+            name: "store_conversation_starters",
+          },
         },
         signal,
       },
@@ -235,7 +307,9 @@ ${skills}`;
 
     const toolBlock = extractToolUse(response);
     if (!toolBlock) {
-      log.warn("No tool_use block in thread starters generation response");
+      log.warn(
+        "No tool_use block in conversation starters generation response",
+      );
       return [];
     }
 
@@ -253,12 +327,15 @@ ${skills}`;
           typeof s.prompt === "string" &&
           s.prompt.length > 0,
       )
+      .slice(0, 4)
       .map((s) => ({
-        label: truncate(s.label, 50, ""),
+        label: truncate(s.label, 40, ""),
         prompt: truncate(s.prompt, 500, ""),
         category:
           typeof s.category === "string" &&
-          (THREAD_STARTER_CATEGORIES as readonly string[]).includes(s.category)
+          (CONVERSATION_STARTER_CATEGORIES as readonly string[]).includes(
+            s.category,
+          )
             ? s.category
             : "productivity",
       }));
@@ -270,12 +347,14 @@ ${skills}`;
 
 // ── Job handler ───────────────────────────────────────────────────
 
-export async function generateThreadStartersJob(job: MemoryJob): Promise<void> {
+export async function generateConversationStartersJob(
+  job: MemoryJob,
+): Promise<void> {
   const scopeId = asString(job.payload.scopeId) ?? "default";
 
   const starters = await generateStarters(scopeId);
   if (starters.length === 0) {
-    log.info({ scopeId }, "No thread starters generated");
+    log.info({ scopeId }, "No conversation starters generated");
     return;
   }
 
@@ -303,14 +382,20 @@ export async function generateThreadStartersJob(job: MemoryJob): Promise<void> {
     .all();
   const sourceKinds = kindRows.map((r) => r.kind).join(",");
 
-  // Insert starters
+  // Remove previous starters for this scope before inserting the new batch
+  db.delete(conversationStarters)
+    .where(eq(conversationStarters.scopeId, scopeId))
+    .run();
+
+  // Insert starters — all are chips
   for (const starter of starters) {
-    db.insert(threadStarters)
+    db.insert(conversationStarters)
       .values({
         id: uuid(),
         label: starter.label,
         prompt: starter.prompt,
         category: starter.category,
+        cardType: "chip",
         generationBatch: nextBatch,
         scopeId,
         sourceMemoryKinds: sourceKinds,
@@ -343,6 +428,6 @@ export async function generateThreadStartersJob(job: MemoryJob): Promise<void> {
 
   log.info(
     { scopeId, batch: nextBatch, count: starters.length },
-    "Generated thread starters",
+    "Generated conversation starters",
   );
 }

package/src/memory/jobs-store.ts

@@ -26,8 +26,9 @@ export type MemoryJobType =
   | "media_processing"
   | "embed_media"
   | "embed_attachment"
-  | "generate_thread_starters"
-  | "generate_capability_cards";
+  | "generate_conversation_starters"
+  | "generate_capability_cards" // legacy compat — silently dropped by worker (capability cards removed)
+  | "generate_thread_starters"; // legacy compat — silently dropped by worker (renamed to generate_conversation_starters)
 
 const EMBED_JOB_TYPES: MemoryJobType[] = [
   "embed_segment",

package/src/memory/jobs-worker.ts

@@ -3,11 +3,11 @@ import type { AssistantConfig } from "../config/types.js";
 import { getLogger } from "../util/logger.js";
 import { rawRun } from "./db.js";
 import { backfillJob } from "./job-handlers/backfill.js";
-import { generateCapabilityCardsJob } from "./job-handlers/capability-cards.js";
 import {
   cleanupStaleSupersededItemsJob,
   pruneOldConversationsJob,
 } from "./job-handlers/cleanup.js";
+import { generateConversationStartersJob } from "./job-handlers/conversation-starters.js";
 // ── Per-job-type handlers ──────────────────────────────────────────
 import {
   embedAttachmentJob,
@@ -23,7 +23,6 @@ import {
 } from "./job-handlers/index-maintenance.js";
 import { mediaProcessingJob } from "./job-handlers/media-processing.js";
 import { buildConversationSummaryJob } from "./job-handlers/summarization.js";
-import { generateThreadStartersJob } from "./job-handlers/thread-starters.js";
 import {
   BackendUnavailableError,
   classifyError,
@@ -308,11 +307,14 @@ async function processJob(
     case "embed_attachment":
       await embedAttachmentJob(job, config);
       return;
-    case "generate_thread_starters":
-      await generateThreadStartersJob(job);
+    case "generate_conversation_starters":
+      await generateConversationStartersJob(job);
       return;
     case "generate_capability_cards":
-      await generateCapabilityCardsJob(job);
+      // Capability cards were removed — silently drop legacy jobs.
+      return;
+    case "generate_thread_starters":
+      // Thread starters renamed to conversation starters — silently drop legacy jobs
       return;
     default:
       throw new Error(

package/src/memory/lifecycle-events-store.ts

@@ -0,0 +1,63 @@
+import { and, asc, eq, gt, or } from "drizzle-orm";
+import { v4 as uuid } from "uuid";
+
+import { getDb } from "./db.js";
+import { lifecycleEvents } from "./schema.js";
+
+export interface LifecycleEvent {
+  id: string;
+  eventName: string;
+  createdAt: number;
+}
+
+/** Record a lifecycle event (e.g. app_open, hatch). */
+export function recordLifecycleEvent(eventName: string): LifecycleEvent {
+  const db = getDb();
+  const event: LifecycleEvent = {
+    id: uuid(),
+    eventName,
+    createdAt: Date.now(),
+  };
+  db.insert(lifecycleEvents)
+    .values({
+      id: event.id,
+      eventName: event.eventName,
+      createdAt: event.createdAt,
+    })
+    .run();
+  return event;
+}
+
+/**
+ * Query lifecycle events that haven't been reported to telemetry yet.
+ * Uses a compound cursor (createdAt + id) for reliable watermarking.
+ */
+export function queryUnreportedLifecycleEvents(
+  afterCreatedAt: number,
+  afterId: string | undefined,
+  limit: number,
+): LifecycleEvent[] {
+  const db = getDb();
+  const rows = db
+    .select({
+      id: lifecycleEvents.id,
+      eventName: lifecycleEvents.eventName,
+      createdAt: lifecycleEvents.createdAt,
+    })
+    .from(lifecycleEvents)
+    .where(
+      afterId
+        ? or(
+            gt(lifecycleEvents.createdAt, afterCreatedAt),
+            and(
+              eq(lifecycleEvents.createdAt, afterCreatedAt),
+              gt(lifecycleEvents.id, afterId),
+            ),
+          )
+        : gt(lifecycleEvents.createdAt, afterCreatedAt),
+    )
+    .orderBy(asc(lifecycleEvents.createdAt), asc(lifecycleEvents.id))
+    .limit(limit)
+    .all();
+  return rows;
+}

package/src/memory/migrations/172-rename-created-by-session-id.ts

@@ -0,0 +1,27 @@
+import { type DrizzleDb } from "../db-connection.js";
+
+/**
+ * Rename `created_by_session_id` to `source_conversation_id` in two tables,
+ * aligning with the broader session → conversation terminology unification.
+ *
+ * Each rename is wrapped in try/catch so re-running the migration is
+ * idempotent (SQLite throws if the source column does not exist).
+ */
+export function migrateRenameCreatedBySessionIdColumns(
+  database: DrizzleDb,
+): void {
+  try {
+    database.run(
+      `ALTER TABLE channel_verification_sessions RENAME COLUMN created_by_session_id TO source_conversation_id`,
+    );
+  } catch {
+    /* already renamed */
+  }
+  try {
+    database.run(
+      `ALTER TABLE assistant_ingress_invites RENAME COLUMN created_by_session_id TO source_conversation_id`,
+    );
+  } catch {
+    /* already renamed */
+  }
+}

package/src/memory/migrations/173-rename-source-session-id.ts

@@ -0,0 +1,16 @@
+import { type DrizzleDb } from "../db-connection.js";
+
+/**
+ * Rename `source_session_id` to `source_context_id` in the `notification_events`
+ * table, aligning with the field's actual polymorphic usage (it holds conversation
+ * IDs, call session IDs, schedule IDs, etc.).
+ */
+export function migrateRenameSourceSessionIdColumn(database: DrizzleDb): void {
+  try {
+    database.run(
+      `ALTER TABLE notification_events RENAME COLUMN source_session_id TO source_context_id`,
+    );
+  } catch {
+    /* already renamed */
+  }
+}