@vellumai/assistant 0.7.3 → 0.8.1

package/src/memory/v2/injection.ts

@@ -40,6 +40,7 @@ import {
 import { hydrate, save } from "./activation-store.js";
 import { getEdgeIndex } from "./edge-index.js";
 import { readPage, renderPageContent } from "./page-store.js";
+import { runRouter } from "./router.js";
 import { getSkillCapability, isSkillSlug } from "./skill-store.js";
 import type { ActivationState, EverInjectedEntry } from "./types.js";
 
@@ -58,6 +59,16 @@ const log = getLogger("memory-v2-injection");
  */
 export type InjectMemoryV2Mode = "context-load" | "per-turn";
 
+/**
+ * Internal mode union for `finalizeInjection`. Extends the public
+ * `InjectMemoryV2Mode` with `"router"` (router-driven success path) and
+ * `"errored"` (caller-supplied failure path or the helper's own
+ * try/catch promotion). The public surface intentionally only carries
+ * the caller-facing modes — these two are persistence/telemetry concerns
+ * that don't belong on `InjectMemoryV2BlockParams`.
+ */
+type FinalizeInjectionMode = InjectMemoryV2Mode | "router" | "errored";
+
 export interface InjectMemoryV2BlockParams {
   /** SQLite database handle for activation_state hydrate/save. */
   database: DrizzleDb;
@@ -94,8 +105,12 @@ export interface InjectMemoryV2BlockResult {
    */
   block: string | null;
   /**
-   * Slugs that were freshly attached on this turn. Empty when `block` is
-   * null. Returned for telemetry / debug logging by the call site.
+   * Slugs we attempted to attach this turn (top-K minus everInjected).
+   * Always populated even when `block` is `null` — phantom slugs whose
+   * backing page is missing on disk land here and are recorded in
+   * `everInjected` so we don't infinite-retry next turn. Callers using
+   * this for "we injected N slugs" telemetry should cross-reference
+   * `block !== null` (or the activation log's `page_missing` status).
    */
   toInject: string[];
 }
@@ -135,6 +150,27 @@ export async function injectMemoryV2Block(
   throwIfAborted(signal);
   const priorState = await hydrate(database, conversationId);
 
+  // Flag-gated router dispatch: when the LLM router is enabled, route the
+  // per-turn page selection through `runRouter` and reuse `finalizeInjection`
+  // for persistence, render, and telemetry. The activation pipeline below
+  // remains the default (flag-off) behavior — every code path past this
+  // branch only runs when the router is disabled.
+  if (config.memory.v2.router.enabled) {
+    return injectViaRouter({
+      workspaceDir,
+      database,
+      conversationId,
+      currentTurn,
+      userMessage,
+      assistantMessage,
+      nowText,
+      messageId,
+      config,
+      priorState,
+      signal,
+    });
+  }
+
   // (2) Topology. `getEdgeIndex` walks concept-page frontmatter and caches
   // the result module-locally; an empty workspace yields an empty index.
   throwIfAborted(signal);
@@ -178,7 +214,7 @@ export async function injectMemoryV2Block(
   // prior cached attachments don't exist or have been thrown away. The user
   // message gets a complete top-K dump alongside the static
   // essentials/threads/recent block, then per-turn turns just add deltas.
-  const mode = params.mode ?? "per-turn";
+  const mode: InjectMemoryV2Mode = params.mode ?? "per-turn";
   const priorEverInjected: readonly EverInjectedEntry[] =
     priorState?.everInjected ?? [];
   const { topNow, toInject } = selectInjections({
@@ -192,11 +228,108 @@ export async function injectMemoryV2Block(
   // even on a "no new injection" turn, prior-state activations decay via the
   // candidate-set carry-forward and need to be rewritten so `epsilon`-trimmed
   // slugs drop out of consideration next turn.
-  const nextState: Record<string, number> = {};
+  const nextStateMap: Record<string, number> = {};
   for (const [slug, value] of finalActivation) {
-    if (value > epsilon) nextState[slug] = value;
+    if (value > epsilon) nextStateMap[slug] = value;
   }
 
+  // Build the rich per-candidate telemetry rows up front (status assigned
+  // later by `finalizeInjection` once we know what actually rendered).
+  const telemetryRows: MemoryV2ConceptRowRecord[] = [...candidates].map(
+    (slug) => {
+      const breakdown = ownBreakdown.get(slug);
+      const inPrior = fromPrior.has(slug);
+      const inAnn = fromAnn.has(slug);
+      return {
+        slug,
+        finalActivation: finalActivation.get(slug) ?? 0,
+        ownActivation: ownActivation.get(slug) ?? 0,
+        priorActivation: breakdown?.priorContribution ?? 0,
+        simUser: breakdown?.simUser ?? 0,
+        simAssistant: breakdown?.simAssistant ?? 0,
+        simNow: breakdown?.simNow ?? 0,
+        simUserRerankBoost: breakdown?.simUserRerankBoost ?? 0,
+        simAssistantRerankBoost: breakdown?.simAssistantRerankBoost ?? 0,
+        inRerankPool: breakdown?.inRerankPool ?? false,
+        spreadContribution: spreadContribution.get(slug) ?? 0,
+        source:
+          inPrior && inAnn ? "both" : inPrior ? "prior_state" : "ann_top50",
+        status: "not_injected",
+      };
+    },
+  );
+
+  return finalizeInjection({
+    workspaceDir,
+    database,
+    conversationId,
+    mode,
+    currentTurn,
+    messageId,
+    priorEverInjected,
+    slugsToRender,
+    telemetryRows,
+    config,
+    nextStateMap,
+  });
+}
+
+/**
+ * Tail of `injectMemoryV2Block` extracted as a private helper so the
+ * router branch (PR 10) can reuse the same persistence + render +
+ * telemetry-finalization pipeline. Performs:
+ *
+ *   1. Build `nextEverInjected` from `slugsToRender`, filtering out skill
+ *      slugs whose capability cache entry is missing so future turns
+ *      re-attempt attachment once the cache is populated.
+ *   2. Persist the next activation_state row.
+ *   3. Render the injection block.
+ *   4. Finalize per-row `status` (`injected | in_context | not_injected |
+ *      page_missing | corrupt`) on the caller-provided telemetry rows
+ *      using the render result.
+ *   5. Sort rows by `finalActivation` descending and flush the activation
+ *      log — even when an error is thrown partway through, so silent
+ *      failures remain observable.
+ *   6. Return the rendered block plus `toInject = newlyInjected`.
+ *
+ * The caller pre-builds `telemetryRows` with all per-candidate breakdown
+ * fields filled in (router-mode callers can pass zeros where the
+ * breakdown doesn't apply) and a placeholder `status: "not_injected"`
+ * which this helper overwrites. `nextStateMap` is the activation
+ * pipeline's sparse next-state; router-mode callers pass an empty map.
+ */
+async function finalizeInjection(args: {
+  workspaceDir: string;
+  database: DrizzleDb;
+  conversationId: string;
+  mode: FinalizeInjectionMode;
+  currentTurn: number;
+  messageId: string;
+  priorEverInjected: readonly EverInjectedEntry[];
+  slugsToRender: string[];
+  telemetryRows: MemoryV2ConceptRowRecord[];
+  config: AssistantConfig;
+  nextStateMap: Record<string, number>;
+}): Promise<InjectMemoryV2BlockResult> {
+  const {
+    workspaceDir,
+    database,
+    conversationId,
+    currentTurn,
+    messageId,
+    priorEverInjected,
+    slugsToRender,
+    telemetryRows,
+    config,
+    nextStateMap,
+  } = args;
+
+  // `mode` is `let` because the trailing try/finally promotes it to "errored"
+  // when the render/telemetry path throws — we still want a log row written
+  // (with whatever rows we managed to build) so silent failures are
+  // observable in the database.
+  let mode: FinalizeInjectionMode = args.mode;
+
   // Mark every rendered slug as ever-injected so future per-turn deltas don't
   // re-attach the same content. On context-load this is the full top-K (we
   // just rendered all of them); on per-turn it's just the newly added slugs.
@@ -206,9 +339,21 @@ export async function injectMemoryV2Block(
   // like concept slugs — once attached on a turn, the cached attachment lives
   // on that user message and the agent keeps seeing it across subsequent turns
   // until compaction evicts the turn.
+  //
+  // Skill slugs whose in-process cache entry is missing (e.g. startup race
+  // between the skill seed and the first turn, or stale Qdrant index pointing
+  // at an uninstalled skill) are excluded from `everInjected` so future
+  // per-turn runs re-attempt attachment once the cache is populated. Without
+  // this, the slug would be marked injected even though `renderInjectionBlock`
+  // silently dropped it.
+  const missingSkillSlugs = new Set(
+    slugsToRender.filter(
+      (slug) => isSkillSlug(slug) && !getSkillCapability(slug),
+    ),
+  );
   const everInjectedSet = new Set(priorEverInjected.map((entry) => entry.slug));
   const newlyInjected = slugsToRender.filter(
-    (slug) => !everInjectedSet.has(slug),
+    (slug) => !everInjectedSet.has(slug) && !missingSkillSlugs.has(slug),
   );
   const nextEverInjected: EverInjectedEntry[] = [
     ...priorEverInjected,
@@ -217,62 +362,76 @@ export async function injectMemoryV2Block(
 
   const nextActivationState: ActivationState = {
     messageId,
-    state: nextState,
+    state: nextStateMap,
     everInjected: nextEverInjected,
     currentTurn,
     updatedAt: Date.now(),
   };
 
-  await save(database, conversationId, nextActivationState);
+  // `block` and `conceptRowsForLog` are declared outside the try so the
+  // finally block can flush activation telemetry even if rendering, status
+  // finalization, or the activation-state save throws partway through.
+  // Without this, a Zod failure on a single concept page (e.g. unrecognized
+  // frontmatter key) silently dropped the entire turn's activation log row,
+  // masking the underlying data-corruption bug.
+  //
+  // `conceptRowsForLog` only receives the caller-provided `telemetryRows`
+  // *after* status finalization succeeds — matching the prior behavior where
+  // an early `save()` / `renderInjectionBlock()` throw produced an empty
+  // `concepts` array on the log row.
+  let block: string | null = null;
+  let conceptRowsForLog: MemoryV2ConceptRowRecord[] = [];
+  let caughtErr: unknown = undefined;
 
-  // Render before recording telemetry so the activation log can mark slugs
-  // whose backing file is gone — those are no-op renders that would otherwise
-  // be indistinguishable from successful "injected" rows in the log.
-  // `renderInjectionBlock` itself short-circuits on empty inputs.
-  const { block, missingSlugs } = await renderInjectionBlock(
-    workspaceDir,
-    slugsToRender,
-  );
-  const missingSlugSet = new Set(missingSlugs);
-  if (missingSlugs.length > 0) {
-    log.warn(
-      {
-        conversationId,
-        turn: currentTurn,
-        missingSlugs,
-        renderedCount: slugsToRender.length - missingSlugs.length,
-      },
-      "Memory v2 injection skipped slugs whose page was missing on disk — Qdrant index may be stale; consider reembed",
-    );
-  }
+  try {
+    await save(database, conversationId, nextActivationState);
+
+    // Render before recording telemetry so the activation log can mark slugs
+    // whose backing file is gone or failed to load — those are no-op renders
+    // that would otherwise be indistinguishable from successful "injected"
+    // rows in the log. `renderInjectionBlock` itself short-circuits on empty
+    // inputs and emits per-slug `log.warn` for each corrupt page.
+    const rendered = await renderInjectionBlock(workspaceDir, slugsToRender);
+    block = rendered.block;
+    const { missingSlugs, corruptSlugs } = rendered;
+    const missingSlugSet = new Set(missingSlugs);
+    const corruptSlugSet = new Set(corruptSlugs);
+    if (missingSlugs.length > 0) {
+      log.warn(
+        {
+          conversationId,
+          turn: currentTurn,
+          missingSlugs,
+          renderedCount:
+            slugsToRender.length - missingSlugs.length - corruptSlugs.length,
+        },
+        "Memory v2 injection skipped slugs whose page was missing on disk — Qdrant index may be stale; consider reembed",
+      );
+    }
 
-  // Record per-turn activation telemetry. Failures are warn-logged and never
-  // block memory injection.
-  const toInjectSet = new Set(toInject);
-  const renderedSet = new Set(slugsToRender);
-  const conceptRows: MemoryV2ConceptRowRecord[] = [...candidates].map(
-    (slug) => {
-      const breakdown = ownBreakdown.get(slug);
-      const inPrior = fromPrior.has(slug);
-      const inAnn = fromAnn.has(slug);
-      // Status reflects what was rendered for *this* turn:
-      //   - context-load: cache was wiped (turn 1 / post-compaction), so
-      //     `slugsToRender = topNow` and every rendered slug is freshly
-      //     injected on this turn. `in_context` is unreachable because there
-      //     is no prior cached attachment for the inspector to point at.
-      //   - per-turn: cached attachments from prior turns are still on the
-      //     user message, so prior-everInjected slugs are `in_context` and
-      //     the delta (`toInject`) is `injected`.
-      // `page_missing` overrides any "would-have-been-injected" status when
-      // `readPage` returned null for the slug — telemetry surfaces stale
-      // ANN/edge entries instead of silently masquerading as a successful
-      // injection.
+    // Finalize per-row status onto the caller-provided telemetry rows.
+    //   - context-load: cache was wiped (turn 1 / post-compaction), so
+    //     `slugsToRender = topNow` and every rendered slug is freshly
+    //     injected on this turn. `in_context` is unreachable because there
+    //     is no prior cached attachment for the inspector to point at.
+    //   - per-turn: cached attachments from prior turns are still on the
+    //     user message, so prior-everInjected slugs are `in_context` and
+    //     the delta (`slugsToRender`, which equals `toInject` in this mode)
+    //     is `injected`.
+    // `page_missing` and `corrupt` override any "would-have-been-injected"
+    // status when `readPage` returned null or threw — telemetry surfaces
+    // stale ANN/edge entries and malformed pages instead of silently
+    // masquerading as successful injections. `corrupt` takes priority over
+    // `page_missing` since they're mutually exclusive per slug.
+    const renderedSet = new Set(slugsToRender);
+    for (const row of telemetryRows) {
+      const slug = row.slug;
       let status: MemoryV2ConceptRowRecord["status"];
       if (mode === "context-load") {
         status = renderedSet.has(slug) ? "injected" : "not_injected";
       } else if (everInjectedSet.has(slug)) {
         status = "in_context";
-      } else if (toInjectSet.has(slug)) {
+      } else if (renderedSet.has(slug)) {
         status = "injected";
       } else {
         status = "not_injected";
@@ -280,52 +439,195 @@ export async function injectMemoryV2Block(
       if (status === "injected" && missingSlugSet.has(slug)) {
         status = "page_missing";
       }
-      return {
-        slug,
-        finalActivation: finalActivation.get(slug) ?? 0,
-        ownActivation: ownActivation.get(slug) ?? 0,
-        priorActivation: breakdown?.priorContribution ?? 0,
-        simUser: breakdown?.simUser ?? 0,
-        simAssistant: breakdown?.simAssistant ?? 0,
-        simNow: breakdown?.simNow ?? 0,
-        simUserRerankBoost: breakdown?.simUserRerankBoost ?? 0,
-        simAssistantRerankBoost: breakdown?.simAssistantRerankBoost ?? 0,
-        inRerankPool: breakdown?.inRerankPool ?? false,
-        spreadContribution: spreadContribution.get(slug) ?? 0,
-        source:
-          inPrior && inAnn ? "both" : inPrior ? "prior_state" : "ann_top50",
-        status,
-      };
-    },
-  );
-  conceptRows.sort((a, b) => b.finalActivation - a.finalActivation);
-
-  const v2Cfg = config.memory.v2;
-  try {
-    recordMemoryV2ActivationLog({
-      conversationId,
-      turn: currentTurn,
-      mode,
-      concepts: conceptRows,
-      config: {
-        d: v2Cfg.d,
-        c_user: v2Cfg.c_user,
-        c_assistant: v2Cfg.c_assistant,
-        c_now: v2Cfg.c_now,
-        k: v2Cfg.k,
-        hops: v2Cfg.hops,
-        top_k: v2Cfg.top_k,
-        epsilon: v2Cfg.epsilon,
-      },
-    });
+      if (corruptSlugSet.has(slug)) {
+        status = "corrupt";
+      }
+      row.status = status;
+    }
+    telemetryRows.sort((a, b) => b.finalActivation - a.finalActivation);
+    conceptRowsForLog = telemetryRows;
   } catch (err) {
+    // Stash the error and let `finally` flush a best-effort telemetry row
+    // before we re-throw to the caller. `mode = "errored"` flags the row
+    // for observability dashboards / inspector queries.
+    caughtErr = err;
+    mode = "errored";
+  } finally {
+    try {
+      recordMemoryV2ActivationLog({
+        conversationId,
+        turn: currentTurn,
+        mode,
+        concepts: conceptRowsForLog,
+        config: configSnapshot(config),
+      });
+    } catch (telemetryErr) {
+      log.warn(
+        { err: telemetryErr, conversationId, turn: currentTurn },
+        "Failed to record memory v2 activation telemetry — continuing",
+      );
+    }
+  }
+
+  if (caughtErr !== undefined) throw caughtErr;
+  return { block, toInject: newlyInjected };
+}
+
+/**
+ * Router-mode dispatch path. Replaces the spreading-activation pipeline with
+ * a single LLM call that picks the per-turn concept-page set. On success we
+ * reuse `finalizeInjection` so the persistence/render/telemetry contract
+ * stays identical to the activation path; on `runRouter` failure we still
+ * advance `activation_state` (so `currentTurn` and `messageId` move forward)
+ * and emit a `mode: "errored"` telemetry row so the failure is observable.
+ *
+ * Failure rows are tagged `errored`, not `router`, because router-mode rows
+ * are reserved for successful selections — keeping the two visually distinct
+ * in inspector queries. `nextStateMap` is always empty in router mode: the
+ * router does not compute spreading-activation scores, so there is no sparse
+ * activation map to persist.
+ */
+async function injectViaRouter(args: {
+  workspaceDir: string;
+  database: DrizzleDb;
+  conversationId: string;
+  currentTurn: number;
+  userMessage: string;
+  assistantMessage: string;
+  nowText: string;
+  messageId: string;
+  config: AssistantConfig;
+  priorState: ActivationState | null;
+  signal?: AbortSignal;
+}): Promise<InjectMemoryV2BlockResult> {
+  const {
+    workspaceDir,
+    database,
+    conversationId,
+    currentTurn,
+    userMessage,
+    assistantMessage,
+    nowText,
+    messageId,
+    config,
+    priorState,
+    signal,
+  } = args;
+
+  const priorEverInjected: readonly EverInjectedEntry[] =
+    priorState?.everInjected ?? [];
+
+  const routerResult = await runRouter({
+    workspaceDir,
+    userMessage,
+    assistantMessage,
+    nowText,
+    priorEverInjected,
+    config,
+    ...(signal ? { signal } : {}),
+  });
+
+  if (routerResult.failureReason !== null) {
     log.warn(
-      { err, conversationId, turn: currentTurn },
-      "Failed to record memory v2 activation telemetry — continuing",
+      { failureReason: routerResult.failureReason },
+      "memory v2 router failure; skipping injection",
     );
+    // Delegate the failure path to `finalizeInjection` with empty inputs
+    // and `mode: "errored"`. The helper persists a stub activation_state
+    // (preserving `priorEverInjected` so future turns still subtract
+    // previously-attached slugs) and writes the telemetry row through the
+    // same code path as the success branch — no inline duplication of
+    // `save` + `recordMemoryV2ActivationLog`.
+    return finalizeInjection({
+      workspaceDir,
+      database,
+      conversationId,
+      mode: "errored",
+      currentTurn,
+      messageId,
+      priorEverInjected,
+      slugsToRender: [],
+      telemetryRows: [],
+      config,
+      nextStateMap: {},
+    });
   }
 
-  return { block, toInject: newlyInjected };
+  // Dedupe router-picked slugs against `priorEverInjected` BEFORE rendering.
+  // The router prompt explicitly invites the model to re-pick already-injected
+  // pages "to re-anchor"; if we passed those through, `renderInjectionBlock`
+  // would re-emit the slug into a fresh `<memory>` block while the prior
+  // turn's cached attachment is still on the prior user message — duplicate
+  // content. Activation per-turn mode does not have this issue because
+  // `selectInjections()` returns `toInject = topNow - everInjected`.
+  //
+  // Telemetry rows for prior-everInjected slugs are still emitted below,
+  // but tagged `source: "carry_over"` (not `"router"`) so inspector queries
+  // can attribute selections correctly.
+  const everInjectedSet = new Set(priorEverInjected.map((e) => e.slug));
+  const slugsToRender = routerResult.selectedSlugs.filter(
+    (s) => !everInjectedSet.has(s),
+  );
+
+  // Build minimal telemetry rows for the union of router-selected slugs and
+  // prior `everInjected` slugs. Router-mode rows zero out every activation
+  // value (no spreading activation runs). Slugs the router picked this turn
+  // get `source: "router"`; prior-everInjected slugs the router did NOT
+  // re-pick get `source: "carry_over"`. The `status` placeholder is
+  // overwritten by `finalizeInjection`.
+  const routerPicked = new Set(routerResult.selectedSlugs);
+  const telemetrySlugs = new Set<string>(routerPicked);
+  for (const entry of priorEverInjected) telemetrySlugs.add(entry.slug);
+  const telemetryRows: MemoryV2ConceptRowRecord[] = [...telemetrySlugs].map(
+    (slug) => ({
+      slug,
+      finalActivation: 0,
+      ownActivation: 0,
+      priorActivation: 0,
+      simUser: 0,
+      simAssistant: 0,
+      simNow: 0,
+      simUserRerankBoost: 0,
+      simAssistantRerankBoost: 0,
+      inRerankPool: false,
+      spreadContribution: 0,
+      source: routerPicked.has(slug) ? "router" : "carry_over",
+      status: "not_injected",
+    }),
+  );
+
+  return finalizeInjection({
+    workspaceDir,
+    database,
+    conversationId,
+    mode: "router",
+    currentTurn,
+    messageId,
+    priorEverInjected,
+    slugsToRender,
+    telemetryRows,
+    config,
+    nextStateMap: {},
+  });
+}
+
+/**
+ * Snapshot the v2 config tunables in the shape `recordMemoryV2ActivationLog`
+ * persists. Pulled out so the router-failure path does not duplicate the
+ * field list inline.
+ */
+function configSnapshot(config: AssistantConfig) {
+  const v2Cfg = config.memory.v2;
+  return {
+    d: v2Cfg.d,
+    c_user: v2Cfg.c_user,
+    c_assistant: v2Cfg.c_assistant,
+    c_now: v2Cfg.c_now,
+    k: v2Cfg.k,
+    hops: v2Cfg.hops,
+    top_k: v2Cfg.top_k,
+    epsilon: v2Cfg.epsilon,
+  };
 }
 
 function throwIfAborted(signal: AbortSignal | undefined): void {
@@ -358,8 +660,28 @@ interface RenderInjectionBlockResult {
    * edge-index entries that pointed at pages no longer on disk.
    */
   missingSlugs: string[];
+  /**
+   * Slugs whose `readPage` call threw (e.g. invalid frontmatter that fails
+   * Zod validation, unreadable file). These are reported separately from
+   * `missingSlugs` because they're a different failure mode — the file
+   * exists but is malformed, not absent — and surfaced so the caller can
+   * mark them in the activation log (`status: "corrupt"`). Per-page errors
+   * are isolated: one bad page no longer rejects the whole batch.
+   */
+  corruptSlugs: string[];
 }
 
+/**
+ * Leading instruction line emitted at the top of an injection block when at
+ * least one section was rendered from a page's `summary` field. Tells the
+ * agent the truncated entries are summaries and to read the underlying file
+ * if relevant. Suppressed when every section is a full-page fallback —
+ * claiming "these are summaries" over already-complete content would mislead
+ * the agent into wasted reads.
+ */
+const INJECTION_HEADER =
+  "**CRITICAL:** These are page summaries. Read the page file if it looks relevant.";
+
 /**
  * Render the inner content of the `<memory>` block for a list of slugs.
  * The caller wraps the result in `<memory>...</memory>` exactly once at
@@ -370,11 +692,15 @@ interface RenderInjectionBlockResult {
  * trailing `### Skills You Can Use` subsection; everything else is read
  * from disk via `readPage` and rendered as a concept-page section.
  *
- * Concept pages are read in parallel via `readPage`. Pages whose file has
- * gone missing between selection and render (e.g. consolidation deleted
- * them, folder reorg renamed the slug) are dropped from the rendered
- * block but reported back via `missingSlugs` so callers can surface the
- * divergence.
+ * Concept pages are read in parallel via `Promise.allSettled`. Per-page
+ * errors are isolated: a `readPage` rejection (e.g. invalid frontmatter
+ * failing Zod validation) collects the slug into `corruptSlugs` and the
+ * remaining pages still render normally. Pages whose file has gone missing
+ * between selection and render (e.g. consolidation deleted them, folder
+ * reorg renamed the slug) are dropped from the rendered block but reported
+ * back via `missingSlugs`. The two buckets are kept separate so callers can
+ * distinguish "file vanished" (stale index) from "file is malformed"
+ * (data-corruption / programmer error).
  *
  * Skill slugs whose entry the cache no longer knows (e.g. uninstalled
  * mid-run) are silently dropped, mirroring the missing-pages behavior but
@@ -383,23 +709,24 @@ interface RenderInjectionBlockResult {
  * skill is an expected catalog-level outcome rather than a stale-index
  * bug.
  *
- * The block shape mirrors the §5 layout — concept-page sections first,
- * skills subsection last — preserving the prompt format the agent sees:
+ * Each concept-page section is rendered as a path header followed by either
+ * the page's `summary` (when present in frontmatter) or the full page (the
+ * fallback for pages predating the summary field). Skills sit at the end
+ * under `### Skills You Can Use`, unchanged. The leading `**CRITICAL:**`
+ * line tells the agent how to read the block.
  *
- *   ### <concept-slug-1>
+ *   **CRITICAL:** These are page summaries. Read the page file if it looks relevant.
+ *
+ *   # memory/concepts/<concept-slug-1>.md
+ *   <summary-1>
+ *
+ *   # memory/concepts/<concept-slug-2>.md
  *   ---
  *   edges:
  *     - <neighbor-slug>
  *   ref_files:
  *     - <path/to/asset>
  *   ---
- *   <body-1>
- *
- *   ### <concept-slug-2>
- *   ---
- *   edges: []
- *   ref_files: []
- *   ---
  *   <body-2>
  *
  *   ### Skills You Can Use
@@ -413,23 +740,43 @@ async function renderInjectionBlock(
   const conceptSlugs = slugs.filter((s) => !isSkillSlug(s));
   const skillSlugs = slugs.filter((s) => isSkillSlug(s));
 
-  const pages = await Promise.all(
-    conceptSlugs.map(async (slug) => {
-      const page = await readPage(workspaceDir, slug);
-      return { slug, page };
-    }),
+  const settled = await Promise.allSettled(
+    conceptSlugs.map((slug) => readPage(workspaceDir, slug)),
   );
 
   const sections: string[] = [];
   const missingSlugs: string[] = [];
-  for (const { slug, page } of pages) {
+  const corruptSlugs: string[] = [];
+  let anySummarySection = false;
+  for (let i = 0; i < settled.length; i++) {
+    const slug = conceptSlugs[i]!;
+    const result = settled[i]!;
+    if (result.status === "rejected") {
+      corruptSlugs.push(slug);
+      log.warn(
+        { slug, err: result.reason },
+        "Memory v2 injection skipped slug whose page failed to load — frontmatter may be malformed",
+      );
+      continue;
+    }
+    const page = result.value;
     if (!page) {
       missingSlugs.push(slug);
       continue;
     }
+    const summary = page.frontmatter.summary?.trim();
+    const path = `memory/concepts/${slug}.md`;
+    if (summary && summary.length > 0) {
+      sections.push(`# ${path}\n${summary}`);
+      anySummarySection = true;
+      continue;
+    }
+    // Fallback: page predates the `summary` field (or the field was set to
+    // empty). Render the full page — frontmatter + body — so retrieval
+    // still surfaces the same content the agent saw before this change.
     const content = renderPageContent(page).trim();
     if (content.length === 0) continue;
-    sections.push(`### ${slug}\n${content}`);
+    sections.push(`# ${path}\n${content}`);
   }
 
   const skillLines: string[] = [];
@@ -442,10 +789,14 @@ async function renderInjectionBlock(
     sections.push(`### Skills You Can Use\n${skillLines.join("\n")}`);
   }
 
-  if (sections.length === 0) return { block: null, missingSlugs };
+  if (sections.length === 0) {
+    return { block: null, missingSlugs, corruptSlugs };
+  }
 
+  const body = sections.join("\n\n");
   return {
-    block: sections.join("\n\n"),
+    block: anySummarySection ? `${INJECTION_HEADER}\n\n${body}` : body,
     missingSlugs,
+    corruptSlugs,
   };
 }