@vellumai/assistant 0.6.3 → 0.6.5

package/src/memory/jobs-worker.ts

@@ -2,6 +2,13 @@ import { getConfig } from "../config/loader.js";
 import type { AssistantConfig } from "../config/types.js";
 import { getLogger } from "../util/logger.js";
 import { getMemoryCheckpoint, setMemoryCheckpoint } from "./checkpoints.js";
+import {
+  getLastScheduledCleanupEnqueueMs,
+  markScheduledCleanupEnqueued,
+  resetCleanupScheduleThrottle as resetCleanupScheduleThrottleImpl,
+} from "./cleanup-schedule-state.js";
+import { conversationAnalyzeJob } from "./conversation-analyze-job.js";
+import { maybeRunDbMaintenance } from "./db-maintenance.js";
 import { bootstrapFromHistory } from "./graph/bootstrap.js";
 import { runConsolidation } from "./graph/consolidation.js";
 import { runDecayTick } from "./graph/decay.js";
@@ -37,6 +44,7 @@ import {
   RETRY_MAX_ATTEMPTS,
   retryDelayForAttempt,
 } from "./job-utils.js";
+import { embedPkbFileJob } from "./jobs/embed-pkb-file.js";
 import {
   claimMemoryJobs,
   completeMemoryJob,
@@ -160,6 +168,7 @@ export async function runMemoryJobsOnce(
       maybeEnqueueScheduledCleanupJobs(config);
     }
     maybeEnqueueGraphMaintenanceJobs();
+    maybeRunDbMaintenance();
     return 0;
   }
 
@@ -256,6 +265,7 @@ export async function runMemoryJobsOnce(
     maybeEnqueueScheduledCleanupJobs(config);
   }
   maybeEnqueueGraphMaintenanceJobs();
+  maybeRunDbMaintenance();
   return processed;
 }
 
@@ -411,12 +421,18 @@ async function processJob(
     case "embed_graph_node":
       await embedGraphNodeJob(job, config);
       return;
+    case "embed_pkb_file":
+      await embedPkbFileJob(job, config);
+      return;
     case "graph_trigger_embed":
       await embedGraphTriggerJob(job, config);
       return;
     case "graph_extract":
       await graphExtractJob(job, config);
       return;
+    case "conversation_analyze":
+      await conversationAnalyzeJob(job, config);
+      return;
     case "graph_decay":
       graphDecayJob(job);
       return;
@@ -449,12 +465,13 @@ async function processJob(
 
 // ── Cleanup scheduling ─────────────────────────────────────────────
 
-let lastScheduledCleanupEnqueueMs = 0;
-
-/** Reset the cleanup enqueue throttle so tests can run deterministic checks. */
-export function resetCleanupScheduleThrottle(): void {
-  lastScheduledCleanupEnqueueMs = 0;
-}
+/**
+ * Re-export of the shared throttle-reset helper. The underlying state lives
+ * in cleanup-schedule-state.ts so that lighter-weight callers (e.g.
+ * ConfigWatcher) can reset it without pulling in jobs-worker's transitive
+ * imports.
+ */
+export const resetCleanupScheduleThrottle = resetCleanupScheduleThrottleImpl;
 
 /**
  * Enqueue periodic cleanup jobs using config-driven retention windows.
@@ -466,7 +483,7 @@ export function maybeEnqueueScheduledCleanupJobs(
 ): boolean {
   const cleanup = config.memory.cleanup;
   if (!cleanup.enabled) return false;
-  if (nowMs - lastScheduledCleanupEnqueueMs < cleanup.enqueueIntervalMs)
+  if (nowMs - getLastScheduledCleanupEnqueueMs() < cleanup.enqueueIntervalMs)
     return false;
 
   const pruneConversationsJobId =
@@ -474,10 +491,10 @@ export function maybeEnqueueScheduledCleanupJobs(
       ? enqueuePruneOldConversationsJob(cleanup.conversationRetentionDays)
       : null;
   const pruneLlmRequestLogsJobId =
-    cleanup.llmRequestLogRetentionMs > 0
+    cleanup.llmRequestLogRetentionMs !== null
       ? enqueuePruneOldLlmRequestLogsJob(cleanup.llmRequestLogRetentionMs)
       : null;
-  lastScheduledCleanupEnqueueMs = nowMs;
+  markScheduledCleanupEnqueued(nowMs);
   log.debug(
     {
       pruneConversationsJobId,

package/src/memory/llm-usage-store.ts

@@ -9,6 +9,11 @@ import type {
 import { getDb } from "./db.js";
 import { rawAll } from "./raw-query.js";
 import { llmUsageEvents } from "./schema.js";
+import {
+  bucketEventsByDay,
+  bucketEventsByHour,
+  type UsageEventBucketRow,
+} from "./usage-buckets.js";
 
 // ---------------------------------------------------------------------------
 // Write
@@ -152,8 +157,25 @@ export type UsageGranularity = "daily" | "hourly";
 
 /** A single time bucket with its aggregate totals. */
 export interface UsageDayBucket {
-  /** ISO date string: "YYYY-MM-DD" (daily) or "YYYY-MM-DD HH:00" (hourly), UTC. */
+  /**
+   * Stable unique identifier for the bucket. Safe for use as a SwiftUI/React
+   * list key. Distinct even for DST fall-back duplicate hours (which share the
+   * same `date` string). Daily buckets use `date` directly; hourly buckets use
+   * "YYYY-MM-DD HH:00|<offsetMinutes>" to disambiguate repeated local hours.
+   */
+  bucketId: string;
+  /**
+   * Local-time bucket key in the requested tz:
+   * "YYYY-MM-DD" (daily) or "YYYY-MM-DD HH:00" (hourly).
+   * NOT unique: on DST fall-back days, two 01:00 hourly buckets share this key.
+   * Use `bucketId` as a list identifier and `date` for display/sort only.
+   */
   date: string;
+  /**
+   * Human-readable label for the bucket, formatted in the requested tz.
+   * Hourly: "3pm". Daily: "Apr 11".
+   */
+  displayLabel?: string;
   /** Direct input tokens only; cache traffic is tracked separately in totals. */
   totalInputTokens: number;
   totalOutputTokens: number;
@@ -164,6 +186,14 @@ export interface UsageDayBucket {
 /** A grouped breakdown row (by actor, provider, or model). */
 export interface UsageGroupBreakdown {
   group: string;
+  /**
+   * Stable identifier for the group. Populated with the conversation id when
+   * `groupBy === "conversation"` (and `null` for that mode's "Other" bucket,
+   * which aggregates events with no conversation id). For all other group-bys
+   * (`actor`, `provider`, `model`) this is always `null` — the raw grouping
+   * column is already exposed via `group`.
+   */
+  groupId: string | null;
   /** Direct input tokens only; cache traffic is reported separately below. */
   totalInputTokens: number;
   totalOutputTokens: number;
@@ -186,16 +216,10 @@ interface TotalsRow {
   unpriced_event_count: number;
 }
 
-interface DayBucketRow {
-  date: string;
-  total_input_tokens: number;
-  total_output_tokens: number;
-  total_estimated_cost_usd: number | null;
-  event_count: number;
-}
 
 interface GroupRow {
   group_key: string;
+  group_id: string | null;
   total_input_tokens: number;
   total_output_tokens: number;
   total_cache_creation_tokens: number;
@@ -238,67 +262,68 @@ export function getUsageTotals(range: UsageTimeRange): UsageTotals {
   };
 }
 
-/**
- * Return per-day aggregates (UTC) within the given time range, ordered by date ascending.
- *
- * Each bucket key is a YYYY-MM-DD string derived by dividing the epoch-millis
- * timestamp by 86400000 and formatting as a date.
- */
-export function getUsageDayBuckets(range: UsageTimeRange): UsageDayBucket[] {
-  const rows = rawAll<DayBucketRow>(
+/** Fetch raw events in a time range for in-memory bucketing. */
+function fetchRawBucketRows(range: UsageTimeRange): UsageEventBucketRow[] {
+  return rawAll<UsageEventBucketRow>(
     /*sql*/ `
     SELECT
-      strftime('%Y-%m-%d', created_at / 1000, 'unixepoch')  AS date,
-      COALESCE(SUM(input_tokens), 0)                         AS total_input_tokens,
-      COALESCE(SUM(output_tokens), 0)                        AS total_output_tokens,
-      COALESCE(SUM(estimated_cost_usd), 0)                   AS total_estimated_cost_usd,
-      COALESCE(SUM(COALESCE(llm_call_count, 1)), 0)          AS event_count
+      created_at,
+      input_tokens,
+      output_tokens,
+      estimated_cost_usd,
+      llm_call_count
     FROM llm_usage_events
     WHERE created_at >= ?1 AND created_at <= ?2
-    GROUP BY date
-    ORDER BY date ASC
     `,
     range.from,
     range.to,
   );
-  return rows.map((r) => ({
-    date: r.date,
-    totalInputTokens: r.total_input_tokens,
-    totalOutputTokens: r.total_output_tokens,
-    totalEstimatedCostUsd: r.total_estimated_cost_usd ?? 0,
-    eventCount: r.event_count,
-  }));
+}
+
+/** Options for bucket aggregation. */
+export interface UsageBucketOptions {
+  /**
+   * When true, emit a zero-value bucket for every day (or hour) in the range
+   * even if no events fall inside it. Defaults to false so the CLI and other
+   * callers only see active periods; the chart route opts in.
+   */
+  fillEmpty?: boolean;
 }
 
 /**
- * Return per-hour aggregates (UTC) within the given time range, ordered ascending.
+ * Return per-day aggregates within the given time range, keyed by local date
+ * in the requested timezone (default UTC).
  *
- * Each bucket key is a "YYYY-MM-DD HH:00" string.
+ * Each bucket key is a "YYYY-MM-DD" string anchored on local midnight in `tz`.
+ * When `options.fillEmpty` is true, empty days within the range are filled
+ * with zero-value buckets. DST-short and DST-long local days are handled
+ * correctly.
  */
-export function getUsageHourBuckets(range: UsageTimeRange): UsageDayBucket[] {
-  const rows = rawAll<DayBucketRow>(
-    /*sql*/ `
-    SELECT
-      strftime('%Y-%m-%d %H:00', created_at / 1000, 'unixepoch')  AS date,
-      COALESCE(SUM(input_tokens), 0)                               AS total_input_tokens,
-      COALESCE(SUM(output_tokens), 0)                              AS total_output_tokens,
-      COALESCE(SUM(estimated_cost_usd), 0)                         AS total_estimated_cost_usd,
-      COALESCE(SUM(COALESCE(llm_call_count, 1)), 0)                AS event_count
-    FROM llm_usage_events
-    WHERE created_at >= ?1 AND created_at <= ?2
-    GROUP BY date
-    ORDER BY date ASC
-    `,
-    range.from,
-    range.to,
-  );
-  return rows.map((r) => ({
-    date: r.date,
-    totalInputTokens: r.total_input_tokens,
-    totalOutputTokens: r.total_output_tokens,
-    totalEstimatedCostUsd: r.total_estimated_cost_usd ?? 0,
-    eventCount: r.event_count,
-  }));
+export function getUsageDayBuckets(
+  range: UsageTimeRange,
+  tz: string = "UTC",
+  options: UsageBucketOptions = {},
+): UsageDayBucket[] {
+  const rows = fetchRawBucketRows(range);
+  return bucketEventsByDay(rows, range, tz, options);
+}
+
+/**
+ * Return per-hour aggregates within the given time range, keyed by local hour
+ * in the requested timezone (default UTC).
+ *
+ * Each bucket key is a "YYYY-MM-DD HH:00" string anchored on local hour starts.
+ * When `options.fillEmpty` is true, empty hours are filled with zero-value
+ * buckets. DST fall-back produces two distinct buckets for the duplicated hour;
+ * DST spring-forward produces 23 buckets for the affected day.
+ */
+export function getUsageHourBuckets(
+  range: UsageTimeRange,
+  tz: string = "UTC",
+  options: UsageBucketOptions = {},
+): UsageDayBucket[] {
+  const rows = fetchRawBucketRows(range);
+  return bucketEventsByHour(rows, range, tz, options);
 }
 
 type GroupByDimension = "actor" | "provider" | "model" | "conversation";
@@ -330,6 +355,7 @@ export function getUsageGroupBreakdown(
         CASE WHEN e.conversation_id IS NULL THEN 'Other'
              ELSE COALESCE(c.title, 'Untitled')
         END AS group_key,
+        e.conversation_id                                AS group_id,
         COALESCE(SUM(e.input_tokens), 0)                 AS total_input_tokens,
         COALESCE(SUM(e.output_tokens), 0)                AS total_output_tokens,
         COALESCE(SUM(e.cache_creation_input_tokens), 0)  AS total_cache_creation_tokens,
@@ -348,6 +374,10 @@ export function getUsageGroupBreakdown(
     );
     return rows.map((r) => ({
       group: r.group_key,
+      // `GROUP BY e.conversation_id` makes `e.conversation_id` unambiguous
+      // inside each group — it is the seeded conversation id for real rows
+      // and `null` for the "Other" bucket (events with no conversation).
+      groupId: r.group_id,
       totalInputTokens: r.total_input_tokens,
       totalOutputTokens: r.total_output_tokens,
       totalCacheCreationTokens: r.total_cache_creation_tokens,
@@ -362,6 +392,7 @@ export function getUsageGroupBreakdown(
     /*sql*/ `
     SELECT
       ${column}                                      AS group_key,
+      NULL                                           AS group_id,
       COALESCE(SUM(input_tokens), 0)                 AS total_input_tokens,
       COALESCE(SUM(output_tokens), 0)                AS total_output_tokens,
       COALESCE(SUM(cache_creation_input_tokens), 0)  AS total_cache_creation_tokens,
@@ -378,6 +409,11 @@ export function getUsageGroupBreakdown(
   );
   return rows.map((r) => ({
     group: r.group_key,
+    // Non-conversation group-bys (actor/provider/model) don't have a
+    // separate stable id — the grouping column itself is the identifier
+    // and is already exposed via `group`. The SELECT projects
+    // `NULL AS group_id` so the runtime shape matches `GroupRow`.
+    groupId: r.group_id,
     totalInputTokens: r.total_input_tokens,
     totalOutputTokens: r.total_output_tokens,
     totalCacheCreationTokens: r.total_cache_creation_tokens,

package/src/memory/migrations/140-backfill-usage-cache-accounting.ts

@@ -196,7 +196,7 @@ export function migrateBackfillUsageCacheAccounting(database: DrizzleDb): void {
     const requestLogsByConversation = buildRequestLogMap(requestLogRows);
     const requestOffsets = new Map<string, number>();
     const previousUsageEventCreatedAt = new Map<string, number>();
-    const pricingOverrides = getConfig().pricingOverrides;
+    const pricingOverrides = getConfig().llm.pricingOverrides;
 
     let scannedAnthropicRows = 0;
     let updatedRows = 0;

package/src/memory/migrations/219-oauth-providers-token-exchange-body-format.ts

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

package/src/memory/migrations/220-normalize-user-file-by-principal.ts

@@ -0,0 +1,190 @@
+import { computeUserFileBaseSlug } from "../../contacts/contact-store.js";
+import { type DrizzleDb, getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+/**
+ * Reverse is a no-op. This migration only consolidates `user_file` across
+ * contacts sharing the same `principal_id`; the pre-migration split values
+ * cannot be reconstructed after normalization, and no schema changes.
+ */
+export function downNormalizeUserFileByPrincipal(_database: DrizzleDb): void {
+  /* no-op */
+}
+
+/**
+ * Heuristic: does `userFile` look like an auto-incremented persona slug?
+ *
+ * `generateUserFileSlug` appends `-<N>.md` where N is any positive integer
+ * (the loop is unbounded, so a very dense principal space could reach 4+
+ * digits). Matching is anchored to the end so a slug that happens to contain
+ * digits earlier (e.g. `alex-2024.md` for display name "Alex 2024") is not
+ * affected.
+ *
+ * The final-integer suffix also matches year-like or date-like names
+ * (`-2025.md`, `-2025-04-13.md` via the trailing `-13.md`). Those must NOT
+ * be classified as auto-increments, so we exclude any filename that ends
+ * with a date-shaped tail: `-YYYY.md`, `-YYYY-MM.md`, or `-YYYY-MM-DD.md`
+ * where YYYY is a 4-digit year starting with 19, 20, or 21. A counter that
+ * happens to fall in that range (e.g. `-1999.md`) is indistinguishable from
+ * a year by filename alone, so we conservatively treat it as non-auto.
+ *
+ * Month/day segments must be 2 digits (ISO style) to discriminate them from
+ * single-digit collision counters: `generateUserFileSlug` emits `-2.md`,
+ * `-3.md`, etc. without leading zeros, so `alex-2025-2.md` is a counter on
+ * base `alex-2025.md` — not a date — and must remain classified as auto.
+ *
+ * Filename-only classification is still ambiguous at the margins: a display
+ * name like "Alex 2025 4" legitimately produces `alex-2025-4.md` as a base
+ * slug, which looks identical to a year-prefixed counter. When the caller can
+ * supply the row's display name, we disambiguate by recomputing the expected
+ * base slug: if it matches the filename, the name is a base slug and we
+ * classify as non-auto. This closes the only remaining false-positive hole.
+ */
+const DATE_LIKE_SUFFIX = /-(19|20|21)\d{2}((-\d{2}){1,2})?\.md$/;
+const INTEGER_SUFFIX = /-\d+\.md$/;
+
+export function isAutoIncrementedUserFile(
+  userFile: string,
+  displayName?: string,
+): boolean {
+  if (DATE_LIKE_SUFFIX.test(userFile)) return false;
+  if (!INTEGER_SUFFIX.test(userFile)) return false;
+  if (displayName !== undefined) {
+    const expectedBase = `${computeUserFileBaseSlug(displayName)}.md`;
+    if (expectedBase === userFile) return false;
+  }
+  return true;
+}
+
+/**
+ * Normalize `contacts.user_file` across contact rows that share the same
+ * `principal_id`.
+ *
+ * Multiple contact rows may represent the same principal (one per channel:
+ * desktop, phone, Slack, etc.). When a new row was created for a second
+ * channel, `generateUserFileSlug(displayName)` auto-incremented to avoid a
+ * filename collision (e.g. `alice.md` → `alice-2.md`), even though no
+ * `alice-2.md` file ever existed on disk. The persona resolver then silently
+ * fell back to `users/default.md` for that channel's messages — and the same
+ * slug is used for the journal directory, so the user lost per-principal
+ * continuity on every non-primary channel.
+ *
+ * This migration picks one canonical `user_file` per principal and updates
+ * every sibling row to match. Selection heuristic:
+ *
+ *   1. Prefer values that do NOT look auto-incremented (see
+ *      `isAutoIncrementedUserFile`).
+ *   2. Among those, prefer the oldest contact row (earliest `created_at`).
+ *   3. Ties broken by `id` for determinism.
+ *
+ * Skips principals where only one distinct (non-null) value exists — nothing
+ * to normalize. Principals whose contacts all have `user_file = NULL` are
+ * left untouched; the code path in `upsertContact` will populate them on the
+ * next write.
+ */
+export function migrateNormalizeUserFileByPrincipal(
+  database: DrizzleDb,
+): void {
+  withCrashRecovery(
+    database,
+    "migration_normalize_user_file_by_principal_v1",
+    () => {
+      const raw = getSqliteFrom(database);
+
+      const tableExists = raw
+        .query(
+          `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'contacts'`,
+        )
+        .get();
+      if (!tableExists) return;
+
+      const userFileColExists = raw
+        .query(
+          `SELECT 1 FROM pragma_table_info('contacts') WHERE name = 'user_file'`,
+        )
+        .get();
+      const principalColExists = raw
+        .query(
+          `SELECT 1 FROM pragma_table_info('contacts') WHERE name = 'principal_id'`,
+        )
+        .get();
+      if (!userFileColExists || !principalColExists) return;
+
+      try {
+        raw.exec("BEGIN");
+
+        const principals = raw
+          .query(
+            /*sql*/ `
+            SELECT principal_id
+            FROM contacts
+            WHERE principal_id IS NOT NULL
+            GROUP BY principal_id
+            HAVING COUNT(DISTINCT COALESCE(user_file, '')) > 1
+          `,
+          )
+          .all() as Array<{ principal_id: string }>;
+
+        // Fetch all non-null candidates and rank in JS. The auto-increment
+        // classification is a regex that SQLite's GLOB can't express cleanly
+        // (unbounded digit count, date-pattern exclusion), and keeping the
+        // logic in one place avoids SQL/JS drift.
+        const selectCandidates = raw.prepare(
+          /*sql*/ `
+          SELECT user_file, display_name, created_at, id FROM contacts
+          WHERE principal_id = ? AND user_file IS NOT NULL
+          `,
+        );
+
+        const updateSiblings = raw.prepare(
+          /*sql*/ `
+          UPDATE contacts
+          SET user_file = ?, updated_at = ?
+          WHERE principal_id = ?
+            AND (user_file IS NULL OR user_file != ?)
+          `,
+        );
+
+        for (const { principal_id } of principals) {
+          const candidates = selectCandidates.all(principal_id) as Array<{
+            user_file: string;
+            display_name: string;
+            created_at: number;
+            id: string;
+          }>;
+          if (candidates.length === 0) continue;
+
+          candidates.sort((a, b) => {
+            const aAuto = isAutoIncrementedUserFile(a.user_file, a.display_name)
+              ? 1
+              : 0;
+            const bAuto = isAutoIncrementedUserFile(b.user_file, b.display_name)
+              ? 1
+              : 0;
+            if (aAuto !== bAuto) return aAuto - bAuto;
+            if (a.created_at !== b.created_at)
+              return a.created_at - b.created_at;
+            return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+          });
+
+          const canonical = candidates[0]!.user_file;
+          updateSiblings.run(
+            canonical,
+            Date.now(),
+            principal_id,
+            canonical,
+          );
+        }
+
+        raw.exec("COMMIT");
+      } catch (e) {
+        try {
+          raw.exec("ROLLBACK");
+        } catch {
+          /* no active transaction */
+        }
+        throw e;
+      }
+    },
+  );
+}

package/src/memory/migrations/221-conversations-archived-at.ts

@@ -0,0 +1,16 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+export function migrateConversationsArchivedAt(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+  try {
+    raw.exec(
+      `ALTER TABLE conversations ADD COLUMN archived_at INTEGER DEFAULT NULL`,
+    );
+  } catch {
+    // Column already exists — nothing to do.
+  }
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_conversations_archived_at ON conversations (archived_at)`,
+  );
+}

package/src/memory/migrations/222-strip-placeholder-sentinels-from-messages.ts

@@ -0,0 +1,82 @@
+import { isPlaceholderSentinelText } from "../../providers/anthropic/client.js";
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+/**
+ * Strip Anthropic provider placeholder sentinel text blocks from persisted
+ * assistant messages.
+ *
+ * PLACEHOLDER_EMPTY_TURN and PLACEHOLDER_BLOCKS_OMITTED are injected into
+ * outbound Anthropic request bodies to preserve role alternation when an
+ * assistant turn would otherwise be empty. They are never supposed to be
+ * persisted, but a leak path caused them to be stored in the messages table
+ * where they render in chat bubbles as bold "PLACEHOLDER[...]" (markdown
+ * interprets the double-underscore surround as bold).
+ *
+ * This migration walks every assistant message, parses its content blocks,
+ * and drops text blocks whose text matches either sentinel (with or without
+ * the null-byte prefix, to cover rows that round-tripped through tools that
+ * stripped null bytes). If stripping leaves the message empty, stores [].
+ *
+ * Idempotent — safe to re-run.
+ */
+export function migrateStripPlaceholderSentinelsFromMessages(
+  database: DrizzleDb,
+): void {
+  withCrashRecovery(
+    database,
+    "migration_strip_placeholder_sentinels_from_messages_v1",
+    () => {
+      const raw = getSqliteFrom(database);
+
+      const BATCH_SIZE = 100;
+      let lastRowid = 0;
+
+      for (;;) {
+        const rows = raw
+          .query(
+            `SELECT rowid, id, content FROM messages
+             WHERE role = 'assistant'
+               AND content LIKE '%__PLACEHOLDER__%'
+               AND rowid > ?
+             ORDER BY rowid
+             LIMIT ?`,
+          )
+          .all(lastRowid, BATCH_SIZE) as Array<{
+          rowid: number;
+          id: string;
+          content: string;
+        }>;
+
+        if (rows.length === 0) break;
+
+        for (const row of rows) {
+          lastRowid = row.rowid;
+
+          let blocks: Array<Record<string, unknown>>;
+          try {
+            const parsed = JSON.parse(row.content);
+            if (!Array.isArray(parsed)) continue;
+            blocks = parsed;
+          } catch {
+            continue;
+          }
+
+          const stripped = blocks.filter((b) => {
+            if (typeof b !== "object" || b === null) return false;
+            if (b.type !== "text") return true;
+            const text = typeof b.text === "string" ? b.text : "";
+            return !isPlaceholderSentinelText(text);
+          });
+
+          if (stripped.length === blocks.length) continue;
+
+          raw
+            .query(`UPDATE messages SET content = ? WHERE id = ?`)
+            .run(JSON.stringify(stripped), row.id);
+        }
+      }
+    },
+  );
+}

package/src/memory/migrations/index.ts

@@ -160,6 +160,13 @@ export { migrateOAuthProvidersRevoke } from "./215-oauth-providers-revoke.js";
 export { migrateOAuthProvidersTokenAuthMethodDefault } from "./216-oauth-providers-token-auth-method.js";
 export { migrateConversationHostAccess } from "./217-conversation-host-access.js";
 export { migrateOAuthProvidersLogoUrl } from "./218-oauth-providers-logo-url.js";
+export { migrateOAuthProvidersTokenExchangeBodyFormat } from "./219-oauth-providers-token-exchange-body-format.js";
+export {
+  downNormalizeUserFileByPrincipal,
+  migrateNormalizeUserFileByPrincipal,
+} from "./220-normalize-user-file-by-principal.js";
+export { migrateConversationsArchivedAt } from "./221-conversations-archived-at.js";
+export { migrateStripPlaceholderSentinelsFromMessages } from "./222-strip-placeholder-sentinels-from-messages.js";
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/memory/migrations/registry.ts

@@ -42,6 +42,7 @@ import { migrateStripIntegrationPrefixFromProviderKeysDown } from "./196-strip-i
 import { migrateRenameMemoryGraphTypeValuesDown } from "./204-rename-memory-graph-type-values.js";
 import { migrateScrubCorruptedImageAttachmentsDown } from "./206-scrub-corrupted-image-attachments.js";
 import { downConversationHostAccess } from "./217-conversation-host-access.js";
+import { downNormalizeUserFileByPrincipal } from "./220-normalize-user-file-by-principal.js";
 
 export interface MigrationRegistryEntry {
   /** The checkpoint key written to memory_checkpoints on completion. */
@@ -365,6 +366,13 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
       "Add a host_access column to conversations so computer access is persisted per conversation with a safe default of disabled",
     down: downConversationHostAccess,
   },
+  {
+    key: "migration_normalize_user_file_by_principal_v1",
+    version: 42,
+    description:
+      "Normalize contacts.user_file across rows sharing the same principal_id so every channel for one principal loads the same users/<slug>.md persona and journal directory",
+    down: downNormalizeUserFileByPrincipal,
+  },
 ];
 
 export function getMaxMigrationVersion(): number {