@vellumai/assistant 0.7.2 → 0.8.0

package/src/memory/v2/sim.ts

@@ -30,7 +30,6 @@ import { applyCorrectionIfCalibrated } from "../anisotropy.js";
 import { embedWithBackend } from "../embedding-backend.js";
 import { clampUnitInterval } from "../validation.js";
 import { hybridQueryConceptPages } from "./qdrant.js";
-import { hybridQuerySkills } from "./skill-qdrant.js";
 import { generateBm25QueryEmbedding } from "./sparse-bm25.js";
 
 /**
@@ -121,14 +120,18 @@ export function effectiveWeights(
  *      sparse via the in-process TF-IDF encoder).
  *   2. Run server-side dense + sparse queries against the v2 concept-page
  *      Qdrant collection, restricted to `candidateSlugs` so we don't waste
- *      query bandwidth on unrelated pages.
- *   3. Fuse: per slug, `score = clamp01(dense_weight · denseCosine +
- *      sparse_weight · normalizedSparse)`. Sparse scores are normalized by
- *      the per-batch maximum (so the largest is 1.0); slugs missing from a
- *      channel contribute 0 from that channel.
+ *      query bandwidth on unrelated pages. The query hits four channels per
+ *      page: body dense + body sparse, and (for pages that have a summary
+ *      embedded) summary dense + summary sparse.
+ *   3. Fuse: per slug, score = `max(fused(body), fused(summary))`. Each
+ *      half is `clamp01(dense_weight · denseCosine + sparse_weight ·
+ *      normalizedSparse)` with sparse normalized by the per-batch maximum.
+ *      Pages without a summary embedding fall back to body-only fusion —
+ *      the summary half is undefined and the max collapses to the body
+ *      score.
  *
  * Returns a `Map<slug, score>` containing only the candidate slugs that hit
- * in at least one channel. Slugs in `candidateSlugs` that miss both channels
+ * in at least one channel. Slugs in `candidateSlugs` that miss every channel
  * are absent from the map; callers should treat absence as score = 0 (the
  * activation pipeline does this implicitly when reading back A_o).
  *
@@ -147,6 +150,7 @@ export async function simBatch(
   text: string,
   candidateSlugs: readonly string[],
   config: AssistantConfig,
+  options?: { signal?: AbortSignal },
 ): Promise<Map<string, number>> {
   if (candidateSlugs.length === 0) {
     return new Map();
@@ -158,12 +162,16 @@ export async function simBatch(
   // Sparse uses BM25: the query side encodes binary occurrences per token,
   // and the stored doc vectors carry the IDF · TF-saturated weights — Qdrant
   // dot product then yields the BM25 score directly.
-  const denseResult = await embedWithBackend(config, [text]);
+  throwIfAborted(options?.signal);
+  const denseResult = await embedWithBackend(config, [text], {
+    signal: options?.signal,
+  });
   const denseVector = await applyCorrectionIfCalibrated(
     denseResult.vectors[0],
     denseResult.provider,
     denseResult.model,
   );
+  throwIfAborted(options?.signal);
   const sparseVector = generateBm25QueryEmbedding(text);
 
   const hits = await hybridQueryConceptPages(
@@ -177,140 +185,99 @@ export async function simBatch(
     return new Map();
   }
 
-  const maxSparse = computeMaxSparse(hits);
+  // Compute per-batch sparse maxima independently for the body and summary
+  // channels so each side normalizes against its own scale. Mixing the two
+  // — e.g. dividing every sparse score by the larger of the two maxima —
+  // would punish whichever channel happened to have lower-magnitude scores
+  // even when its hits were the best matches available.
+  const maxBodySparse = computeMaxSparse(hits, (h) => h.sparseScore);
+  const maxSummarySparse = computeMaxSparse(hits, (h) => h.summarySparseScore);
   const { dense_weight: baseDense, sparse_weight: baseSparse } =
     config.memory.v2;
-  const { dense: denseWeight, sparse: sparseWeight } = effectiveWeights(
-    hits,
-    maxSparse,
+  const { dense: bodyDenseWeight, sparse: bodySparseWeight } = effectiveWeights(
+    hits.map((h) => ({ sparseScore: h.sparseScore })),
+    maxBodySparse,
     baseDense,
     baseSparse,
     config,
   );
+  const { dense: summaryDenseWeight, sparse: summarySparseWeight } =
+    effectiveWeights(
+      hits.map((h) => ({ sparseScore: h.summarySparseScore })),
+      maxSummarySparse,
+      baseDense,
+      baseSparse,
+      config,
+    );
 
   const scores = new Map<string, number>();
   for (const hit of hits) {
-    scores.set(hit.slug, fuseHit(hit, maxSparse, denseWeight, sparseWeight));
+    const bodyScore = fuseHalf(
+      hit.denseScore,
+      hit.sparseScore,
+      maxBodySparse,
+      bodyDenseWeight,
+      bodySparseWeight,
+    );
+    const summaryScore = fuseHalf(
+      hit.summaryDenseScore,
+      hit.summarySparseScore,
+      maxSummarySparse,
+      summaryDenseWeight,
+      summarySparseWeight,
+    );
+    // Pages without a summary embedding return undefined for both summary
+    // channels; their `summaryScore` falls back to the body score so the
+    // max collapses cleanly to body-only behavior.
+    const score = Math.max(bodyScore ?? 0, summaryScore ?? bodyScore ?? 0);
+    scores.set(hit.slug, score);
   }
+
   return scores;
 }
 
-/**
- * Compute hybrid (dense + sparse) similarity scores between a query text and
- * a fixed set of candidate skill ids. Mirrors `simBatch` but targets the
- * dedicated `memory_v2_skills` Qdrant collection via `hybridQuerySkills`.
- *
- * Differences from `simBatch`:
- *   - Keys are skill `id` values (not concept-page slugs).
- *   - Restricts the query to the caller's candidate ids server-side via
- *     `hybridQuerySkills`'s `restrictToIds` parameter. Without this, when the
- *     skills collection has more skills than `ids.length`, Qdrant would
- *     return its global top-K and candidate ids absent from that top-K would
- *     silently score 0 — corrupting the activation calculation.
- *
- * Returns a `Map<id, score>` of fused scores in [0, 1]. Ids that did not hit
- * either channel are absent from the map.
- *
- * Edge cases:
- *   - Empty `ids` → returns an empty map without touching Qdrant or the
- *     embedding backend.
- *   - Empty / whitespace-only `text` → returns an empty map without touching
- *     Qdrant or the embedding backend. Same rationale as {@link simBatch}:
- *     Gemini rejects empty content with HTTP 400, so the activation pipeline
- *     would otherwise fail on turn 1 (where the assistant-text channel is
- *     `""`). Treating the channel's contribution as 0 matches a no-hit
- *     query.
- */
-export async function simSkillBatch(
-  text: string,
-  ids: readonly string[],
-  config: AssistantConfig,
-): Promise<Map<string, number>> {
-  if (ids.length === 0) {
-    return new Map();
-  }
-  if (text.trim().length === 0) {
-    return new Map();
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw new DOMException("Aborted", "AbortError");
   }
-
-  const denseResult = await embedWithBackend(config, [text]);
-  const denseVector = await applyCorrectionIfCalibrated(
-    denseResult.vectors[0],
-    denseResult.provider,
-    denseResult.model,
-  );
-  const sparseVector = generateBm25QueryEmbedding(text);
-
-  const hits = await hybridQuerySkills(
-    denseVector,
-    sparseVector,
-    ids.length,
-    ids,
-  );
-
-  if (hits.length === 0) {
-    return new Map();
-  }
-
-  // Defensive post-filter — `hybridQuerySkills` restricts server-side, so
-  // every hit should already be in `ids`, but keep this guard so a buggy
-  // payload (e.g. a missing/typoed id index) can't silently inject
-  // out-of-set ids into the score map.
-  const idSet = new Set(ids);
-  const filtered = hits.filter((h) => idSet.has(h.id));
-  if (filtered.length === 0) {
-    return new Map();
-  }
-
-  const maxSparse = computeMaxSparse(filtered);
-  const { dense_weight: baseDense, sparse_weight: baseSparse } =
-    config.memory.v2;
-  const { dense: denseWeight, sparse: sparseWeight } = effectiveWeights(
-    filtered,
-    maxSparse,
-    baseDense,
-    baseSparse,
-    config,
-  );
-
-  const scores = new Map<string, number>();
-  for (const hit of filtered) {
-    scores.set(hit.id, fuseHit(hit, maxSparse, denseWeight, sparseWeight));
-  }
-  return scores;
 }
 
 /**
- * Per-batch sparse-score maximum used for normalization. Hits missing from
- * the sparse channel contribute 0 (handled by the `undefined` guard).
+ * Per-batch sparse-score maximum used for normalization. The accessor picks
+ * which sparse channel to scan — `sparseScore` for the body channel,
+ * `summarySparseScore` for the summary channel. Hits missing from the
+ * channel contribute 0 (handled by the `undefined` guard).
  */
-function computeMaxSparse(
-  hits: ReadonlyArray<{ sparseScore?: number }>,
+function computeMaxSparse<T>(
+  hits: ReadonlyArray<T>,
+  accessor: (hit: T) => number | undefined,
 ): number {
   let max = 0;
   for (const hit of hits) {
-    if (hit.sparseScore !== undefined && hit.sparseScore > max) {
-      max = hit.sparseScore;
+    const value = accessor(hit);
+    if (value !== undefined && value > max) {
+      max = value;
     }
   }
   return max;
 }
 
 /**
- * Fuse a single hit's dense + sparse scores into a normalized [0, 1] score
+ * Fuse one half of a hit (body or summary) into a normalized [0, 1] score
  * via `clamp01(dense_weight · dense + sparse_weight · sparse/maxSparse)`.
- * Missing-channel scores contribute 0.
+ * Returns `undefined` when neither channel hit — a signal the half had no
+ * match at all, so the caller can fall back to the other half cleanly.
  */
-function fuseHit(
-  hit: { denseScore?: number; sparseScore?: number },
+function fuseHalf(
+  denseScore: number | undefined,
+  sparseScore: number | undefined,
   maxSparse: number,
   denseWeight: number,
   sparseWeight: number,
-): number {
-  const dense = hit.denseScore ?? 0;
+): number | undefined {
+  if (denseScore === undefined && sparseScore === undefined) return undefined;
+  const dense = denseScore ?? 0;
   const sparseNormalized =
-    hit.sparseScore !== undefined && maxSparse > 0
-      ? hit.sparseScore / maxSparse
-      : 0;
+    sparseScore !== undefined && maxSparse > 0 ? sparseScore / maxSparse : 0;
   return clamp01(denseWeight * dense + sparseWeight * sparseNormalized);
 }

package/src/memory/v2/skill-content.ts

@@ -2,9 +2,10 @@ import { getConfig } from "../../config/loader.js";
 import type { SkillCapabilityInput } from "../../skills/skill-memory.js";
 
 /**
- * Render the prose-style capability statement embedded into the
- * `memory_v2_skills` Qdrant collection and rendered in
- * `### Skills You Can Use`. Capped at 500 chars to match v1's behavior.
+ * Render the prose-style capability statement embedded into the unified
+ * `memory_v2_concept_pages` Qdrant collection (under the `skills/<id>` slug
+ * prefix) and rendered in `### Skills You Can Use`. Capped at 500 chars to
+ * match v1's behavior.
  */
 export function buildSkillContent(input: SkillCapabilityInput): string {
   let content = `The "${input.displayName}" skill (${input.id}) is available. ${input.description}.`;

package/src/memory/v2/skill-store.ts

@@ -2,18 +2,22 @@
 // Memory v2 — Skill catalog → embedded skill entries
 // ---------------------------------------------------------------------------
 //
-// Mirrors v1's `seedSkillGraphNodes` + `seedUninstalledCatalogSkillMemories`
-// (capability-seed.ts) for the v2 pipeline: enumerate the enabled-skill
-// catalog AND uninstalled catalog skills, render each skill's prose statement
-// via `buildSkillContent`, embed dense + sparse, upsert into the dedicated
-// `memory_v2_skills` Qdrant collection, and prune stale points from prior
-// catalog state. Including uninstalled catalog skills ensures their activation
-// hints are discoverable by intent so the model can auto-install them.
+// Enumerate the enabled-skill catalog AND uninstalled catalog skills, render
+// each skill's prose statement via `buildSkillContent`, embed dense + sparse,
+// and upsert into `memory_v2_concept_pages` under the slug `skills/<id>`.
+// Including uninstalled catalog skills ensures their activation hints are
+// discoverable by intent so the model can auto-install them.
 //
-// Unlike v1, skill entries are kept in a small in-process cache so the render
-// path can fetch a `SkillEntry` synchronously by id without round-tripping to
-// Qdrant. The cache is replaced atomically at the end of a successful seed
-// run; on error the prior cache stays intact (skills are best-effort).
+// Skills share the concept-page collection rather than living in a dedicated
+// one so the per-turn activation pipeline scores them against the same
+// candidate ANN as concept pages, with the same decay and spread machinery.
+// The render path branches on the `skills/` slug prefix to surface them as
+// the `### Skills You Can Use` subsection.
+//
+// Skill entries are kept in a small in-process cache so the render path can
+// fetch a `SkillEntry` synchronously by id without round-tripping to Qdrant.
+// The cache is replaced atomically at the end of a successful seed run; on
+// error the prior cache stays intact (skills are best-effort).
 
 import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getConfig } from "../../config/loader.js";
@@ -30,15 +34,31 @@ import {
   embedWithBackend,
   generateSparseEmbedding,
 } from "../embedding-backend.js";
+import {
+  pruneSlugsWithPrefixExcept,
+  upsertConceptPageEmbedding,
+} from "./qdrant.js";
 import {
   augmentMcpSetupDescription,
   buildSkillContent,
 } from "./skill-content.js";
-import { pruneSkillsExcept, upsertSkillEmbedding } from "./skill-qdrant.js";
 import type { SkillEntry } from "./types.js";
 
 const log = getLogger("memory-v2-skill-store");
 
+/**
+ * Slug prefix under which skill embeddings are indexed in
+ * `memory_v2_concept_pages`. Concept-page slugs must match
+ * `[a-z0-9][a-z0-9-]*(/...)*`, and `skills` matches that pattern, so the
+ * prefix coexists with hand-authored concept pages without escape work.
+ */
+export const SKILL_SLUG_PREFIX = "skills/";
+
+/** Compose the unified-collection slug for a skill id. */
+export function skillSlugFor(id: string): string {
+  return `${SKILL_SLUG_PREFIX}${id}`;
+}
+
 /**
  * Module-level cache of rendered skill entries keyed by skill id. `null` until
  * the first successful seed run completes; replaced atomically on each
@@ -47,30 +67,27 @@ const log = getLogger("memory-v2-skill-store");
 let entries: Map<string, SkillEntry> | null = null;
 
 /**
- * Seed (or re-seed) the v2 skill embedding collection from the live skill
- * catalog. Idempotent: safe to call repeatedly. Best-effort: never throws —
- * any failure leaves the prior `entries` cache in place and logs a warning.
+ * Seed (or re-seed) skill embeddings into the unified concept-page collection.
+ * Idempotent: safe to call repeatedly. Best-effort: never throws — any
+ * failure leaves the prior `entries` cache in place and logs a warning.
  *
  * Steps:
- *   1. Enumerate the local skill catalog and resolve each skill's enabled state
- *      (`resolveSkillStates`).
- *   2. Build a `SkillCapabilityInput` per enabled skill, applying the
- *      mcp-setup augmentation (mirrors v1) and the prose-style content render
- *      (`buildSkillContent`, capped at 500 chars).
+ *   1. Enumerate the local skill catalog and resolve each skill's enabled
+ *      state (`resolveSkillStates`).
+ *   2. Build a `SkillEntry` per enabled skill, applying the mcp-setup
+ *      augmentation and the prose-style content render (`buildSkillContent`,
+ *      capped at 500 chars).
  *   3. Defense-in-depth feature-flag filter: drop any skill whose declared
- *      `metadata.vellum.feature-flag` is currently disabled. `resolveSkillStates`
- *      already enforces this, but we mirror v1's enforcement point so the v2
- *      collection never holds an embedding for a flag-gated skill if the two
- *      ever drift.
- *   3b. Fetch the full remote catalog and seed any uninstalled skills so their
- *      activation hints are discoverable by semantic search. Best-effort: if
- *      the catalog fetch fails, only installed skills are seeded.
+ *      `metadata.vellum.feature-flag` is currently disabled.
+ *   3b. Fetch the full remote catalog and seed any uninstalled skills so
+ *      their activation hints are discoverable by semantic search. Best-effort:
+ *      if the catalog fetch fails, only installed skills are seeded.
  *   4. Embed all `content` strings in a single dense `embedWithBackend` call,
  *      and a per-skill synchronous `generateSparseEmbedding`.
- *   5. Upsert one Qdrant point per skill via `upsertSkillEmbedding` (keyed
- *      deterministically on id so re-runs replace in place).
- *   6. Call `pruneSkillsExcept` with the active id list to drop any stale
- *      points from prior catalog state (e.g. uninstalled skills).
+ *   5. Upsert one Qdrant point per skill via `upsertConceptPageEmbedding`
+ *      keyed deterministically on slug `skills/<id>`.
+ *   6. Call `pruneSlugsWithPrefixExcept(SKILL_SLUG_PREFIX, ...)` to drop any
+ *      stale points from prior catalog state (e.g. uninstalled skills).
  *   7. Replace the module-level `entries` cache with the freshly built map.
  */
 export async function seedV2SkillEntries(): Promise<void> {
@@ -83,8 +100,7 @@ export async function seedV2SkillEntries(): Promise<void> {
     // Track every locally-installed skill id (regardless of enabled/disabled
     // state) so the catalog-seeding loop below treats them all as "installed"
     // and never re-seeds a disabled skill from `getCatalog()` as if it were
-    // uninstalled. Mirrors v1's `seedUninstalledCatalogSkillMemories`, which
-    // keys off `loadSkillCatalog()` (the installed set) for the same reason.
+    // uninstalled.
     const installedIds = new Set<string>(catalog.map((s) => s.id));
 
     // Build the input list, applying the mcp-setup description augmentation
@@ -100,8 +116,8 @@ export async function seedV2SkillEntries(): Promise<void> {
     }
 
     // Seed uninstalled catalog skills so their activation hints are
-    // discoverable by intent (mirrors v1's seedUninstalledCatalogSkillMemories).
-    // Track whether the catalog was available so we can guard pruning below.
+    // discoverable by intent. Track whether the catalog was available so we
+    // can guard pruning below.
     let catalogAvailable = false;
     try {
       const fullCatalog = await getCatalog();
@@ -135,24 +151,29 @@ export async function seedV2SkillEntries(): Promise<void> {
 
     const now = Date.now();
     const nextEntries = new Map<string, SkillEntry>();
-    for (let i = 0; i < seeds.length; i++) {
-      const seed = seeds[i];
-      await upsertSkillEmbedding({
-        ...seed,
-        dense: denseVectors[i],
-        sparse: generateSparseEmbedding(seed.content),
-        updatedAt: now,
-      });
+    await Promise.all(
+      seeds.map((seed, i) =>
+        upsertConceptPageEmbedding({
+          slug: skillSlugFor(seed.id),
+          dense: denseVectors[i],
+          sparse: generateSparseEmbedding(seed.content),
+          updatedAt: now,
+        }),
+      ),
+    );
+    for (const seed of seeds) {
       nextEntries.set(seed.id, seed);
     }
 
-    // Prune stale points. When the catalog is unavailable (empty array from
-    // network failure or cold cache), we cannot enumerate which uninstalled
-    // catalog skills should exist, so skip pruning entirely to avoid
-    // aggressively removing previously-seeded catalog skill embeddings.
-    // Mirrors v1's safeguard in capability-seed.ts (lines 124–143).
+    // Prune stale skill slugs. When the catalog is unavailable (empty array
+    // from network failure or cold cache), we cannot enumerate which
+    // uninstalled catalog skills should exist, so skip pruning entirely to
+    // avoid aggressively removing previously-seeded catalog skill embeddings.
     if (catalogAvailable) {
-      await pruneSkillsExcept(seeds.map((s) => s.id));
+      await pruneSlugsWithPrefixExcept(
+        SKILL_SLUG_PREFIX,
+        seeds.map((s) => s.id),
+      );
     } else {
       log.info(
         "Catalog unavailable — skipping skill pruning to preserve prior catalog embeddings",
@@ -169,20 +190,22 @@ export async function seedV2SkillEntries(): Promise<void> {
 /**
  * Synchronous lookup of a previously-seeded `SkillEntry` by skill id. Returns
  * `null` when the cache has not yet been populated, when the id is unknown,
- * or when a prior seed run dropped the id (e.g. the skill was disabled). Used
- * by the render path to attach skill-related content to outgoing prompts.
+ * or when a prior seed run dropped the id (e.g. the skill was disabled).
+ *
+ * Accepts either a bare skill id (`example-skill`) or its unified-collection
+ * slug (`skills/example-skill`) so render-side callers can pass through what
+ * they have without a manual prefix strip.
  */
-export function getSkillCapability(id: string): SkillEntry | null {
+export function getSkillCapability(idOrSlug: string): SkillEntry | null {
+  const id = idOrSlug.startsWith(SKILL_SLUG_PREFIX)
+    ? idOrSlug.slice(SKILL_SLUG_PREFIX.length)
+    : idOrSlug;
   return entries?.get(id) ?? null;
 }
 
-/**
- * Every skill id in the cache — both installed-and-enabled skills and
- * uninstalled-catalog skills. Empty before the first `seedV2SkillEntries`
- * run completes.
- */
-export function getAllSkillIds(): string[] {
-  return entries ? [...entries.keys()] : [];
+/** True iff the slug refers to a skill entry in the unified collection. */
+export function isSkillSlug(slug: string): boolean {
+  return slug.startsWith(SKILL_SLUG_PREFIX);
 }
 
 /** @internal Test-only: clear the module-level cache. */

package/src/memory/v2/static-context.ts

@@ -17,7 +17,7 @@
 // content through when `mode === "full"` (first turn / post-compaction),
 // matching the existing PKB auto-inject pattern.
 
-import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
+import type { ChannelId } from "../../channels/types.js";
 import { loadConfig } from "../../config/loader.js";
 import { readPromptFile } from "../../prompts/system-prompt.js";
 import { getWorkspacePromptPath } from "../../util/platform.js";
@@ -35,9 +35,9 @@ const MEMORY_V2_STATIC_BLOCKS: readonly MemoryV2StaticBlock[] = [
 ];
 
 /**
- * Build the v2 static memory block, gated on `memory-v2-enabled` +
- * `config.memory.v2.enabled`. Empty/missing files are skipped; returns
- * `null` when the gate is off or every file is empty.
+ * Build the v2 static memory block, gated on `config.memory.v2.enabled`.
+ * Empty/missing files are skipped; returns `null` when the gate is off or
+ * every file is empty.
  */
 export function readMemoryV2StaticContent(): string | null {
   let config;
@@ -46,10 +46,7 @@ export function readMemoryV2StaticContent(): string | null {
   } catch {
     return null;
   }
-  if (
-    !isAssistantFeatureFlagEnabled("memory-v2-enabled", config) ||
-    !config.memory.v2.enabled
-  ) {
+  if (!config.memory.v2.enabled) {
     return null;
   }
 
@@ -61,3 +58,24 @@ export function readMemoryV2StaticContent(): string | null {
   }
   return sections.length > 0 ? sections.join("\n\n") : null;
 }
+
+/**
+ * Static memory holds the user's aggregate personal pages
+ * (essentials/threads/recent/buffer). Block injection when a non-guardian
+ * actor reaches the assistant over a remote channel — otherwise the model
+ * can be prompt-injected into reciting private memory. Internal flows
+ * (`sourceChannel: "vellum"`) and turns with no trust context pass through
+ * unchanged; this gate exists only to keep remote untrusted actors out.
+ */
+export function shouldLoadMemoryV2Static(args: {
+  shouldInjectNowAndPkb: boolean;
+  sourceChannel: ChannelId | undefined;
+  isTrustedActor: boolean;
+}): boolean {
+  if (!args.shouldInjectNowAndPkb) return false;
+  const isRemoteUntrustedActor =
+    args.sourceChannel !== undefined &&
+    args.sourceChannel !== "vellum" &&
+    !args.isTrustedActor;
+  return !isRemoteUntrustedActor;
+}

package/src/memory/v2/sweep-job.ts

@@ -13,10 +13,10 @@
  * extraction-trigger path. Until then this handler is invoked only by
  * `memory_v2_sweep` rows enqueued explicitly (tests, future CLI).
  *
- * Skipped entirely when the `memory-v2-enabled` feature flag is off, or when
+ * Skipped entirely when `config.memory.v2.enabled` is false, or when
  * `config.memory.v2.sweep_enabled` is false — keeps the sweep dormant in
  * v1-only workspaces and in v2 workspaces that haven't opted in, even if a
- * stale row sits in the queue at flag-flip time.
+ * stale row sits in the queue when v2 is disabled.
  */
 
 import { readFileSync } from "node:fs";
@@ -25,7 +25,6 @@ import { join } from "node:path";
 import { desc, gt } from "drizzle-orm";
 import { z } from "zod";
 
-import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import type { AssistantConfig } from "../../config/types.js";
 import { getAssistantName } from "../../daemon/identity-helpers.js";
 import {
@@ -104,12 +103,12 @@ export async function memoryV2SweepJob(
   _job: MemoryJob,
   config: AssistantConfig,
 ): Promise<number> {
-  if (!isAssistantFeatureFlagEnabled("memory-v2-enabled", config)) {
-    log.debug("memory-v2-enabled flag off; sweep skipped");
+  if (!config.memory?.v2?.enabled) {
+    log.debug("memory.v2.enabled is false; sweep skipped");
     return 0;
   }
 
-  if (!config.memory?.v2?.sweep_enabled) {
+  if (!config.memory.v2.sweep_enabled) {
     log.debug("memory.v2.sweep_enabled is false; sweep skipped");
     return 0;
   }

package/src/memory/v2/types.ts

@@ -26,10 +26,17 @@ import { z } from "zod";
  * B → A. The full graph is the union of every page's `edges:` list — there
  * is no separate edges-index file. `ref_files` lists paths to attached media
  * (images, audio, etc.).
+ *
+ * `summary` is a 1-4 sentence prose description of the page. When present,
+ * retrieval injects the path + summary instead of the full page so the agent
+ * can decide whether to read the file. Optional because legacy pages predating
+ * the summary field still parse — those fall back to full-page injection and
+ * full-page-only similarity.
  */
 export const ConceptPageFrontmatterSchema = z.object({
   edges: z.array(z.string()).default([]),
   ref_files: z.array(z.string()).default([]),
+  summary: z.string().optional(),
 });
 
 export type ConceptPageFrontmatter = z.infer<
@@ -85,20 +92,20 @@ export const ActivationStateSchema = z.object({
 export type ActivationState = z.infer<typeof ActivationStateSchema>;
 
 // ---------------------------------------------------------------------------
-// Skill autoinjection (synthetic in-memory entries, not on-disk pages)
+// Skill entries (synthetic concept-collection rows, not on-disk pages)
 // ---------------------------------------------------------------------------
 
 /**
- * Per-skill capability snapshot held in-process and embedded into the
- * `memory_v2_skills` Qdrant collection. `content` is the rendered
- * `buildSkillContent` string — already capped at 500 chars upstream and
- * already containing the skill's display name — and is what we embed and
- * what we render verbatim in `### Skills You Can Use`.
+ * Per-skill capability snapshot held in-process and embedded into the unified
+ * `memory_v2_concept_pages` Qdrant collection under the slug `skills/<id>`.
+ * `content` is the rendered `buildSkillContent` string — already capped at
+ * 500 chars upstream and already containing the skill's display name — and
+ * is what we embed and what we render verbatim in `### Skills You Can Use`.
  *
- * Plain interface (no Zod) because skill data does not cross a
- * serialization boundary: it is built in-process by `seedV2SkillEntries`
- * and read in-process by `renderInjectionBlock`. The Qdrant payload is
- * not parsed back through this type.
+ * Plain interface (no Zod) because skill data does not cross a serialization
+ * boundary: it is built in-process by `seedV2SkillEntries` and read in-process
+ * by `renderInjectionBlock`. The Qdrant payload is not parsed back through
+ * this type.
  */
 export interface SkillEntry {
   id: string;