@vellumai/assistant 0.10.0-dev.202606200539.c052d10 → 0.10.0-dev.202606201539.0cebd50

package/src/memory/__tests__/db-maintenance.test.ts

@@ -2,14 +2,12 @@
  * Tests for `db-maintenance.ts` (orchestration) and the underlying
  * `db-async-query.ts` abstraction.
  *
- * The contract this PR locks in:
- *   1. `runDbMaintenance` runs `VACUUM` through the async abstraction
- *      — when the `sqlite3` CLI is available, that means a subprocess
- *      and the daemon's main event loop keeps ticking. (The structural
- *      anti-block assertion lives in
- *      `db-async-query.test.ts`; here we focus on orchestration.)
- *   2. The subprocess actually shrinks the on-disk page count when
- *      there's reclaimable space.
+ * The contract this locks in:
+ *   1. `runDbMaintenance` runs `PRAGMA optimize` through the async
+ *      abstraction and then truncates the WAL on the daemon connection.
+ *      It intentionally does NOT run a full VACUUM (which in WAL mode
+ *      inflates the WAL to ~the DB size and needs ~2x the DB size free).
+ *   2. The truncating checkpoint shrinks the WAL file once it has grown.
  *   3. `maybeRunDbMaintenance` is genuinely async — callers can `await`
  *      it and observe completion.
  *   4. The 24 h interval guard short-circuits a recent re-run.
@@ -17,7 +15,7 @@
  * The per-file temp workspace is set up by `test-preload.ts`; tests just
  * dynamic-import the DB modules so they resolve paths under that temp dir.
  */
-import { Database } from "bun:sqlite";
+import { existsSync, statSync } from "node:fs";
 import { beforeEach, describe, expect, test } from "bun:test";
 
 const { getSqlite } = await import("../db-connection.js");
@@ -56,8 +54,9 @@ function insertMessage(role: "user" | "assistant", createdAt: number): void {
     .run(`msg-${createdAt}-${role}`, convId, role, "[]", createdAt);
 }
 
-/** Inflate the test DB with bloat that VACUUM can reclaim. */
-function inflateAndDelete(byteTarget: number): void {
+/** Pile writes into the WAL (without checkpointing) so a truncating
+ *  checkpoint has measurable work to do. */
+function inflateWal(byteTarget: number): void {
   const sqlite = getSqlite();
   sqlite.exec(
     "CREATE TABLE IF NOT EXISTS bloat (id INTEGER PRIMARY KEY, payload BLOB)",
@@ -72,11 +71,10 @@ function inflateAndDelete(byteTarget: number): void {
   for (let i = 0; i < rowsTarget; i++) {
     insert.run(payload);
   }
+  // Commit, but do not checkpoint — the frames stay in the WAL, leaving it at
+  // its high-water mark (a PASSIVE auto-checkpoint resets the WAL for reuse but
+  // never shrinks the file). Maintenance is what should truncate it.
   sqlite.exec("COMMIT");
-  sqlite.exec("DELETE FROM bloat");
-  sqlite.exec("DROP TABLE bloat");
-  // Force the WAL onto the main DB file so the bloat is visible on disk.
-  sqlite.exec("PRAGMA wal_checkpoint(TRUNCATE)");
 }
 
 describe("maybeRunDbMaintenance", () => {
@@ -106,36 +104,30 @@ describe("maybeRunDbMaintenance", () => {
     expect(getMemoryCheckpoint(MAINTENANCE_CHECKPOINT_KEY)).toBe(String(now));
   });
 
-  test("VACUUM reclaims pages on a bloated DB", async () => {
+  test("truncates a bloated WAL", async () => {
     const sqlite = getSqlite();
     sqlite.exec("DROP TABLE IF EXISTS bloat");
     sqlite.exec("PRAGMA wal_checkpoint(TRUNCATE)");
 
-    inflateAndDelete(8 * 1024 * 1024);
-
-    const dbPath = getDbPath();
-    // Read page_count from a fresh connection so we observe post-write
-    // ground truth without snapshot caching on the main test connection.
-    const readPageCount = (): number => {
-      const probe = new Database(dbPath, { readonly: true });
-      try {
-        return (
-          probe.query("PRAGMA page_count").get() as { page_count: number }
-        ).page_count;
-      } finally {
-        probe.close();
-      }
-    };
-    const pagesBefore = readPageCount();
+    const walPath = `${getDbPath()}-wal`;
+    const walSize = (): number =>
+      existsSync(walPath) ? statSync(walPath).size : 0;
+
+    inflateWal(4 * 1024 * 1024);
+    // Sanity: the writes really did grow the WAL on disk.
+    expect(walSize()).toBeGreaterThan(1024 * 1024);
 
     await maybeRunDbMaintenance();
 
-    const pagesAfter = readPageCount();
-    expect(pagesAfter).toBeLessThan(pagesBefore);
+    // Maintenance truncates the WAL back down (no VACUUM, so the data is folded
+    // into the main file rather than rebuilt).
+    expect(walSize()).toBeLessThan(64 * 1024);
+
+    sqlite.exec("DROP TABLE IF EXISTS bloat");
   }, 60_000);
 
   test("defers maintenance while the last user message is within the quiet period", async () => {
-    /** VACUUM must not fire while the user is active, so a recent user
+    /** Maintenance must not fire while the user is active, so a recent user
      *  message keeps maintenance deferred. */
     // GIVEN the user sent a message one minute ago (well within the quiet period)
     const now = Date.now();

package/src/memory/__tests__/db-memory-attach.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Tests for the secondary memory database file wiring (infra PR).
+ *
+ * What this locks in:
+ *   1. Opening the connection ATTACHes `assistant-memory.db` as the `memory`
+ *      schema and creates the file on disk.
+ *   2. The attached schema runs in WAL mode (its own `-wal`, independent of
+ *      the main DB) — the regression that lets a high-churn table (the
+ *      `memory_jobs` queue) bloat the *main* WAL is exactly what this split
+ *      exists to prevent.
+ *   3. A table created in the `memory` schema lives in the separate file, not
+ *      in `main` — proving the physical split rather than just an alias.
+ *   4. `runAsyncSqlite({ dbPath })` targets the given file via the sqlite3
+ *      CLI backend, leaving the main DB untouched.
+ */
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import { removeTestDbFiles } from "../../__tests__/assert-not-live-db.js";
+
+const { getSqlite, MEMORY_DB_SCHEMA } = await import("../db-connection.js");
+const { initializeDb } = await import("../db-init.js");
+const { runAsyncSqlite } = await import("../db-async-query.js");
+const { getMemoryDbPath } = await import("../../util/memory-db-path.js");
+const { findSqlite3 } = await import("../../util/sqlite3-runtime.js");
+
+initializeDb();
+
+const sqlite3Available = findSqlite3() !== undefined;
+
+describe("memory database attachment", () => {
+  test("ATTACHes the memory file as the memory schema and creates it on disk", () => {
+    // Touch the connection so the attach runs.
+    getSqlite();
+    expect(existsSync(getMemoryDbPath())).toBe(true);
+
+    const attached = getSqlite()
+      .query<{ name: string; file: string }, []>("PRAGMA database_list")
+      .all();
+    const memoryEntry = attached.find((e) => e.name === MEMORY_DB_SCHEMA);
+    expect(memoryEntry).toBeDefined();
+    expect(memoryEntry?.file).toBe(getMemoryDbPath());
+  });
+
+  test("the attached schema runs in WAL mode", () => {
+    const mode = getSqlite()
+      .query<
+        { journal_mode: string },
+        []
+      >(`PRAGMA ${MEMORY_DB_SCHEMA}.journal_mode`)
+      .get();
+    expect(mode?.journal_mode).toBe("wal");
+  });
+
+  test("a table created in the memory schema lives in the memory file, not main", () => {
+    const sqlite = getSqlite();
+    sqlite.exec(
+      `CREATE TABLE IF NOT EXISTS ${MEMORY_DB_SCHEMA}.attach_probe (id INTEGER PRIMARY KEY)`,
+    );
+    try {
+      const inMemory = sqlite
+        .query<
+          { name: string },
+          []
+        >(`SELECT name FROM ${MEMORY_DB_SCHEMA}.sqlite_master WHERE name = 'attach_probe'`)
+        .get();
+      expect(inMemory?.name).toBe("attach_probe");
+
+      const inMain = sqlite
+        .query<
+          { name: string },
+          []
+        >(`SELECT name FROM main.sqlite_master WHERE name = 'attach_probe'`)
+        .get();
+      expect(inMain).toBeNull();
+    } finally {
+      sqlite.exec(`DROP TABLE ${MEMORY_DB_SCHEMA}.attach_probe`);
+    }
+  });
+
+  test.if(sqlite3Available)(
+    "runAsyncSqlite({ dbPath }) targets the given file, not the main DB",
+    async () => {
+      const targetPath = join(
+        tmpdir(),
+        `vellum-async-memory-dbpath-${Date.now()}.db`,
+      );
+      try {
+        const result = await runAsyncSqlite(
+          "CREATE TABLE dbpath_probe (x INTEGER); INSERT INTO dbpath_probe VALUES (42); SELECT changes();",
+          { dbPath: targetPath, forceBackend: "sqlite3-cli" },
+        );
+        expect(result.ok).toBe(true);
+        expect(result.backend).toBe("sqlite3-cli");
+
+        // The target file got the table…
+        const { Database } = await import("bun:sqlite");
+        const probe = new Database(targetPath, { readonly: true });
+        try {
+          const row = probe
+            .query<
+              { name: string },
+              []
+            >("SELECT name FROM sqlite_master WHERE name = 'dbpath_probe'")
+            .get();
+          expect(row?.name).toBe("dbpath_probe");
+        } finally {
+          probe.close();
+        }
+
+        // …and the main DB did not.
+        const inMain = getSqlite()
+          .query<
+            { name: string },
+            []
+          >("SELECT name FROM main.sqlite_master WHERE name = 'dbpath_probe'")
+          .get();
+        expect(inMain).toBeNull();
+      } finally {
+        removeTestDbFiles(targetPath);
+      }
+    },
+  );
+});

package/src/memory/conversation-crud.ts

@@ -37,6 +37,7 @@ import { publishSyncInvalidation } from "../runtime/sync/sync-publisher.js";
 import { UserError } from "../util/errors.js";
 import { safeParseRecord } from "../util/json.js";
 import { getLogger } from "../util/logger.js";
+import { getLogsDbPath } from "../util/logs-db-path.js";
 import { getConversationsDir } from "../util/platform.js";
 import { createRowMapper } from "../util/row-mapper.js";
 import {
@@ -2140,8 +2141,11 @@ export async function clearAll(): Promise<{
   // Each DELETE goes through `runAsyncSqlite`. The original code threw
   // on rawExec failure; mirror that here by throwing when the async
   // result reports `ok: false`, so the route handler still returns 500.
-  const runOrThrow = async (sql: string): Promise<void> => {
-    const result = await runAsyncSqlite(sql);
+  const runOrThrow = async (
+    sql: string,
+    options?: { dbPath?: string },
+  ): Promise<void> => {
+    const result = await runAsyncSqlite(sql, options);
     if (!result.ok) {
       throw new Error(
         `clearAll: \`${sql}\` failed (${result.backend}): ${result.error ?? "unknown"}`,
@@ -2163,7 +2167,9 @@ export async function clearAll(): Promise<{
   await runOrThrow("DELETE FROM memory_embeddings");
   await runOrThrow("DELETE FROM memory_jobs");
   await runOrThrow("DELETE FROM memory_checkpoints");
-  await runOrThrow("DELETE FROM llm_request_logs");
+  // llm_request_logs lives in the attached logs database; point the sqlite3
+  // subprocess at that file (the in-process fallback resolves it via ATTACH).
+  await runOrThrow("DELETE FROM llm_request_logs", { dbPath: getLogsDbPath() });
   await runOrThrow("DELETE FROM llm_usage_events");
   await runOrThrow("DELETE FROM message_attachments");
   await runOrThrow("DELETE FROM attachments");

package/src/memory/db-connection.ts

@@ -6,6 +6,7 @@ import { Database } from "bun:sqlite";
 import { drizzle } from "drizzle-orm/bun-sqlite";
 
 import { getLogsDbPath } from "../util/logs-db-path.js";
+import { getMemoryDbPath } from "../util/memory-db-path.js";
 import { ensureDataDir, getDbPath } from "../util/platform.js";
 import { clearStoredDb, getStoredDb, setStoredDb } from "./db-singleton.js";
 import * as schema from "./schema.js";
@@ -58,6 +59,53 @@ function attachLogsDb(sqlite: Database): void {
   }
 }
 
+/**
+ * Schema name under which the secondary memory database file
+ * (`assistant-memory.db`) is ATTACHed to the main connection. High-churn memory
+ * tables (starting with `memory_jobs`) live in this separate file but remain
+ * queryable — and joinable against main-schema tables — over the single daemon
+ * connection. Because no such table exists in the `main` schema once a table is
+ * relocated, an unqualified reference (e.g. `memory_jobs`) resolves to the
+ * attached copy.
+ */
+export const MEMORY_DB_SCHEMA = "memory";
+
+/**
+ * ATTACH the secondary memory database to an open connection and apply its
+ * per-database PRAGMAs.
+ *
+ * `journal_mode` and `synchronous` are per-database settings, so they must be
+ * set against the attached schema explicitly — the PRAGMAs run on `main` before
+ * the attach do not carry over. `busy_timeout`, `foreign_keys`, `cache_size`,
+ * and `temp_store` are connection-wide and already configured on the connection.
+ *
+ * Best-effort: a failure here (e.g. a filesystem permission problem on the new
+ * file) must not take down the main database. We log and continue in line with
+ * the daemon's "never block startup on a subsystem failure" policy; relocated
+ * memory tables are simply unavailable until the next successful open.
+ *
+ * The logger is pulled in lazily (dynamic import) only on the error path. This
+ * file is intentionally kept import-light — see `db-singleton.ts` — so it does
+ * not take a static dependency on the logger (and transitively on pino).
+ */
+function attachMemoryDb(sqlite: Database): void {
+  const memoryPath = getMemoryDbPath();
+  try {
+    // Escape single quotes for the SQL string literal (paths can contain them).
+    const escaped = memoryPath.replace(/'/g, "''");
+    sqlite.exec(`ATTACH DATABASE '${escaped}' AS ${MEMORY_DB_SCHEMA}`);
+    sqlite.exec(`PRAGMA ${MEMORY_DB_SCHEMA}.journal_mode=WAL`);
+    sqlite.exec(`PRAGMA ${MEMORY_DB_SCHEMA}.synchronous=FULL`);
+  } catch (err) {
+    void import("../util/logger.js").then(({ getLogger }) =>
+      getLogger("db-connection").error(
+        { err, memoryPath },
+        "Failed to ATTACH memory database; relocated memory tables will be unavailable",
+      ),
+    );
+  }
+}
+
 function canonicalizePathThroughExistingParent(path: string): string {
   const resolvedPath = resolve(path);
   const pendingSegments: string[] = [];
@@ -130,6 +178,7 @@ export function getDb(): DrizzleDb {
   sqlite.exec("PRAGMA cache_size=-256000");
   sqlite.exec("PRAGMA temp_store=MEMORY");
   attachLogsDb(sqlite);
+  attachMemoryDb(sqlite);
   const db = drizzle(sqlite, { schema });
   setStoredDb(db, () => sqlite.close());
   return db;

package/src/memory/db-init.ts

@@ -10,12 +10,14 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
 import { getLogger } from "../util/logger.js";
+import { getLogsDbPath } from "../util/logs-db-path.js";
 import { ensureDataDir, getDbPath } from "../util/platform.js";
 import { backfillAppConversationIds } from "./app-store.js";
 import { getDb, getSqlite } from "./db-connection.js";
 import { migrateToolCreatedItems } from "./graph/bootstrap.js";
 import {
   addCoreColumns,
+  complexMigrationSteps,
   createActivationSessionsTable,
   createApprovalPromptTsTrackerTable,
   createAssistantInboxTables,
@@ -26,7 +28,6 @@ import {
   createContactsAndTriageTables,
   createConversationAttentionTables,
   createCoreIndexes,
-  createCoreTables,
   createExternalConversationBindingsTables,
   createFollowupsTables,
   createLifecycleEventsTable,
@@ -41,6 +42,7 @@ import {
   createTasksAndWorkItemsTables,
   createWatchersAndLogsTables,
   dropApprovalPromptTsTrackerTable,
+  lateMigrationSteps,
   migrate230AcpSessionHistory,
   migrate231RepairMemoryGraphEventDates,
   migrateA2ATasks,
@@ -86,6 +88,7 @@ import {
   migrateConversationsLastMessageAt,
   migrateConversationsSurfacedAt,
   migrateConversationsThreadTypeIndex,
+  migrateCoreTables,
   migrateCreateConversationGraphMemoryState,
   migrateCreateDocumentComments,
   migrateCreateDocumentConversations,
@@ -154,6 +157,7 @@ import {
   migrateMessagesConversationCreatedAtIndex,
   migrateMessagesFtsBackfill,
   migrateMessagesRoleCreatedAtIndex,
+  migrateMoveLlmRequestLogsToLogsDb,
   migrateNormalizePhoneIdentities,
   migrateNormalizeSlackExternalContent,
   migrateNormalizeUserFileByPrincipal,
@@ -230,9 +234,6 @@ import {
   migrateWorkflowJournalLeafTokens,
   migrateWorkflowRuns,
   migrateWorkflowRunTrust,
-  recoverCrashedMigrations,
-  runComplexMigrations,
-  runLateMigrations,
   validateMigrationState,
 } from "./migrations/index.js";
 import { runMigrationSteps } from "./migrations/run-migrations.js";
@@ -265,12 +266,31 @@ function getTemplateDbPath(): string {
   );
 }
 
+/**
+ * Template path for the attached `logs` database, kept alongside the main
+ * template. Both files must be captured/restored together: the migrated state
+ * now spans two files (llm_request_logs and its indexes live in `logs`), so
+ * restoring only the main DB would leave a fresh, empty logs DB with no
+ * `llm_request_logs` table.
+ */
+function getLogsTemplateDbPath(): string {
+  return `${getTemplateDbPath()}.logs`;
+}
+
 function tryRestoreTemplate(): boolean {
   const templatePath = getTemplateDbPath();
   if (!existsSync(templatePath)) return false;
   // getDb() hasn't run yet, so the data directory may not exist.
   ensureDataDir();
   copyFileSync(templatePath, getDbPath());
+  // Restore the attached logs DB before getDb() opens (and ATTACHes) it, so the
+  // relocated llm_request_logs table is present. Older templates may predate
+  // the split; the hash includes the migration files, so a stale template
+  // without this sibling won't be reused — but guard anyway.
+  const logsTemplate = getLogsTemplateDbPath();
+  if (existsSync(logsTemplate)) {
+    copyFileSync(logsTemplate, getLogsDbPath());
+  }
   // Open the pre-migrated copy — getDb() will set PRAGMAs but skip migrations.
   getDb();
   return true;
@@ -278,12 +298,18 @@ function tryRestoreTemplate(): boolean {
 
 function saveTemplate(): void {
   try {
-    // Flush WAL to main DB file before copying.
+    // Flush each DB's WAL to its main file before copying.
     getSqlite().exec("PRAGMA wal_checkpoint(TRUNCATE)");
-    const tmpFile = `${getTemplateDbPath()}.${process.pid}`;
-    copyFileSync(getDbPath(), tmpFile);
-    // Atomic rename — safe even with parallel test workers.
-    renameSync(tmpFile, getTemplateDbPath());
+    getSqlite().exec("PRAGMA logs.wal_checkpoint(TRUNCATE)");
+
+    const mainTmp = `${getTemplateDbPath()}.${process.pid}`;
+    copyFileSync(getDbPath(), mainTmp);
+    const logsTmp = `${getLogsTemplateDbPath()}.${process.pid}`;
+    copyFileSync(getLogsDbPath(), logsTmp);
+
+    // Atomic renames — safe even with parallel test workers.
+    renameSync(mainTmp, getTemplateDbPath());
+    renameSync(logsTmp, getLogsTemplateDbPath());
   } catch {
     // Best effort — next file will just run migrations normally.
   }
@@ -302,11 +328,10 @@ export function initializeDb(): void {
   // Every migration step, in execution order. Each function accepts a
   // DrizzleDb and is identified by its .name.
   const migrationSteps = [
-    createCoreTables,
-    recoverCrashedMigrations,
+    migrateCoreTables,
     createWatchersAndLogsTables,
     addCoreColumns,
-    runComplexMigrations,
+    ...complexMigrationSteps,
     createCoreIndexes,
     createContactsAndTriageTables,
     createCallSessionsTables,
@@ -320,7 +345,7 @@ export function initializeDb(): void {
     migrateGuardianVerificationPurpose,
     createMediaAssetsTables,
     createAssistantInboxTables,
-    runLateMigrations,
+    ...lateMigrationSteps,
     migrateChannelInboundDeliveredSegments,
     migrateGuardianActionFollowup,
     migrateGuardianActionToolMetadata,
@@ -531,11 +556,22 @@ export function initializeDb(): void {
     migrateDropExternalUserId,
     dropApprovalPromptTsTrackerTable,
     migrateRewriteBalancedEconomyProfilePins,
+    migrateMoveLlmRequestLogsToLogsDb,
   ];
 
   // Run each migration step, catching and logging individual failures so one
   // broken migration doesn't prevent independent later ones from succeeding.
-  const { failed } = runMigrationSteps(database, migrationSteps);
+  // The runner creates the checkpoint ledger, recovers crashed migrations, then
+  // records each step so an already-migrated database skips it on later boots.
+  const { failed, skipped } = runMigrationSteps(database, migrationSteps);
+
+  log.debug(
+    {
+      ranCount: migrationSteps.length - skipped.length,
+      skipped: skipped.length,
+    },
+    `DB migration steps complete (${skipped.length} skipped via checkpoint)`,
+  );
 
   if (failed.length > 0) {
     log.error(

package/src/memory/db-maintenance.ts

@@ -58,11 +58,10 @@ async function runDbMaintenance(): Promise<void> {
   );
 
   // Prune finished workflow runs (and their journals) past the retention
-  // window BEFORE VACUUM so the freed pages are reclaimed in the same pass.
-  // This is a fast bounded DELETE on the small workflow tables, so it runs on
-  // the main connection (`rawRun`) — unlike VACUUM/optimize it doesn't need the
-  // async/subprocess path. The maintenance scheduler below already defers this
-  // whole routine to an idle window.
+  // window. This is a fast bounded DELETE on the small workflow tables, so it
+  // runs on the main connection (`rawRun`). SQLite reuses the pages it frees
+  // for later writes — we deliberately do not VACUUM to hand them back to the
+  // OS (see the WAL note below).
   try {
     const deletedRuns = pruneRuns(getConfig().workflows.journalRetentionDays);
     if (deletedRuns > 0) {
@@ -72,18 +71,9 @@ async function runDbMaintenance(): Promise<void> {
     log.warn({ err }, "Workflow run pruning failed (non-fatal)");
   }
 
-  // VACUUM is the long-running one — minutes on a multi-GB DB. PRAGMA
-  // optimize is fast but routed through the same async path for
-  // consistency and to keep both off the main thread when the CLI
-  // backend is available.
-  const vacuumResult = await runAsyncSqlite("VACUUM");
-  if (!vacuumResult.ok) {
-    log.warn(
-      { error: vacuumResult.error, backend: vacuumResult.backend },
-      "VACUUM failed (non-fatal)",
-    );
-  }
-
+  // Refresh the query planner's statistics. PRAGMA optimize is cheap; it is
+  // routed through the async path for consistency and to keep it off the main
+  // thread when the sqlite3 CLI backend is available.
   const optimizeResult = await runAsyncSqlite("PRAGMA optimize");
   if (!optimizeResult.ok) {
     log.warn(
@@ -92,26 +82,42 @@ async function runDbMaintenance(): Promise<void> {
     );
   }
 
-  const after = getDbStats();
-  const reclaimedPages = before.pageCount - after.pageCount;
-  const reclaimedBytes =
-    before.fileSizeBytes != null && after.fileSizeBytes != null
-      ? before.fileSizeBytes - after.fileSizeBytes
-      : null;
+  // Truncate the WAL so it doesn't sit at its high-water mark. We intentionally
+  // do NOT run a full VACUUM: in WAL mode VACUUM rewrites the whole database
+  // through the WAL, inflating it to ~the database size and needing up to 2x the
+  // DB size in free disk to finish. SQLite already reuses freed pages for new
+  // writes, so eager space return isn't worth that cost on a multi-GB database.
+  //
+  // The checkpoint goes through the async path (sqlite3 subprocess when one is
+  // available) for the same reason VACUUM/optimize do: a synchronous
+  // wal_checkpoint(TRUNCATE) on the shared connection blocks the event loop
+  // while it checkpoints frames and waits out readers — the health/IPC stall
+  // runAsyncSqlite exists to avoid. A checkpoint from a separate connection
+  // still truncates the shared WAL; if a reader holds it back it's a
+  // best-effort no-op and the next maintenance pass retries.
+  const checkpointResult = await runAsyncSqlite(
+    "PRAGMA wal_checkpoint(TRUNCATE)",
+  );
+  if (!checkpointResult.ok) {
+    log.warn(
+      { error: checkpointResult.error, backend: checkpointResult.backend },
+      "WAL checkpoint failed (non-fatal)",
+    );
+  }
 
+  const after = getDbStats();
   log.info(
     {
-      backend: vacuumResult.backend,
-      vacuumOk: vacuumResult.ok,
       optimizeOk: optimizeResult.ok,
-      vacuumElapsedMs: vacuumResult.elapsedMs,
+      optimizeBackend: optimizeResult.backend,
       optimizeElapsedMs: optimizeResult.elapsedMs,
-      beforePageCount: before.pageCount,
-      afterPageCount: after.pageCount,
-      reclaimedPages,
-      beforeFileSizeBytes: before.fileSizeBytes,
-      afterFileSizeBytes: after.fileSizeBytes,
-      reclaimedBytes,
+      checkpointOk: checkpointResult.ok,
+      checkpointBackend: checkpointResult.backend,
+      checkpointResult: checkpointResult.stdout?.trim(),
+      checkpointElapsedMs: checkpointResult.elapsedMs,
+      pageCount: after.pageCount,
+      freelistCount: after.freelistCount,
+      fileSizeBytes: after.fileSizeBytes,
     },
     "Database maintenance complete",
   );
@@ -126,12 +132,11 @@ export async function maybeRunDbMaintenance(nowMs = Date.now()): Promise<void> {
   );
   if (nowMs - lastRun < intervalMs) return;
 
-  // VACUUM holds an exclusive lock on the database for its full duration —
-  // minutes on a multi-GB DB — during which every other write fails with
-  // SQLITE_BUSY ("database is locked"). Defer maintenance until the user has
-  // been quiet for `quietPeriodMs` so that lock never lands mid-conversation.
-  // The checkpoint below is only written once maintenance actually runs, so a
-  // deferred run is simply retried on a later (still-idle) worker tick.
+  // Maintenance still takes brief write locks (PRAGMA optimize and the
+  // truncating WAL checkpoint), so defer it until the user has been quiet for
+  // `quietPeriodMs` and those locks never land mid-conversation. The checkpoint
+  // below is only written once maintenance actually runs, so a deferred run is
+  // simply retried on a later (still-idle) worker tick.
   if (quietPeriodMs > 0) {
     const lastUserMessageAt = getLastUserMessageTimestamp();
     if (lastUserMessageAt > 0 && nowMs - lastUserMessageAt < quietPeriodMs) {

package/src/memory/job-handlers/cleanup.ts

@@ -1,5 +1,6 @@
 import type { AssistantConfig } from "../../config/types.js";
 import { getLogger } from "../../util/logger.js";
+import { getLogsDbPath } from "../../util/logs-db-path.js";
 import { runAsyncSqlite } from "../db-async-query.js";
 import { getDb } from "../db-connection.js";
 import { enqueueMemoryJob, type MemoryJob } from "../jobs-store.js";
@@ -49,9 +50,14 @@ export async function pruneOldLlmRequestLogsJob(
   // fallback backend in `db-async-query.ts` synthesizes the same shape
   // by capturing `changes()` atomically after `exec()`. Both backends
   // end up on the parser path below.
+  // llm_request_logs lives in the attached logs database. Point the sqlite3
+  // subprocess at that file directly (it can't see the daemon connection's
+  // ATTACH); the in-process fallback runs on the daemon connection, where the
+  // unqualified name already resolves to the attached table.
   const result = await runAsyncSqlite(
     `DELETE FROM llm_request_logs WHERE rowid IN (SELECT rowid FROM llm_request_logs WHERE created_at < ${cutoffMs} LIMIT ${PRUNE_LOG_BATCH_LIMIT});
 SELECT changes();`,
+    { dbPath: getLogsDbPath() },
   );
   if (!result.ok) {
     log.warn(

package/src/memory/migrations/{100-core-tables.ts → 000-core-tables.ts}

@@ -3,12 +3,16 @@ import type { DrizzleDb } from "../db-connection.js";
 /**
  * Core tables: conversations, messages, tool_invocations, memory_segments,
  * memory_items, memory_item_sources, memory_item_conflicts, memory_summaries,
- * memory_embeddings, memory_jobs, memory_checkpoints, attachments,
+ * memory_embeddings, memory_jobs, attachments,
  * message_attachments, message_surfaces, channel_inbound_events,
  * message_runs, cron_jobs, cron_runs, documents,
  * published_pages, shared_app_links, home_base_app_links.
+ *
+ * The migration bookkeeping table `memory_checkpoints` is created by the
+ * migration runner (`runMigrationSteps`) before any step runs, so it is not
+ * created here.
  */
-export function createCoreTables(database: DrizzleDb): void {
+export function migrateCoreTables(database: DrizzleDb): void {
   database.run(/*sql*/ `
     CREATE TABLE IF NOT EXISTS conversations (
       id TEXT PRIMARY KEY,
@@ -150,14 +154,6 @@ export function createCoreTables(database: DrizzleDb): void {
     )
   `);
 
-  database.run(/*sql*/ `
-    CREATE TABLE IF NOT EXISTS memory_checkpoints (
-      key TEXT PRIMARY KEY,
-      value TEXT NOT NULL,
-      updated_at INTEGER NOT NULL
-    )
-  `);
-
   database.run(/*sql*/ `
     CREATE TABLE IF NOT EXISTS attachments (
       id TEXT PRIMARY KEY,