@vellumai/assistant 0.8.4 → 0.8.5

package/src/config/bundled-skills/playbooks/tools/playbook-update.ts

@@ -2,7 +2,10 @@ import { and, eq, sql } from "drizzle-orm";
 
 import { getDb } from "../../../../memory/db-connection.js";
 import { getNode, updateNode } from "../../../../memory/graph/store.js";
-import { enqueueMemoryJob } from "../../../../memory/jobs-store.js";
+import {
+  enqueueMemoryJob,
+  isMemoryEnabled,
+} from "../../../../memory/jobs-store.js";
 import { memoryGraphNodes } from "../../../../memory/schema.js";
 import type {
   Playbook,
@@ -123,7 +126,9 @@ export async function executePlaybookUpdate(
       lastAccessed: Date.now(),
     });
 
-    enqueueMemoryJob("embed_graph_node", { nodeId: existing.id });
+    if (isMemoryEnabled()) {
+      enqueueMemoryJob("embed_graph_node", { nodeId: existing.id });
+    }
 
     const autonomyLabel =
       updated.autonomyLevel === "auto"

package/src/config/bundled-tool-registry.ts

@@ -58,6 +58,7 @@ import * as documentCreate from "./bundled-skills/document-editor/tools/document
 import * as documentDelete from "./bundled-skills/document-editor/tools/document-delete.js";
 import * as documentFind from "./bundled-skills/document-editor/tools/document-find.js";
 import * as documentList from "./bundled-skills/document-editor/tools/document-list.js";
+import * as documentOpen from "./bundled-skills/document-editor/tools/document-open.js";
 import * as documentRead from "./bundled-skills/document-editor/tools/document-read.js";
 import * as documentReplaceText from "./bundled-skills/document-editor/tools/document-replace-text.js";
 import * as documentUpdate from "./bundled-skills/document-editor/tools/document-update.js";
@@ -175,6 +176,7 @@ export const bundledToolRegistry = new Map<string, SkillToolScript>([
   ["contacts:tools/google-contacts.ts", googleContacts],
 
   // document-editor
+  ["document-editor:tools/document-open.ts", documentOpen],
   ["document-editor:tools/document-create.ts", documentCreate],
   ["document-editor:tools/document-update.ts", documentUpdate],
   ["document-editor:tools/document-read.ts", documentRead],

package/src/config/call-site-defaults.ts

@@ -47,6 +47,13 @@ export const CALL_SITE_DEFAULTS: Record<LLMCallSite, CallSiteDefaultConfig> = {
   memoryV2Migration: { profile: "cost-optimized" },
   memoryV2Sweep: { profile: "cost-optimized" },
   memoryV2Consolidation: { profile: "balanced" },
+  // memory v3: cheap filter + descent, capable gate. All three are
+  // selection/classification calls, not generation — pin temperature to 0 so
+  // the same candidate set yields the same keep/descend/select decision instead
+  // of sampling-driven variance.
+  memoryV3Filter: { profile: "cost-optimized", temperature: 0 },
+  memoryV3Descent: { profile: "cost-optimized", temperature: 0 },
+  memoryV3Gate: { profile: "balanced", temperature: 0 },
   conversationSummarization: { profile: "cost-optimized" },
   conversationTitle: { profile: "cost-optimized" },
   approvalCopy: { profile: "cost-optimized" },
@@ -115,10 +122,4 @@ export const CALL_SITE_DEFAULTS: Record<LLMCallSite, CallSiteDefaultConfig> = {
     effort: "low",
     thinking: { enabled: false },
   },
-  queryComplexityRouter: {
-    profile: "cost-optimized",
-    maxTokens: 16,
-    effort: "low",
-    thinking: { enabled: false },
-  },
 };

package/src/config/feature-flag-registry.json

@@ -393,6 +393,14 @@
       "description": "Enable the Notifications tab in settings.",
       "defaultEnabled": false
     },
+    {
+      "id": "preview-channel",
+      "scope": "client",
+      "key": "preview-channel",
+      "label": "Preview Channel",
+      "description": "Enable user-facing Preview release channel controls in assistant settings.",
+      "defaultEnabled": false
+    },
     {
       "id": "rollback-enabled",
       "scope": "assistant",
@@ -424,6 +432,14 @@
       "label": "Velvet",
       "description": "Enable the Velvet design theme.",
       "defaultEnabled": false
+    },
+    {
+      "id": "memory-router-playground",
+      "scope": "client",
+      "key": "memory-router-playground",
+      "label": "Memory Router Playground",
+      "description": "Expose the developer-only Memory Router Playground tab in macOS Settings and the /assistant/memory-router-playground web page for dry-running v4 router config overrides against the live page index. Dev-only; default off.",
+      "defaultEnabled": false
     }
   ]
 }

package/src/config/schemas/__tests__/memory-v2.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
 import { MemoryConfigSchema } from "../memory.js";
-import { MemoryV2ConfigSchema } from "../memory-v2.js";
+import { MemoryV2ConfigSchema, MemoryV3ConfigSchema } from "../memory-v2.js";
 
 describe("MemoryV2ConfigSchema", () => {
   test("parses an empty object to documented defaults", () => {
@@ -40,6 +40,8 @@ describe("MemoryV2ConfigSchema", () => {
         batch_size: null,
         tier1_size: null,
         tier2_size: null,
+        historical_pairs: 1,
+        historical_pairs_max_chars: null,
       },
     });
   });
@@ -210,6 +212,216 @@ describe("MemoryV2ConfigSchema", () => {
   });
 });
 
+describe("MemoryV3ConfigSchema", () => {
+  test("parses an empty object to documented defaults", () => {
+    const parsed = MemoryV3ConfigSchema.parse({});
+    expect(parsed).toEqual({
+      enabled: false,
+      shadow: false,
+      passCap: 3,
+      breadthBudget: 6,
+      maxDepth: 6,
+      denseQuota: { activeDomain: 30, offDomain: 8 },
+      hotLimit: 50,
+      lanes: { hot: true, sparse: true, dense: true, tree: true, edges: true },
+      ks: [5, 10, 25, 50],
+      write: {
+        enabled: false,
+        consolidateIntervalMs: 3600000,
+        coactivation: false,
+      },
+      prompts: {
+        filter: { override: null, path: null },
+        descent: { override: null, path: null },
+        gate: { override: null, path: null },
+      },
+      gateCandidateSummaries: false,
+    });
+  });
+
+  test("parses undefined to the same defaults (top-level .default)", () => {
+    expect(MemoryV3ConfigSchema.parse(undefined)).toEqual(
+      MemoryV3ConfigSchema.parse({}),
+    );
+  });
+
+  test("defaults to disabled for backwards compatibility", () => {
+    expect(MemoryV3ConfigSchema.parse({}).enabled).toBe(false);
+    expect(MemoryV3ConfigSchema.parse({}).shadow).toBe(false);
+  });
+
+  test("accepts explicit scalar overrides", () => {
+    const parsed = MemoryV3ConfigSchema.parse({
+      enabled: true,
+      shadow: true,
+      passCap: 5,
+      breadthBudget: 10,
+      maxDepth: 8,
+    });
+    expect(parsed.enabled).toBe(true);
+    expect(parsed.shadow).toBe(true);
+    expect(parsed.passCap).toBe(5);
+    expect(parsed.breadthBudget).toBe(10);
+    expect(parsed.maxDepth).toBe(8);
+  });
+
+  test("accepts explicit denseQuota override", () => {
+    const parsed = MemoryV3ConfigSchema.parse({
+      denseQuota: { activeDomain: 50, offDomain: 12 },
+    });
+    expect(parsed.denseQuota).toEqual({ activeDomain: 50, offDomain: 12 });
+  });
+
+  test("accepts a partial lanes override and defaults the rest", () => {
+    const parsed = MemoryV3ConfigSchema.parse({ lanes: { dense: false } });
+    expect(parsed.lanes).toEqual({
+      hot: true,
+      sparse: true,
+      dense: false,
+      tree: true,
+      edges: true,
+    });
+  });
+
+  test("accepts an explicit ks override", () => {
+    const parsed = MemoryV3ConfigSchema.parse({ ks: [1, 3, 7] });
+    expect(parsed.ks).toEqual([1, 3, 7]);
+  });
+
+  test("rejects a non-boolean enabled", () => {
+    expect(() => MemoryV3ConfigSchema.parse({ enabled: "yes" })).toThrow();
+  });
+
+  test("rejects a non-integer passCap", () => {
+    expect(() => MemoryV3ConfigSchema.parse({ passCap: 2.5 })).toThrow();
+  });
+
+  test("rejects non-number ks entries", () => {
+    expect(() => MemoryV3ConfigSchema.parse({ ks: ["a"] })).toThrow();
+  });
+
+  test("parses the write subtree to safe off defaults when omitted", () => {
+    const parsed = MemoryV3ConfigSchema.parse({});
+    expect(parsed.write).toEqual({
+      enabled: false,
+      consolidateIntervalMs: 3600000,
+      coactivation: false,
+    });
+  });
+
+  test("accepts a partial write override and defaults the rest", () => {
+    const parsed = MemoryV3ConfigSchema.parse({ write: { enabled: true } });
+    expect(parsed.write).toEqual({
+      enabled: true,
+      consolidateIntervalMs: 3600000,
+      coactivation: false,
+    });
+  });
+
+  test("rejects a non-integer write.consolidateIntervalMs", () => {
+    expect(() =>
+      MemoryV3ConfigSchema.parse({ write: { consolidateIntervalMs: 1.5 } }),
+    ).toThrow();
+  });
+
+  test("rejects a non-positive write.consolidateIntervalMs", () => {
+    // 0 or negative would make the scheduler's `now - lastRun >= interval`
+    // check always true, flooding the queue with consolidation jobs.
+    expect(() =>
+      MemoryV3ConfigSchema.parse({ write: { consolidateIntervalMs: 0 } }),
+    ).toThrow();
+    expect(() =>
+      MemoryV3ConfigSchema.parse({ write: { consolidateIntervalMs: -1000 } }),
+    ).toThrow();
+  });
+
+  test("accepts a positive write.consolidateIntervalMs override", () => {
+    const parsed = MemoryV3ConfigSchema.parse({
+      write: { consolidateIntervalMs: 1800000 },
+    });
+    expect(parsed.write.consolidateIntervalMs).toBe(1800000);
+  });
+
+  test("parses the prompts subtree to null overrides when omitted", () => {
+    const parsed = MemoryV3ConfigSchema.parse({});
+    expect(parsed.prompts).toEqual({
+      filter: { override: null, path: null },
+      descent: { override: null, path: null },
+      gate: { override: null, path: null },
+    });
+  });
+
+  test("accepts a partial prompts override and defaults the rest", () => {
+    const parsed = MemoryV3ConfigSchema.parse({
+      prompts: { filter: { override: "custom filter prompt" } },
+    });
+    expect(parsed.prompts.filter).toEqual({
+      override: "custom filter prompt",
+      path: null,
+    });
+    // Lanes not mentioned keep their null defaults.
+    expect(parsed.prompts.descent).toEqual({ override: null, path: null });
+    expect(parsed.prompts.gate).toEqual({ override: null, path: null });
+  });
+
+  test("accepts a file path override for a prompt lane", () => {
+    const parsed = MemoryV3ConfigSchema.parse({
+      prompts: { gate: { path: "~/prompts/v3-gate.md" } },
+    });
+    expect(parsed.prompts.gate).toEqual({
+      override: null,
+      path: "~/prompts/v3-gate.md",
+    });
+  });
+
+  test("rejects a non-string prompts override", () => {
+    expect(() =>
+      MemoryV3ConfigSchema.parse({ prompts: { filter: { override: 42 } } }),
+    ).toThrow();
+  });
+
+  test("rejects a non-string prompts path", () => {
+    expect(() =>
+      MemoryV3ConfigSchema.parse({ prompts: { descent: { path: 7 } } }),
+    ).toThrow();
+  });
+});
+
+describe("MemoryConfigSchema integration with v3 block", () => {
+  test("includes a v3 block defaulting to disabled when v3 is omitted", () => {
+    const parsed = MemoryConfigSchema.parse({});
+    expect(parsed.v3).toBeDefined();
+    expect(parsed.v3.enabled).toBe(false);
+    expect(parsed.v3.shadow).toBe(false);
+    expect(parsed.v3.passCap).toBe(3);
+    expect(parsed.v3.lanes.dense).toBe(true);
+    expect(parsed.v3.ks).toEqual([5, 10, 25, 50]);
+    expect(parsed.v3.write).toEqual({
+      enabled: false,
+      consolidateIntervalMs: 3600000,
+      coactivation: false,
+    });
+  });
+
+  test("leaves pre-existing configs (no v3 key) otherwise unchanged", () => {
+    // A config authored before v3 existed parses fine and its v2 block is
+    // untouched; the v3 block is purely additive.
+    const parsed = MemoryConfigSchema.parse({ v2: { top_k: 50 } });
+    expect(parsed.v2.top_k).toBe(50);
+    expect(parsed.v3.enabled).toBe(false);
+  });
+
+  test("propagates v3 overrides through MemoryConfigSchema", () => {
+    const parsed = MemoryConfigSchema.parse({
+      v3: { enabled: true, passCap: 4 },
+    });
+    expect(parsed.v3.enabled).toBe(true);
+    expect(parsed.v3.passCap).toBe(4);
+    // Non-overridden v3 fields keep their defaults.
+    expect(parsed.v3.maxDepth).toBe(6);
+  });
+});
+
 describe("MemoryConfigSchema integration with v2 block", () => {
   test("parses an empty memory config and includes a v2 block with defaults", () => {
     const parsed = MemoryConfigSchema.parse({});

package/src/config/schemas/call-site-catalog.ts

@@ -121,6 +121,27 @@ const CATALOG_RECORD: CatalogRecord = {
       "Selects which concept pages to inject for the next agent turn by routing over a cached page index.",
     domain: "memory",
   },
+  memoryV3Filter: {
+    id: "memoryV3Filter",
+    displayName: "Memory V3 Filter",
+    description:
+      "Cheaply filters the V3 multi-lane candidate set before descent.",
+    domain: "memory",
+  },
+  memoryV3Descent: {
+    id: "memoryV3Descent",
+    displayName: "Memory V3 Descent",
+    description:
+      "Drives the V3 bounded-descent traversal through the memory tree.",
+    domain: "memory",
+  },
+  memoryV3Gate: {
+    id: "memoryV3Gate",
+    displayName: "Memory V3 Gate",
+    description:
+      "Final capable gate that decides which V3 candidates are injected for the next turn.",
+    domain: "memory",
+  },
   memoryV2Consolidation: {
     id: "memoryV2Consolidation",
     displayName: "Memory V2 Consolidation",
@@ -314,13 +335,6 @@ const CATALOG_RECORD: CatalogRecord = {
       "Generates contextual conversation-starter suggestions for the Home page.",
     domain: "ui",
   },
-  queryComplexityRouter: {
-    id: "queryComplexityRouter",
-    displayName: "Query Complexity Router",
-    description:
-      "Classifies user message complexity to route to the appropriate inference profile.",
-    domain: "agentLoop",
-  },
 };
 
 // Source of truth for call-site display metadata. API responses and usage

package/src/config/schemas/llm.ts

@@ -49,6 +49,9 @@ export const LLMCallSiteEnum = z.enum([
   "memoryV2Migration",
   "memoryV2Sweep",
   "memoryRouter",
+  "memoryV3Filter",
+  "memoryV3Descent",
+  "memoryV3Gate",
   "memoryV2Consolidation",
   "memoryRetrospective",
   "recall",
@@ -78,7 +81,6 @@ export const LLMCallSiteEnum = z.enum([
   "proactiveArtifactBuild",
   "homeGreeting",
   "homeSuggestedPrompts",
-  "queryComplexityRouter",
 ]);
 export type LLMCallSite = z.infer<typeof LLMCallSiteEnum>;
 
@@ -152,10 +154,18 @@ const TemperatureSchema = z.number().min(0).max(2).nullable();
 // defaulted (`ThinkingSchema`) and fragment (`ThinkingFragmentSchema`) views.
 const ThinkingEnabledSchema = z.boolean();
 const ThinkingStreamThinkingSchema = z.boolean();
+// Gemini-style thinking depth knob. Maps to Gemini's `thinkingLevel`. Other
+// providers (Anthropic, OpenRouter) ignore this field — they use `effort`
+// instead to size reasoning. Optional with no default so the underlying
+// provider can pick its own default (Gemini 3.x defaults to "medium").
+export const THINKING_LEVELS = ["minimal", "low", "medium", "high"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+const ThinkingLevelSchema = z.enum(THINKING_LEVELS);
 
 const ThinkingSchema = z.object({
   enabled: ThinkingEnabledSchema.default(true),
   streamThinking: ThinkingStreamThinkingSchema.default(true),
+  level: ThinkingLevelSchema.optional(),
 });
 
 // Fragment view: every field optional, no defaults injected. Defining this
@@ -165,6 +175,7 @@ const ThinkingSchema = z.object({
 const ThinkingFragmentSchema = z.object({
   enabled: ThinkingEnabledSchema.optional(),
   streamThinking: ThinkingStreamThinkingSchema.optional(),
+  level: ThinkingLevelSchema.optional(),
 });
 
 // Leaf primitives for context-overflow recovery.

package/src/config/schemas/memory-v2.ts

@@ -322,6 +322,23 @@ export const MemoryV2ConfigSchema = z
           .describe(
             "Pool size for the tier-2 'useful' batch. `null` (default) disables tier 2 — pages skip straight from tier 1 to tier 3. When set, the top-M pages by injection-frequency EMA (excluding tier 1) become their own parallel batch ordered by score desc. Pages with score 0 (never selected since EMA tracking began) are ineligible for tier 2 and stay in tier 3 regardless of `tier2_size`. Score is the time-decayed sum `Σ exp(-λ(now - tᵢ))` with 3-day half-life, computed on read from `memory_v2_injection_events`.",
           ),
+        historical_pairs: z
+          .number()
+          .int()
+          .min(1)
+          .default(1)
+          .describe(
+            "Number of recent (assistant, user) turn pairs to render inside the router prompt's `<last_turn>` block. Each pair is the assistant's reply followed by the user message that came after; the most recent pair's user line is the just-arrived turn that triggered the router. `1` (default) shows only the prior assistant reply plus the current user message — bit-identical to pre-knob behavior. Higher values walk further back through conversation history to give the router more dialogue context at the cost of larger per-turn prompt size. Pairs are emitted in chronological order (oldest first).",
+          ),
+        historical_pairs_max_chars: z
+          .number()
+          .int()
+          .min(1)
+          .nullable()
+          .default(null)
+          .describe(
+            "Optional character cap on the total message content rendered inside `<last_turn>`. `null` (default) means no limit — every message inside the configured `historical_pairs` window is included verbatim. When set, the router walks the assembled pairs newest-first; messages are included until the budget is exhausted, at which point the oldest still-includable message is front-truncated with a leading `…` marker. Older pairs whose content does not fit are dropped entirely. The cap counts message content only — framing characters (`[assistant]: `, `[user]: `, newlines) are not deducted from the budget. Set this when raising `historical_pairs` on workspaces with long messages so the router prompt stays bounded.",
+          ),
       })
       .default({
         enabled: true,
@@ -330,6 +347,8 @@ export const MemoryV2ConfigSchema = z
         batch_size: null,
         tier1_size: null,
         tier2_size: null,
+        historical_pairs: 1,
+        historical_pairs_max_chars: null,
       })
       .describe(
         "LLM router configuration. When enabled, a single router LLM call replaces spreading activation for per-turn page selection.",
@@ -369,3 +388,230 @@ export const MemoryV2ConfigSchema = z
   });
 
 export type MemoryV2Config = z.infer<typeof MemoryV2ConfigSchema>;
+
+/**
+ * Per-lane system-prompt override for a v3 LLM call site. `override` is an
+ * inline prompt string (highest precedence); `path` points at a file whose
+ * contents replace the bundled prompt. Both default to `null` (use the bundled
+ * prompt). Shared by the filter, descent, and gate entries under
+ * `memory.v3.prompts`. The whole object is `.default(...)`-wrapped so an
+ * omitted lane parses to `{ override: null, path: null }`.
+ */
+const V3PromptOverrideSchema = z
+  .object({
+    override: z
+      .string({ error: "memory.v3.prompts.*.override must be a string" })
+      .nullable()
+      .default(null)
+      .describe(
+        "Optional inline system-prompt string that replaces the bundled prompt for this lane. Takes precedence over `path`. An empty or whitespace-only string is ignored (falls back to `path` / bundled).",
+      ),
+    path: z
+      .string({ error: "memory.v3.prompts.*.path must be a string" })
+      .nullable()
+      .default(null)
+      .describe(
+        "Optional path to a file whose contents replace the bundled prompt for this lane. Absolute paths are used as-is, a leading `~/` expands to the home directory, otherwise the path resolves under the workspace root. If the file is missing, unreadable, or empty, the bundled prompt is used and a warning is logged.",
+      ),
+  })
+  .default({ override: null, path: null });
+
+/**
+ * Memory v3 (multi-lane, bounded-descent retrieval) configuration.
+ *
+ * Additive scaffolding only — defaults to `enabled: false` so existing
+ * configs are untouched and the v3 retrieval loop stays inert until later
+ * PRs wire it up. Every field carries a default and the whole block is
+ * `.default(...)`-wrapped so a config that omits `memory.v3` entirely still
+ * parses to these documented defaults.
+ */
+export const MemoryV3ConfigSchema = z
+  .object({
+    enabled: z
+      .boolean({ error: "memory.v3.enabled must be a boolean" })
+      .default(false)
+      .describe(
+        "Whether the v3 memory subsystem (multi-lane bounded-descent retrieval) is enabled. Off by default until the v3 loop is wired up.",
+      ),
+    shadow: z
+      .boolean({ error: "memory.v3.shadow must be a boolean" })
+      .default(false)
+      .describe(
+        "Live-shadow toggle: when on, the v3 retrieval loop runs alongside the active path for comparison without affecting injected context. Consumed by a later PR.",
+      ),
+    passCap: z
+      .number({ error: "memory.v3.passCap must be a number" })
+      .int("memory.v3.passCap must be an integer")
+      .default(3)
+      .describe(
+        "Maximum number of retrieval passes (router → descent rounds) the v3 loop may run per turn.",
+      ),
+    breadthBudget: z
+      .number({ error: "memory.v3.breadthBudget must be a number" })
+      .int("memory.v3.breadthBudget must be an integer")
+      .default(6)
+      .describe(
+        "Per-pass breadth budget — the number of frontier candidates the v3 loop may expand at each step.",
+      ),
+    maxDepth: z
+      .number({ error: "memory.v3.maxDepth must be a number" })
+      .int("memory.v3.maxDepth must be an integer")
+      .default(6)
+      .describe(
+        "Maximum descent depth the v3 loop traverses through the memory tree before stopping.",
+      ),
+    denseQuota: z
+      .object({
+        activeDomain: z
+          .number({
+            error: "memory.v3.denseQuota.activeDomain must be a number",
+          })
+          .describe(
+            "Dense-lane candidate quota allocated to the conversation's active domain.",
+          ),
+        offDomain: z
+          .number({ error: "memory.v3.denseQuota.offDomain must be a number" })
+          .describe(
+            "Dense-lane candidate quota allocated to off-domain (exploratory) retrieval.",
+          ),
+      })
+      .default({ activeDomain: 30, offDomain: 8 })
+      .describe(
+        "Dense-lane candidate quotas split between the active domain and off-domain exploration.",
+      ),
+    hotLimit: z
+      .number({ error: "memory.v3.hotLimit must be a number" })
+      .int("memory.v3.hotLimit must be an integer")
+      .positive("memory.v3.hotLimit must be positive")
+      .default(50)
+      .describe(
+        "Top-N cap on the hot scout lane, ranked by injection-frequency EMA. Hot hits are sticky (kept past the gate), so this bounds how many always-on pages the lane forces into the selection. Without a cap a mature corpus — where nearly every page has been injected at some point — surfaces the entire corpus.",
+      ),
+    lanes: z
+      .object({
+        hot: z
+          .boolean()
+          .default(true)
+          .describe("Whether the hot (recently-touched) retrieval lane is on."),
+        sparse: z
+          .boolean()
+          .default(true)
+          .describe("Whether the sparse (BM25-style keyword) lane is on."),
+        dense: z
+          .boolean()
+          .default(true)
+          .describe("Whether the dense (embedding-similarity) lane is on."),
+        tree: z
+          .boolean()
+          .default(true)
+          .describe("Whether the tree (hierarchical descent) lane is on."),
+        edges: z
+          .boolean()
+          .default(true)
+          .describe("Whether the edges (graph-adjacency) lane is on."),
+      })
+      .default({
+        hot: true,
+        sparse: true,
+        dense: true,
+        tree: true,
+        edges: true,
+      })
+      .describe(
+        "Per-lane on/off toggles for the v3 multi-lane retrieval fanout. All lanes on by default.",
+      ),
+    ks: z
+      .array(z.number({ error: "memory.v3.ks entries must be numbers" }))
+      .default([5, 10, 25, 50])
+      .describe(
+        "Evaluation top-K cutoffs the v3 loop reports metrics at (e.g. recall@K).",
+      ),
+    write: z
+      .object({
+        enabled: z
+          .boolean({ error: "memory.v3.write.enabled must be a boolean" })
+          .default(false)
+          .describe(
+            "Whether v3 consolidation owns the shared-buffer drain + tree build. Off by default — v2 consolidation stays the sole buffer-drainer. Does NOT introduce a separate buffer.",
+          ),
+        consolidateIntervalMs: z
+          .number({
+            error: "memory.v3.write.consolidateIntervalMs must be a number",
+          })
+          .int("memory.v3.write.consolidateIntervalMs must be an integer")
+          .positive("memory.v3.write.consolidateIntervalMs must be positive")
+          .default(3600000)
+          .describe(
+            "Interval, in milliseconds, between scheduled v3 consolidation runs once the v3 write path owns the drain. Default 1 hour.",
+          ),
+        coactivation: z
+          .boolean({ error: "memory.v3.write.coactivation must be a boolean" })
+          .default(false)
+          .describe(
+            "Whether v3 consolidation learns co-activation edges during the tree build. Off by default; consumed by a later PR.",
+          ),
+      })
+      .default({
+        enabled: false,
+        consolidateIntervalMs: 3600000,
+        coactivation: false,
+      })
+      .describe(
+        "Memory v3 write-path configuration. All default-off scaffolding — controls whether v3 consolidation owns the shared-buffer drain + tree build. Consumed by later PRs.",
+      ),
+    prompts: z
+      .object({
+        filter: V3PromptOverrideSchema.describe(
+          "Override for the dense-hit filter lane's system prompt.",
+        ),
+        descent: V3PromptOverrideSchema.describe(
+          "Override for the tree-walk descent driver's system prompt.",
+        ),
+        gate: V3PromptOverrideSchema.describe(
+          "Override for the selection gate's system prompt.",
+        ),
+      })
+      .default({
+        filter: { override: null, path: null },
+        descent: { override: null, path: null },
+        gate: { override: null, path: null },
+      })
+      .describe(
+        "Per-lane system-prompt overrides for the three v3 LLM call sites (filter, descent, gate). Each entry takes an inline `override` string (highest precedence) and/or a file `path` whose contents replace the bundled prompt; absolute paths are used as-is, a leading `~/` expands to the home directory, otherwise the path resolves under the workspace root. An empty/whitespace inline override or a missing/unreadable/empty file falls back to the bundled prompt. Lets the prompts be iterated at runtime without a rebuild/restart — mirroring `memory.v2.router.router_prompt_path`.",
+      ),
+    gateCandidateSummaries: z
+      .boolean({
+        error: "memory.v3.gateCandidateSummaries must be a boolean",
+      })
+      .default(false)
+      .describe(
+        "When true, the selection gate sees each candidate as `slug — summary` instead of the bare slug, so it can judge relevance on page content. Off by default: with the bundled (precision-leaning) gate prompt this makes the gate more selective. It pays off paired with a recall-leaning gate prompt override, where the summaries let the gate recognize non-obvious associative/emotional matches it would otherwise pass over. Adds the candidate summaries to the gate prompt (larger input).",
+      ),
+  })
+  .default({
+    enabled: false,
+    shadow: false,
+    passCap: 3,
+    breadthBudget: 6,
+    maxDepth: 6,
+    denseQuota: { activeDomain: 30, offDomain: 8 },
+    hotLimit: 50,
+    lanes: { hot: true, sparse: true, dense: true, tree: true, edges: true },
+    ks: [5, 10, 25, 50],
+    write: {
+      enabled: false,
+      consolidateIntervalMs: 3600000,
+      coactivation: false,
+    },
+    prompts: {
+      filter: { override: null, path: null },
+      descent: { override: null, path: null },
+      gate: { override: null, path: null },
+    },
+    gateCandidateSummaries: false,
+  })
+  .describe(
+    "Memory v3 — multi-lane bounded-descent retrieval. Additive scaffolding, disabled by default.",
+  );
+
+export type MemoryV3Config = z.infer<typeof MemoryV3ConfigSchema>;