@vellumai/assistant 0.8.4 → 0.8.6

package/src/memory/llm-request-log-store.ts

@@ -1,6 +1,22 @@
-import { and, desc, eq, gte, inArray, isNull, lte, sql } from "drizzle-orm";
+import {
+  and,
+  asc,
+  desc,
+  eq,
+  gt,
+  gte,
+  inArray,
+  isNull,
+  lt,
+  lte,
+  ne,
+  or,
+  sql,
+} from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
+import { CALL_SITE_SYNTHETIC_AGENT_ERROR_MESSAGE } from "../api/constants/call-sites.js";
+import type { LLMCallSite } from "../config/schemas/llm.js";
 import { AssistantError, ProviderError } from "../util/errors.js";
 import {
   getAssistantMessageIdsInTurn,
@@ -26,6 +42,12 @@ export type LogRow = {
    * `AgentLoopExitReason` in `agent/loop.ts`.
    */
   agentLoopExitReason: string | null;
+  /**
+   * Logical call site that produced this row — `mainAgent`,
+   * `compactionAgent`, etc. NULL on pre-migration-264 rows (no backfill).
+   * In practice values come from `LLMCallSite` (`config/schemas/llm.ts`).
+   */
+  callSite: string | null;
 };
 
 /**
@@ -73,6 +95,7 @@ export function recordRequestLog(
   responsePayload: string,
   messageId?: string,
   provider?: string,
+  callSite?: LLMCallSite,
 ): string {
   const db = getDb();
   const id = uuid();
@@ -88,6 +111,84 @@ export function recordRequestLog(
       // Stamped later via setAgentLoopExitReasonOnLatestLog, once the
       // agent loop body actually exits. Intermediate rows stay NULL.
       agentLoopExitReason: null,
+      // Logical call site (`mainAgent`, `compactionAgent`, …). NULL when
+      // a caller hasn't been updated yet — preserves backward compat
+      // while we plumb call sites through one site at a time.
+      callSite: callSite ?? null,
+    })
+    .run();
+  return id;
+}
+
+/**
+ * Insert a synthetic `llm_request_logs` row for an agent-loop error
+ * message that has no LLM call backing it but should appear in the
+ * inspector rail. Today the only caller is the
+ * `budget_yield_unrecovered` persistence path
+ * (`conversation-agent-loop.ts`); the helper is named generically so
+ * the next out-of-funds / provider-error / etc. path can route through
+ * the same primitive.
+ *
+ * The caller persists the user-visible assistant message separately
+ * via the `persistence` pipeline; this helper only writes the synthetic
+ * call row. `messageId` should be the id of the just-persisted notice
+ * so `getRequestLogsByMessageId` surfaces both together.
+ *
+ * Payload semantics mirror real LLM-call rows:
+ *  - `requestPayload`: the best-known LLM request body the loop was
+ *    about to send when it yielded — typically the prepared messages
+ *    snapshot and any input-token budget context. Stored as JSON so
+ *    the Raw tab renders it consistently with real calls.
+ *  - `responsePayload`: the synthetic notice text the user saw plus
+ *    the exit reason. This is the "response" from the user's point of
+ *    view — what came back from a call that never actually happened.
+ *
+ * Stamps `agent_loop_exit_reason` directly so the row already carries
+ * the reason at insert time — the post-loop
+ * `setAgentLoopExitReasonOnLatestLog` query then skips it (its IS NULL
+ * guard) and stamps the prior real LLM call instead, preserving the
+ * existing "latest LLM call carries the exit reason" invariant that
+ * other consumers depend on.
+ */
+export function recordSyntheticAgentErrorMessageLog(args: {
+  conversationId: string;
+  messageId: string;
+  exitReason: string;
+  /** User-visible notice text — goes into `response_payload`. */
+  noticeText: string;
+  /**
+   * Best-known LLM request state at the moment the loop gave up.
+   * `null` when no prepared request was available (rare — generally
+   * we know at least the conversation history we were about to send).
+   */
+  preparedRequest: unknown | null;
+  createdAt: number;
+}): string {
+  const db = getDb();
+  const id = uuid();
+  const requestPayload = JSON.stringify({
+    syntheticAgentErrorMessage: {
+      exitReason: args.exitReason,
+      preparedRequest: args.preparedRequest,
+    },
+  });
+  const responsePayload = JSON.stringify({
+    syntheticAgentErrorMessage: {
+      exitReason: args.exitReason,
+      noticeText: args.noticeText,
+    },
+  });
+  db.insert(llmRequestLogs)
+    .values({
+      id,
+      conversationId: args.conversationId,
+      messageId: args.messageId,
+      provider: null,
+      requestPayload,
+      responsePayload,
+      createdAt: args.createdAt,
+      agentLoopExitReason: args.exitReason,
+      callSite: CALL_SITE_SYNTHETIC_AGENT_ERROR_MESSAGE,
     })
     .run();
   return id;
@@ -182,6 +283,7 @@ function selectLogsByMessageIds(messageIds: string[]): LogRow[] {
       responsePayload: llmRequestLogs.responsePayload,
       createdAt: llmRequestLogs.createdAt,
       agentLoopExitReason: llmRequestLogs.agentLoopExitReason,
+      callSite: llmRequestLogs.callSite,
     })
     .from(llmRequestLogs)
     .where(inArray(llmRequestLogs.messageId, messageIds))
@@ -189,6 +291,34 @@ function selectLogsByMessageIds(messageIds: string[]): LogRow[] {
     .all();
 }
 
+/**
+ * Query every LLM request log recorded for a conversation, ordered by
+ * creation time. Conversation-scoped inspector views intentionally do
+ * not apply turn recovery: the `conversation_id` column already includes
+ * linked, unlinked, and orphaned rows for the full conversation.
+ */
+export function getRequestLogsByConversationId(
+  conversationId: string,
+): LogRow[] {
+  const db = getDb();
+  return db
+    .select({
+      id: llmRequestLogs.id,
+      conversationId: llmRequestLogs.conversationId,
+      messageId: llmRequestLogs.messageId,
+      provider: llmRequestLogs.provider,
+      requestPayload: llmRequestLogs.requestPayload,
+      responsePayload: llmRequestLogs.responsePayload,
+      createdAt: llmRequestLogs.createdAt,
+      agentLoopExitReason: llmRequestLogs.agentLoopExitReason,
+      callSite: llmRequestLogs.callSite,
+    })
+    .from(llmRequestLogs)
+    .where(eq(llmRequestLogs.conversationId, conversationId))
+    .orderBy(asc(llmRequestLogs.createdAt), asc(llmRequestLogs.id))
+    .all();
+}
+
 /**
  * Find orphaned logs — logs whose `message_id` references a message that no
  * longer exists in the DB. These are left behind when intermediate assistant
@@ -214,6 +344,7 @@ function selectOrphanedLogsInRange(
       responsePayload: llmRequestLogs.responsePayload,
       createdAt: llmRequestLogs.createdAt,
       agentLoopExitReason: llmRequestLogs.agentLoopExitReason,
+      callSite: llmRequestLogs.callSite,
     })
     .from(llmRequestLogs)
     .leftJoin(messages, eq(llmRequestLogs.messageId, messages.id))
@@ -255,6 +386,7 @@ function selectUnlinkedLogsInRange(
       responsePayload: llmRequestLogs.responsePayload,
       createdAt: llmRequestLogs.createdAt,
       agentLoopExitReason: llmRequestLogs.agentLoopExitReason,
+      callSite: llmRequestLogs.callSite,
     })
     .from(llmRequestLogs)
     .where(
@@ -269,6 +401,100 @@ function selectUnlinkedLogsInRange(
     .all();
 }
 
+/**
+ * Fetch every `compactionAgent` log row in the conversation whose
+ * `createdAt` falls in the **open window** `(afterCreatedAt, beforeCreatedAt)`,
+ * ordered chronologically.
+ *
+ * Drives the Inspector's Compaction tab. The caller resolves both
+ * bounds:
+ *   - `beforeCreatedAt` = the selected LLM call's `createdAt` (ceiling).
+ *   - `afterCreatedAt` = the previous non-`compactionAgent` call's
+ *     `createdAt` (floor), or `null` when the selected call is the first
+ *     real call in the conversation.
+ *
+ * Both bounds are **strict**: the selected call itself never appears in
+ * its own trail (`<` ceiling), and compactions that fed an earlier real
+ * call's context don't bleed into this call's window (`>` floor). When
+ * `afterCreatedAt` is `null` the floor is dropped entirely — every
+ * preceding compaction is in scope, which is the right behavior for the
+ * very first real call in the conversation.
+ *
+ * NULL `callSite` rows (pre-migration-264) are excluded by the explicit
+ * `callSite = 'compactionAgent'` predicate without a separate IS NOT
+ * NULL clause.
+ */
+export function getCompactionLogsBetween(
+  conversationId: string,
+  afterCreatedAt: number | null,
+  beforeCreatedAt: number,
+): LogRow[] {
+  const db = getDb();
+  const predicates = [
+    eq(llmRequestLogs.conversationId, conversationId),
+    eq(llmRequestLogs.callSite, "compactionAgent"),
+    lt(llmRequestLogs.createdAt, beforeCreatedAt),
+  ];
+  if (afterCreatedAt !== null) {
+    predicates.push(gt(llmRequestLogs.createdAt, afterCreatedAt));
+  }
+  return db
+    .select({
+      id: llmRequestLogs.id,
+      conversationId: llmRequestLogs.conversationId,
+      messageId: llmRequestLogs.messageId,
+      provider: llmRequestLogs.provider,
+      requestPayload: llmRequestLogs.requestPayload,
+      responsePayload: llmRequestLogs.responsePayload,
+      createdAt: llmRequestLogs.createdAt,
+      agentLoopExitReason: llmRequestLogs.agentLoopExitReason,
+      callSite: llmRequestLogs.callSite,
+    })
+    .from(llmRequestLogs)
+    .where(and(...predicates))
+    .orderBy(asc(llmRequestLogs.createdAt), asc(llmRequestLogs.id))
+    .all();
+}
+
+/**
+ * Find the `createdAt` of the most recent non-`compactionAgent` LLM
+ * call in the conversation strictly before `beforeCreatedAt`, or `null`
+ * when no such call exists (i.e. the cutoff is the first real call).
+ *
+ * Pairs with `getCompactionLogsBetween` to bound the compaction trail
+ * to the window between the prior real call and the selected call.
+ *
+ * "Non-compactionAgent" means `callSite IS NULL OR callSite !=
+ * 'compactionAgent'`. NULL rows are pre-migration-264 (no backfill) and
+ * are treated as real agent calls — they were `mainAgent` in practice.
+ * The OR-with-IS NULL is required because SQL's three-valued logic
+ * makes `callSite != 'compactionAgent'` return UNKNOWN (not TRUE) for
+ * NULL rows, which would otherwise filter them out.
+ */
+export function getPreviousNonCompactionCallCreatedAt(
+  conversationId: string,
+  beforeCreatedAt: number,
+): number | null {
+  const db = getDb();
+  const row = db
+    .select({ createdAt: llmRequestLogs.createdAt })
+    .from(llmRequestLogs)
+    .where(
+      and(
+        eq(llmRequestLogs.conversationId, conversationId),
+        lt(llmRequestLogs.createdAt, beforeCreatedAt),
+        or(
+          isNull(llmRequestLogs.callSite),
+          ne(llmRequestLogs.callSite, "compactionAgent"),
+        ),
+      ),
+    )
+    .orderBy(desc(llmRequestLogs.createdAt), desc(llmRequestLogs.id))
+    .limit(1)
+    .get();
+  return row?.createdAt ?? null;
+}
+
 export function getRequestLogById(logId: string): LogRow | null {
   const db = getDb();
   return (
@@ -282,6 +508,7 @@ export function getRequestLogById(logId: string): LogRow | null {
         responsePayload: llmRequestLogs.responsePayload,
         createdAt: llmRequestLogs.createdAt,
         agentLoopExitReason: llmRequestLogs.agentLoopExitReason,
+        callSite: llmRequestLogs.callSite,
       })
       .from(llmRequestLogs)
       .where(eq(llmRequestLogs.id, logId))

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

@@ -57,6 +57,7 @@ export function recordUsageEvent(
       outputTokens: event.outputTokens,
       cacheCreationInputTokens: event.cacheCreationInputTokens,
       cacheReadInputTokens: event.cacheReadInputTokens,
+      rawUsage: event.rawUsage === null ? null : JSON.stringify(event.rawUsage),
       estimatedCostUsd: event.estimatedCostUsd,
       pricingStatus: event.pricingStatus,
       llmCallCount: event.llmCallCount ?? 1,
@@ -87,6 +88,7 @@ function rowToUsageEvent(row: {
   outputTokens: number;
   cacheCreationInputTokens: number | null;
   cacheReadInputTokens: number | null;
+  rawUsage: string | null;
   estimatedCostUsd: number | null;
   pricingStatus: string;
 }): UsageEvent {
@@ -107,11 +109,32 @@ function rowToUsageEvent(row: {
     outputTokens: row.outputTokens,
     cacheCreationInputTokens: row.cacheCreationInputTokens,
     cacheReadInputTokens: row.cacheReadInputTokens,
+    rawUsage: parseRawUsage(row.rawUsage),
     estimatedCostUsd: row.estimatedCostUsd,
     pricingStatus: row.pricingStatus as "priced" | "unpriced",
   };
 }
 
+/**
+ * Parse the JSON-serialized provider usage payload stored in `raw_usage`.
+ * Returns `null` for missing or malformed values; malformed JSON is logged
+ * and discarded rather than failing the read, because callers (admin
+ * dashboards, telemetry forwarders) treat `raw_usage` as opaque diagnostic
+ * data and shouldn't be blocked by a single corrupt row.
+ */
+function parseRawUsage(value: string | null): Record<string, unknown> | null {
+  if (value === null) return null;
+  try {
+    const parsed = JSON.parse(value);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 export function listUsageEvents(options?: { limit?: number }): UsageEvent[] {
   const db = getDb();
   const rows = db
@@ -187,6 +210,7 @@ export function queryUnreportedUsageEvents(
       outputTokens: llmUsageEvents.outputTokens,
       cacheCreationInputTokens: llmUsageEvents.cacheCreationInputTokens,
       cacheReadInputTokens: llmUsageEvents.cacheReadInputTokens,
+      rawUsage: llmUsageEvents.rawUsage,
       estimatedCostUsd: llmUsageEvents.estimatedCostUsd,
       pricingStatus: llmUsageEvents.pricingStatus,
       conversationType: conversations.conversationType,

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

@@ -19,7 +19,10 @@ import {
 } from "../runtime/actor-trust-resolver.js";
 import { getLogger } from "../util/logger.js";
 import { getConversationSource } from "./conversation-crud.js";
-import { upsertMemoryRetrospectiveJob } from "./jobs-store.js";
+import {
+  isMemoryEnabled,
+  upsertMemoryRetrospectiveJob,
+} from "./jobs-store.js";
 import { MEMORY_RETROSPECTIVE_SOURCES } from "./memory-retrospective-constants.js";
 
 const log = getLogger("memory-retrospective-enqueue");
@@ -38,6 +41,10 @@ export function enqueueMemoryRetrospectiveIfEnabled(args: {
 }): void {
   const { conversationId, trigger } = args;
 
+  if (!isMemoryEnabled()) {
+    return;
+  }
+
   if (isMemoryRetrospectiveConversation(conversationId)) {
     log.debug(
       { conversationId, trigger },

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

@@ -208,6 +208,11 @@ async function runLegacyRetrospective(
       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;

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

@@ -1,8 +1,9 @@
-import { and, desc, eq, inArray, isNull } from "drizzle-orm";
+import { and, desc, eq, gte, inArray, isNull, lte, ne } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import { getDb } from "./db-connection.js";
 import { memoryV2ActivationLogs } from "./schema.js";
+import type { ShadowDiffLogRow } from "./v3/shadow-diff.js";
 
 export interface MemoryV2ConceptRowRecord {
   slug: string;
@@ -94,6 +95,14 @@ export interface MemoryV2ConceptRowRecord {
     | "not_injected"
     | "page_missing"
     | "corrupt";
+  /**
+   * v3 shadow only: the retrieval lane that surfaced this slug
+   * (`hot` | `sparse` | `dense` | `tree` | `edge`). Lets a shadow run be
+   * analyzed by provenance — which lane each v3 pick came from. Undefined on
+   * `router`/`per-turn`/etc. v2 rows; stored in the JSON concept blob, so older
+   * rows decode with `undefined`.
+   */
+  lane?: string;
 }
 
 export interface MemoryV2ConfigSnapshot {
@@ -115,11 +124,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;
 }
@@ -153,12 +166,16 @@ export function backfillMemoryV2ActivationMessageId(
   messageId: string,
 ): void {
   const db = getDb();
+  // `v3_shadow` rows are detached telemetry written outside the live turn with
+  // a null messageId; they are not tied to any specific message. Excluding them
+  // keeps their messageId null instead of stamping them with a later turn's id.
   db.update(memoryV2ActivationLogs)
     .set({ messageId })
     .where(
       and(
         eq(memoryV2ActivationLogs.conversationId, conversationId),
         isNull(memoryV2ActivationLogs.messageId),
+        ne(memoryV2ActivationLogs.mode, "v3_shadow"),
       ),
     )
     .run();
@@ -167,7 +184,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;
 }
@@ -188,8 +205,94 @@ 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,
   };
 }
+
+function parseConcepts(conceptsJson: string): MemoryV2ConceptRowRecord[] {
+  try {
+    const parsed = JSON.parse(conceptsJson);
+    return Array.isArray(parsed) ? (parsed as MemoryV2ConceptRowRecord[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read the activation-log rows the v3 shadow-diff needs: every `v3_shadow` row
+ * (optionally newer than `sinceMs`), plus the `router` rows that could pair
+ * with them. The router read is bounded to the shadow rows' conversations and
+ * their time span (padded by `paddingMs`) so a shadow-diff over a few turns
+ * never scans the entire multi-GB log table. Returns `{ shadow, router }` for
+ * {@link computeShadowDiff} to pair and diff.
+ */
+export function readActivationLogsForShadowDiff(opts: {
+  sinceMs: number | null;
+  paddingMs: number;
+}): { shadow: ShadowDiffLogRow[]; router: ShadowDiffLogRow[] } {
+  const db = getDb();
+
+  const shadow = db
+    .select({
+      conversationId: memoryV2ActivationLogs.conversationId,
+      createdAt: memoryV2ActivationLogs.createdAt,
+      conceptsJson: memoryV2ActivationLogs.conceptsJson,
+    })
+    .from(memoryV2ActivationLogs)
+    .where(
+      opts.sinceMs !== null
+        ? and(
+            eq(memoryV2ActivationLogs.mode, "v3_shadow"),
+            gte(memoryV2ActivationLogs.createdAt, opts.sinceMs),
+          )
+        : eq(memoryV2ActivationLogs.mode, "v3_shadow"),
+    )
+    .orderBy(memoryV2ActivationLogs.createdAt)
+    .all()
+    .map((row) => ({
+      conversationId: row.conversationId,
+      createdAt: row.createdAt,
+      concepts: parseConcepts(row.conceptsJson),
+    }));
+
+  if (shadow.length === 0) return { shadow: [], router: [] };
+
+  const convIds = [...new Set(shadow.map((s) => s.conversationId))];
+  let tMin = Number.POSITIVE_INFINITY;
+  let tMax = Number.NEGATIVE_INFINITY;
+  for (const s of shadow) {
+    if (s.createdAt < tMin) tMin = s.createdAt;
+    if (s.createdAt > tMax) tMax = s.createdAt;
+  }
+
+  const router = db
+    .select({
+      conversationId: memoryV2ActivationLogs.conversationId,
+      createdAt: memoryV2ActivationLogs.createdAt,
+      conceptsJson: memoryV2ActivationLogs.conceptsJson,
+    })
+    .from(memoryV2ActivationLogs)
+    .where(
+      and(
+        eq(memoryV2ActivationLogs.mode, "router"),
+        inArray(memoryV2ActivationLogs.conversationId, convIds),
+        gte(memoryV2ActivationLogs.createdAt, tMin - opts.paddingMs),
+        lte(memoryV2ActivationLogs.createdAt, tMax + opts.paddingMs),
+      ),
+    )
+    .all()
+    .map((row) => ({
+      conversationId: row.conversationId,
+      createdAt: row.createdAt,
+      concepts: parseConcepts(row.conceptsJson),
+    }));
+
+  return { shadow, router };
+}

package/src/memory/migrations/260-rename-cleaned-at.ts

@@ -0,0 +1,44 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_rename_cleaned_at_v1";
+
+const OLD_COLUMN = "cleaned_at";
+const NEW_COLUMN = "history_stripped_at";
+
+/**
+ * Rename `conversations.cleaned_at` → `conversations.history_stripped_at`.
+ *
+ * The marker now records any injection-strip event (`/clean` or compaction),
+ * not just `/clean`. Renaming reflects the broader semantics; compaction
+ * sets it alongside its summary state instead of destructively wiping
+ * message metadata.
+ */
+export function migrateRenameCleanedAt(database: DrizzleDb): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    if (tableHasColumn(database, "conversations", NEW_COLUMN)) {
+      return;
+    }
+    if (!tableHasColumn(database, "conversations", OLD_COLUMN)) {
+      // 259 didn't run (fresh install on a newer schema where 259's column
+      // was added under the new name) — nothing to rename.
+      return;
+    }
+    database.run(
+      `ALTER TABLE conversations RENAME COLUMN ${OLD_COLUMN} TO ${NEW_COLUMN}`,
+    );
+  });
+}
+
+export function downRenameCleanedAt(database: DrizzleDb): void {
+  if (!tableHasColumn(database, "conversations", NEW_COLUMN)) {
+    return;
+  }
+  if (tableHasColumn(database, "conversations", OLD_COLUMN)) {
+    return;
+  }
+  database.run(
+    `ALTER TABLE conversations RENAME COLUMN ${NEW_COLUMN} TO ${OLD_COLUMN}`,
+  );
+}

package/src/memory/migrations/261-llm-usage-add-raw-usage.ts

@@ -0,0 +1,36 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { tableHasColumn } from "./schema-introspection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_llm_usage_add_raw_usage_v1";
+
+const TABLE = "llm_usage_events";
+const COLUMN = "raw_usage";
+
+/**
+ * Add a `raw_usage` TEXT column to `llm_usage_events` for storing the
+ * provider's untouched `usage` block as JSON.
+ *
+ * The Anthropic API surfaces a TTL breakdown of cache writes
+ * (`usage.cache_creation.ephemeral_5m_input_tokens`,
+ * `usage.cache_creation.ephemeral_1h_input_tokens`); OpenAI surfaces
+ * nested `prompt_tokens_details` and `completion_tokens_details`; both
+ * are kept as opaque JSON so admin charts and downstream consumers can
+ * extract provider-specific detail without requiring a new column every
+ * time a provider adds a usage field. `NULL` for rows persisted before
+ * this migration ran and for providers that did not return a usage
+ * payload.
+ */
+export function migrateLlmUsageAddRawUsage(database: DrizzleDb): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    if (!tableHasColumn(database, TABLE, COLUMN)) {
+      database.run(`ALTER TABLE ${TABLE} ADD COLUMN ${COLUMN} TEXT`);
+    }
+  });
+}
+
+export function downLlmUsageAddRawUsage(database: DrizzleDb): void {
+  if (tableHasColumn(database, TABLE, COLUMN)) {
+    database.run(`ALTER TABLE ${TABLE} DROP COLUMN ${COLUMN}`);
+  }
+}

package/src/memory/migrations/262-memory-v3-coactivation.ts

@@ -0,0 +1,57 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_memory_v3_coactivation_v1";
+
+/**
+ * Create the memory_v3_coactivation table — an append-only log of
+ * pass-1 → pass-N co-activation pairs observed during a v3 retrieval loop.
+ *
+ * Each row records that a page (`target_slug`) first surfaced on a later
+ * descent pass was co-selected alongside a page (`source_slug`) that surfaced
+ * on pass 1, with `pass_gap` = passOf(target) − passOf(source). This is the
+ * raw gradient signal that edge-learning later reconciles into curated-graph
+ * edge weights: a source that repeatedly precedes a target across turns is a
+ * candidate association. `used` is the usefulness flag (0 here — the loop
+ * cannot know whether the target was actually load-bearing for the turn; a
+ * later edge-learning pass reconciles it).
+ *
+ * The table just accumulates raw events; the edge-learning formula or the
+ * decay/weighting can change later without losing signal.
+ *
+ * Indexes:
+ * - `(source_slug, target_slug)` for per-pair aggregation (the hot path for
+ *   edge-learning reads).
+ * - `(created_at)` for time-range pruning later.
+ */
+export function migrateMemoryV3Coactivation(database: DrizzleDb): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    const raw = getSqliteFrom(database);
+    raw.exec(/*sql*/ `
+      CREATE TABLE IF NOT EXISTS memory_v3_coactivation (
+        id INTEGER PRIMARY KEY,
+        conversation_id TEXT NOT NULL,
+        turn INTEGER NOT NULL,
+        source_slug TEXT NOT NULL,
+        target_slug TEXT NOT NULL,
+        pass_gap INTEGER NOT NULL,
+        used INTEGER NOT NULL,
+        created_at INTEGER NOT NULL
+      )
+    `);
+    raw.exec(/*sql*/ `
+      CREATE INDEX IF NOT EXISTS idx_memory_v3_coactivation_pair
+        ON memory_v3_coactivation (source_slug, target_slug)
+    `);
+    raw.exec(/*sql*/ `
+      CREATE INDEX IF NOT EXISTS idx_memory_v3_coactivation_time
+        ON memory_v3_coactivation (created_at)
+    `);
+  });
+}
+
+export function downMemoryV3Coactivation(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+  raw.exec(/*sql*/ `DROP TABLE IF EXISTS memory_v3_coactivation`);
+}