@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/plugins/defaults/memory/{v3/substrate → substrate}/cli-command-store.ts

@@ -1,7 +1,10 @@
 // ---------------------------------------------------------------------------
-// Memory v2 — `assistant` CLI subcommands → embedded capability entries
+// Memory substrate — `assistant` CLI subcommands → embedded capability entries
 // ---------------------------------------------------------------------------
 //
+// Shared by the v2 injection engine and memory-v3; active whenever
+// `usesConceptPageMemory()` holds.
+//
 // Enumerate the top-level `assistant` CLI commands from their declarative help
 // (`CLI_COMMAND_HELP`, exposed via `@vellumai/plugin-api`), render each as a
 // prose capability statement, embed dense + sparse, and upsert into
@@ -26,11 +29,11 @@
 
 import { CLI_COMMAND_HELP } from "@vellumai/plugin-api";
 
-import { getConfig } from "../../../../../config/loader.js";
-import { generateSparseEmbedding } from "../../../../../persistence/embeddings/embedding-backend.js";
-import { applyCorrectionIfCalibrated } from "../../anisotropy.js";
-import { embedWithBackend } from "../../embeddings.js";
-import { getLogger } from "../../logging.js";
+import { getConfig } from "../../../../config/loader.js";
+import { generateSparseEmbedding } from "../../../../persistence/embeddings/embedding-backend.js";
+import { applyCorrectionIfCalibrated } from "../anisotropy.js";
+import { embedWithBackend } from "../embeddings.js";
+import { getLogger } from "../logging.js";
 import { buildCliCommandHelpContent } from "./cli-command-content.js";
 import { invalidatePageIndex } from "./page-index.js";
 import {
@@ -42,6 +45,7 @@ import {
   generateBm25DocEmbedding,
   getConceptPageCorpusStats,
 } from "./sparse-bm25.js";
+import { resolveSubstrateTuning } from "./tuning.js";
 import type { CliCommandEntry } from "./types.js";
 
 const log = getLogger("memory-v2-cli-command-store");
@@ -185,11 +189,12 @@ async function runSeedV2CliCommandEntries(generation: number): Promise<void> {
       // start window before corpus stats finish building — same rationale as
       // the skill-store path.
       const corpusStats = getConceptPageCorpusStats();
+      const { bm25_k1, bm25_b } = resolveSubstrateTuning(config.memory);
       encodeSparse = (input: string) =>
         corpusStats
           ? generateBm25DocEmbedding(input, corpusStats, {
-              k1: config.memory.v2.bm25_k1,
-              b: config.memory.v2.bm25_b,
+              k1: bm25_k1,
+              b: bm25_b,
             })
           : generateSparseEmbedding(input);
       try {

package/src/plugins/defaults/memory/{v3/substrate → substrate}/consolidation-job.ts

@@ -1,5 +1,8 @@
 /**
- * Memory v2 — `memory_v2_consolidate` job handler.
+ * Memory substrate — `memory_v2_consolidate` job handler.
+ *
+ * Shared by the v2 injection engine and memory-v3; active whenever
+ * `usesConceptPageMemory()` holds.
  *
  * The consolidation job is the centerpiece of v2: an hourly background pass
  * that routes accumulated `memory/buffer.md` entries into concept pages,
@@ -80,27 +83,28 @@ import { dirname, join } from "node:path";
 import {
   isMemoryV3Live,
   usesConceptPageMemory,
-} from "../../../../../config/memory-v3-gate.js";
-import type { AssistantConfig } from "../../../../../config/types.js";
+} from "../../../../config/memory-v3-gate.js";
+import type { AssistantConfig } from "../../../../config/types.js";
 import {
   deleteMemoryCheckpoint,
   getMemoryCheckpoint,
   setMemoryCheckpoint,
-} from "../../../../../persistence/checkpoints.js";
+} from "../../../../persistence/checkpoints.js";
 import {
   enqueueMemoryJob,
   hasPendingJobOfType,
   type MemoryJob,
   type MemoryJobType,
-} from "../../../../../persistence/jobs-store.js";
-import { runBackgroundJob } from "../../../../../runtime/background-job-runner.js";
-import { formatBufferTimestamp } from "../../graph/tool-handlers.js";
-import { isProcessAlive } from "../../host-utils.js";
-import { getLogger } from "../../logging.js";
-import { getWorkspaceDir } from "../../paths.js";
+} from "../../../../persistence/jobs-store.js";
+import { runBackgroundJob } from "../../../../runtime/background-job-runner.js";
+import { formatBufferTimestamp } from "../graph/tool-handlers.js";
+import { isProcessAlive } from "../host-utils.js";
+import { getLogger } from "../logging.js";
+import { getWorkspaceDir } from "../paths.js";
 import { MEMORY_V2_CONSOLIDATION_SOURCE } from "./constants.js";
 import { getPageIndex, type PageParseFailure } from "./page-index.js";
 import { resolveConsolidationPrompt } from "./prompts/consolidation.js";
+import { resolveSubstrateTuning } from "./tuning.js";
 
 const log = getLogger("memory-v2-consolidate");
 
@@ -195,6 +199,7 @@ const STALE_LOCK_TTL_MS = 4 * CONSOLIDATION_TIMEOUT_MS;
  *
  * Value is JSON: `{ consecutiveFailures, lastFailureAt, kind }`.
  */
+// FROZEN: persisted checkpoint key — never rename the value.
 export const CONSOLIDATION_FAILURE_CHECKPOINT_KEY =
   "memory_v2_consolidate_failure_state";
 
@@ -323,17 +328,17 @@ export async function memoryV2ConsolidateJob(
   _job: MemoryJob,
   config: AssistantConfig,
 ): Promise<ConsolidationOutcome> {
-  if (config.memory.enabled === false) {
-    log.debug("memory.enabled is false; consolidation skipped");
-    return { kind: "disabled" };
-  }
-
+  // One gate, not two: `usesConceptPageMemory` already returns false on an
+  // explicit `memory.enabled === false`, so the memory-off case lands here
+  // with the same `"disabled"` outcome a separate early return would have
+  // produced.
   if (!usesConceptPageMemory(config.memory)) {
     log.debug("concept-page memory is not active; consolidation skipped");
     return { kind: "disabled" };
   }
 
   const memoryDir = join(getWorkspaceDir(), "memory");
+  // FROZEN: `memory/.v2-state/` is a persisted workspace path — never rename.
   const lockPath = join(memoryDir, ".v2-state", "consolidation.lock");
   const bufferPath = join(memoryDir, "buffer.md");
 
@@ -381,7 +386,8 @@ export async function memoryV2ConsolidateJob(
     // lines belong to the preceding entry, not the count.
     let cutoff = formatBufferTimestamp(new Date());
     let deferredEntries = 0;
-    const maxEntries = config.memory.v2.consolidation_max_entries_per_run;
+    const tuning = resolveSubstrateTuning(config.memory);
+    const maxEntries = tuning.consolidation_max_entries_per_run;
     if (maxEntries != null) {
       const entryTimestamps = bufferContent
         .split("\n")
@@ -430,7 +436,7 @@ export async function memoryV2ConsolidateJob(
     // Sentry-side reporting is unchanged.
     //
     // The prompt body comes from `resolveConsolidationPrompt`, which honors
-    // the `memory.v2.consolidation_prompt_path` config override but bounds
+    // the `consolidation_prompt_path` substrate tunable but bounds
     // it to a regular file under 1 MiB before substitution so a stray path
     // (or a `/dev/zero`-style pseudo-file) cannot exfiltrate megabytes of
     // bytes through the wake hint. The core-pages curation section and the
@@ -453,7 +459,7 @@ export async function memoryV2ConsolidateJob(
       );
     }
     const prompt = resolveConsolidationPrompt(
-      config.memory.v2.consolidation_prompt_path,
+      tuning.consolidation_prompt_path,
       cutoff,
       {
         includeCorePagesSection: memoryV3Live,
@@ -612,7 +618,9 @@ function readBufferContent(bufferPath: string): string {
   try {
     return readFileSync(bufferPath, "utf-8");
   } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") return "";
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return "";
+    }
     throw err;
   }
 }
@@ -685,9 +693,13 @@ function tryAcquireLock(lockPath: string): string | null {
   mkdirSync(dirname(lockPath), { recursive: true });
 
   const firstHolder = tryCreate(lockPath);
-  if (firstHolder === null) return null;
+  if (firstHolder === null) {
+    return null;
+  }
   const staleReason = holderStaleReason(firstHolder);
-  if (staleReason === null) return firstHolder;
+  if (staleReason === null) {
+    return firstHolder;
+  }
 
   log.info(
     { lockPath, holder: firstHolder, reason: staleReason },
@@ -721,7 +733,9 @@ function tryCreate(lockPath: string): string | null {
   try {
     fd = openSync(lockPath, "wx");
   } catch (err) {
-    if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+    if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw err;
+    }
     try {
       return readFileSync(lockPath, "utf-8").trim() || "unknown";
     } catch {
@@ -760,9 +774,13 @@ function parseHolder(
   holder: string,
 ): { pid: number; timestamp: number | null } | null {
   const match = /^(\d+)(?:\s+(\d+))?/.exec(holder);
-  if (!match) return null;
+  if (!match) {
+    return null;
+  }
   const pid = Number.parseInt(match[1], 10);
-  if (!Number.isFinite(pid) || pid <= 0) return null;
+  if (!Number.isFinite(pid) || pid <= 0) {
+    return null;
+  }
   const timestamp =
     match[2] !== undefined ? Number.parseInt(match[2], 10) : null;
   return {
@@ -790,8 +808,12 @@ function parseHolder(
  */
 function holderStaleReason(holder: string): StaleReason | null {
   const parsed = parseHolder(holder);
-  if (parsed === null) return "unparseable";
-  if (!isProcessAlive(parsed.pid)) return "pid_dead";
+  if (parsed === null) {
+    return "unparseable";
+  }
+  if (!isProcessAlive(parsed.pid)) {
+    return "pid_dead";
+  }
   if (
     parsed.timestamp !== null &&
     Date.now() - parsed.timestamp > STALE_LOCK_TTL_MS
@@ -812,7 +834,9 @@ function releaseLock(lockPath: string): void {
     unlinkSync(lockPath);
   } catch (err) {
     const code = (err as NodeJS.ErrnoException).code;
-    if (code === "ENOENT") return;
+    if (code === "ENOENT") {
+      return;
+    }
     log.warn(
       { err, lockPath },
       "consolidation: failed to release lock (best-effort)",

package/src/plugins/defaults/memory/{v3/substrate → substrate}/constants.ts

@@ -4,4 +4,5 @@
  * recognize consolidation conversations without importing the consolidation
  * job (which pulls in agent-wake + bootstrap dependencies).
  */
+// FROZEN: persisted `conversations.source` value — never rename it.
 export const MEMORY_V2_CONSOLIDATION_SOURCE = "memory_v2_consolidation";

package/src/plugins/defaults/memory/{v3/substrate → substrate}/edge-index.ts

@@ -1,7 +1,10 @@
 /**
- * Memory v2 — In-memory directed edge index, derived from concept-page
+ * Memory substrate — In-memory directed edge index, derived from concept-page
  * frontmatter.
  *
+ * Shared by the v2 injection engine and memory-v3; active whenever
+ * `usesConceptPageMemory()` holds.
+ *
  * Each concept page's `edges:` frontmatter list is the canonical source of
  * truth for that page's *outgoing* edges. Edges are directed: an entry of
  * `B` in A's `edges:` means "activating A pulls in B" — activation flows
@@ -78,13 +81,19 @@ export async function getEdgeIndex(workspaceDir: string): Promise<EdgeIndex> {
       } catch {
         return;
       }
-      if (!page) return;
+      if (!page) {
+        return;
+      }
       const out = new Set<string>();
       for (const target of page.frontmatter.edges) {
-        if (target === slug) continue;
+        if (target === slug) {
+          continue;
+        }
         out.add(target);
       }
-      if (out.size > 0) outgoing.set(slug, out);
+      if (out.size > 0) {
+        outgoing.set(slug, out);
+      }
       for (const target of out) {
         ensureSet(incoming, target).add(slug);
       }
@@ -102,7 +111,9 @@ export async function getEdgeIndex(workspaceDir: string): Promise<EdgeIndex> {
  * workspaces); omit it to clear unconditionally.
  */
 export function invalidateEdgeIndex(workspaceDir?: string): void {
-  if (!cache) return;
+  if (!cache) {
+    return;
+  }
   if (workspaceDir === undefined || cache.workspaceDir === workspaceDir) {
     cache = null;
   }
@@ -125,7 +136,9 @@ export function getReachable(
   direction: EdgeDirection,
 ): Set<string> {
   const result = new Set<string>();
-  if (hops <= 0) return result;
+  if (hops <= 0) {
+    return result;
+  }
 
   const adjacency = direction === "out" ? index.outgoing : index.incoming;
   const visited = new Set<string>([slug]);
@@ -135,9 +148,13 @@ export function getReachable(
     const next: string[] = [];
     for (const node of frontier) {
       const neighbors = adjacency.get(node);
-      if (!neighbors) continue;
+      if (!neighbors) {
+        continue;
+      }
       for (const neighbor of neighbors) {
-        if (visited.has(neighbor)) continue;
+        if (visited.has(neighbor)) {
+          continue;
+        }
         visited.add(neighbor);
         result.add(neighbor);
         next.push(neighbor);
@@ -172,7 +189,9 @@ export function validateEdgeTargets(
   for (const from of sources) {
     const targets = [...(index.outgoing.get(from) ?? [])].sort();
     for (const to of targets) {
-      if (!knownSlugs.has(to)) missing.push({ from, to });
+      if (!knownSlugs.has(to)) {
+        missing.push({ from, to });
+      }
     }
   }
   return { ok: missing.length === 0, missing };

package/src/plugins/defaults/memory/{v3/substrate → substrate}/frontmatter-sweep.ts

@@ -1,7 +1,10 @@
 // ---------------------------------------------------------------------------
-// Memory v2 — Concept page frontmatter sweep
+// Memory substrate — Concept page frontmatter sweep
 // ---------------------------------------------------------------------------
 //
+// Shared by the v2 injection engine and memory-v3; active whenever
+// `usesConceptPageMemory()` holds.
+//
 // At daemon startup, walk every concept page on disk and validate its
 // frontmatter against `ConceptPageFrontmatterSchema`. The schema is
 // `.passthrough()`, so unknown keys are tolerated; what this sweep catches is
@@ -23,10 +26,10 @@ import { join } from "node:path";
 
 import { parse as parseYaml } from "yaml";
 
-import { usesConceptPageMemory } from "../../../../../config/memory-v3-gate.js";
-import type { AssistantConfig } from "../../../../../config/schema.js";
-import { FRONTMATTER_REGEX } from "../../frontmatter.js";
-import { getLogger } from "../../logging.js";
+import { usesConceptPageMemory } from "../../../../config/memory-v3-gate.js";
+import type { AssistantConfig } from "../../../../config/schema.js";
+import { FRONTMATTER_REGEX } from "../frontmatter.js";
+import { getLogger } from "../logging.js";
 import { listPages } from "./page-store.js";
 import { ConceptPageFrontmatterSchema } from "./types.js";
 
@@ -43,7 +46,9 @@ export async function sweepConceptPageFrontmatter(
   config: AssistantConfig,
   workspaceDir: string,
 ): Promise<void> {
-  if (!usesConceptPageMemory(config.memory)) return;
+  if (!usesConceptPageMemory(config.memory)) {
+    return;
+  }
 
   let slugs: string[];
   try {
@@ -81,7 +86,9 @@ export async function sweepConceptPageFrontmatter(
     }
 
     const result = ConceptPageFrontmatterSchema.safeParse(parsed);
-    if (result.success) continue;
+    if (result.success) {
+      continue;
+    }
 
     for (const issue of result.error.issues) {
       log.warn(

package/src/plugins/defaults/memory/{v3/substrate → substrate}/injected-block-slugs.ts

@@ -44,7 +44,9 @@ export function extractInjectedConceptSlugs(block: string): string[] {
   const seen = new Set<string>();
   for (const match of block.matchAll(INJECTED_CONCEPT_HEADER_REGEX)) {
     const slug = match[1]!;
-    if (seen.has(slug)) continue;
+    if (seen.has(slug)) {
+      continue;
+    }
     seen.add(slug);
     slugs.push(slug);
   }
@@ -65,12 +67,16 @@ export function readInjectedBlock(
   metadata: string | null | undefined,
   key: string,
 ): string | null {
-  if (!metadata) return null;
+  if (!metadata) {
+    return null;
+  }
   try {
     const parsed: unknown = JSON.parse(metadata);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       const block = (parsed as Record<string, unknown>)[key];
-      if (typeof block === "string") return block;
+      if (typeof block === "string") {
+        return block;
+      }
     }
   } catch {
     // Malformed metadata — treat as no block.

package/src/plugins/defaults/memory/{v3/substrate → substrate}/page-index.ts

@@ -1,5 +1,8 @@
 /**
- * Memory v2 — Numbered page index for the router prompt.
+ * Memory substrate — Numbered page index for the router prompt.
+ *
+ * Shared by the v2 injection engine and memory-v3; active whenever
+ * `usesConceptPageMemory()` holds.
  *
  * Renders a compact catalog of every concept page plus every seeded skill
  * entry, sorted by slug ASCII for deterministic IDs, with each entry's
@@ -16,7 +19,7 @@
  * concept pages or seeded skill entries change.
  */
 
-import { getLogger } from "../../logging.js";
+import { getLogger } from "../logging.js";
 import { getPageMtimeMs, listPages, readPage } from "./page-store.js";
 
 // Dynamic import for `./skill-store.js` happens inside `getPageIndex` so that
@@ -186,7 +189,9 @@ export async function getPageIndex(workspaceDir: string): Promise<PageIndex> {
       continue;
     }
     const { page, mtimeMs } = result.value;
-    if (!page) continue;
+    if (!page) {
+      continue;
+    }
     if (page.parseWarning !== undefined) {
       parseFailures.push({ slug, error: page.parseWarning, dropped: false });
     }
@@ -260,7 +265,9 @@ export async function getPageIndex(workspaceDir: string): Promise<PageIndex> {
     const resolved: number[] = [];
     for (const targetSlug of draft.outgoingSlugs) {
       const target = bySlug.get(targetSlug);
-      if (target) resolved.push(target.id);
+      if (target) {
+        resolved.push(target.id);
+      }
     }
     resolved.sort((a, b) => a - b);
     entries[i].edges = resolved;
@@ -290,7 +297,9 @@ function firstErrorLine(reason: unknown): string {
  * specific cache entry; omit it to clear unconditionally.
  */
 export function invalidatePageIndex(workspaceDir?: string): void {
-  if (!cache) return;
+  if (!cache) {
+    return;
+  }
   if (workspaceDir === undefined || cache.workspaceDir === workspaceDir) {
     cache = null;
   }
@@ -305,7 +314,9 @@ export function invalidatePageIndex(workspaceDir?: string): void {
 function renderIndex(entries: readonly PageIndexEntry[]): string {
   const lines = entries.map((entry) => {
     const head = `[${entry.id}] ${entry.slug} — ${entry.summary}`;
-    if (entry.edges.length === 0) return head;
+    if (entry.edges.length === 0) {
+      return head;
+    }
     return `${head} (edges: ${entry.edges.join(", ")})`;
   });
   return lines.length > 0 ? `${lines.join("\n")}\n` : "";
@@ -389,9 +400,13 @@ function buildLocalPageIndex(
     const localEdges: number[] = [];
     for (const globalEdgeId of entries[i].edges) {
       const target = source.byId.get(globalEdgeId);
-      if (!target) continue;
+      if (!target) {
+        continue;
+      }
       const localTarget = localBySlug.get(target.slug);
-      if (localTarget) localEdges.push(localTarget.id);
+      if (localTarget) {
+        localEdges.push(localTarget.id);
+      }
     }
     localEdges.sort((a, b) => a - b);
     localEntries[i].edges = localEdges;
@@ -431,7 +446,9 @@ export function splitTier1(
     return { tier1: null, rest: pageIndex };
   }
   const sortedByRecency = [...pageIndex.entries].sort((a, b) => {
-    if (a.modifiedAt !== b.modifiedAt) return b.modifiedAt - a.modifiedAt;
+    if (a.modifiedAt !== b.modifiedAt) {
+      return b.modifiedAt - a.modifiedAt;
+    }
     return a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0;
   });
   const tier1Entries = sortedByRecency.slice(0, tier1Size);
@@ -471,7 +488,9 @@ export function splitTier2(
     .map((entry) => ({ entry, score: scores.get(entry.slug) ?? 0 }))
     .filter((x) => x.score > 0)
     .sort((a, b) => {
-      if (a.score !== b.score) return b.score - a.score;
+      if (a.score !== b.score) {
+        return b.score - a.score;
+      }
       return a.entry.slug < b.entry.slug
         ? -1
         : a.entry.slug > b.entry.slug

package/src/plugins/defaults/memory/{v3/substrate → substrate}/page-store.ts

@@ -1,5 +1,8 @@
 /**
- * Memory v2 — Concept page store.
+ * Memory substrate — Concept page store.
+ *
+ * Shared by the v2 injection engine and memory-v3; active whenever
+ * `usesConceptPageMemory()` holds.
  *
  * Owns the on-disk read/write contract for `memory/concepts/<slug>.md`.
  * Pages may live directly under `memory/concepts/` or nested in subdirectories
@@ -31,7 +34,7 @@ import { dirname, join, relative, sep } from "node:path";
 
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 
-import { FRONTMATTER_REGEX } from "../../frontmatter.js";
+import { FRONTMATTER_REGEX } from "../frontmatter.js";
 import { invalidateEdgeIndex } from "./edge-index.js";
 import { invalidatePageIndex } from "./page-index.js";
 import { type ConceptPage, ConceptPageFrontmatterSchema } from "./types.js";
@@ -356,23 +359,33 @@ export async function listPages(workspaceDir: string): Promise<string[]> {
       if ((err as NodeJS.ErrnoException).code === "ENOENT") {
         // Root missing → return []. Nested missing dir is impossible mid-walk
         // (we only enqueue what readdir surfaced) but treat the same defensively.
-        if (dir === root) return [];
+        if (dir === root) {
+          return [];
+        }
         continue;
       }
       throw err;
     }
 
     for (const entry of entries) {
-      if (entry.name.startsWith(".")) continue;
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
       const fullPath = join(dir, entry.name);
       if (entry.isDirectory()) {
         queue.push(fullPath);
         continue;
       }
-      if (!entry.isFile()) continue;
-      if (!entry.name.endsWith(PAGE_EXTENSION)) continue;
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (!entry.name.endsWith(PAGE_EXTENSION)) {
+        continue;
+      }
       // Skip orphaned temp files left behind by a crashed atomic write.
-      if (entry.name.includes(".tmp.")) continue;
+      if (entry.name.includes(".tmp.")) {
+        continue;
+      }
       slugs.push(slugFromConceptPath(root, fullPath));
     }
   }
@@ -398,21 +411,31 @@ export async function hasConceptPages(workspaceDir: string): Promise<boolean> {
       entries = await readdir(dir, { withFileTypes: true });
     } catch (err) {
       if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-        if (dir === root) return false;
+        if (dir === root) {
+          return false;
+        }
         continue;
       }
       throw err;
     }
 
     for (const entry of entries) {
-      if (entry.name.startsWith(".")) continue;
+      if (entry.name.startsWith(".")) {
+        continue;
+      }
       if (entry.isDirectory()) {
         queue.push(join(dir, entry.name));
         continue;
       }
-      if (!entry.isFile()) continue;
-      if (!entry.name.endsWith(PAGE_EXTENSION)) continue;
-      if (entry.name.includes(".tmp.")) continue;
+      if (!entry.isFile()) {
+        continue;
+      }
+      if (!entry.name.endsWith(PAGE_EXTENSION)) {
+        continue;
+      }
+      if (entry.name.includes(".tmp.")) {
+        continue;
+      }
       return true;
     }
   }

package/src/plugins/defaults/memory/{v3/substrate → substrate}/prompts/consolidation.ts

@@ -1,5 +1,8 @@
 /**
- * Memory v2 — consolidation prompt template.
+ * Memory substrate — consolidation prompt template.
+ *
+ * Shared by the v2 injection engine and memory-v3; active whenever
+ * `usesConceptPageMemory()` holds.
  *
  * Body adapted from the live-mode form of the workspace consolidation prompt.
  * The consolidation job calls `wakeAgentForOpportunity()` so the assistant
@@ -18,10 +21,10 @@
  * the convention established for the sweep prompt.
  */
 
-import { truncate } from "../../../host-utils.js";
-import { getLogger } from "../../../logging.js";
-import { getWorkspaceDir } from "../../../paths.js";
-import { loadPromptOverride } from "../../../prompt-override.js";
+import { truncate } from "../../host-utils.js";
+import { getLogger } from "../../logging.js";
+import { getWorkspaceDir } from "../../paths.js";
+import { loadPromptOverride } from "../../prompt-override.js";
 import type { PageParseFailure } from "../page-index.js";
 
 const log = getLogger("memory-v2-consolidate-prompt");
@@ -111,7 +114,7 @@ export const CORE_PAGES_PLACEHOLDER = "{{CORE_PAGES_SECTION}}";
 
 /**
  * Legacy placeholder kept only for backward compatibility. A custom
- * `memory.v2.consolidation_prompt_path` override copied from an older bundled
+ * `consolidation_prompt_path` override copied from an older bundled
  * prompt may still contain `{{PROC_TO_SKILLS_SECTION}}`; it is always replaced
  * with an empty string so the raw token never reaches the consolidation LLM.
  */
@@ -929,7 +932,8 @@ export function renderConsolidationPrompt(
 
 /**
  * Load the consolidation prompt template, optionally overridden from the file
- * referenced by `memory.v2.consolidation_prompt_path`, then substitute
+ * referenced by the `consolidation_prompt_path` substrate tunable, then
+ * substitute
  * `{{CUTOFF}}`. File loading (path resolution, size guard, and the permissive
  * fall-back to the bundled prompt on a missing/unreadable/empty/oversized
  * override) is handled by the shared {@link loadPromptOverride}.
@@ -958,7 +962,9 @@ export function resolveConsolidationPrompt(
     log,
     label: "consolidation prompt",
   });
-  if (override === null) return renderConsolidationPrompt(cutoff, options);
+  if (override === null) {
+    return renderConsolidationPrompt(cutoff, options);
+  }
 
   const substituted = substitutePlaceholders(override, cutoff, options);
   if (override.includes(PARSE_FAILURES_PLACEHOLDER)) {

package/src/plugins/defaults/memory/{v3/substrate → substrate}/prompts/sweep.ts

@@ -1,5 +1,8 @@
 /**
- * Memory v2 — sweep prompt template.
+ * Memory substrate — sweep prompt template.
+ *
+ * Shared by the v2 injection engine and memory-v3; active whenever
+ * `usesConceptPageMemory()` holds.
  *
  * Body taken from §9 of the design doc (`memoized-spinning-wadler.md`). The
  * template uses two placeholders that the sweep job substitutes at runtime: