@vellumai/assistant 0.8.4 → 0.8.6

package/src/memory/jobs-store.ts

@@ -1,6 +1,7 @@
 import { and, asc, eq, inArray, lte, notInArray, or, sql } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
+import { getConfig } from "../config/loader.js";
 import { getLogger } from "../util/logger.js";
 import { truncate } from "../util/truncate.js";
 import { getDb } from "./db-connection.js";
@@ -43,6 +44,9 @@ export type MemoryJobType =
   | "memory_v2_migrate"
   | "memory_v2_reembed"
   | "memory_v2_activation_recompute"
+  | "memory_v3_consolidate"
+  | "memory_v3_index_maintenance"
+  | "memory_v3_edge_learning"
   | "memory_retrospective";
 
 export const EMBED_JOB_TYPES: MemoryJobType[] = [
@@ -66,12 +70,22 @@ export const SLOW_LLM_JOB_TYPES: MemoryJobType[] = [
   "generate_conversation_starters",
   "memory_v2_sweep",
   "memory_v2_consolidate",
+  "memory_v3_consolidate",
   "memory_v2_migrate",
   "memory_retrospective",
   "backfill",
   "graph_bootstrap",
 ];
 
+/** Returns `false` only when `config.memory.enabled` is explicitly `false`; defaults to `true` on missing config or load errors. */
+export function isMemoryEnabled(): boolean {
+  try {
+    return getConfig().memory?.enabled !== false;
+  } catch {
+    return true;
+  }
+}
+
 export interface MemoryJob<T = Record<string, unknown>> {
   id: string;
   type: MemoryJobType;

package/src/memory/jobs-worker.ts

@@ -65,6 +65,7 @@ import {
   enqueuePruneOldTraceEventsJob,
   failMemoryJob,
   failStalledJobs,
+  hasActiveJobOfType,
   type MemoryJob,
   type MemoryJobType,
   resetRunningJobsToPending,
@@ -83,6 +84,9 @@ import {
   memoryV2ConsolidateJob,
 } from "./v2/consolidation-job.js";
 import { memoryV2SweepJob } from "./v2/sweep-job.js";
+import { memoryV3ConsolidateJob } from "./v3/consolidation-job.js";
+import { memoryV3EdgeLearningJob } from "./v3/edge-learning-job.js";
+import { memoryV3IndexMaintenanceJob } from "./v3/maintenance.js";
 
 const log = getLogger("memory-jobs-worker");
 
@@ -259,7 +263,7 @@ export async function runMemoryJobsOnce(
       maybeEnqueueScheduledCleanupJobs(config);
     }
     maybeEnqueueGraphMaintenanceJobs(config);
-    maybeRunDbMaintenance();
+    await maybeRunDbMaintenance();
     return 0;
   }
 
@@ -313,7 +317,7 @@ export async function runMemoryJobsOnce(
     maybeEnqueueScheduledCleanupJobs(config);
   }
   maybeEnqueueGraphMaintenanceJobs(config);
-  maybeRunDbMaintenance();
+  await maybeRunDbMaintenance();
   return slowProcessed + fastProcessed + embedProcessed;
 }
 
@@ -524,10 +528,10 @@ async function processJob(
       pruneOldConversationsJob(job, config);
       return;
     case "prune_old_llm_request_logs":
-      pruneOldLlmRequestLogsJob(job, config);
+      await pruneOldLlmRequestLogsJob(job, config);
       return;
     case "prune_old_trace_events":
-      pruneOldTraceEventsJob(job, config);
+      await pruneOldTraceEventsJob(job, config);
       return;
     case "build_conversation_summary":
       // Stale rows enqueued before v2 was enabled must not consume the
@@ -603,6 +607,16 @@ async function processJob(
     case "memory_v2_consolidate":
       await memoryV2ConsolidateJob(job, config);
       return;
+    case "memory_v3_consolidate":
+      await memoryV3ConsolidateJob(job, config);
+      return;
+    case "memory_v3_index_maintenance":
+      await memoryV3IndexMaintenanceJob(job);
+      return;
+    case "memory_v3_edge_learning":
+      // Fast lane: bounded DB work (decay + reinforce + read), no LLM.
+      memoryV3EdgeLearningJob(job);
+      return;
     case "memory_v2_migrate":
       await memoryV2MigrateJob(job, config);
       return;
@@ -681,17 +695,28 @@ export const GRAPH_MAINTENANCE_CHECKPOINTS = {
   patternScan: "graph_maintenance:pattern_scan:last_run",
   narrative: "graph_maintenance:narrative:last_run",
   memoryV2Consolidate: "memory_v2_consolidate_last_run",
+  memoryV3Consolidate: "memory_v3_consolidate_last_run",
 } as const;
 
 /**
  * Enqueue periodic graph maintenance jobs.
  *
  * Mutually exclusive between v1 and v2:
- *   - v2 active (`memory.v2.enabled` on) → only `memory_v2_consolidate` is
- *     scheduled.
+ *   - v2 active (`memory.v2.enabled` on) → only one buffer-drainer is
+ *     scheduled (see below).
  *   - v2 inactive → the four v1 entries (decay, consolidate, pattern_scan,
  *     narrative) are scheduled instead.
  *
+ * **Buffer-drainer retarget (v2 vs v3).** The `memory/buffer.md` is shared, so
+ * exactly one consolidator may own the drain at a time. When
+ * `memory.v3.write.enabled` is on, the v3 consolidator (`memory_v3_consolidate`)
+ * is scheduled INSTEAD of `memory_v2_consolidate` — same shared buffer +
+ * standing-context files, additionally authored into the v3 tree. When the v3
+ * write flag is off (default) the v2 consolidator stays the sole drainer,
+ * unchanged. The retarget is a clean conditional, fully reversible via the flag.
+ * Concept pages stay the shared canonical store, so the v2 router keeps working
+ * off pages v3 writes regardless of which consolidator ran.
+ *
  * Read/write paths route to v2 when the flag is on, so v1 graph data goes
  * unread; running v1 maintenance alongside v2 is wasted compute and LLM
  * spend. The v1 code path remains live so flipping the flag back to off
@@ -708,20 +733,29 @@ export function maybeEnqueueGraphMaintenanceJobs(
   nowMs = Date.now(),
 ): void {
   const v2Active = config.memory.v2.enabled;
+  const v3WriteActive = config.memory.v3.write.enabled;
+
+  // The single buffer-drainer entry for the v2-active branch: v3 when the v3
+  // write flag owns the drain, v2 otherwise. Same shared buffer either way.
+  const consolidateEntry = v3WriteActive
+    ? {
+        key: GRAPH_MAINTENANCE_CHECKPOINTS.memoryV3Consolidate,
+        intervalMs: config.memory.v3.write.consolidateIntervalMs,
+        jobType: "memory_v3_consolidate" as MemoryJobType,
+      }
+    : {
+        key: GRAPH_MAINTENANCE_CHECKPOINTS.memoryV2Consolidate,
+        intervalMs:
+          config.memory.v2.consolidation_interval_hours * 60 * 60 * 1000,
+        jobType: "memory_v2_consolidate" as MemoryJobType,
+      };
 
   const schedule: Array<{
     key: string;
     intervalMs: number;
     jobType: MemoryJobType;
   }> = v2Active
-    ? [
-        {
-          key: GRAPH_MAINTENANCE_CHECKPOINTS.memoryV2Consolidate,
-          intervalMs:
-            config.memory.v2.consolidation_interval_hours * 60 * 60 * 1000,
-          jobType: "memory_v2_consolidate",
-        },
-      ]
+    ? [consolidateEntry]
     : [
         {
           key: GRAPH_MAINTENANCE_CHECKPOINTS.decay,
@@ -745,25 +779,35 @@ export function maybeEnqueueGraphMaintenanceJobs(
         },
       ];
 
-  let enqueuedV2 = false;
+  let enqueuedConsolidate = false;
   for (const { key, intervalMs, jobType } of schedule) {
     const lastRun = parseInt(getMemoryCheckpoint(key) ?? "0", 10);
     if (nowMs - lastRun >= intervalMs) {
       enqueueMemoryJob(jobType, {});
       setMemoryCheckpoint(key, String(nowMs));
-      if (jobType === "memory_v2_consolidate") enqueuedV2 = true;
+      if (jobType === consolidateEntry.jobType) enqueuedConsolidate = true;
     }
   }
 
+  // Size-based trigger: when the shared buffer crosses the configured line
+  // count, drain it now rather than waiting out the interval. Retargets to the
+  // same consolidator the interval branch above selected.
+  //
+  // The size branch is checkpoint-blind by design (it must fire before the
+  // interval elapses), so it dedupes against an already-active consolidate job
+  // instead — otherwise it would re-enqueue on every worker tick while the
+  // buffer stays over threshold, flooding the queue with redundant LLM work.
   const maxLines = config.memory.v2.consolidation_max_buffer_lines;
-  if (v2Active && !enqueuedV2 && maxLines !== null) {
+  if (
+    v2Active &&
+    !enqueuedConsolidate &&
+    maxLines !== null &&
+    !hasActiveJobOfType(consolidateEntry.jobType)
+  ) {
     const bufferPath = join(getWorkspaceDir(), "memory", "buffer.md");
     if (countBufferLines(bufferPath) >= maxLines) {
-      enqueueMemoryJob("memory_v2_consolidate", {});
-      setMemoryCheckpoint(
-        GRAPH_MAINTENANCE_CHECKPOINTS.memoryV2Consolidate,
-        String(nowMs),
-      );
+      enqueueMemoryJob(consolidateEntry.jobType, {});
+      setMemoryCheckpoint(consolidateEntry.key, String(nowMs));
     }
   }
 }

package/src/memory/llm-request-log-source-clickhouse.ts

@@ -58,6 +58,16 @@ interface ClickHouseRow {
   response_payload: string;
   created_at: string;
   agent_loop_exit_reason: string;
+  /**
+   * Mirrors `llm_request_logs.call_site` from the SQLite source. Added
+   * to the CH `default.llm_request_logs` table via ALTER TABLE (matching
+   * the `agent_loop_exit_reason` precedent — see
+   * `memory/concepts/objects/clickhouse-mirror.md`).
+   *
+   * CH columns are `DEFAULT ''` rather than Nullable, so empty-string
+   * means "not set" — `toLogRow` maps that back to NULL on the JS side.
+   */
+  call_site: string;
 }
 
 /** Injectable fetch override for tests. Defaults to globalThis.fetch. */
@@ -125,7 +135,8 @@ export class ClickHouseLlmRequestLogSource implements LlmRequestLogSource {
         request_payload,
         response_payload,
         toUnixTimestamp64Milli(created_at) AS created_at,
-        agent_loop_exit_reason
+        agent_loop_exit_reason,
+        call_site
       FROM ${this.tableRef()}
       WHERE assistant_id = {assistant_id:String}
         AND id = {log_id:String}
@@ -171,6 +182,113 @@ export class ClickHouseLlmRequestLogSource implements LlmRequestLogSource {
     );
   }
 
+  async getRequestLogsByConversationId(
+    conversationId: string,
+  ): Promise<LogRow[]> {
+    const aid = await this.assistantId();
+    const sql = `SELECT
+        id,
+        conversation_id,
+        message_id,
+        provider,
+        request_payload,
+        response_payload,
+        toUnixTimestamp64Milli(created_at) AS created_at,
+        agent_loop_exit_reason,
+        call_site
+      FROM ${this.tableRef()}
+      WHERE assistant_id = {assistant_id:String}
+        AND conversation_id = {conversation_id:String}
+      ORDER BY created_at ASC, id ASC
+      LIMIT 1 BY id
+      FORMAT JSONEachRow`;
+    const rows = await this.exec(sql, {
+      assistant_id: aid,
+      conversation_id: conversationId,
+    });
+    return rows.map((r) => this.toLogRow(r));
+  }
+
+  async getCompactionLogsBetween(
+    conversationId: string,
+    afterCreatedAt: number | null,
+    beforeCreatedAt: number,
+  ): Promise<LogRow[]> {
+    const aid = await this.assistantId();
+    // `call_site` is bound as a literal via type-bound parameter (not
+    // string interpolation) for parity with the rest of this class —
+    // even though "compactionAgent" is a hard-coded identifier today,
+    // future call sites should plug into the same parameter slot
+    // without re-templating the query string.
+    //
+    // The `afterCreatedAt` lower bound is appended dynamically because
+    // type-bound parameter slots that are referenced in the SQL but
+    // unbound at exec time return a server error — so we only template
+    // the predicate in when the caller actually has a floor to enforce.
+    const params: Record<string, string> = {
+      assistant_id: aid,
+      conversation_id: conversationId,
+      call_site: "compactionAgent",
+      before_created_at: String(beforeCreatedAt),
+    };
+    let afterPredicate = "";
+    if (afterCreatedAt !== null) {
+      params.after_created_at = String(afterCreatedAt);
+      afterPredicate =
+        " AND created_at > fromUnixTimestamp64Milli({after_created_at:Int64})";
+    }
+    const sql = `SELECT
+        id,
+        conversation_id,
+        message_id,
+        provider,
+        request_payload,
+        response_payload,
+        toUnixTimestamp64Milli(created_at) AS created_at,
+        agent_loop_exit_reason,
+        call_site
+      FROM ${this.tableRef()}
+      WHERE assistant_id = {assistant_id:String}
+        AND conversation_id = {conversation_id:String}
+        AND call_site = {call_site:String}
+        AND created_at < fromUnixTimestamp64Milli({before_created_at:Int64})${afterPredicate}
+      ORDER BY created_at ASC, id ASC
+      LIMIT 1 BY id
+      FORMAT JSONEachRow`;
+    const rows = await this.exec(sql, params);
+    return rows.map((r) => this.toLogRow(r));
+  }
+
+  async getPreviousNonCompactionCallCreatedAt(
+    conversationId: string,
+    beforeCreatedAt: number,
+  ): Promise<number | null> {
+    const aid = await this.assistantId();
+    // "Non-compactionAgent" includes empty-string `call_site`, which is
+    // what the CH mirror writes for pre-migration-264 rows whose SQLite
+    // value was NULL (CH columns are `DEFAULT ''`, not Nullable — see
+    // `toLogRow`). The local store treats NULL `callSite` the same way,
+    // so the predicate stays in sync.
+    const sql = `SELECT
+        toUnixTimestamp64Milli(created_at) AS created_at
+      FROM ${this.tableRef()}
+      WHERE assistant_id = {assistant_id:String}
+        AND conversation_id = {conversation_id:String}
+        AND created_at < fromUnixTimestamp64Milli({before_created_at:Int64})
+        AND call_site != {call_site:String}
+      ORDER BY created_at DESC, id DESC
+      LIMIT 1
+      FORMAT JSONEachRow`;
+    const rows = await this.exec(sql, {
+      assistant_id: aid,
+      conversation_id: conversationId,
+      call_site: "compactionAgent",
+      before_created_at: String(beforeCreatedAt),
+    });
+    const value = rows[0]?.created_at;
+    return value === undefined ? null : Number(value);
+  }
+
   private async selectByMessageIds(ids: string[]): Promise<LogRow[]> {
     if (ids.length === 0) return [];
     const aid = await this.assistantId();
@@ -197,7 +315,8 @@ export class ClickHouseLlmRequestLogSource implements LlmRequestLogSource {
         request_payload,
         response_payload,
         toUnixTimestamp64Milli(created_at) AS created_at,
-        agent_loop_exit_reason
+        agent_loop_exit_reason,
+        call_site
       FROM ${this.tableRef()}
       WHERE assistant_id = {assistant_id:String}
         AND message_id IN (${placeholders.join(",")})
@@ -288,6 +407,7 @@ export class ClickHouseLlmRequestLogSource implements LlmRequestLogSource {
       createdAt: Number(row.created_at),
       agentLoopExitReason:
         row.agent_loop_exit_reason === "" ? null : row.agent_loop_exit_reason,
+      callSite: row.call_site === "" ? null : row.call_site,
     };
   }
 

package/src/memory/llm-request-log-source-local.ts

@@ -10,7 +10,10 @@
  */
 import type { LlmRequestLogSource } from "./llm-request-log-source.js";
 import {
+  getCompactionLogsBetween,
+  getPreviousNonCompactionCallCreatedAt,
   getRequestLogById,
+  getRequestLogsByConversationId,
   getRequestLogsByMessageId,
   type LogRow,
 } from "./llm-request-log-store.js";
@@ -23,4 +26,32 @@ export class LocalLlmRequestLogSource implements LlmRequestLogSource {
   async getRequestLogsByMessageId(messageId: string): Promise<LogRow[]> {
     return getRequestLogsByMessageId(messageId);
   }
+
+  async getRequestLogsByConversationId(
+    conversationId: string,
+  ): Promise<LogRow[]> {
+    return getRequestLogsByConversationId(conversationId);
+  }
+
+  async getCompactionLogsBetween(
+    conversationId: string,
+    afterCreatedAt: number | null,
+    beforeCreatedAt: number,
+  ): Promise<LogRow[]> {
+    return getCompactionLogsBetween(
+      conversationId,
+      afterCreatedAt,
+      beforeCreatedAt,
+    );
+  }
+
+  async getPreviousNonCompactionCallCreatedAt(
+    conversationId: string,
+    beforeCreatedAt: number,
+  ): Promise<number | null> {
+    return getPreviousNonCompactionCallCreatedAt(
+      conversationId,
+      beforeCreatedAt,
+    );
+  }
 }

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

@@ -1,8 +1,8 @@
 /**
  * Pluggable read source for LLM request logs.
  *
- * The Inspector view at `GET /v1/messages/:id/llm-context` (and the
- * single-log payload route) historically read directly from the local
+ * The Inspector views at `GET /v1/messages/:id/llm-context` and
+ * `GET /v1/conversations/llm-context` (plus the single-log payload route) historically read directly from the local
  * SQLite `llm_request_logs` table via `llm-request-log-store.ts`. The
  * source-of-truth remains local, but the *read path* is now configurable
  * via `llmRequestLogs.readSource` in workspace config.
@@ -31,6 +31,44 @@ export interface LlmRequestLogSource {
    * INSERT-only against the source-of-truth).
    */
   getRequestLogsByMessageId(messageId: string): Promise<LogRow[]>;
+
+  /**
+   * Fetch every LLM request log associated with the given conversation.
+   * This is the conversation-wide inspector read path: linked, unlinked,
+   * and orphaned logs are all included because they share conversation_id.
+   */
+  getRequestLogsByConversationId(conversationId: string): Promise<LogRow[]>;
+
+  /**
+   * Fetch every `callSite = "compactionAgent"` log row in the conversation
+   * whose `createdAt` falls in the **open window**
+   * `(afterCreatedAt, beforeCreatedAt)`, ordered chronologically.
+   *
+   * Drives the Inspector's Compaction tab. The route handler resolves
+   * both bounds: the selected LLM call's `createdAt` (ceiling) and the
+   * previous non-`compactionAgent` call's `createdAt` (floor) — passing
+   * `null` for the floor when the selected call is the first real call
+   * in the conversation. See `getCompactionLogsBetween` and
+   * `getPreviousNonCompactionCallCreatedAt` in `llm-request-log-store.ts`
+   * for the full bound semantics.
+   */
+  getCompactionLogsBetween(
+    conversationId: string,
+    afterCreatedAt: number | null,
+    beforeCreatedAt: number,
+  ): Promise<LogRow[]>;
+
+  /**
+   * Find the `createdAt` of the most recent non-`compactionAgent` LLM
+   * call in the conversation strictly before `beforeCreatedAt`, or
+   * `null` when no such call exists. Pairs with
+   * `getCompactionLogsBetween` to bound the compaction trail to the
+   * window between the prior real call and the selected call.
+   */
+  getPreviousNonCompactionCallCreatedAt(
+    conversationId: string,
+    beforeCreatedAt: number,
+  ): Promise<number | null>;
 }
 
 /**