@vellumai/assistant 0.6.2 → 0.6.3

package/src/config/bundled-skills/outlook/SKILL.md

@@ -35,6 +35,13 @@ When the user mentions "email" - sending, reading, checking, decluttering, draft
 
 Do not offer AgentMail as an option or mention it unless the user specifically asks. If Outlook is not connected, guide them through Outlook setup - do not suggest AgentMail as an alternative.
 
+## Connection Setup
+
+### Outlook
+
+1. **Try connecting directly first.** Run `assistant oauth status outlook`. This will show whether or not the user had previously connected their Outlook/Microsoft account. If so, they are ready to go.
+2. **If no connections are found:** Call `skill_load` with `skill: "vellum-oauth-integrations"`. The skill will evaluate whether managed or your-own mode is appropriate and guide the user accordingly.
+
 ## Communication Style
 
 - **Be action-oriented.** When the user asks to do something ("declutter", "check my email"), start doing it immediately. Don't ask for permission to read their inbox - that's obviously what they want.

package/src/config/bundled-skills/subagent/SKILL.md

@@ -63,6 +63,24 @@ Only the parent conversation that spawned a subagent can interact with it (check
 
 Set `send_result_to_user: false` when spawning a subagent whose result is for internal processing only. The parent will still be notified on completion, but the notification will instruct it to read the result without presenting it to the user.
 
+## Fork Mode
+
+Forks are sub-agents that inherit the parent's full context -- messages, system prompt, and memory -- sharing the KV cache for near-free context inheritance. Use forks when the task benefits from knowing what you've been discussing; use a regular sub-agent when the task is self-contained.
+
+**Key behaviors:** Forks always run as `general` role (the `role` parameter is ignored). `send_result_to_user` defaults to `false`. Read fork output with `last_n: 1` to get only the final synthesis.
+
+**When to fork vs regular sub-agent:**
+
+| Task | Mode |
+|---|---|
+| Single tool call (one search, one file read) | Direct -- don't spawn at all |
+| Multi-page web research needing conversation context | Fork |
+| Exploratory file search informed by prior discussion | Fork |
+| Comparing multiple sources against what was discussed | Parallel forks |
+| Self-contained task with a clear objective | Regular sub-agent |
+
+Rule of thumb: "Does this task need to know what we've been talking about?" If yes, fork. If the objective is fully self-describing, use a regular sub-agent with a scoped role.
+
 ## Tips
 
 - Do NOT poll `subagent_status` in a loop. You will be notified automatically when a subagent completes.
@@ -71,3 +89,6 @@ Set `send_result_to_user: false` when spawning a subagent whose result is for in
 - Use `notify_parent` for interim findings instead of waiting for completion. This lets the parent act on partial results early.
 - Use `subagent_message` to send follow-up instructions to a running subagent.
 - Use `subagent_abort` to cancel a subagent that is no longer needed.
+- Default to spawning subagents for any task that involves web research, multi-file exploration, or independent coding work. Serial execution should be the exception, not the rule.
+- When a user request has both an information-gathering component and an action component, spawn a researcher immediately rather than doing the research inline yourself.
+- Prefer spawning 2-3 focused subagents over one large general-purpose subagent. Smaller scopes finish faster and fail more gracefully.

package/src/config/bundled-skills/subagent/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "subagent_spawn",
-      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.",
+      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.\n\nTwo modes:\n- **Regular sub-agent** (fork: false or omitted): Gets only the objective + context fields. Use for self-contained tasks with clear objectives. Can use scoped roles (researcher, coder, planner).\n- **Fork** (fork: true): Inherits full parent context (messages, system prompt, memory). Shares KV cache for near-free context inheritance. Use when the task benefits from knowing what you've been discussing. Always runs as general role. Results are internal by default (send_result_to_user: false). Read with last_n: 1 to get only the final synthesis.\n\nDecision heuristic: Does the task need to know what we've been talking about? Fork. Is it self-contained? Regular sub-agent.",
       "category": "orchestration",
       "risk": "low",
       "input_schema": {
@@ -19,16 +19,20 @@
           },
           "context": {
             "type": "string",
-            "description": "Optional additional context to pass to the subagent"
+            "description": "Optional additional context to pass to the subagent. Ignored when fork is true — forks inherit the parent's full context."
+          },
+          "fork": {
+            "type": "boolean",
+            "description": "When true, the subagent inherits the parent's full context (messages, system prompt, memory) instead of receiving only the objective + context fields. Fork mode always runs as 'general' role (the role parameter is ignored) and defaults send_result_to_user to false. Use for tasks that benefit from the full conversational context."
           },
           "send_result_to_user": {
             "type": "boolean",
-            "description": "Whether to present the subagent's result to the user when it completes. Defaults to true. Set to false for internal/silent processing."
+            "description": "Whether to present the subagent's result to the user when it completes. Defaults to true for regular sub-agents, false for forks. Set explicitly to override."
           },
           "role": {
             "type": "string",
             "enum": ["general", "researcher", "coder", "planner"],
-            "description": "Agent specialization that controls tool access. 'researcher': read-only (web, files, memory). 'coder': file and bash access. 'planner': read-only analysis. 'general': full access (default)."
+            "description": "Agent specialization that controls tool access. 'researcher': read-only (web, files, memory). 'coder': file and bash access. 'planner': read-only analysis. 'general': full access (default). Ignored when fork: true (forks always use general)."
           },
           "activity": {
             "type": "string",

package/src/config/bundled-skills/tasks/SKILL.md

@@ -6,6 +6,11 @@ metadata:
   emoji: "✅"
   vellum:
     display-name: "Tasks"
+    activation-hints:
+      - "User wants to add, check, or manage items on their to-do list or task queue"
+      - "For one-off action items, not recurring automations (use schedule for those)"
+    avoid-when:
+      - "User wants recurring/scheduled automation — use the schedule skill instead"
 ---
 
 Two-layer task system: **task templates** (reusable definitions with input placeholders) and **work items** (instances in the Task Queue with priority tiers and status tracking).

package/src/config/env-registry.ts

@@ -86,6 +86,17 @@ export function getWorkspaceDirOverride(): string | undefined {
 // profiler mode. The runtime uses them to locate, scope, and budget-limit
 // profiler output on the workspace volume.
 
+/**
+ * VELLUM_CPU_LIMIT — string (K8s resource format), default: undefined
+ * The CPU resource limit for the container (e.g. "2000m", "2").
+ * Set by the platform StatefulSet template to the exact K8s CPU limit.
+ * Used by the health endpoint to report accurate CPU core count inside
+ * gVisor sandboxes where cgroup files may expose the host node's CPUs.
+ */
+export function getCpuLimit(): string | undefined {
+  return str("VELLUM_CPU_LIMIT");
+}
+
 /**
  * VELLUM_PROFILER_RUN_ID — string, default: undefined
  * Unique identifier for the current profiler run. When set, the profiler
@@ -148,6 +159,7 @@ const KNOWN_VELLUM_VARS = new Set([
   "VELLUM_DATA_DIR",
   "VELLUM_DESKTOP_APP",
   "VELLUM_DEV",
+  "VELLUM_DOCS_BASE_URL",
   "VELLUM_ENABLE_INSECURE_LAN_PAIRING",
   "VELLUM_HATCHED_BY",
   "VELLUM_HOOK_EVENT",
@@ -164,6 +176,8 @@ const KNOWN_VELLUM_VARS = new Set([
   "VELLUM_SSH_USER",
   "VELLUM_UNSAFE_AUTH_BYPASS",
   "VELLUM_WORKSPACE_DIR",
+  "VELLUM_CPU_LIMIT",
+  "VELLUM_MEMORY_LIMIT",
 ]);
 
 /**

package/src/config/env.ts

@@ -164,6 +164,27 @@ export function getPlatformBaseUrl(): string {
   );
 }
 
+/**
+ * Derive the assistant service domain from the platform base URL.
+ *
+ * - `dev-platform.vellum.ai`  → `dev.vellum.me`
+ * - `platform.vellum.ai`      → `vellum.me`
+ * - anything else              → `vellum.me` (safe default)
+ */
+export function getAssistantDomain(): string {
+  try {
+    const url = getPlatformBaseUrl();
+    const host = new URL(url).hostname;
+    const prefix = host.replace(/[-.]?platform\.vellum\.ai$/, "");
+    if (prefix) {
+      return `${prefix}.vellum.me`;
+    }
+  } catch {
+    // Fall through to default
+  }
+  return "vellum.me";
+}
+
 let _platformAssistantIdOverride: string | undefined;
 
 export function setPlatformAssistantId(value: string | undefined): void {

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

@@ -178,11 +178,11 @@
       "defaultEnabled": false
     },
     {
-      "id": "settings-integrations-grid",
+      "id": "multi-platform-assistant",
       "scope": "assistant",
-      "key": "settings-integrations-grid",
-      "label": "Integrations Grid",
-      "description": "Show the Integrations grid in Models & Services settings, replacing individual OAuth provider cards",
+      "key": "multi-platform-assistant",
+      "label": "Multi-Platform Assistant Switcher",
+      "description": "Enable the menu-bar assistant switcher for managing multiple platform-hosted assistants (new/switch/retire)",
       "defaultEnabled": false
     },
     {
@@ -288,7 +288,46 @@
       "label": "Permission Controls V2",
       "description": "Replace risk-level permission system with two independent controls: 'Ask before acting' (LLM behavior toggle) and 'Host access' (system-enforced gate)",
       "defaultEnabled": false
+    },
+    {
+      "id": "apple-container",
+      "scope": "macos",
+      "key": "apple-container",
+      "label": "Apple Container",
+      "description": "Enable assistant sandboxing via Apple Containers on macOS 26+, providing a lightweight native sandbox without third-party dependencies",
+      "defaultEnabled": false
+    },
+    {
+      "id": "tool-result-truncation",
+      "scope": "assistant",
+      "key": "tool-result-truncation",
+      "label": "Post-Turn Tool Result Truncation",
+      "description": "Truncate large tool results after each assistant turn, persisting full content to disk for on-demand re-reads",
+      "defaultEnabled": false
+    },
+    {
+      "id": "managed-gemini-embeddings-enabled",
+      "scope": "assistant",
+      "key": "managed-gemini-embeddings-enabled",
+      "label": "Managed Gemini Embeddings Enabled",
+      "description": "Route embedding requests through the platform runtime proxy using Vellum-managed Gemini credentials when available",
+      "defaultEnabled": false
+    },
+    {
+      "id": "fork-from-message",
+      "scope": "macos",
+      "key": "fork-from-message",
+      "label": "Fork from Message",
+      "description": "Show the 'Fork from here' option in message overflow menus",
+      "defaultEnabled": false
+    },
+    {
+      "id": "fork-from-message",
+      "scope": "macos",
+      "key": "fork-from-message",
+      "label": "Fork from Message",
+      "description": "Show the Fork from here option in message overflow menus",
+      "defaultEnabled": false
     }
   ]
 }
-

package/src/config/loader.ts

@@ -11,6 +11,7 @@ import { dirname, join } from "node:path";
 import { ConfigError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
 import { ensureDataDir, getWorkspaceConfigPath } from "../util/platform.js";
+import { isAssistantFeatureFlagEnabled } from "./assistant-feature-flags.js";
 import { AssistantConfigSchema } from "./schema.js";
 import type { AssistantConfig } from "./types.js";
 
@@ -385,7 +386,46 @@ export function loadConfig(): AssistantConfig {
     warnAndStripDeprecatedFields(fileConfig, configPath);
 
     // Validate and apply defaults via Zod schema
-    const config = validateWithSchema(fileConfig);
+    let config = validateWithSchema(fileConfig);
+
+    // Managed Gemini embedding defaults migration.
+    // When on a managed platform (IS_PLATFORM=true) with the feature flag
+    // enabled and no explicit embedding provider chosen (provider=auto),
+    // persist Gemini embedding defaults into the raw config file.
+    // Idempotent: once provider=gemini is written, subsequent loads skip this.
+    if (config.memory.embeddings.provider === "auto") {
+      try {
+        if (
+          (process.env.IS_PLATFORM === "true" ||
+            process.env.IS_PLATFORM === "1") &&
+          isManagedGeminiFFEnabled(config)
+        ) {
+          setNestedValue(fileConfig, "memory.embeddings.provider", "gemini");
+          setNestedValue(
+            fileConfig,
+            "memory.embeddings.geminiModel",
+            "gemini-embedding-2-preview",
+          );
+          setNestedValue(
+            fileConfig,
+            "memory.embeddings.geminiDimensions",
+            3072,
+          );
+          setNestedValue(fileConfig, "memory.qdrant.vectorSize", 3072);
+          writeFileSync(configPath, JSON.stringify(fileConfig, null, 2) + "\n");
+          log.info(
+            "Applied managed Gemini embedding defaults (provider=gemini, model=gemini-embedding-2-preview, dimensions=3072, vectorSize=3072)",
+          );
+          // Re-validate so the returned config reflects the migration.
+          config = validateWithSchema(fileConfig);
+        }
+      } catch (err) {
+        log.warn(
+          { err },
+          "Managed Gemini defaults migration failed — continuing with existing config",
+        );
+      }
+    }
 
     // If the config file didn't exist, write the full defaults to disk so
     // users can discover and edit all available options.
@@ -421,6 +461,21 @@ export function loadConfig(): AssistantConfig {
   }
 }
 
+/**
+ * Check whether the managed-gemini-embeddings-enabled feature flag is on.
+ * Wrapped in a try/catch so a flag-resolver failure never breaks config loading.
+ */
+function isManagedGeminiFFEnabled(config: AssistantConfig): boolean {
+  try {
+    return isAssistantFeatureFlagEnabled(
+      "managed-gemini-embeddings-enabled",
+      config,
+    );
+  } catch {
+    return false;
+  }
+}
+
 export function saveConfig(config: AssistantConfig): void {
   ensureMigratedDataDir();
   const configPath = getConfigPath();

package/src/config/sanitize-for-transfer.ts

@@ -0,0 +1,47 @@
+/**
+ * Strips environment-specific fields from config JSON before transferring
+ * between local and platform environments (teleport/restore).
+ *
+ * Fields removed or reset:
+ * - `ingress.publicBaseUrl` → set to `""`
+ * - `ingress.enabled` → deleted
+ * - `daemon` → deleted entirely
+ * - `skills.load.extraDirs` → set to `[]`
+ */
+export function sanitizeConfigForTransfer(configJson: string): string {
+  let config: Record<string, unknown>;
+  try {
+    const parsed = JSON.parse(configJson);
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      Array.isArray(parsed)
+    ) {
+      return configJson;
+    }
+    config = parsed;
+  } catch {
+    return configJson;
+  }
+
+  // Strip ingress environment-specific fields
+  if (config.ingress && typeof config.ingress === "object") {
+    const ingress = config.ingress as Record<string, unknown>;
+    ingress.publicBaseUrl = "";
+    delete ingress.enabled;
+  }
+
+  // Strip daemon entirely
+  delete config.daemon;
+
+  // Strip skills.load.extraDirs
+  if (config.skills && typeof config.skills === "object") {
+    const skills = config.skills as Record<string, unknown>;
+    if (skills.load && typeof skills.load === "object") {
+      const load = skills.load as Record<string, unknown>;
+      load.extraDirs = [];
+    }
+  }
+
+  return JSON.stringify(config, null, 2) + "\n";
+}

package/src/config/schema.ts

@@ -49,6 +49,14 @@ export type { FishAudioConfig } from "./schemas/fish-audio.js";
 export { FishAudioConfigSchema } from "./schemas/fish-audio.js";
 export type { HeartbeatConfig } from "./schemas/heartbeat.js";
 export { HeartbeatConfigSchema } from "./schemas/heartbeat.js";
+export type {
+  HostBrowserCdpInspectConfig,
+  HostBrowserConfig,
+} from "./schemas/host-browser.js";
+export {
+  HostBrowserCdpInspectConfigSchema,
+  HostBrowserConfigSchema,
+} from "./schemas/host-browser.js";
 export type {
   ContextOverflowRecoveryConfig,
   ContextWindowConfig,
@@ -115,6 +123,7 @@ export {
 export type { MemoryRetrievalConfig } from "./schemas/memory-retrieval.js";
 export {
   MemoryDynamicBudgetConfigSchema,
+  MemoryInjectionConfigSchema,
   MemoryRetrievalConfigSchema,
 } from "./schemas/memory-retrieval.js";
 export type {
@@ -139,8 +148,6 @@ export {
   PlatformConfigSchema,
   UiConfigSchema,
 } from "./schemas/platform.js";
-export type { SandboxConfig } from "./schemas/sandbox.js";
-export { SandboxConfigSchema } from "./schemas/sandbox.js";
 export type {
   PermissionsConfig,
   SecretDetectionConfig,
@@ -206,6 +213,7 @@ import { ElevenLabsConfigSchema } from "./schemas/elevenlabs.js";
 import { FilingConfigSchema } from "./schemas/filing.js";
 import { FishAudioConfigSchema } from "./schemas/fish-audio.js";
 import { HeartbeatConfigSchema } from "./schemas/heartbeat.js";
+import { HostBrowserConfigSchema } from "./schemas/host-browser.js";
 import {
   ContextWindowConfigSchema,
   EffortSchema,
@@ -227,7 +235,6 @@ import {
   PlatformConfigSchema,
   UiConfigSchema,
 } from "./schemas/platform.js";
-import { SandboxConfigSchema } from "./schemas/sandbox.js";
 import {
   PermissionsConfigSchema,
   SecretDetectionConfigSchema,
@@ -247,7 +254,7 @@ export const AssistantConfigSchema = z
       .number({ error: "maxTokens must be a number" })
       .int("maxTokens must be an integer")
       .positive("maxTokens must be a positive integer")
-      .default(16000)
+      .default(64000)
       .describe("Maximum number of output tokens per LLM response"),
     effort: EffortSchema,
     speed: SpeedSchema,
@@ -261,7 +268,6 @@ export const AssistantConfigSchema = z
       .default(getDataDir())
       .describe("Directory for storing assistant data (database, logs, etc.)"),
     timeouts: TimeoutConfigSchema.default(TimeoutConfigSchema.parse({})),
-    sandbox: SandboxConfigSchema.default(SandboxConfigSchema.parse({})),
     rateLimit: RateLimitConfigSchema.default(RateLimitConfigSchema.parse({})),
     secretDetection: SecretDetectionConfigSchema.default(
       SecretDetectionConfigSchema.parse({}),
@@ -281,6 +287,9 @@ export const AssistantConfigSchema = z
       ),
     filing: FilingConfigSchema.default(FilingConfigSchema.parse({})),
     heartbeat: HeartbeatConfigSchema.default(HeartbeatConfigSchema.parse({})),
+    hostBrowser: HostBrowserConfigSchema.default(
+      HostBrowserConfigSchema.parse({}),
+    ),
     journal: JournalConfigSchema.default(JournalConfigSchema.parse({})),
     mcp: McpConfigSchema.default(McpConfigSchema.parse({})),
     acp: AcpConfigSchema.default(AcpConfigSchema.parse({})),
@@ -321,6 +330,13 @@ export const AssistantConfigSchema = z
       .max(200, "maxStepsPerSession must be <= 200")
       .default(50)
       .describe("Maximum number of computer-use steps per session"),
+    systemPromptPrefix: z
+      .string({ error: "systemPromptPrefix must be a string" })
+      .nullable()
+      .default(null)
+      .describe(
+        "Custom text injected at the very beginning of the system prompt. Defaults to null (no injection).",
+      ),
   })
   .superRefine((config, ctx) => {
     if (
@@ -373,6 +389,31 @@ export const AssistantConfigSchema = z
           "memory.retrieval.dynamicBudget.minInjectTokens must be <= memory.retrieval.dynamicBudget.maxInjectTokens",
       });
     }
+    const injection = config.memory?.retrieval?.injection;
+    const ctxLoad = injection?.contextLoad;
+    if (
+      ctxLoad &&
+      ctxLoad.capabilityReserve + ctxLoad.serendipitySlots >= ctxLoad.maxNodes
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["memory", "retrieval", "injection", "contextLoad"],
+        message:
+          "memory.retrieval.injection.contextLoad.capabilityReserve + serendipitySlots must be less than maxNodes",
+      });
+    }
+    const perTurn = injection?.perTurn;
+    if (
+      perTurn &&
+      perTurn.capabilityReserve + perTurn.serendipitySlots >= perTurn.maxNodes
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["memory", "retrieval", "injection", "perTurn"],
+        message:
+          "memory.retrieval.injection.perTurn.capabilityReserve + serendipitySlots must be less than maxNodes",
+      });
+    }
   });
 
 export type AssistantConfig = z.infer<typeof AssistantConfigSchema>;

package/src/config/schemas/host-browser.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+
+/**
+ * Configuration for the `cdp-inspect` browser backend — connects directly
+ * to a host Chrome instance that was launched with `--remote-debugging-port`
+ * (e.g. `chrome://inspect`-style remote debugging) as an alternative to the
+ * extension or local Playwright backend.
+ */
+export const HostBrowserCdpInspectConfigSchema = z
+  .object({
+    enabled: z
+      .boolean({ error: "hostBrowser.cdpInspect.enabled must be a boolean" })
+      .default(false)
+      .describe(
+        "Whether the cdp-inspect backend is enabled. When true, the factory will route browser tool calls through the configured host/port instead of the local Playwright backend.",
+      ),
+    host: z
+      .string({ error: "hostBrowser.cdpInspect.host must be a string" })
+      .min(1, "hostBrowser.cdpInspect.host must not be empty")
+      .default("localhost")
+      .describe(
+        "Host name or IP address where the host Chrome instance exposes its remote debugging endpoint.",
+      ),
+    port: z
+      .number({ error: "hostBrowser.cdpInspect.port must be a number" })
+      .int("hostBrowser.cdpInspect.port must be an integer")
+      .min(1, "hostBrowser.cdpInspect.port must be >= 1")
+      .max(65535, "hostBrowser.cdpInspect.port must be <= 65535")
+      .default(9222)
+      .describe(
+        "TCP port for the host Chrome remote-debugging endpoint (matches `--remote-debugging-port`).",
+      ),
+    probeTimeoutMs: z
+      .number({
+        error: "hostBrowser.cdpInspect.probeTimeoutMs must be a number",
+      })
+      .int("hostBrowser.cdpInspect.probeTimeoutMs must be an integer")
+      .min(50, "hostBrowser.cdpInspect.probeTimeoutMs must be >= 50")
+      .max(5000, "hostBrowser.cdpInspect.probeTimeoutMs must be <= 5000")
+      .default(500)
+      .describe(
+        "Timeout (in milliseconds) for the backend availability probe. Kept small so browser tool calls fail fast when the endpoint is unreachable.",
+      ),
+  })
+  .describe(
+    "Settings for the cdp-inspect backend that connects to a host Chrome instance via its remote-debugging endpoint.",
+  );
+
+export type HostBrowserCdpInspectConfig = z.infer<
+  typeof HostBrowserCdpInspectConfigSchema
+>;
+
+/**
+ * Top-level configuration for host-browser backends. Currently only exposes
+ * `cdpInspect`, but the shape leaves room for additional host-browser knobs
+ * (e.g. extension-specific settings) without another namespace churn.
+ */
+export const HostBrowserConfigSchema = z
+  .object({
+    cdpInspect: HostBrowserCdpInspectConfigSchema.default(
+      HostBrowserCdpInspectConfigSchema.parse({}),
+    ),
+  })
+  .describe("Host-browser backend configuration (cdp-inspect, etc.)");
+
+export type HostBrowserConfig = z.infer<typeof HostBrowserConfigSchema>;

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

@@ -80,7 +80,7 @@ export const MemoryCleanupConfigSchema = z
       .nonnegative(
         "memory.cleanup.llmRequestLogRetentionMs must be non-negative",
       )
-      .default(7 * 24 * 60 * 60 * 1000)
+      .default(1 * 24 * 60 * 60 * 1000)
       .describe(
         "Retention period for LLM request/response logs in milliseconds (0 disables pruning)",
       ),

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

@@ -184,6 +184,106 @@ const MemoryFreshnessConfigSchema = z
     "Freshness-based ranking for memory retrieval — down-ranks old items unless recently reinforced",
   );
 
+const MemoryContextLoadInjectionSchema = z
+  .object({
+    maxNodes: z
+      .number({
+        error:
+          "memory.retrieval.injection.contextLoad.maxNodes must be a number",
+      })
+      .int("memory.retrieval.injection.contextLoad.maxNodes must be an integer")
+      .positive(
+        "memory.retrieval.injection.contextLoad.maxNodes must be a positive integer",
+      )
+      .default(25)
+      .describe("Maximum number of memory nodes to load at conversation start"),
+    serendipitySlots: z
+      .number({
+        error:
+          "memory.retrieval.injection.contextLoad.serendipitySlots must be a number",
+      })
+      .int(
+        "memory.retrieval.injection.contextLoad.serendipitySlots must be an integer",
+      )
+      .nonnegative(
+        "memory.retrieval.injection.contextLoad.serendipitySlots must be non-negative",
+      )
+      .default(5)
+      .describe("Number of random wildcard memory picks at conversation start"),
+    capabilityReserve: z
+      .number({
+        error:
+          "memory.retrieval.injection.contextLoad.capabilityReserve must be a number",
+      })
+      .int(
+        "memory.retrieval.injection.contextLoad.capabilityReserve must be an integer",
+      )
+      .nonnegative(
+        "memory.retrieval.injection.contextLoad.capabilityReserve must be non-negative",
+      )
+      .default(5)
+      .describe(
+        "Reserved slots for skill/CLI capability nodes at conversation start",
+      ),
+  })
+  .describe("Memory injection limits at conversation start");
+
+const MemoryPerTurnInjectionSchema = z
+  .object({
+    maxNodes: z
+      .number({
+        error: "memory.retrieval.injection.perTurn.maxNodes must be a number",
+      })
+      .int("memory.retrieval.injection.perTurn.maxNodes must be an integer")
+      .positive(
+        "memory.retrieval.injection.perTurn.maxNodes must be a positive integer",
+      )
+      .default(6)
+      .describe(
+        "Maximum total memory nodes injected per turn (general + capability + serendipity)",
+      ),
+    serendipitySlots: z
+      .number({
+        error:
+          "memory.retrieval.injection.perTurn.serendipitySlots must be a number",
+      })
+      .int(
+        "memory.retrieval.injection.perTurn.serendipitySlots must be an integer",
+      )
+      .nonnegative(
+        "memory.retrieval.injection.perTurn.serendipitySlots must be non-negative",
+      )
+      .default(1)
+      .describe("Number of random wildcard memory picks per turn"),
+    capabilityReserve: z
+      .number({
+        error:
+          "memory.retrieval.injection.perTurn.capabilityReserve must be a number",
+      })
+      .int(
+        "memory.retrieval.injection.perTurn.capabilityReserve must be an integer",
+      )
+      .nonnegative(
+        "memory.retrieval.injection.perTurn.capabilityReserve must be non-negative",
+      )
+      .default(2)
+      .describe("Reserved slots for skill/CLI capability nodes per turn"),
+  })
+  .describe("Memory injection limits for mid-conversation turns");
+
+export const MemoryInjectionConfigSchema = z
+  .object({
+    contextLoad: MemoryContextLoadInjectionSchema.default(
+      MemoryContextLoadInjectionSchema.parse({}),
+    ),
+    perTurn: MemoryPerTurnInjectionSchema.default(
+      MemoryPerTurnInjectionSchema.parse({}),
+    ),
+  })
+  .describe(
+    "Controls how many memory items are injected at conversation start and per turn",
+  );
+
 export const MemoryRetrievalConfigSchema = z
   .object({
     maxInjectTokens: z
@@ -209,6 +309,9 @@ export const MemoryRetrievalConfigSchema = z
     dynamicBudget: MemoryDynamicBudgetConfigSchema.default(
       MemoryDynamicBudgetConfigSchema.parse({}),
     ),
+    injection: MemoryInjectionConfigSchema.default(
+      MemoryInjectionConfigSchema.parse({}),
+    ),
   })
   .describe(
     "Controls how memories are retrieved and injected into conversations",