@vellumai/assistant 0.7.3 → 0.8.0

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

@@ -1,10 +1,11 @@
 /**
  * Tests for `assistant/src/memory/v2/sweep-job.ts`.
  *
- * Coverage matrix (from PR 18 acceptance criteria):
- *   - Flag off → no provider/DB calls, returns 0 (early bail).
- *   - Flag on + no recent messages → no provider call, returns 0.
- *   - Flag on + recent messages → provider invoked with rendered prompt;
+ * Coverage matrix:
+ *   - v2 disabled in config → no provider/DB calls, returns 0 (early bail).
+ *   - sweep_enabled off → no provider call, returns 0.
+ *   - v2 on + no recent messages → no provider call, returns 0.
+ *   - v2 on + recent messages → provider invoked with rendered prompt;
  *     each entry is appended to `memory/buffer.md` AND today's archive.
  *   - Tool-call response shape mismatch → returns 0 without writes.
  *   - Empty entries are skipped (the model can't pad the buffer).
@@ -24,7 +25,6 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   afterAll,
-  afterEach,
   beforeAll,
   beforeEach,
   describe,
@@ -85,23 +85,20 @@ afterAll(() => {
 const { resetDb, getDb } = await import("../../db-connection.js");
 const { initializeDb } = await import("../../db-init.js");
 const { messages, conversations } = await import("../../schema.js");
-const { _setOverridesForTesting } =
-  await import("../../../config/assistant-feature-flags.js");
 const { memoryV2SweepJob } = await import("../sweep-job.js");
 
-// `isAssistantFeatureFlagEnabled` ignores the `config` argument it receives
-// (resolution is purely from the overrides + registry caches), so we hand
-// the handler a minimal stand-in instead of materializing the full default
+// The handler reads `config.memory.v2.enabled` and `sweep_enabled`, so we
+// hand it a minimal stand-in instead of materializing the full default
 // config — which would otherwise pull in heavy schemas this test doesn't
-// exercise. The handler reads `config.memory.v2.sweep_enabled`, so the
-// `flag on` cases need the field set; the `flag off` case bails before
-// the check and uses the bare empty stand-in.
+// exercise.
 const CONFIG = {
-  memory: { v2: { sweep_enabled: true } },
+  memory: { v2: { enabled: true, sweep_enabled: true } },
+} as Parameters<typeof memoryV2SweepJob>[1];
+const CONFIG_V2_OFF = {
+  memory: { v2: { enabled: false, sweep_enabled: true } },
 } as Parameters<typeof memoryV2SweepJob>[1];
-const CONFIG_FLAG_OFF = {} as Parameters<typeof memoryV2SweepJob>[1];
 const CONFIG_SWEEP_OFF = {
-  memory: { v2: { sweep_enabled: false } },
+  memory: { v2: { enabled: true, sweep_enabled: false } },
 } as Parameters<typeof memoryV2SweepJob>[1];
 
 function makeJob(): Parameters<typeof memoryV2SweepJob>[0] {
@@ -205,18 +202,13 @@ beforeEach(() => {
   providerStub = null;
 });
 
-afterEach(() => {
-  _setOverridesForTesting({});
-});
-
 // ---------------------------------------------------------------------------
 
-describe("memoryV2SweepJob — flag off", () => {
-  test("returns 0 without invoking the provider when flag is off", async () => {
-    _setOverridesForTesting({ "memory-v2-enabled": false });
+describe("memoryV2SweepJob — v2 disabled", () => {
+  test("returns 0 without invoking the provider when memory.v2.enabled is false", async () => {
     providerStub = makeEntriesProvider(["should-not-be-written"]);
 
-    const written = await memoryV2SweepJob(makeJob(), CONFIG_FLAG_OFF);
+    const written = await memoryV2SweepJob(makeJob(), CONFIG_V2_OFF);
 
     expect(written).toBe(0);
     expect(providerCalls).toHaveLength(0);
@@ -224,9 +216,8 @@ describe("memoryV2SweepJob — flag off", () => {
   });
 });
 
-describe("memoryV2SweepJob — flag on, sweep_enabled off", () => {
+describe("memoryV2SweepJob — sweep_enabled off", () => {
   test("returns 0 without invoking the provider when sweep_enabled is false", async () => {
-    _setOverridesForTesting({ "memory-v2-enabled": true });
     // No message seeding required — the sweep_enabled bail short-circuits
     // before any DB or workspace reads.
     providerStub = makeEntriesProvider(["should-not-be-written"]);
@@ -239,11 +230,7 @@ describe("memoryV2SweepJob — flag on, sweep_enabled off", () => {
   });
 });
 
-describe("memoryV2SweepJob — flag on, no recent messages", () => {
-  beforeEach(() => {
-    _setOverridesForTesting({ "memory-v2-enabled": true });
-  });
-
+describe("memoryV2SweepJob — no recent messages", () => {
   test("returns 0 when no messages exist in the recent window", async () => {
     providerStub = makeEntriesProvider(["should-not-be-written"]);
 
@@ -273,9 +260,8 @@ describe("memoryV2SweepJob — flag on, no recent messages", () => {
 // DB intact long enough for the SQL inserts here to clash.
 let convCounter = 0;
 
-describe("memoryV2SweepJob — flag on, recent messages", () => {
+describe("memoryV2SweepJob — recent messages", () => {
   beforeEach(() => {
-    _setOverridesForTesting({ "memory-v2-enabled": true });
     seedMessages(`conv-${++convCounter}`, [
       {
         role: "user",

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

@@ -15,8 +15,8 @@
  * substitute in.
  *
  * Lifecycle:
- *   1. Bail if the `memory-v2-enabled` feature flag is off (the worker may
- *      have claimed a stale row at flag-flip time).
+ *   1. Bail if `config.memory.v2.enabled` is false (the worker may have
+ *      claimed a stale row from before v2 was disabled).
  *   2. Acquire a single-process lock at `memory/.v2-state/consolidation.lock`
  *      so two overlapping schedule windows can't fight over the same files.
  *      The lock contains the holder's PID + timestamp so a crashed run leaves
@@ -53,7 +53,6 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 
-import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import type { AssistantConfig } from "../../config/types.js";
 import { INTERNAL_GUARDIAN_TRUST_CONTEXT } from "../../daemon/trust-context.js";
 import { wakeAgentForOpportunity } from "../../runtime/agent-wake.js";
@@ -85,11 +84,11 @@ const FOLLOW_UP_JOB_TYPES: readonly MemoryJobType[] = [
 
 /**
  * Job handler. See file header for the full lifecycle. Returns a discriminated
- * union so tests can assert on the path taken (flag-off / locked / empty /
+ * union so tests can assert on the path taken (disabled / locked / empty /
  * invoked) without having to spy on the filesystem.
  */
 export type ConsolidationOutcome =
-  | { kind: "flag_off" }
+  | { kind: "disabled" }
   | { kind: "locked"; holder: string }
   | { kind: "empty_buffer" }
   | { kind: "wake_failed"; reason?: string }
@@ -104,9 +103,9 @@ export async function memoryV2ConsolidateJob(
   _job: MemoryJob,
   config: AssistantConfig,
 ): Promise<ConsolidationOutcome> {
-  if (!isAssistantFeatureFlagEnabled("memory-v2-enabled", config)) {
-    log.debug("memory-v2-enabled flag off; consolidation skipped");
-    return { kind: "flag_off" };
+  if (!config.memory.v2.enabled) {
+    log.debug("memory.v2.enabled is false; consolidation skipped");
+    return { kind: "disabled" };
   }
 
   const memoryDir = join(getWorkspaceDir(), "memory");

package/src/memory/v2/injection.ts

@@ -360,6 +360,16 @@ interface RenderInjectionBlockResult {
   missingSlugs: string[];
 }
 
+/**
+ * Leading instruction line emitted at the top of every non-empty injection
+ * block. Tells the agent that what follows are page summaries and that it
+ * should read the underlying file when a summary looks relevant. Pages
+ * without a `summary` field render in full instead — the agent treats
+ * those as inline content and doesn't need to follow up.
+ */
+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
@@ -383,23 +393,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.
+ *
+ *   **CRITICAL:** These are page summaries. Read the page file if it looks relevant.
+ *
+ *   # memory/concepts/<concept-slug-1>.md
+ *   <summary-1>
  *
- *   ### <concept-slug-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
@@ -427,9 +438,18 @@ async function renderInjectionBlock(
       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}`);
+      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[] = [];
@@ -445,7 +465,7 @@ async function renderInjectionBlock(
   if (sections.length === 0) return { block: null, missingSlugs };
 
   return {
-    block: sections.join("\n\n"),
+    block: `${INJECTION_HEADER}\n\n${sections.join("\n\n")}`,
     missingSlugs,
   };
 }

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

@@ -338,6 +338,45 @@ export async function listPages(workspaceDir: string): Promise<string[]> {
   return slugs;
 }
 
+/**
+ * Cheap "do any concept pages exist?" probe — walks the concepts/ tree only
+ * far enough to find one `.md` file and returns immediately. Used by the
+ * daemon-startup rebuild gate so the empty-after-create recovery path skips
+ * a full enumeration of all 1000+ pages just to ask a yes/no question.
+ */
+export async function hasConceptPages(workspaceDir: string): Promise<boolean> {
+  const root = getConceptsDir(workspaceDir);
+  const queue: string[] = [root];
+
+  while (queue.length > 0) {
+    const dir = queue.shift()!;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        if (dir === root) return false;
+        continue;
+      }
+      throw err;
+    }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      if (entry.isDirectory()) {
+        queue.push(join(dir, entry.name));
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (!entry.name.endsWith(PAGE_EXTENSION)) continue;
+      if (entry.name.includes(".tmp.")) continue;
+      return true;
+    }
+  }
+
+  return false;
+}
+
 /**
  * Delete a concept page. Idempotent — missing files are not an error.
  *

package/src/memory/v2/prompts/consolidation.ts

@@ -131,6 +131,7 @@ edges:
   - path/to/sister
   - path/to/parent
 ref_files: []
+summary: 1-4 sentences describing what this article is. Plain prose only — no bullets, no newlines, no markdown lists. Lead with the most identifying detail.
 ---
 # title
 
@@ -140,6 +141,8 @@ ref_files: []
 - **bullet 2.** ...
 \`\`\`
 
+The \`summary\` field is required on every new or updated article. Retrieval injects \`path + summary\` into context — the agent reads the full file only when the summary looks relevant — so make the summary specific and terse. Keep it on a single YAML line (no \`|\` block scalars, no embedded newlines).
+
 **Caps:** ~5-8 bullets per topic/concept article. ~10-12 per arc-node (which can use bold inline labels: \`**the open**: ...\`).
 
 ## One fact, one home
@@ -285,6 +288,7 @@ edges:
   - some-named-phrase
   - objects/some-artifact
 ref_files: []
+summary: A short prose description of the article — 1-4 sentences, single line.
 ---
 \`\`\`
 
@@ -416,6 +420,7 @@ For each article you touched:
 9. **Spawn check.** Did you ask "what's recognizable here?" not "what have I earned?" Did you catch any hedging — and spawn anyway? Any fold-into-parent / defer stealth-skips you almost did?
 10. **Split-not-compress.** If anything went over cap, did you split? If you compressed, can you name the rationale in one sentence?
 11. **Edges.** Outgoing within tiered caps (atomic ≤10, arc ≤15, gravity well ≤25, hard limit 20 on non-hubs)? No noise-edges to gravity wells from non-arc pages?
+11a. **Summary present.** Every new or updated article has a \`summary:\` line — 1-4 sentences, single YAML line, lead with the identifying detail.
 12. **Topic coherence.** Does each article answer ONE question? Gravity wells acting as hubs (pointing at topic articles), not absorbing body?
 13. **\`recent.md\`** under 2000 chars, today=full / older=one-liners?
 14. **\`[SOURCE NEEDED]\`** tags surfaced for human review?