@vellumai/assistant 0.8.3 → 0.8.5

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", () => {
@@ -23,6 +23,7 @@ describe("MemoryV2ConfigSchema", () => {
       bm25_k1: 1.2,
       bm25_b: 0.4,
       consolidation_interval_hours: 4,
+      consolidation_max_buffer_lines: 100,
       max_page_chars: 5000,
       consolidation_prompt_path: null,
       rerank: {
@@ -36,6 +37,11 @@ describe("MemoryV2ConfigSchema", () => {
         enabled: true,
         max_page_ids: 25,
         router_prompt_path: null,
+        batch_size: null,
+        tier1_size: null,
+        tier2_size: null,
+        historical_pairs: 1,
+        historical_pairs_max_chars: null,
       },
     });
   });
@@ -206,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",
@@ -300,6 +321,20 @@ const CATALOG_RECORD: CatalogRecord = {
       "Builds the personalized artifact in a background conversation with tool access.",
     domain: "agentLoop",
   },
+  homeGreeting: {
+    id: "homeGreeting",
+    displayName: "Home Greeting",
+    description:
+      "Generates the personalized greeting shown on the Home page in the assistant's tone/persona.",
+    domain: "ui",
+  },
+  homeSuggestedPrompts: {
+    id: "homeSuggestedPrompts",
+    displayName: "Home Suggested Prompts",
+    description:
+      "Generates contextual conversation-starter suggestions for the Home page.",
+    domain: "ui",
+  },
 };
 
 // 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",
@@ -76,6 +79,8 @@ export const LLMCallSiteEnum = z.enum([
   "trustRuleSuggestion",
   "proactiveArtifactDecision",
   "proactiveArtifactBuild",
+  "homeGreeting",
+  "homeSuggestedPrompts",
 ]);
 export type LLMCallSite = z.infer<typeof LLMCallSiteEnum>;
 
@@ -149,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
@@ -162,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

@@ -194,6 +194,19 @@ export const MemoryV2ConfigSchema = z
       .describe(
         "Hours between scheduled consolidation runs that synthesize buffered memories into concept pages",
       ),
+    consolidation_max_buffer_lines: z
+      .number({
+        error: "memory.v2.consolidation_max_buffer_lines must be a number",
+      })
+      .int("memory.v2.consolidation_max_buffer_lines must be an integer")
+      .positive(
+        "memory.v2.consolidation_max_buffer_lines must be a positive integer",
+      )
+      .nullable()
+      .default(100)
+      .describe(
+        "Size-based trigger for consolidation. When `memory/buffer.md` reaches this many non-empty lines, consolidation runs even if the time-based interval hasn't elapsed. Defaults to 100. Set to `null` to disable the size trigger and rely solely on `consolidation_interval_hours`.",
+      ),
     max_page_chars: z
       .number({ error: "memory.v2.max_page_chars must be a number" })
       .int("memory.v2.max_page_chars must be an integer")
@@ -282,8 +295,61 @@ export const MemoryV2ConfigSchema = z
           .describe(
             "Optional path to a file whose contents replace the bundled router prompt. Absolute paths are used as-is, a leading `~/` is expanded to the home directory, otherwise the path is resolved under the workspace root. The loaded contents may include `{{ASSISTANT_NAME}}`, `{{USER_NAME}}`, and `{{PAGE_INDEX}}`, which are substituted at runtime. If the file is missing, unreadable, or empty, the bundled prompt is used and a warning is logged.",
           ),
+        batch_size: z
+          .number()
+          .int()
+          .min(1)
+          .nullable()
+          .default(null)
+          .describe(
+            "Target batch size for parallel page-index routing. `null` (default) sends the entire page index in one call — identical to v3 behavior. When set, pages are split into `ceil(N / batch_size)` batches by stable FNV-1a hash on slug (so adding/removing a single page only invalidates one batch's KV cache), routed in parallel, and the selected slugs are unioned. A failure in one batch does not abort the turn as long as at least one batch succeeds.",
+          ),
+        tier1_size: z
+          .number()
+          .int()
+          .min(1)
+          .nullable()
+          .default(null)
+          .describe(
+            "Pool size for the tier-1 'recently modified' batch. `null` (default) disables tier 1 entirely — all pages flow through tier 3 batching. When set, the top-N concept pages by file mtime become their own dedicated parallel batch with mtime-desc ordering; everything else is partitioned into tier 3 batches by `batch_size`. Synthetic entries (skills, CLI commands) have mtime=0 and naturally rank below real concept pages so they don't crowd tier 1.",
+          ),
+        tier2_size: z
+          .number()
+          .int()
+          .min(1)
+          .nullable()
+          .default(null)
+          .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,
+        max_page_ids: 25,
+        router_prompt_path: null,
+        batch_size: null,
+        tier1_size: null,
+        tier2_size: null,
+        historical_pairs: 1,
+        historical_pairs_max_chars: null,
       })
-      .default({ enabled: true, max_page_ids: 25, router_prompt_path: null })
       .describe(
         "LLM router configuration. When enabled, a single router LLM call replaces spreading activation for per-turn page selection.",
       ),
@@ -322,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>;

package/src/config/schemas/memory.ts

@@ -16,7 +16,7 @@ import {
   MemorySegmentationConfigSchema,
   QdrantConfigSchema,
 } from "./memory-storage.js";
-import { MemoryV2ConfigSchema } from "./memory-v2.js";
+import { MemoryV2ConfigSchema, MemoryV3ConfigSchema } from "./memory-v2.js";
 
 export const MemoryConfigSchema = z
   .object({
@@ -50,6 +50,7 @@ export const MemoryConfigSchema = z
       MemorySummarizationConfigSchema.parse({}),
     ),
     v2: MemoryV2ConfigSchema.default(MemoryV2ConfigSchema.parse({})),
+    v3: MemoryV3ConfigSchema.default(MemoryV3ConfigSchema.parse({})),
     retrospective: MemoryRetrospectiveConfigSchema.default(
       MemoryRetrospectiveConfigSchema.parse({}),
     ),