@vellumai/assistant 0.7.0 → 0.7.1

package/src/__tests__/context-search-memory-source.test.ts

@@ -1,7 +1,12 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
+import { _setOverridesForTesting } from "../config/assistant-feature-flags.js";
 import type { AssistantConfig } from "../config/schema.js";
-import type { RecallSearchContext } from "../memory/context-search/types.js";
+import type {
+  RecallEvidence,
+  RecallSearchContext,
+  RecallSearchResult,
+} from "../memory/context-search/types.js";
 import type { MemoryNode } from "../memory/graph/types.js";
 
 const loggerModule = import.meta.resolve("../util/logger.js");
@@ -11,6 +16,8 @@ const embeddingBackendModule = import.meta
 const graphSearchModule = import.meta
   .resolve("../memory/graph/graph-search.js");
 const graphStoreModule = import.meta.resolve("../memory/graph/store.js");
+const memoryV2SourceModule = import.meta
+  .resolve("../memory/context-search/sources/memory-v2.js");
 
 const warnCalls: unknown[][] = [];
 mock.module(loggerModule, () => ({
@@ -48,6 +55,11 @@ mock.module(embedModule, () => ({
 }));
 
 mock.module(embeddingBackendModule, () => ({
+  embedWithBackend: async () => ({
+    provider: "test",
+    model: "test-model",
+    vectors: [[0.1, 0.2, 0.3]],
+  }),
   generateSparseEmbedding: (text: string) =>
     text.trim().length === 0
       ? { indices: [], values: [] }
@@ -90,6 +102,28 @@ mock.module(graphStoreModule, () => ({
   },
 }));
 
+const v2Calls: Array<{
+  query: string;
+  context: RecallSearchContext;
+  limit: number;
+}> = [];
+let v2EvidenceReturn: RecallEvidence[] = [];
+
+const realMemoryV2 =
+  await import("../memory/context-search/sources/memory-v2.js");
+
+mock.module(memoryV2SourceModule, () => ({
+  isMemoryV2ReadActive: realMemoryV2.isMemoryV2ReadActive,
+  searchMemoryV2Source: async (
+    query: string,
+    context: RecallSearchContext,
+    limit: number,
+  ): Promise<RecallSearchResult> => {
+    v2Calls.push({ query, context, limit });
+    return { evidence: v2EvidenceReturn };
+  },
+}));
+
 const { searchMemorySource } =
   await import("../memory/context-search/sources/memory.js");
 
@@ -104,6 +138,9 @@ describe("searchMemorySource", () => {
     searchCalls.length = 0;
     hydratedNodes = [];
     getNodesByIdsCalls.length = 0;
+    v2Calls.length = 0;
+    v2EvidenceReturn = [];
+    _setOverridesForTesting({ "memory-v2-enabled": false });
   });
 
   test("hydrates graph hits into memory recall evidence", async () => {
@@ -263,8 +300,90 @@ describe("searchMemorySource", () => {
       "Failed to search memory graph for recall",
     );
   });
+
+  test("routes to v2 source when both v2 gates are on", async () => {
+    _setOverridesForTesting({ "memory-v2-enabled": true });
+    v2EvidenceReturn = [
+      {
+        id: "memory:v2:alice",
+        source: "memory",
+        title: "alice",
+        locator: "memory/concepts/alice.md",
+        excerpt: "Alice prefers concise notes.",
+        score: 0.9,
+        metadata: {
+          path: "memory/concepts/alice.md",
+          slug: "alice",
+          retrieval: "activation",
+        },
+      },
+    ];
+
+    const result = await searchMemorySource(
+      "alice",
+      makeContext({
+        config: makeV2EnabledConfig(),
+      }),
+      6,
+    );
+
+    expect(v2Calls).toHaveLength(1);
+    expect(v2Calls[0]?.query).toBe("alice");
+    expect(v2Calls[0]?.limit).toBe(6);
+    expect(searchCalls).toHaveLength(0);
+    expect(getNodesByIdsCalls).toHaveLength(0);
+    expect(result.evidence.map((e) => e.locator)).toEqual([
+      "memory/concepts/alice.md",
+    ]);
+  });
+
+  test("stays on legacy path when feature flag is on but config.memory.v2.enabled is off", async () => {
+    _setOverridesForTesting({ "memory-v2-enabled": true });
+    searchHits = [{ nodeId: "node-a", score: 0.7, text: "" }];
+    hydratedNodes = [makeNode({ id: "node-a", content: "Legacy hit" })];
+
+    await searchMemorySource(
+      "alice",
+      makeContext({ config: makeV2DisabledConfig() }),
+      5,
+    );
+
+    expect(v2Calls).toHaveLength(0);
+    expect(searchCalls).toHaveLength(1);
+  });
+
+  test("stays on legacy path when feature flag is off", async () => {
+    _setOverridesForTesting({ "memory-v2-enabled": false });
+    searchHits = [{ nodeId: "node-a", score: 0.7, text: "" }];
+    hydratedNodes = [makeNode({ id: "node-a", content: "Legacy hit" })];
+
+    await searchMemorySource(
+      "alice",
+      makeContext({ config: makeV2EnabledConfig() }),
+      5,
+    );
+
+    expect(v2Calls).toHaveLength(0);
+    expect(searchCalls).toHaveLength(1);
+  });
 });
 
+function makeV2EnabledConfig(): AssistantConfig {
+  return {
+    memory: {
+      v2: { enabled: true },
+    },
+  } as unknown as AssistantConfig;
+}
+
+function makeV2DisabledConfig(): AssistantConfig {
+  return {
+    memory: {
+      v2: { enabled: false },
+    },
+  } as unknown as AssistantConfig;
+}
+
 function makeContext(
   overrides: Partial<RecallSearchContext> = {},
 ): RecallSearchContext {

package/src/__tests__/context-search-memory-v2-source.test.ts

@@ -0,0 +1,383 @@
+/**
+ * Tests for `assistant/src/memory/context-search/sources/memory-v2.ts`.
+ *
+ * Covers the recall-side adapter the `memory` source delegates to when the
+ * v2 flag is on. Two retrieval paths run in parallel:
+ *   - Activation + 2-hop spreading over the v2 concept-page Qdrant collection.
+ *   - Lexical file-search fallback over `<workspace>/memory/concepts/*.md`.
+ *
+ * The activation path is exercised by mocking `hybridQueryConceptPages`,
+ * `getEdgeIndex`, and `readPage`. The lexical fallback is exercised against
+ * a real temp workspace so its directory walk and term scoring run end-to-end.
+ *
+ * Generic placeholders (`alice`, `bob`, etc.) per the cross-cutting safety
+ * rules. Tests are hermetic — no live Qdrant, no embedding backend round-trip.
+ */
+import {
+  mkdirSync,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { AssistantConfig } from "../config/schema.js";
+import type { RecallSearchContext } from "../memory/context-search/types.js";
+import type { EdgeIndex } from "../memory/v2/edge-index.js";
+import type { ConceptPage } from "../memory/v2/types.js";
+import { makeMockLogger } from "./helpers/mock-logger.js";
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () => makeMockLogger(),
+}));
+
+let denseEmbedReturn: number[] = [0.1, 0.2, 0.3];
+mock.module("../memory/embedding-backend.js", () => ({
+  embedWithBackend: async () => ({
+    provider: "test",
+    model: "test-model",
+    vectors: [denseEmbedReturn],
+  }),
+  generateSparseEmbedding: () => ({ indices: [1], values: [1] }),
+}));
+
+interface QdrantHit {
+  slug: string;
+  denseScore?: number;
+  sparseScore?: number;
+}
+
+let qdrantHits: QdrantHit[] = [];
+let qdrantThrows: Error | null = null;
+const qdrantCalls: Array<{ limit: number }> = [];
+
+mock.module("../memory/v2/qdrant.js", () => ({
+  hybridQueryConceptPages: async (
+    _dense: number[],
+    _sparse: { indices: number[]; values: number[] },
+    limit: number,
+  ): Promise<QdrantHit[]> => {
+    qdrantCalls.push({ limit });
+    if (qdrantThrows) throw qdrantThrows;
+    return qdrantHits;
+  },
+}));
+
+let edgeIndex: EdgeIndex = {
+  outgoing: new Map<string, Set<string>>(),
+  incoming: new Map<string, Set<string>>(),
+};
+
+mock.module("../memory/v2/edge-index.js", () => ({
+  getEdgeIndex: async (): Promise<EdgeIndex> => edgeIndex,
+  invalidateEdgeIndex: () => {},
+  getReachable: () => new Set<string>(),
+  validateEdgeTargets: () => ({ ok: true, missing: [] }),
+  totalEdgeCount: () => 0,
+}));
+
+const pageStore = new Map<string, ConceptPage>();
+
+mock.module("../memory/v2/page-store.js", () => ({
+  getConceptsDir: (workspaceDir: string): string =>
+    join(workspaceDir, "memory", "concepts"),
+  listPages: async (): Promise<string[]> => [...pageStore.keys()],
+  readPage: async (
+    _workspaceDir: string,
+    slug: string,
+  ): Promise<ConceptPage | null> => pageStore.get(slug) ?? null,
+  writePage: async () => {},
+  deletePage: async () => {},
+  slugFromConceptPath: (conceptsRoot: string, filePath: string): string => {
+    const rel = filePath.startsWith(conceptsRoot)
+      ? filePath.slice(conceptsRoot.length).replace(/^\/+/, "")
+      : filePath;
+    return rel.endsWith(".md") ? rel.slice(0, -3) : rel;
+  },
+  validateSlug: () => {},
+}));
+
+const { searchMemoryV2Source } =
+  await import("../memory/context-search/sources/memory-v2.js");
+
+const testDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of testDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function makeTempDir(): string {
+  const dir = realpathSync(
+    mkdtempSync(join(tmpdir(), "context-search-memory-v2-")),
+  );
+  testDirs.push(dir);
+  return dir;
+}
+
+function writeFile(root: string, relativePath: string, body: string): void {
+  const filePath = join(root, relativePath);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, body);
+}
+
+function writeConceptPage(root: string, slug: string, body: string): void {
+  writeFile(
+    root,
+    `memory/concepts/${slug}.md`,
+    `---\nedges: []\nref_files: []\n---\n${body}`,
+  );
+}
+
+function makeConfig(): AssistantConfig {
+  return {
+    memory: {
+      v2: {
+        enabled: true,
+        dense_weight: 0.6,
+        sparse_weight: 0.4,
+        k: 0.5,
+        hops: 2,
+        epsilon: 0.05,
+        d: 0.5,
+        c_user: 1,
+        c_assistant: 0.5,
+        c_now: 0.5,
+        top_k: 8,
+        top_k_skills: 0,
+      },
+    },
+  } as unknown as AssistantConfig;
+}
+
+function makeContext(workingDir: string): RecallSearchContext {
+  return {
+    workingDir,
+    memoryScopeId: "scope-default",
+    conversationId: "conv-test",
+    config: makeConfig(),
+  };
+}
+
+beforeEach(() => {
+  qdrantHits = [];
+  qdrantThrows = null;
+  qdrantCalls.length = 0;
+  edgeIndex = {
+    outgoing: new Map<string, Set<string>>(),
+    incoming: new Map<string, Set<string>>(),
+  };
+  pageStore.clear();
+  denseEmbedReturn = [0.1, 0.2, 0.3];
+});
+
+describe("searchMemoryV2Source", () => {
+  test("returns activation evidence with memory/concepts/<slug>.md locators", async () => {
+    const root = makeTempDir();
+    writeConceptPage(root, "alice", "Alice prefers concise notes.\n");
+
+    qdrantHits = [{ slug: "alice", denseScore: 0.9 }];
+    pageStore.set("alice", {
+      slug: "alice",
+      frontmatter: { edges: [], ref_files: [] },
+      body: "Alice prefers concise notes.",
+    });
+
+    const result = await searchMemoryV2Source("alice", makeContext(root), 5);
+
+    expect(result.evidence.length).toBeGreaterThan(0);
+    const activationHit = result.evidence.find(
+      (e) => e.metadata?.retrieval === "activation",
+    );
+    expect(activationHit).toBeDefined();
+    expect(activationHit?.locator).toBe("memory/concepts/alice.md");
+    expect(activationHit?.title).toBe("alice");
+    expect(activationHit?.excerpt).toContain("Alice prefers concise notes");
+    expect(activationHit?.metadata?.path).toBe("memory/concepts/alice.md");
+    expect(activationHit?.metadata?.slug).toBe("alice");
+    expect(qdrantCalls.length).toBeGreaterThan(0);
+  });
+
+  test("falls back to lexical evidence when activation finds nothing", async () => {
+    const root = makeTempDir();
+    writeConceptPage(
+      root,
+      "bob",
+      "# Bob\n\nBob's birthday party plans for next month.\n",
+    );
+
+    qdrantHits = [];
+
+    const result = await searchMemoryV2Source(
+      "birthday party",
+      makeContext(root),
+      5,
+    );
+
+    expect(result.evidence.length).toBeGreaterThan(0);
+    const lexicalHit = result.evidence.find(
+      (e) => e.metadata?.retrieval === "lexical",
+    );
+    expect(lexicalHit).toBeDefined();
+    expect(lexicalHit?.metadata?.path).toBe("memory/concepts/bob.md");
+    expect(lexicalHit?.locator).toMatch(/^memory\/concepts\/bob\.md:\d+$/);
+    expect(lexicalHit?.excerpt).toContain("birthday");
+  });
+
+  test("returns lexical evidence when Qdrant is unavailable", async () => {
+    const root = makeTempDir();
+    writeConceptPage(
+      root,
+      "carol",
+      "# Carol\n\nCarol joined the launch checklist review.\n",
+    );
+
+    qdrantThrows = new Error("qdrant unavailable");
+
+    const result = await searchMemoryV2Source(
+      "launch checklist",
+      makeContext(root),
+      5,
+    );
+
+    expect(result.evidence.length).toBeGreaterThan(0);
+    expect(
+      result.evidence.every((e) => e.metadata?.retrieval === "lexical"),
+    ).toBe(true);
+  });
+
+  test("returns empty when neither activation nor lexical matches anything", async () => {
+    const root = makeTempDir();
+    qdrantHits = [];
+    // No concept pages on disk
+
+    const result = await searchMemoryV2Source("anything", makeContext(root), 5);
+
+    expect(result.evidence).toEqual([]);
+  });
+
+  test("handles a missing memory/concepts directory gracefully", async () => {
+    const root = makeTempDir(); // workspace exists, but no memory/ dir
+    qdrantHits = [];
+
+    const result = await searchMemoryV2Source(
+      "no concepts",
+      makeContext(root),
+      5,
+    );
+
+    expect(result.evidence).toEqual([]);
+  });
+
+  test("respects the recall limit", async () => {
+    const root = makeTempDir();
+    for (let i = 0; i < 5; i++) {
+      const slug = `concept-${i}`;
+      writeConceptPage(
+        root,
+        slug,
+        `# ${slug}\n\nbirthday party reminder ${i}\n`,
+      );
+    }
+
+    qdrantHits = [];
+
+    const result = await searchMemoryV2Source(
+      "birthday party",
+      makeContext(root),
+      2,
+    );
+
+    expect(result.evidence.length).toBeLessThanOrEqual(2);
+  });
+
+  test("activation hits use slug as title and full body as excerpt", async () => {
+    const root = makeTempDir();
+    pageStore.set("alice", {
+      slug: "alice",
+      frontmatter: { edges: [], ref_files: [] },
+      body: "Alice memory body content.",
+    });
+    qdrantHits = [{ slug: "alice", denseScore: 0.85 }];
+
+    const result = await searchMemoryV2Source(
+      "alice memory",
+      makeContext(root),
+      5,
+    );
+
+    const hit = result.evidence.find(
+      (e) => e.metadata?.retrieval === "activation",
+    );
+    expect(hit?.title).toBe("alice");
+    expect(hit?.excerpt).toBe("Alice memory body content.");
+  });
+
+  test("activation hit for nested slug produces nested locator and slug", async () => {
+    const root = makeTempDir();
+    writeConceptPage(root, "people/alice", "Alice prefers concise notes.\n");
+
+    qdrantHits = [{ slug: "people/alice", denseScore: 0.92 }];
+    pageStore.set("people/alice", {
+      slug: "people/alice",
+      frontmatter: { edges: [], ref_files: [] },
+      body: "Alice prefers concise notes.",
+    });
+
+    const result = await searchMemoryV2Source(
+      "alice notes",
+      makeContext(root),
+      5,
+    );
+
+    const hit = result.evidence.find(
+      (e) => e.metadata?.retrieval === "activation",
+    );
+    expect(hit).toBeDefined();
+    expect(hit?.locator).toBe("memory/concepts/people/alice.md");
+    expect(hit?.metadata?.path).toBe("memory/concepts/people/alice.md");
+    expect(hit?.metadata?.slug).toBe("people/alice");
+    expect(hit?.title).toBe("people/alice");
+  });
+
+  test("lexical fallback surfaces nested concept pages with nested locators", async () => {
+    const root = makeTempDir();
+    writeConceptPage(
+      root,
+      "people/bob",
+      "# Bob\n\nbirthday party plans for next month.\n",
+    );
+
+    qdrantHits = [];
+
+    const result = await searchMemoryV2Source(
+      "birthday party",
+      makeContext(root),
+      5,
+    );
+
+    const lexicalHit = result.evidence.find(
+      (e) => e.metadata?.retrieval === "lexical",
+    );
+    expect(lexicalHit).toBeDefined();
+    expect(lexicalHit?.metadata?.path).toBe("memory/concepts/people/bob.md");
+    expect(lexicalHit?.locator).toMatch(
+      /^memory\/concepts\/people\/bob\.md:\d+$/,
+    );
+  });
+
+  test("returns empty when limit is zero", async () => {
+    const root = makeTempDir();
+    writeConceptPage(root, "alice", "Alice content");
+    qdrantHits = [{ slug: "alice", denseScore: 0.9 }];
+
+    const result = await searchMemoryV2Source("alice", makeContext(root), 0);
+
+    expect(result.evidence).toEqual([]);
+    expect(qdrantCalls).toHaveLength(0);
+  });
+});

package/src/__tests__/context-search-pkb-source.test.ts

@@ -9,6 +9,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
+import { _setOverridesForTesting } from "../config/assistant-feature-flags.js";
 import type { AssistantConfig } from "../config/schema.js";
 import type { RecallSearchContext } from "../memory/context-search/types.js";
 import { PKB_WORKSPACE_SCOPE } from "../memory/pkb/types.js";
@@ -193,6 +194,7 @@ describe("PKB context-search source", () => {
     denseThrows = null;
     pkbContext = null;
     nowScratchpad = null;
+    _setOverridesForTesting({ "memory-v2-enabled": false });
   });
 
   test("converts PKB hits to recall evidence with snippets and scores", async () => {
@@ -441,4 +443,51 @@ describe("PKB context-search source", () => {
       },
     ]);
   });
+
+  test("short-circuits to empty when both v2 gates are on", async () => {
+    _setOverridesForTesting({ "memory-v2-enabled": true });
+    denseResults = [
+      {
+        id: "dense-a",
+        score: 0.9,
+        payload: {
+          target_type: "pkb_file",
+          target_id: "a",
+          path: "notes/should-not-appear.md",
+          text: "should not appear",
+        },
+      },
+    ];
+
+    const result = await searchPkbSource(
+      "anything",
+      makeContext({ config: makeV2EnabledConfig() }),
+      5,
+    );
+
+    expect(result).toEqual({ evidence: [] });
+    expect(qdrantSearchCalls).toHaveLength(0);
+    expect(hybridSearchCalls).toHaveLength(0);
+    expect(embedCalls).toHaveLength(0);
+  });
+
+  test("readPkbContextEvidence short-circuits when v2 read is active", () => {
+    _setOverridesForTesting({ "memory-v2-enabled": true });
+    pkbContext = "should not surface under v2";
+    nowScratchpad = "should not surface under v2";
+
+    const evidence = readPkbContextEvidence(
+      makeContext({ config: makeV2EnabledConfig() }),
+    );
+
+    expect(evidence).toEqual([]);
+  });
 });
+
+function makeV2EnabledConfig(): AssistantConfig {
+  return {
+    memory: {
+      v2: { enabled: true },
+    },
+  } as unknown as AssistantConfig;
+}

package/src/__tests__/context-search-workspace-source.test.ts

@@ -109,10 +109,10 @@ describe("searchWorkspaceSource", () => {
     writeWorkspaceFile(root, ".hidden.md", "needle hidden");
     writeWorkspaceFile(
       root,
-      ".birthday-builds/.format-rec.md",
+      ".notes/.format-rec.md",
       "needle safe hidden file",
     );
-    writeWorkspaceFile(root, ".birthday-builds/cake.md", "needle safe hidden");
+    writeWorkspaceFile(root, ".notes/cake.md", "needle safe hidden");
     writeWorkspaceFile(root, ".git/config.md", "needle git");
     writeWorkspaceFile(root, ".private/notes.md", "needle private");
     writeWorkspaceFile(root, "node_modules/pkg/index.md", "needle dependency");
@@ -136,9 +136,9 @@ describe("searchWorkspaceSource", () => {
     const result = await searchWorkspaceSource("needle", makeContext(root), 10);
 
     expect(result.evidence.map((item) => item.locator)).toEqual([
-      ".birthday-builds/.format-rec.md:1",
-      ".birthday-builds/cake.md:1",
       ".hidden.md:1",
+      ".notes/.format-rec.md:1",
+      ".notes/cake.md:1",
       "src/readme.md:1",
     ]);
   });
@@ -182,11 +182,6 @@ describe("searchWorkspaceSource", () => {
         "sharedneedle scratch filler",
       );
     }
-    writeWorkspaceFile(
-      root,
-      ".birthday-builds/format.md",
-      "formatneedle hidden authored decision",
-    );
     writeWorkspaceFile(root, "work/source.md", "workneedle live authored doc");
     writeWorkspaceFile(
       root,
@@ -199,17 +194,13 @@ describe("searchWorkspaceSource", () => {
     );
 
     const result = await searchWorkspaceSource(
-      "sharedneedle formatneedle workneedle appneedle",
+      "sharedneedle workneedle appneedle",
       makeContext(root),
       10,
     );
 
     expect(result.evidence.map((item) => item.title)).toEqual(
-      expect.arrayContaining([
-        ".birthday-builds/format.md",
-        "work/source.md",
-        "data/apps/example-app.json",
-      ]),
+      expect.arrayContaining(["work/source.md", "data/apps/example-app.json"]),
     );
   });
 
@@ -519,21 +510,17 @@ describe("inspectWorkspacePaths", () => {
   test("inspects up to five safe surfaced files and reports unsafe paths", async () => {
     const root = makeTempDir();
     writeWorkspaceFile(root, "scratch/handoff.md", "handoff exact truth");
-    writeWorkspaceFile(
-      root,
-      ".birthday-builds/format.md",
-      "hidden exact truth",
-    );
+    writeWorkspaceFile(root, ".notes/format.md", "hidden exact truth");
 
     const result = await inspectWorkspacePaths(
-      ["scratch/handoff.md", ".birthday-builds/format.md", "../secret.md"],
+      ["scratch/handoff.md", ".notes/format.md", "../secret.md"],
       "unrelated query terms",
       makeContext(root),
     );
 
     expect(result.evidence.map((item) => item.title)).toEqual([
       "scratch/handoff.md",
-      ".birthday-builds/format.md",
+      ".notes/format.md",
     ]);
     expect(result.errors).toEqual([
       {