@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

package/src/plugins/defaults/memory-v3-shadow/orchestrate.ts

@@ -0,0 +1,266 @@
+/**
+ * Memory v3 — orchestrator composing the section-grain lanes into one turn.
+ *
+ * Each turn runs:
+ *   1. Candidate generation over three deterministic lanes:
+ *        - the section-grain BM25 needle (`SectionNeedle.query`, KB articles),
+ *        - the dense lane (`denseLane`, KD articles), and
+ *        - link-graph edge expansion (`edgeExpand`) over the top needle+dense
+ *          article seeds.
+ *      Each lane only ever ADDS candidates, so the pool is recall-safe by
+ *      construction.
+ *   2. Build the unified candidate pool of `{ slug, descriptor }`. The
+ *      descriptor is the matched section's text for needle/dense hits (resolved
+ *      via the section index); for edge-only pages it is the curated `links`
+ *      description when the traversed edge carried one, else the page's best
+ *      section against the query. Edge-only pages record NO matched section, so
+ *      they inject the FULL page (the lead the query never hit is often empty;
+ *      the link-relevant content is elsewhere) — the best-section text is only a
+ *      descriptor fallback. Synthetic capability pages (skills / CLI commands)
+ *      carry sections in the section index too, so they enter the pool through
+ *      the lanes like any other page rather than being always-added.
+ *   3. A SINGLE forced-tool select (`selectPool`) over the whole pool. The
+ *      result is this turn's selections.
+ *   4. Age the carry-forward working set to this turn (evict stale non-pinned
+ *      entries, then the cap) and snapshot it — the pages carried in from
+ *      EARLIER turns.
+ *   5. Final injection = unique union of this turn's selected slugs and that
+ *      carried-forward set, so pages selected on earlier turns carry forward
+ *      even when this turn does not re-select them.
+ *   6. Record this turn's selections into the working set for LATER turns. This
+ *      runs AFTER the snapshot so the cap is spent on genuinely carried pages,
+ *      not on this turn's selections (which are injected directly) — otherwise a
+ *      turn selecting more pages than the cap would evict the entire carry.
+ */
+
+import type { AssistantConfig } from "../../../config/schema.js";
+import { denseLane } from "./dense.js";
+import type { EdgeGraph } from "./edge.js";
+import { edgeExpand } from "./edge.js";
+import type { PoolCandidate } from "./pool-select.js";
+import { selectPool } from "./pool-select.js";
+import type { SectionNeedle } from "./section-needle.js";
+import type {
+  CandidateLane,
+  MemoryRoutingTurn,
+  Section,
+  SectionIndex,
+  SelectedPage,
+  Slug,
+} from "./types.js";
+import { WorkingSet } from "./working-set.js";
+
+/** Default number of BM25 needle articles to fold into the pool. */
+export const DEFAULT_NEEDLE_K = 100;
+/** Default number of dense-lane articles to fold into the pool. */
+export const DEFAULT_DENSE_K = 100;
+
+export interface OrchestrateDeps {
+  sectionIndex: SectionIndex;
+  needle: SectionNeedle;
+  /** Config the dense lane needs to embed the query + search the section
+   *  collection. */
+  denseConfig: AssistantConfig;
+  edgeGraph: EdgeGraph;
+  workingSet: WorkingSet;
+  /** Number of BM25 needle articles. Defaults to {@link DEFAULT_NEEDLE_K}. */
+  needleK?: number;
+  /** Number of dense-lane articles. Defaults to {@link DEFAULT_DENSE_K}. */
+  denseK?: number;
+  /** Number of top needle+dense seeds expanded. When omitted, the edge lane's
+   *  own default applies (canonical value: `memory.v3.edge.seedCount`). */
+  edgeSeeds?: number;
+  /** Neighbours surfaced per expanded edge seed. When omitted, the edge lane's
+   *  own default applies (canonical value: `memory.v3.edge.perSeed`). */
+  edgePerSeed?: number;
+  /** Hard cap on total edge-lane surfaced articles. When omitted, the edge
+   *  lane's own default applies (canonical value: `memory.v3.edge.cap`). */
+  edgeCap?: number;
+}
+
+export interface OrchestrateResult {
+  /** This turn's selections, deduped by slug (pinned flags ORed). */
+  currentSelections: SelectedPage[];
+  /** The carried-forward set: selections from EARLIER turns, aged to this turn
+   *  (snapshotted before this turn's selections are recorded). */
+  workingSetUnion: Set<Slug>;
+  /** Slugs to inject: this turn's selections ∪ the carried-forward working set. */
+  finalInjection: Slug[];
+  /** The matched `Section` for each pooled slug that had one, keyed by slug.
+   *  Populated from the lane hits and consumed by the injector to render each
+   *  selected slug's matched section (progressive disclosure). */
+  sectionBySlug: Map<Slug, Section>;
+  /** The candgen lane that FIRST surfaced each pooled slug, keyed by slug.
+   *  Insertion order is needle → dense → edge, so a page surfaced by more than
+   *  one lane records the highest-precedence one. Consumed by the selection
+   *  telemetry to attribute each selection to its true lane. */
+  laneBySlug: Map<Slug, CandidateLane>;
+}
+
+/** Stable-order de-duplication preserving first occurrence. */
+function unique<T>(items: Iterable<T>): T[] {
+  return [...new Set(items)];
+}
+
+export async function orchestrate(
+  turn: MemoryRoutingTurn,
+  deps: OrchestrateDeps,
+): Promise<OrchestrateResult> {
+  const needleK = deps.needleK ?? DEFAULT_NEEDLE_K;
+  const denseK = deps.denseK ?? DEFAULT_DENSE_K;
+  const { sections } = deps.sectionIndex;
+
+  // Step 1: needle (sync BM25) and dense (async embed + Qdrant) lanes run in
+  // parallel. Both return distinct articles each tagged with their best-scoring
+  // section index/ordinal.
+  const [needled, densed] = await Promise.all([
+    Promise.resolve(deps.needle.query(turn.currentMessage, needleK)),
+    denseLane(deps.denseConfig, turn.currentMessage, denseK),
+  ]);
+
+  // The pool accumulates one entry per distinct article. `sectionBySlug` records
+  // the matched `Section` (when one is known) for downstream injection;
+  // `laneBySlug` records the lane that first surfaced each slug for telemetry.
+  const poolBySlug = new Map<Slug, PoolCandidate>();
+  const sectionBySlug = new Map<Slug, Section>();
+  const laneBySlug = new Map<Slug, CandidateLane>();
+
+  // Add one pool candidate, recording its matched `Section` (when known) for
+  // downstream injection and the `lane` that surfaced it for telemetry.
+  // `descriptor` overrides the section text when supplied (the edge lane prefers
+  // a curated `links` description). The first lane to surface a slug wins the
+  // pool entry, the recorded section, AND the recorded lane — so the
+  // needle → dense → edge call order encodes lane precedence.
+  const addCandidate = (
+    slug: Slug,
+    section: Section | undefined,
+    descriptor: string | undefined,
+    lane: CandidateLane,
+  ): void => {
+    if (section && !sectionBySlug.has(slug)) {
+      sectionBySlug.set(slug, section);
+    }
+    if (poolBySlug.has(slug)) return;
+    laneBySlug.set(slug, lane);
+    poolBySlug.set(slug, {
+      slug,
+      descriptor: descriptor ?? section?.text ?? "",
+    });
+  };
+
+  // Step 2a: needle hits — descriptor is the matched section's text. `section`
+  // is an index into `sections`.
+  for (const hit of needled) {
+    addCandidate(hit.article, sections[hit.section], undefined, "needle");
+  }
+
+  // Step 2b: dense hits — `section` is the matched ORDINAL; resolve it to the
+  // concrete `Section` via the section index. Falls back to undefined (blank
+  // descriptor) if the ordinal is not in the in-memory index.
+  for (const hit of densed) {
+    // A deleted page's points can linger in Qdrant; keep only live-index
+    // articles. The section index is rebuilt from `getPageIndex` at `initLanes`,
+    // so `byArticle` holds exactly the live pages (synthetic capability slugs
+    // included) — only truly-deleted pages are dropped here.
+    if (!deps.sectionIndex.byArticle.has(hit.article)) continue;
+    addCandidate(
+      hit.article,
+      sectionByOrdinal(deps.sectionIndex, hit.article, hit.section),
+      undefined,
+      "dense",
+    );
+  }
+
+  // Step 2c: edge expansion over the top needle+dense article seeds. `alive`
+  // skips slugs already pooled. An edge-only page was surfaced because its
+  // NEIGHBOUR matched — the query did not lexically hit the page itself, so
+  // `bestSection` returns its first/lead section on a zero-score match. That
+  // lead is often empty for heading-structured pages, and it is the curated
+  // `links` description (not the lead) that made the candidate relevant. So we
+  // record NO matched section for edge-only pages (pass `undefined`), which
+  // makes injection fall back to the FULL page — where the link-relevant content
+  // lives. `bestSection`'s text is kept only as the select-pool DESCRIPTOR
+  // fallback for when the traversed edge carried no curated `links` description.
+  const seeds = unique<Slug>([
+    ...needled.map((h) => h.article),
+    ...densed.map((h) => h.article),
+  ]);
+  const surfaced = edgeExpand(deps.edgeGraph, seeds, {
+    seedCount: deps.edgeSeeds,
+    perSeed: deps.edgePerSeed,
+    cap: deps.edgeCap,
+    alive: (slug) => !poolBySlug.has(slug),
+  });
+  for (const neighbor of surfaced) {
+    const best = deps.needle.bestSection(neighbor.article, turn.currentMessage);
+    const fallbackDescriptor = best >= 0 ? sections[best]?.text : undefined;
+    addCandidate(
+      neighbor.article,
+      undefined,
+      neighbor.description ?? fallbackDescriptor,
+      "edge",
+    );
+  }
+
+  // Step 3: a SINGLE forced-tool select over the unified pool.
+  const selected = await selectPool([...poolBySlug.values()], turn);
+  const bySlug = new Map<Slug, SelectedPage>();
+  for (const page of selected) {
+    const existing = bySlug.get(page.slug);
+    bySlug.set(page.slug, {
+      slug: page.slug,
+      pinned: (existing?.pinned ?? false) || page.pinned,
+    });
+  }
+  const currentSelections = [...bySlug.values()];
+
+  // Step 4: age the carry-forward set to this turn (drop stale non-pinned
+  // entries, then the cap) and snapshot it. This is the set carried in from
+  // EARLIER turns; recording this turn happens afterward (step 6) so the cap is
+  // spent on genuinely carried pages, not on this turn's selections (which are
+  // injected directly anyway).
+  deps.workingSet.evict(turn.turnNumber);
+  const workingSetUnion = deps.workingSet.union();
+
+  // Step 5: final injection = this turn's selections ∪ the carried-forward set,
+  // so pages selected on earlier turns carry forward even when this turn does
+  // not re-select them.
+  const finalInjection = unique<Slug>([
+    ...currentSelections.map((s) => s.slug),
+    ...workingSetUnion,
+  ]);
+
+  // Step 6: record this turn's selections so they carry forward to LATER turns.
+  for (const sel of currentSelections) {
+    deps.workingSet.recordSelection(sel.slug, turn.turnNumber, sel.pinned);
+  }
+
+  return {
+    currentSelections,
+    workingSetUnion,
+    finalInjection,
+    sectionBySlug,
+    laneBySlug,
+  };
+}
+
+/**
+ * Resolve a dense-lane hit's matched ordinal to the concrete `Section` in the
+ * in-memory index. The dense store keys sections by `(article, ordinal)`, so we
+ * scan the article's sections for the matching ordinal. Returns `undefined`
+ * when the article or ordinal is not in the index (e.g. the dense store is
+ * ahead of the in-memory rebuild).
+ */
+function sectionByOrdinal(
+  index: SectionIndex,
+  article: Slug,
+  ordinal: number,
+): Section | undefined {
+  const indices = index.byArticle.get(article);
+  if (!indices) return undefined;
+  for (const i of indices) {
+    const section = index.sections[i];
+    if (section && section.ordinal === ordinal) return section;
+  }
+  return undefined;
+}

package/src/plugins/defaults/memory-v3-shadow/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "default-memory-v3-shadow",
+  "version": "1.0.0",
+  "description": "First-party default plugin housing the memory-v3 shadow/live orchestration engine and its injector.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

package/src/plugins/defaults/memory-v3-shadow/page-content.ts

@@ -0,0 +1,71 @@
+import { readPage, renderPageContent } from "../../../memory/v2/page-store.js";
+import { getWorkspaceDir } from "../../../util/platform.js";
+import { renderCapabilityContent } from "./capabilities.js";
+import type { Section, Slug } from "./types.js";
+
+/**
+ * Prefix `body` with the `# memory/concepts/<slug>.md` header marker the v3
+ * `<memory>` block uses. Both the full-page and matched-section renderers emit
+ * this exact marker, and the v2 stripper recognizes pages by it — so the two
+ * call sites MUST stay byte-identical, which is why this lives in one place.
+ */
+function withConceptHeader(slug: Slug, body: string): string {
+  return `# memory/concepts/${slug}.md\n${body}`;
+}
+
+/**
+ * Render a selected page's full content for the v3 `<memory>` block. Mirrors
+ * the v2 dynamic-memory layout (`# memory/concepts/<slug>.md\n<frontmatter+body>`)
+ * so the working-set block reads like v2's. A missing page (or any read
+ * failure) degrades to "" — `renderMemoryBlock` still emits a line for the
+ * slug, and a blank section is preferable to throwing into the turn.
+ *
+ * Synthetic capability slugs (skills, `assistant` CLI commands) have no on-disk
+ * page; they resolve through {@link renderCapabilityContent} instead of
+ * `readPage`. A non-null result (including "") means the slug was a capability
+ * slug and was handled here.
+ *
+ * Shared by the live injector (`shadow-plugin.ts`) and the inspector
+ * selection-log store (`selection-log-store.ts`) so the inspector's rendered
+ * block is byte-identical to what live injection produces.
+ */
+export async function renderV3PageContent(slug: Slug): Promise<string> {
+  const capability = renderCapabilityContent(slug);
+  if (capability !== null) return capability;
+  try {
+    const page = await readPage(getWorkspaceDir(), slug);
+    if (!page) return "";
+    const content = renderPageContent(page).trim();
+    if (content.length === 0) return "";
+    return withConceptHeader(slug, content);
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Render a slug's matched section for the v3 `<memory>` block (progressive
+ * disclosure: inject only the section the lanes matched, not the full page).
+ * Uses the same `# memory/concepts/<slug>.md` header marker as
+ * {@link renderV3PageContent} so the block reads like v2's and the v2 stripper
+ * recognizes it.
+ *
+ * - Capability slugs (skills, `assistant` CLI commands) have no on-disk
+ *   section, so they always render their capability content via
+ *   {@link renderCapabilityContent}, never a section.
+ * - When `section` is undefined (e.g. a carry-forward page with no current
+ *   match), fall back to {@link renderV3PageContent} (the full/lead page) so the
+ *   slug still contributes content.
+ */
+export async function renderV3SectionContent(
+  slug: Slug,
+  section: Section | undefined,
+): Promise<string> {
+  const capability = renderCapabilityContent(slug);
+  if (capability !== null) return capability;
+  if (!section) return renderV3PageContent(slug);
+
+  const text = section.text.trim();
+  if (text.length === 0) return "";
+  return withConceptHeader(slug, text);
+}

package/src/plugins/defaults/memory-v3-shadow/pool-select.ts

@@ -0,0 +1,204 @@
+/**
+ * Memory v3 — single pool selector.
+ *
+ * Runs a SINGLE forced-tool call over one unified candidate pool. Each candidate
+ * is a page slug paired with a per-candidate `descriptor` the caller supplies —
+ * the matched section text for a needle/dense hit, or a curated link description
+ * for an edge page. The caller assembles the pool by unioning the section lanes;
+ * the pool selector only decides which of those candidates the reply will draw
+ * on.
+ *
+ * No cache breakpoint. The pool is recomputed from per-turn section matches and
+ * is therefore dynamic per turn, so it carries no `cache_control` breakpoint:
+ * caching a prefix that changes every turn would never hit. Carry-forward (the
+ * working set unioned in by the orchestrator) is the cache mechanism here, not a
+ * static prefix breakpoint.
+ *
+ * Failure handling is recall-safe by construction:
+ *   - explicit `ids` → select exactly those candidates,
+ *   - explicit empty `ids: []` → select none (deliberate abstention),
+ *   - omitted `ids` → keep ALL candidates (the recall-safe "all of these are
+ *     relevant" signal),
+ *   - infrastructure failure (provider unavailable, a throw that survived the
+ *     provider's own retries, no usable `tool_use`, or a schema mismatch) →
+ *     select nothing after a short re-prompt retry, degrading to the
+ *     deterministic recall lanes the orchestrator unions in regardless.
+ */
+
+import { z } from "zod";
+
+import {
+  extractToolUse,
+  getConfiguredProvider,
+} from "../../../providers/provider-send-message.js";
+import type { Message, ToolDefinition } from "../../../providers/types.js";
+import { getLogger } from "../../../util/logger.js";
+import { truncate } from "../../../util/truncate.js";
+import { retryForResult } from "./llm-retry.js";
+import type { MemoryRoutingTurn, SelectedPage, Slug } from "./types.js";
+
+const log = getLogger("memory-v3-pool-select");
+
+/** A candidate page in the unified pool, with the descriptor that justifies it. */
+export interface PoolCandidate {
+  slug: Slug;
+  /**
+   * The text that justifies this candidate: a matched section for a
+   * needle/dense hit, or a curated link description for an edge page. Rendered
+   * (truncated) in the numbered candidate list the selector judges against.
+   */
+  descriptor: string;
+}
+
+/** Tool name forced via `tool_choice`. Shared constant so tests can match it. */
+const SELECT_PAGES_TOOL_NAME = "select_pages";
+
+/** Descriptors are truncated to keep the candidate list compact. */
+const DESCRIPTOR_MAX_CHARS = 400;
+
+const SelectPagesSchema = z.object({
+  // Optional: an omitted `ids` field is the recall-safe "keep everything"
+  // signal, distinct from an explicit empty array (deliberate abstention).
+  ids: z.array(z.number().int()).optional(),
+  pinned_ids: z.array(z.number().int()).optional(),
+});
+
+const SELECT_PAGES_TOOL: ToolDefinition = {
+  name: SELECT_PAGES_TOOL_NAME,
+  description:
+    "Select the candidate pages whose content the reply would directly draw " +
+    "on. Lean inclusive — when in doubt, keep a candidate; for a list or " +
+    '"all of X" request keep every candidate that belongs. Pass `pinned_ids` ' +
+    "for pages the conversation is centrally about. Omit `ids` only as a " +
+    "recall-safe fallback when you cannot judge the pool (keeps every " +
+    "candidate); return `[]` when candidates are present but none are " +
+    "relevant.",
+  input_schema: {
+    type: "object",
+    properties: {
+      ids: {
+        type: "array",
+        items: { type: "integer" },
+      },
+      pinned_ids: {
+        type: "array",
+        items: { type: "integer" },
+      },
+    },
+  },
+};
+
+const SYSTEM_PROMPT = `You are given a pool of candidate memory pages, each surfaced because some part of it matched the conversation. Select every page whose specific content the reply to THIS message would directly draw on.
+
+Lean inclusive: recall matters more than precision here, so when a candidate could plausibly inform the reply, keep it. For a list or an "all of X" request, keep EVERY candidate that belongs to X rather than guessing a representative subset.
+
+A page can be relevant because of the current situation — the date or the live scratchpad — not only the message: keep a page the situation makes pertinent (e.g. a person whose anniversary is today).
+
+If the conversation is centrally ABOUT a page (rather than only peripherally relevant to it), mark that page as pinned. Call \`select_pages\` with the chosen IDs. Omit \`ids\` only as a recall-safe fallback when you cannot judge the pool (keeps every candidate); return \`[]\` when candidates are present but none are relevant.`;
+
+/** Collapse a descriptor to one line and cap its length for the candidate list. */
+function renderDescriptor(descriptor: string): string {
+  return truncate(descriptor.replace(/\s+/g, " ").trim(), DESCRIPTOR_MAX_CHARS);
+}
+
+/**
+ * Render the numbered candidate list: one `[i] slug — descriptor` line per
+ * candidate, descriptors collapsed to one line and length-capped. The pool is
+ * dynamic per turn, so this block is NOT cached (see the module doc).
+ */
+function renderCandidateList(pool: PoolCandidate[]): string {
+  const lines = pool.map(
+    (c, i) => `[${i + 1}] ${c.slug} — ${renderDescriptor(c.descriptor)}`,
+  );
+  return `<candidates>\n${lines.join("\n")}\n</candidates>`;
+}
+
+/**
+ * Run the single forced-tool selector over the unified candidate pool. Returns
+ * the pages to inject.
+ *
+ * An omitted `ids` keeps ALL candidates (the recall-safe "all of these are
+ * relevant" signal); an explicit `[]` keeps none; an infrastructure failure
+ * (after a short re-prompt retry) keeps none, degrading to the deterministic
+ * recall lanes the orchestrator unions in.
+ */
+export async function selectPool(
+  pool: PoolCandidate[],
+  turn: MemoryRoutingTurn,
+): Promise<SelectedPage[]> {
+  if (pool.length === 0) return [];
+
+  const keepAll = (): SelectedPage[] =>
+    pool.map((c) => ({ slug: c.slug, pinned: false }));
+
+  const provider = await getConfiguredProvider("memoryV3SelectL2");
+  if (!provider) {
+    log.warn(
+      { candidateCount: pool.length },
+      "pool selector provider unavailable; degrading to deterministic lanes",
+    );
+    return [];
+  }
+
+  // The pool is dynamic per turn, so there is no static cache breakpoint here;
+  // carry-forward is the cache mechanism. The candidate list and the per-turn
+  // context go in a single plain text block.
+  const userMsg: Message = {
+    role: "user",
+    content: [
+      {
+        type: "text",
+        text:
+          `${renderCandidateList(pool)}\n` +
+          (turn.situationalContext
+            ? `<situation>${turn.situationalContext}</situation>\n`
+            : "") +
+          `<recent_context>${turn.recentContext}</recent_context>\n` +
+          `<current_message>${turn.currentMessage}</current_message>`,
+      },
+    ],
+  };
+
+  // One forced-tool call, retried a few times so a transient malformed response
+  // (no usable tool_use, or tool input that fails the schema) re-prompts before
+  // we give up. `null` from an attempt means "unusable, retry"; the provider
+  // layer already backs off transient throws, so this loop adds no delay.
+  const parsed = await retryForResult(async () => {
+    const response = await provider.sendMessage([userMsg], {
+      tools: [SELECT_PAGES_TOOL],
+      systemPrompt: SYSTEM_PROMPT,
+      config: {
+        callSite: "memoryV3SelectL2" as const,
+        tool_choice: { type: "tool" as const, name: SELECT_PAGES_TOOL_NAME },
+      },
+    });
+    const toolBlock = extractToolUse(response);
+    if (!toolBlock || toolBlock.name !== SELECT_PAGES_TOOL_NAME) return null;
+    const result = SelectPagesSchema.safeParse(toolBlock.input);
+    return result.success ? result.data : null;
+  });
+
+  if (parsed === null) {
+    log.warn(
+      { candidateCount: pool.length },
+      "pool selector could not obtain a selection after retries; degrading to deterministic lanes",
+    );
+    return [];
+  }
+
+  // Omitted `ids` is the recall-safe "keep all candidates" signal.
+  if (parsed.ids === undefined) return keepAll();
+
+  const pinned = new Set(parsed.pinned_ids ?? []);
+
+  // Map 1-based IDs back to candidate slugs, dropping out-of-range IDs without
+  // throwing. De-duplicate while preserving model-returned order.
+  const seen = new Set<number>();
+  const selected: SelectedPage[] = [];
+  for (const id of parsed.ids) {
+    if (id < 1 || id > pool.length || seen.has(id)) continue;
+    seen.add(id);
+    selected.push({ slug: pool[id - 1]!.slug, pinned: pinned.has(id) });
+  }
+  return selected;
+}

package/src/{memory/v3 → plugins/defaults/memory-v3-shadow}/render-injection.ts

@@ -1,13 +1,15 @@
-import { wrapMemoryBlock } from "../memory-marker.js";
-import { Slug } from "./types.js";
+import { wrapMemoryBlock } from "../../../memory/memory-marker.js";
+import { Section, Slug } from "./types.js";
 
 /**
  * Render a v3 working-set selection into a single `<memory>…</memory>` text
- * block.
+ * block, injecting each slug's matched section (progressive disclosure) rather
+ * than its full page body.
  *
  * Pure and side-effect-free: all I/O is delegated to the injected
- * `pageContent` resolver, which is awaited once per slug in input order. The
- * resulting block uses the shared {@link wrapMemoryBlock} marker — the same
+ * `pageContent` resolver, which is awaited once per slug in input order with
+ * that slug's matched section (`sectionBySlug.get(slug)`, possibly undefined).
+ * The resulting block uses the shared {@link wrapMemoryBlock} marker — the same
  * wrapper the v2 graph-memory path emits — so the existing strip machinery in
  * `conversation-graph-memory.ts` already recognizes (and evicts) it.
  *
@@ -16,17 +18,23 @@ import { Slug } from "./types.js";
  *
  * @param finalInjection - The working-set selection for the turn, in the order
  *   it should appear in the rendered block.
- * @param pageContent - Resolver returning a page's rendered content for a slug.
+ * @param sectionBySlug - The matched `Section` per slug; a slug with no entry
+ *   (e.g. carry-forward with no current match) renders its full/lead page.
+ * @param pageContent - Resolver returning a slug's rendered content given its
+ *   matched section (or undefined).
  * @returns The wrapped `<memory>` block, or `""` for an empty selection (the
  *   caller injects nothing).
  */
 export async function renderMemoryBlock(
   finalInjection: Slug[],
-  pageContent: (slug: Slug) => Promise<string>,
+  sectionBySlug: Map<Slug, Section>,
+  pageContent: (slug: Slug, section: Section | undefined) => Promise<string>,
 ): Promise<string> {
   if (finalInjection.length === 0) return "";
 
-  const contents = await Promise.all(finalInjection.map(pageContent));
+  const contents = await Promise.all(
+    finalInjection.map((slug) => pageContent(slug, sectionBySlug.get(slug))),
+  );
 
   return wrapMemoryBlock(contents.join("\n"));
 }