@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/plugins/defaults/memory/jobs-worker.ts

@@ -3,6 +3,8 @@ import { join } from "node:path";
 
 import { getConfig } from "../../../config/loader.js";
 import {
+  isMemoryEnabled,
+  isMemoryV1Active,
   isMemoryV3Live,
   usesConceptPageMemory,
 } from "../../../config/memory-v3-gate.js";
@@ -62,12 +64,15 @@ import { sweepOrphanConversationMemoryTables } from "./conversation-memory-orpha
 import { getLogger } from "./logging.js";
 import { sweepOrphanMemoryRetrospectiveConversations } from "./memory-retrospective-startup-cleanup.js";
 import { getWorkspaceDir } from "./paths.js";
-import { hasPkbBufferContent } from "./pkb-schedule.js";
+// SUBSTRATE (v2+v3) — feeds `enqueueSubstrateMaintenanceJobs`.
 import {
   type ConsolidationFailureKind,
   countBufferLines,
   readConsolidationFailureState,
-} from "./v3/substrate/consolidation-job.js";
+} from "./substrate/consolidation-job.js";
+import { resolveSubstrateTuning } from "./substrate/tuning.js";
+// V1 — delete with v1. Feeds `enqueueV1MaintenanceJobs`.
+import { hasPkbBufferContent } from "./v1/pkb-schedule.js";
 import { spawnMemoryWorkerProcess } from "./worker-control.js";
 
 const log = getLogger("memory-jobs-worker");
@@ -101,17 +106,18 @@ export const MIN_BUFFER_LINES_FOR_CONSOLIDATION = 10;
 
 /**
  * V1 job types that read or write the v1 Qdrant collection via
- * `getQdrantClient()`. While concept-page memory is active, the v1 client is
- * intentionally left uninitialized in `lifecycle.ts`, so these handlers would
+ * `getQdrantClient()`. While v1 is not the live tier, the v1 client is
+ * intentionally left uninitialized in `startup.ts`, so these handlers would
  * throw `BackendUnavailableError` and accumulate as a deferred backlog. Stale
  * rows from indexer.ts and other unguarded enqueue sites must short-circuit
- * here for the same reason `graph_extract` does below.
+ * here for the same reason the v1 graph handlers do (`isStaleV1GraphJob` in
+ * `job-handlers.ts`) — one shared condition, `isMemoryV1Active`.
  *
  * Completing these as a no-op in that state is safe: their live write paths
  * keep re-enqueuing them, so nothing is lost. The one-shot
  * `sweep_orphaned_graph_node_points` cleanup is deliberately NOT in this set —
  * it has no re-enqueue, so `processJob` holds it pending (see
- * {@link SweepPostponedUnderV2Error}) instead of losing it to a no-op
+ * {@link SweepPostponedOffV1Error}) instead of losing it to a no-op
  * completion.
  */
 const V1_QDRANT_JOB_TYPES = new Set<MemoryJobType>([
@@ -128,17 +134,16 @@ const V1_QDRANT_JOB_TYPES = new Set<MemoryJobType>([
 /**
  * The one-shot cacheless graph-node sweep (migration 341) can only run against
  * the v1 Qdrant collection. Thrown from {@link processJob} when the job is
- * claimed while concept-page memory is active, so {@link handleJobError}
- * reschedules it — keeping it pending with no attempt or deferral spent —
- * until v1 is active again, rather than completing it as a no-op and losing
- * the cleanup on a later rollback to v1.
+ * claimed while v1 is not the live tier, so {@link handleJobError} reschedules
+ * it — keeping it pending with no attempt or deferral spent — until v1 is
+ * active again, rather than completing it as a no-op and losing the cleanup on
+ * a later return to v1 (a rollback off the substrate, or Memory switched back
+ * on).
  */
-class SweepPostponedUnderV2Error extends Error {
+class SweepPostponedOffV1Error extends Error {
   constructor() {
-    super(
-      "Cacheless graph-node sweep postponed while concept-page memory is active",
-    );
-    this.name = "SweepPostponedUnderV2Error";
+    super("Cacheless graph-node sweep postponed while v1 is not the live tier");
+    this.name = "SweepPostponedOffV1Error";
   }
 }
 
@@ -147,7 +152,7 @@ class SweepPostponedUnderV2Error extends Error {
  * that re-checking the gate costs only a trivial claim a few times a day,
  * short enough that a rollback to v1 runs the cleanup within the same day.
  */
-const SWEEP_POSTPONE_UNDER_V2_MS = 6 * 60 * 60 * 1000;
+const SWEEP_POSTPONE_OFF_V1_MS = 6 * 60 * 60 * 1000;
 
 /**
  * Job types whose handlers have been removed. Existing rows may still sit in
@@ -346,7 +351,7 @@ export async function runMemoryJobsOnce(
   // types — host-owned message-search indexing that shares this queue but is
   // not a memory feature. Every memory lane and every maintenance enqueue
   // stays idle in that state; only the lexical types are claimable.
-  const memoryEnabled = config.memory.enabled !== false;
+  const memoryEnabled = isMemoryEnabled(config);
   const enableScheduledCleanup =
     options.enableScheduledCleanup === true && memoryEnabled;
 
@@ -554,11 +559,11 @@ async function runLanePool(
 // ── Job error handling ─────────────────────────────────────────────
 
 function handleJobError(job: MemoryJob, err: unknown): void {
-  if (err instanceof SweepPostponedUnderV2Error) {
-    rescheduleMemoryJob(job.id, SWEEP_POSTPONE_UNDER_V2_MS);
+  if (err instanceof SweepPostponedOffV1Error) {
+    rescheduleMemoryJob(job.id, SWEEP_POSTPONE_OFF_V1_MS);
     log.debug(
       { jobId: job.id, type: job.type },
-      "Cacheless graph-node sweep held pending while memory v2 is enabled",
+      "Cacheless graph-node sweep held pending while v1 is not the live tier",
     );
     return;
   }
@@ -653,12 +658,18 @@ async function processJob(
   job: MemoryJob,
   config: AssistantConfig,
 ): Promise<void> {
-  if (usesConceptPageMemory(config.memory)) {
+  // Dispatch-level half of the v1-staleness guard, on the same condition the
+  // handler-level half uses (`isStaleV1GraphJob` in `job-handlers.ts`): v1 work
+  // runs only while v1 is the live tier, which memory being off is not (see
+  // `isMemoryV1Active`). Memory-off jobs of these types are unclaimable
+  // upstream — `runMemoryJobsOnce` restricts the claim to the message-lexical
+  // types — so this arm is defense in depth for a hot config flip mid-batch.
+  if (!isMemoryV1Active(config)) {
     if (V1_QDRANT_JOB_TYPES.has(job.type)) {
       return;
     }
     if (job.type === "sweep_orphaned_graph_node_points") {
-      throw new SweepPostponedUnderV2Error();
+      throw new SweepPostponedOffV1Error();
     }
   }
   const handler = jobHandlers.get(job.type);
@@ -838,6 +849,7 @@ export const GRAPH_MAINTENANCE_CHECKPOINTS = {
   consolidate: "graph_maintenance:consolidate:last_run",
   patternScan: "graph_maintenance:pattern_scan:last_run",
   narrative: "graph_maintenance:narrative:last_run",
+  // FROZEN: persisted checkpoint key — never rename the value.
   memoryV2Consolidate: "memory_v2_consolidate_last_run",
   memoryV3Maintain: "memory_v3_maintain_last_run",
   pkbFiling: "pkb_filing_last_run",
@@ -874,7 +886,7 @@ export function maybeEnqueueRetrospectiveSweepJob(
   config: AssistantConfig,
   nowMs = Date.now(),
 ): boolean {
-  if (config.memory.enabled === false) {
+  if (!isMemoryEnabled(config)) {
     return false;
   }
 
@@ -900,35 +912,6 @@ export function maybeEnqueueRetrospectiveSweepJob(
   return true;
 }
 
-/**
- * Enqueue periodic graph maintenance jobs.
- *
- * Mutually exclusive between v1 and concept-page memory:
- *   - concept-page memory active ({@link usesConceptPageMemory}) → only one
- *     buffer-drainer is scheduled (see below).
- *   - inactive → the four v1 entries (decay, consolidate, pattern_scan,
- *     narrative) are scheduled instead.
- *
- * The `memory/buffer.md` is shared, so exactly one consolidator owns the drain
- * at a time. When concept-page memory is active, the concept-page consolidator
- * (`memory_v2_consolidate`) is the sole buffer-drainer.
- *
- * Read/write paths route to concept pages when the gate is on, so v1 graph
- * data goes unread; running v1 maintenance alongside it is wasted compute and
- * LLM spend. The v1 code path remains live so disabling concept-page memory
- * fully re-engages v1.
- *
- * Uses durable checkpoints so intervals survive daemon restarts — jobs only
- * fire when the actual elapsed time since last run exceeds the interval.
- * Sweep is intentionally not on this schedule: it is debounced from the
- * live `graph_extract` trigger path (see `indexMessageNow` in `indexer.ts`)
- * so it runs on the same idle/message-count cadence.
- *
- * Independently of the v1/concept-page split, a flag-gated
- * `memory_v3_maintain` backstop is appended when a v3 path is active so the
- * topic tree self-heals even if the primary post-consolidation follow-up
- * enqueue is missed.
- */
 /**
  * Whether `hour` falls inside the PKB jobs' configured active window. A `null`
  * bound on either side means no restriction. Windows may wrap midnight
@@ -1035,121 +1018,93 @@ export function consolidationBackoffRemainingMs(
   return Math.max(0, state.lastFailureAt + backoffMs - nowMs);
 }
 
+/**
+ * Enqueue periodic graph maintenance jobs.
+ *
+ * Mutually exclusive between v1 and concept-page memory:
+ *   - concept-page memory active ({@link usesConceptPageMemory}) → only one
+ *     buffer-drainer is scheduled ({@link enqueueSubstrateMaintenanceJobs}).
+ *   - inactive → the four v1 entries (decay, consolidate, pattern_scan,
+ *     narrative) are scheduled instead ({@link enqueueV1MaintenanceJobs}).
+ *
+ * The `memory/buffer.md` is shared, so exactly one consolidator owns the drain
+ * at a time. When concept-page memory is active, the concept-page consolidator
+ * (`memory_v2_consolidate`) is the sole buffer-drainer.
+ *
+ * Read/write paths route to concept pages when the gate is on, so v1 graph
+ * data goes unread; running v1 maintenance alongside it is wasted compute and
+ * LLM spend. The v1 code path remains live so disabling concept-page memory
+ * fully re-engages v1.
+ *
+ * Uses durable checkpoints so intervals survive daemon restarts — jobs only
+ * fire when the actual elapsed time since last run exceeds the interval.
+ * Sweep is intentionally not on this schedule: it is debounced from the
+ * live `graph_extract` trigger path (see `indexMessageNow` in `indexer.ts`)
+ * so it runs on the same idle/message-count cadence.
+ *
+ * Independently of the v1/concept-page split, a flag-gated
+ * `memory_v3_maintain` backstop is scheduled when a v3 path is active so the
+ * topic tree self-heals even if the primary post-consolidation follow-up
+ * enqueue is missed ({@link enqueueV3BackstopJobs}).
+ */
 export function maybeEnqueueGraphMaintenanceJobs(
   config: AssistantConfig,
   nowMs = Date.now(),
 ): void {
-  const memoryEnabled = config.memory.enabled !== false;
-  if (!memoryEnabled) {
+  if (!isMemoryEnabled(config)) {
     return;
   }
 
-  const conceptPagesActive = usesConceptPageMemory(config.memory);
+  if (usesConceptPageMemory(config.memory)) {
+    enqueueSubstrateMaintenanceJobs(config, nowMs);
+  } else {
+    // V1 — delete with v1. Dropping only the banner-marked function body below
+    // would leave this call dangling: collapse the branch to the substrate arm.
+    enqueueV1MaintenanceJobs(config, nowMs);
+  }
+
+  // v3 self-maintenance backstop. Orthogonal to the mutual exclusion above:
+  // it owns its own checkpoint and operates on the v3 topic tree. Gated on
+  // the same config that gates the v3 plugin so it stays inert when v3 is
+  // off. The job handler itself no-ops when v3 is off, so this guard is
+  // belt-and-suspenders that also avoids a wasted enqueue.
+  if (isMemoryV3Live(config)) {
+    enqueueV3BackstopJobs(nowMs);
+  }
+}
+
+// ── SUBSTRATE (v2+v3) maintenance ─────────────────────────────────
 
-  // The single buffer-drainer entry for the concept-page branch. Referenced
-  // again below by the size-based trigger.
+/**
+ * Substrate maintenance entries; scheduled only while concept-page memory is
+ * active. The concept-page consolidator (`memory_v2_consolidate`) is the sole
+ * buffer-drainer, enqueued on an interval cadence plus a size-based trigger,
+ * both gated by the consolidation failure backoff.
+ */
+function enqueueSubstrateMaintenanceJobs(
+  config: AssistantConfig,
+  nowMs: number,
+): void {
+  const tuning = resolveSubstrateTuning(config.memory);
+
+  // The single buffer-drainer entry, shared by the interval cadence and the
+  // size-based trigger below.
   const consolidateEntry = {
     key: GRAPH_MAINTENANCE_CHECKPOINTS.memoryV2Consolidate,
-    intervalMs: config.memory.v2.consolidation_interval_hours * 60 * 60 * 1000,
+    intervalMs: tuning.consolidation_interval_hours * 60 * 60 * 1000,
     jobType: "memory_v2_consolidate" as MemoryJobType,
   };
 
-  const schedule: Array<{
-    key: string;
-    intervalMs: number;
-    jobType: MemoryJobType;
-  }> = conceptPagesActive
-    ? [consolidateEntry]
-    : [
-        {
-          key: GRAPH_MAINTENANCE_CHECKPOINTS.decay,
-          intervalMs: GRAPH_DECAY_INTERVAL_MS,
-          jobType: "graph_decay",
-        },
-        {
-          key: GRAPH_MAINTENANCE_CHECKPOINTS.consolidate,
-          intervalMs: GRAPH_CONSOLIDATE_INTERVAL_MS,
-          jobType: "graph_consolidate",
-        },
-        {
-          key: GRAPH_MAINTENANCE_CHECKPOINTS.patternScan,
-          intervalMs: GRAPH_PATTERN_SCAN_INTERVAL_MS,
-          jobType: "graph_pattern_scan",
-        },
-        {
-          key: GRAPH_MAINTENANCE_CHECKPOINTS.narrative,
-          intervalMs: GRAPH_NARRATIVE_INTERVAL_MS,
-          jobType: "graph_narrative_refine",
-        },
-      ];
-
-  // v3 self-maintenance backstop. Orthogonal to the mutual exclusion above:
-  // it owns its own checkpoint and operates on the v3 topic tree, so it
-  // runs under either branch. Gated on the same config that gates the v3 plugin
-  // so it stays inert when v3 is off. The post-consolidation follow-up in
-  // `consolidation-job.ts` remains the primary trigger; this interval only
-  // self-heals when that follow-up is missed (failed enqueue). The job handler
-  // itself no-ops when v3 is off, so
-  // this guard is belt-and-suspenders that also avoids a wasted enqueue.
-  if (isMemoryV3Live(config)) {
-    schedule.push({
-      key: GRAPH_MAINTENANCE_CHECKPOINTS.memoryV3Maintain,
-      intervalMs: GRAPH_V3_MAINTAIN_INTERVAL_MS,
-      jobType: "memory_v3_maintain",
-    });
-  }
-
+  const lastRun = parseInt(
+    getMemoryCheckpoint(consolidateEntry.key) ?? "0",
+    10,
+  );
   let enqueuedConsolidate = false;
-  for (const { key, intervalMs, jobType } of schedule) {
-    const lastRun = parseInt(getMemoryCheckpoint(key) ?? "0", 10);
-    if (nowMs - lastRun >= intervalMs) {
-      // Noop scheduled consolidation when the buffer has too few entries to
-      // justify an LLM run — mirrors the heartbeat max-consecutive-runs skip.
-      // The checkpoint advances so the next check fires after the regular
-      // interval. Manual "Run now" is unaffected (routes layer, not schedule).
-      if (jobType === consolidateEntry.jobType) {
-        // Failure backoff: skip WITHOUT advancing the checkpoint so the
-        // enqueue fires on the first tick after the window elapses instead
-        // of a full interval later.
-        const backoffRemainingMs = consolidationBackoffRemainingMs(
-          intervalMs,
-          nowMs,
-        );
-        if (backoffRemainingMs > 0) {
-          log.debug(
-            { backoffRemainingMs },
-            "Scheduled consolidation skipped: failure backoff active",
-          );
-          continue;
-        }
-        const bufferLines = memoryBufferLineCount();
-        if (bufferLines < MIN_BUFFER_LINES_FOR_CONSOLIDATION) {
-          // Staleness override: the minimum only defers while entries are
-          // still arriving. Once a non-empty buffer has sat unwritten for a
-          // full interval, drain it anyway — otherwise a buffer that never
-          // reaches the minimum re-skips every interval forever and its
-          // facts never become concept pages.
-          const stale =
-            bufferLines > 0 && memoryBufferIdleMs(nowMs) >= intervalMs;
-          if (!stale) {
-            log.debug(
-              "Scheduled consolidation skipped: buffer under minimum line threshold",
-            );
-            setMemoryCheckpoint(key, String(nowMs));
-            continue;
-          }
-        }
-      }
-      const payload =
-        jobType === consolidateEntry.jobType
-          ? AUTOMATIC_CONSOLIDATION_JOB_PAYLOAD
-          : {};
-      enqueueMemoryJob(jobType, payload);
-      setMemoryCheckpoint(key, String(nowMs));
-      if (jobType === consolidateEntry.jobType) {
-        enqueuedConsolidate = true;
-      }
-    }
+  if (nowMs - lastRun >= consolidateEntry.intervalMs) {
+    enqueuedConsolidate = maybeEnqueueScheduledConsolidation(
+      consolidateEntry,
+      nowMs,
+    );
   }
 
   // Size-based trigger: when the shared buffer crosses the configured line
@@ -1163,9 +1118,8 @@ export function maybeEnqueueGraphMaintenanceJobs(
   // The failure backoff gates it too: a failed run never trims the buffer, so
   // the size trigger alone would re-fire a failing run on every tick. A
   // backoff skip leaves the checkpoint alone.
-  const maxLines = config.memory.v2.consolidation_max_buffer_lines;
+  const maxLines = tuning.consolidation_max_buffer_lines;
   if (
-    conceptPagesActive &&
     !enqueuedConsolidate &&
     maxLines !== null &&
     !hasActiveJobOfType(consolidateEntry.jobType)
@@ -1189,6 +1143,103 @@ export function maybeEnqueueGraphMaintenanceJobs(
       }
     }
   }
+}
+
+/**
+ * Interval-cadence arm of the substrate consolidation schedule: enqueue the
+ * consolidate job unless the failure backoff or the minimum-buffer-lines gate
+ * (with its staleness override) skips it. Returns true when the job was
+ * enqueued.
+ */
+function maybeEnqueueScheduledConsolidation(
+  entry: { key: string; intervalMs: number; jobType: MemoryJobType },
+  nowMs: number,
+): boolean {
+  // Failure backoff: skip WITHOUT advancing the checkpoint so the enqueue
+  // fires on the first tick after the window elapses instead of a full
+  // interval later.
+  const backoffRemainingMs = consolidationBackoffRemainingMs(
+    entry.intervalMs,
+    nowMs,
+  );
+  if (backoffRemainingMs > 0) {
+    log.debug(
+      { backoffRemainingMs },
+      "Scheduled consolidation skipped: failure backoff active",
+    );
+    return false;
+  }
+  // Noop scheduled consolidation when the buffer has too few entries to
+  // justify an LLM run — mirrors the heartbeat max-consecutive-runs skip.
+  // The checkpoint advances so the next check fires after the regular
+  // interval. Manual "Run now" is unaffected (routes layer, not schedule).
+  const bufferLines = memoryBufferLineCount();
+  if (bufferLines < MIN_BUFFER_LINES_FOR_CONSOLIDATION) {
+    // Staleness override: the minimum only defers while entries are still
+    // arriving. Once a non-empty buffer has sat unwritten for a full
+    // interval, drain it anyway — otherwise a buffer that never reaches the
+    // minimum re-skips every interval forever and its facts never become
+    // concept pages.
+    const stale =
+      bufferLines > 0 && memoryBufferIdleMs(nowMs) >= entry.intervalMs;
+    if (!stale) {
+      log.debug(
+        "Scheduled consolidation skipped: buffer under minimum line threshold",
+      );
+      setMemoryCheckpoint(entry.key, String(nowMs));
+      return false;
+    }
+  }
+  enqueueMemoryJob(entry.jobType, AUTOMATIC_CONSOLIDATION_JOB_PAYLOAD);
+  setMemoryCheckpoint(entry.key, String(nowMs));
+  return true;
+}
+
+// ── V1 (legacy engine) maintenance — delete with v1 ───────────────
+
+/**
+ * v1-only maintenance entries; scheduled only when the legacy graph engine is
+ * the live memory tier. Covers the four v1 graph lifecycle jobs (decay,
+ * consolidate, pattern_scan, narrative) and the PKB filing/compaction
+ * schedule.
+ */
+function enqueueV1MaintenanceJobs(
+  config: AssistantConfig,
+  nowMs: number,
+): void {
+  const schedule: Array<{
+    key: string;
+    intervalMs: number;
+    jobType: MemoryJobType;
+  }> = [
+    {
+      key: GRAPH_MAINTENANCE_CHECKPOINTS.decay,
+      intervalMs: GRAPH_DECAY_INTERVAL_MS,
+      jobType: "graph_decay",
+    },
+    {
+      key: GRAPH_MAINTENANCE_CHECKPOINTS.consolidate,
+      intervalMs: GRAPH_CONSOLIDATE_INTERVAL_MS,
+      jobType: "graph_consolidate",
+    },
+    {
+      key: GRAPH_MAINTENANCE_CHECKPOINTS.patternScan,
+      intervalMs: GRAPH_PATTERN_SCAN_INTERVAL_MS,
+      jobType: "graph_pattern_scan",
+    },
+    {
+      key: GRAPH_MAINTENANCE_CHECKPOINTS.narrative,
+      intervalMs: GRAPH_NARRATIVE_INTERVAL_MS,
+      jobType: "graph_narrative_refine",
+    },
+  ];
+  for (const { key, intervalMs, jobType } of schedule) {
+    const lastRun = parseInt(getMemoryCheckpoint(key) ?? "0", 10);
+    if (nowMs - lastRun >= intervalMs) {
+      enqueueMemoryJob(jobType, {});
+      setMemoryCheckpoint(key, String(nowMs));
+    }
+  }
 
   // PKB filing/compaction — v1-only, like the v1 graph entries above (under
   // concept-page memory the consolidation job owns periodic background memory
@@ -1204,60 +1255,80 @@ export function maybeEnqueueGraphMaintenanceJobs(
   //  - either PKB job already pending/running: skip WITHOUT advancing, so the
   //    next worker tick retries. Filing and compaction both rewrite the PKB
   //    tree, so at most one of the two is ever in the queue.
-  if (!conceptPagesActive) {
-    const filingConfig = config.filing;
-    const withinActiveHours = isWithinPkbActiveHours(
-      new Date(nowMs).getHours(),
-      filingConfig.activeHoursStart ?? null,
-      filingConfig.activeHoursEnd ?? null,
-    );
-    const pkbSchedule: Array<{
-      key: string;
-      intervalMs: number;
-      jobType: MemoryJobType;
-      enabled: boolean;
-      hasWork: () => boolean;
-    }> = [
-      {
-        key: GRAPH_MAINTENANCE_CHECKPOINTS.pkbFiling,
-        intervalMs: filingConfig.intervalMs,
-        jobType: "pkb_filing",
-        enabled: filingConfig.enabled,
-        hasWork: () => hasPkbBufferContent(),
-      },
-      {
-        key: GRAPH_MAINTENANCE_CHECKPOINTS.pkbCompaction,
-        intervalMs: filingConfig.compactionIntervalMs,
-        jobType: "pkb_compaction",
-        enabled: filingConfig.compactionEnabled,
-        hasWork: () => true,
-      },
-    ];
-    for (const { key, intervalMs, jobType, enabled, hasWork } of pkbSchedule) {
-      if (!enabled) {
-        continue;
-      }
-      const checkpoint = getMemoryCheckpoint(key);
-      if (checkpoint === null) {
-        setMemoryCheckpoint(key, String(nowMs));
-        continue;
-      }
-      const lastRun = parseInt(checkpoint, 10);
-      if (nowMs - lastRun < intervalMs) {
-        continue;
-      }
-      if (!withinActiveHours || !hasWork()) {
-        setMemoryCheckpoint(key, String(nowMs));
-        continue;
-      }
-      if (
-        hasActiveJobOfType("pkb_filing") ||
-        hasActiveJobOfType("pkb_compaction")
-      ) {
-        continue;
-      }
-      enqueueMemoryJob(jobType, {});
+  const filingConfig = config.filing;
+  const withinActiveHours = isWithinPkbActiveHours(
+    new Date(nowMs).getHours(),
+    filingConfig.activeHoursStart ?? null,
+    filingConfig.activeHoursEnd ?? null,
+  );
+  const pkbSchedule: Array<{
+    key: string;
+    intervalMs: number;
+    jobType: MemoryJobType;
+    enabled: boolean;
+    hasWork: () => boolean;
+  }> = [
+    {
+      key: GRAPH_MAINTENANCE_CHECKPOINTS.pkbFiling,
+      intervalMs: filingConfig.intervalMs,
+      jobType: "pkb_filing",
+      enabled: filingConfig.enabled,
+      hasWork: () => hasPkbBufferContent(),
+    },
+    {
+      key: GRAPH_MAINTENANCE_CHECKPOINTS.pkbCompaction,
+      intervalMs: filingConfig.compactionIntervalMs,
+      jobType: "pkb_compaction",
+      enabled: filingConfig.compactionEnabled,
+      hasWork: () => true,
+    },
+  ];
+  for (const { key, intervalMs, jobType, enabled, hasWork } of pkbSchedule) {
+    if (!enabled) {
+      continue;
+    }
+    const checkpoint = getMemoryCheckpoint(key);
+    if (checkpoint === null) {
       setMemoryCheckpoint(key, String(nowMs));
+      continue;
+    }
+    const lastRun = parseInt(checkpoint, 10);
+    if (nowMs - lastRun < intervalMs) {
+      continue;
+    }
+    if (!withinActiveHours || !hasWork()) {
+      setMemoryCheckpoint(key, String(nowMs));
+      continue;
     }
+    if (
+      hasActiveJobOfType("pkb_filing") ||
+      hasActiveJobOfType("pkb_compaction")
+    ) {
+      continue;
+    }
+    enqueueMemoryJob(jobType, {});
+    setMemoryCheckpoint(key, String(nowMs));
+  }
+}
+
+// ── V3 backstop ───────────────────────────────────────────────────
+
+/**
+ * v3 self-maintenance backstop on its own durable checkpoint. The
+ * post-consolidation follow-up in `consolidation-job.ts` is the primary
+ * trigger; this interval only self-heals when that follow-up is missed
+ * (failed enqueue).
+ */
+function enqueueV3BackstopJobs(nowMs: number): void {
+  const lastRun = parseInt(
+    getMemoryCheckpoint(GRAPH_MAINTENANCE_CHECKPOINTS.memoryV3Maintain) ?? "0",
+    10,
+  );
+  if (nowMs - lastRun >= GRAPH_V3_MAINTAIN_INTERVAL_MS) {
+    enqueueMemoryJob("memory_v3_maintain", {});
+    setMemoryCheckpoint(
+      GRAPH_MAINTENANCE_CHECKPOINTS.memoryV3Maintain,
+      String(nowMs),
+    );
   }
 }

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

@@ -35,7 +35,7 @@ import { type TrustClass } from "../../../runtime/actor-trust-resolver.js";
 import { resolveCapabilities } from "../../../runtime/capabilities.js";
 import { getLogger } from "./logging.js";
 import { isMemoryRetrospectiveSource } from "./memory-retrospective-constants.js";
-import { MEMORY_V2_CONSOLIDATION_SOURCE } from "./v3/substrate/constants.js";
+import { MEMORY_V2_CONSOLIDATION_SOURCE } from "./substrate/constants.js";
 
 const log = getLogger("memory-retrospective-enqueue");
 
@@ -107,7 +107,9 @@ export function isMemoryRetrospectiveConversation(
  */
 function isLowYieldRetrospectiveSource(conversationId: string): boolean {
   const conversation = getConversation(conversationId);
-  if (!conversation) return false;
+  if (!conversation) {
+    return false;
+  }
   return (
     conversation.conversationType === "scheduled" ||
     conversation.source === MEMORY_V2_CONSOLIDATION_SOURCE