@vellumai/assistant 0.7.0 → 0.7.1

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

@@ -0,0 +1,153 @@
+/**
+ * Tests for `readMemoryV2StaticContent` — the loader that powers the
+ * `memory-v2-static` user-message auto-injection. Mirrors the coverage that
+ * lived in the deprecated `system-prompt-memory-v2.test.ts`:
+ *   - Returns null when the v2 flag is off.
+ *   - Returns null when `config.memory.v2.enabled` is off.
+ *   - Reads the four files in canonical order and joins them under headings.
+ *   - Skips empty / missing files.
+ *   - Returns null when every file is empty or missing.
+ */
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+const TEST_DIR = process.env.VELLUM_WORKSPACE_DIR!;
+
+const noopLogger: Record<string, unknown> = new Proxy(
+  {} as Record<string, unknown>,
+  {
+    get: (_target, prop) => (prop === "child" ? () => noopLogger : () => {}),
+  },
+);
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const realLogger = require("../../../util/logger.js");
+mock.module("../../../util/logger.js", () => ({
+  ...realLogger,
+  getLogger: () => noopLogger,
+  getCliLogger: () => noopLogger,
+  truncateForLog: (v: string) => v,
+  initLogger: () => {},
+  pruneOldLogFiles: () => 0,
+}));
+
+let configMemoryV2Enabled = true;
+
+mock.module("../../../config/loader.js", () => ({
+  getConfig: () => ({}),
+  loadConfig: () => ({
+    memory: { v2: { enabled: configMemoryV2Enabled } },
+  }),
+  loadRawConfig: () => ({}),
+  saveConfig: () => {},
+  saveRawConfig: () => {},
+  invalidateConfigCache: () => {},
+  getNestedValue: () => undefined,
+  setNestedValue: () => {},
+}));
+
+const { _setOverridesForTesting } =
+  await import("../../../config/assistant-feature-flags.js");
+const { readMemoryV2StaticContent } = await import("../static-context.js");
+
+const MEMORY_FILES = [
+  "essentials.md",
+  "threads.md",
+  "recent.md",
+  "buffer.md",
+] as const;
+
+function writeMemoryFile(name: string, body: string): void {
+  const memoryDir = join(TEST_DIR, "memory");
+  mkdirSync(memoryDir, { recursive: true });
+  writeFileSync(join(memoryDir, name), body);
+}
+
+function cleanupMemoryDir(): void {
+  const memoryDir = join(TEST_DIR, "memory");
+  if (existsSync(memoryDir))
+    rmSync(memoryDir, { recursive: true, force: true });
+}
+
+describe("readMemoryV2StaticContent", () => {
+  beforeEach(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+    configMemoryV2Enabled = true;
+    _setOverridesForTesting({ "memory-v2-enabled": true });
+  });
+
+  afterEach(() => {
+    cleanupMemoryDir();
+    _setOverridesForTesting({});
+  });
+
+  test("returns null when the feature flag is off", () => {
+    _setOverridesForTesting({ "memory-v2-enabled": false });
+    for (const file of MEMORY_FILES) writeMemoryFile(file, `Content ${file}`);
+    expect(readMemoryV2StaticContent()).toBeNull();
+  });
+
+  test("returns null when config.memory.v2.enabled is off", () => {
+    configMemoryV2Enabled = false;
+    for (const file of MEMORY_FILES) writeMemoryFile(file, `Content ${file}`);
+    expect(readMemoryV2StaticContent()).toBeNull();
+  });
+
+  test("returns headed sections in canonical order when all files have content", () => {
+    writeMemoryFile("essentials.md", "Alice prefers dark mode.");
+    writeMemoryFile("threads.md", "Open thread: ship PR-123 review.");
+    writeMemoryFile(
+      "recent.md",
+      "Yesterday Alice asked about Postgres tuning.",
+    );
+    writeMemoryFile(
+      "buffer.md",
+      "Bob mentioned a pager rotation conflict on Friday.",
+    );
+
+    const result = readMemoryV2StaticContent();
+    expect(result).not.toBeNull();
+    const text = result!;
+
+    expect(text).toContain("## Essentials");
+    expect(text).toContain("## Threads");
+    expect(text).toContain("## Recent");
+    expect(text).toContain("## Buffer");
+    expect(text).toContain("Alice prefers dark mode.");
+    expect(text).toContain(
+      "Bob mentioned a pager rotation conflict on Friday.",
+    );
+
+    expect(text.indexOf("## Essentials")).toBeLessThan(
+      text.indexOf("## Threads"),
+    );
+    expect(text.indexOf("## Threads")).toBeLessThan(text.indexOf("## Recent"));
+    expect(text.indexOf("## Recent")).toBeLessThan(text.indexOf("## Buffer"));
+  });
+
+  test("omits empty files but keeps populated ones", () => {
+    writeMemoryFile("essentials.md", "Alice prefers VS Code.");
+    writeMemoryFile("threads.md", "");
+    writeMemoryFile("recent.md", "Recent topic: GraphQL pagination.");
+    writeMemoryFile("buffer.md", "");
+
+    const text = readMemoryV2StaticContent();
+    expect(text).not.toBeNull();
+    expect(text).toContain("## Essentials");
+    expect(text).toContain("## Recent");
+    expect(text).not.toContain("## Threads");
+    expect(text).not.toContain("## Buffer");
+  });
+
+  test("returns null when every file is empty", () => {
+    for (const file of MEMORY_FILES) writeMemoryFile(file, "");
+    expect(readMemoryV2StaticContent()).toBeNull();
+  });
+
+  test("returns null when memory directory is missing entirely", () => {
+    cleanupMemoryDir();
+    expect(readMemoryV2StaticContent()).toBeNull();
+  });
+});

package/src/memory/v2/activation.ts

@@ -10,11 +10,15 @@
 //               + c_now       · sim(NOW.md,      n)
 //
 //   A(n, t+1) = [ A_o(n)
-//               + k  · Σ_{m∈1hop} A_o(m)
-//               + k² · Σ_{m∈2hop} A_o(m) ]
-//             / (1 + k · #1hop(n) + k² · #2hop(n))
+//               + k  · Σ_{m∈in1(n)} A_o(m)
+//               + k² · Σ_{m∈in2(n)} A_o(m) ]
+//             / (1 + k · #in1(n) + k² · #in2(n))
 //
-// Bounded in [0, 1]. Orphan nodes (no neighbors within `hops`) reduce to
+// Edges are directed: edge A→B means A's activation contributes to B's. The
+// per-target BFS walks *incoming* adjacency, so `in1(n)` is the set of nodes
+// with an edge A→n and `in2(n)` adds another hop in the same direction.
+//
+// Bounded in [0, 1]. Pure sources (no incoming edges within `hops`) reduce to
 // A == A_o because both numerator and denominator collapse to `A_o(n)` and
 // `1`, respectively.
 //
@@ -33,14 +37,11 @@ import {
   generateSparseEmbedding,
 } from "../embedding-backend.js";
 import { clampUnitInterval } from "../validation.js";
+import type { EdgeIndex } from "./edge-index.js";
 import { hybridQueryConceptPages } from "./qdrant.js";
 import { simBatch, simSkillBatch } from "./sim.js";
 import { hybridQuerySkills } from "./skill-qdrant.js";
-import type {
-  ActivationState,
-  EdgesIndex,
-  EverInjectedEntry,
-} from "./types.js";
+import type { ActivationState, EverInjectedEntry } from "./types.js";
 
 /**
  * Top-K size for the un-restricted ANN candidate query against the v2
@@ -70,27 +71,41 @@ export interface SelectCandidatesParams {
   config: AssistantConfig;
 }
 
+export interface SelectCandidatesResult {
+  /** Union of `fromPrior` and `fromAnn` — the per-turn candidate set. */
+  candidates: Set<string>;
+  /** Slugs carried forward from `priorState` because their activation > epsilon. */
+  fromPrior: Set<string>;
+  /** Slugs surfaced by the unrestricted ANN top-50 against the joined turn text. */
+  fromAnn: Set<string>;
+}
+
 /**
  * Build the per-turn candidate set: the union of slugs in the prior state
  * (above epsilon) and the top-50 ANN hits against the concatenated turn
  * text. The ANN call runs un-restricted (no slug filter) so it can surface
  * pages outside the active set.
  *
+ * Returns the union plus the two source sets separately so downstream
+ * telemetry can attribute each candidate to `prior_state`, `ann_top50`, or
+ * both. A slug present in both sources appears in `fromPrior ∩ fromAnn`.
+ *
  * Empty candidate sets are valid and propagate downstream — both
  * `computeOwnActivation` and `spreadActivation` short-circuit on them.
  */
 export async function selectCandidates(
   params: SelectCandidatesParams,
-): Promise<Set<string>> {
+): Promise<SelectCandidatesResult> {
   const { priorState, userText, assistantText, nowText, config } = params;
 
-  const candidates = new Set<string>();
+  const fromPrior = new Set<string>();
+  const fromAnn = new Set<string>();
 
   // (1) Carry forward prior-state slugs above epsilon.
   if (priorState) {
     const epsilon = config.memory.v2.epsilon;
     for (const [slug, activation] of Object.entries(priorState.state)) {
-      if (activation > epsilon) candidates.add(slug);
+      if (activation > epsilon) fromPrior.add(slug);
     }
   }
 
@@ -110,10 +125,12 @@ export async function selectCandidates(
       sparse,
       ANN_CANDIDATE_LIMIT,
     );
-    for (const hit of hits) candidates.add(hit.slug);
+    for (const hit of hits) fromAnn.add(hit.slug);
   }
 
-  return candidates;
+  const candidates = new Set<string>([...fromPrior, ...fromAnn]);
+
+  return { candidates, fromPrior, fromAnn };
 }
 
 // ---------------------------------------------------------------------------
@@ -129,24 +146,50 @@ export interface ComputeOwnActivationParams {
   config: AssistantConfig;
 }
 
+/**
+ * Per-slug breakdown of the own-activation inputs, captured before any
+ * coefficient weighting is applied. Surfaced for telemetry / inspector views
+ * so the UI can show how each term contributed to the final value.
+ */
+export interface OwnActivationBreakdown {
+  /** `d * prev(slug)` — the decayed prior-turn activation contribution. */
+  priorContribution: number;
+  /** Raw `sim(user, slug)` similarity, before `c_user` weighting. */
+  simUser: number;
+  /** Raw `sim(assistant, slug)` similarity, before `c_assistant` weighting. */
+  simAssistant: number;
+  /** Raw `sim(now, slug)` similarity, before `c_now` weighting. */
+  simNow: number;
+}
+
+export interface ComputeOwnActivationResult {
+  /** Final clamped own-activation value per slug. */
+  activation: Map<string, number>;
+  /** Per-slug breakdown of the inputs that fed into `activation`. */
+  breakdown: Map<string, OwnActivationBreakdown>;
+}
+
 /**
  * Apply the own-activation formula
  *   A_o(n) = d · prev(n) + c_user · sim_u + c_assistant · sim_a + c_now · sim_n
  * over the candidate set. Returns a sparse map keyed by slug; slugs whose
  * computed value rounds to 0 are still included so callers can see the
- * candidate set explicitly.
+ * candidate set explicitly. Also returns a per-slug breakdown of the raw
+ * inputs (decayed prior + raw sims) so callers can render contribution
+ * diagnostics without re-running the math.
  *
  * The three `simBatch` calls run concurrently — they hit independent named
  * vectors and embed independent query texts.
  */
 export async function computeOwnActivation(
   params: ComputeOwnActivationParams,
-): Promise<Map<string, number>> {
+): Promise<ComputeOwnActivationResult> {
   const { candidates, priorState, userText, assistantText, nowText, config } =
     params;
 
-  const result = new Map<string, number>();
-  if (candidates.size === 0) return result;
+  const activation = new Map<string, number>();
+  const breakdown = new Map<string, OwnActivationBreakdown>();
+  if (candidates.size === 0) return { activation, breakdown };
 
   const { d, c_user, c_assistant, c_now } = config.memory.v2;
   const slugList = [...candidates];
@@ -159,63 +202,85 @@ export async function computeOwnActivation(
 
   for (const slug of slugList) {
     const prev = priorState?.state[slug] ?? 0;
-    const value =
-      d * prev +
-      c_user * (simUser.get(slug) ?? 0) +
-      c_assistant * (simAssistant.get(slug) ?? 0) +
-      c_now * (simNow.get(slug) ?? 0);
-    result.set(slug, clampUnitInterval(value));
+    const simU = simUser.get(slug) ?? 0;
+    const simA = simAssistant.get(slug) ?? 0;
+    const simN = simNow.get(slug) ?? 0;
+    const value = d * prev + c_user * simU + c_assistant * simA + c_now * simN;
+    activation.set(slug, clampUnitInterval(value));
+    breakdown.set(slug, {
+      priorContribution: d * prev,
+      simUser: simU,
+      simAssistant: simA,
+      simNow: simN,
+    });
   }
 
-  return result;
+  return { activation, breakdown };
 }
 
 // ---------------------------------------------------------------------------
 // Spreading activation
 // ---------------------------------------------------------------------------
 
+export interface SpreadActivationResult {
+  /** Final activation value per slug after spreading. */
+  final: Map<string, number>;
+  /**
+   * Per-slug spread delta: `final[slug] - own[slug]`. Captures how much
+   * the spread step nudged each node above (or below) its own activation —
+   * useful for inspector views that want to show graph contributions
+   * separate from raw sim contributions. Always 0 when `hops == 0` or
+   * `k == 0` because both short-circuit to `final == own`.
+   */
+  contribution: Map<string, number>;
+}
+
 /**
- * Apply 2-hop spreading activation with neighborhood normalization:
+ * Apply 2-hop spreading activation with neighborhood normalization. Edges are
+ * directed: an edge A→B means A's activation contributes to B's final value.
  *
- *   A(n) = [ A_o(n) + k · Σ_{m∈1hop} A_o(m) + k² · Σ_{m∈2hop} A_o(m) ]
- *        / (1 + k · #1hop(n) + k² · #2hop(n))
+ *   A(n) = [ A_o(n) + k · Σ_{m∈in1(n)} A_o(m) + k² · Σ_{m∈in2(n)} A_o(m) ]
+ *        / (1 + k · #in1(n) + k² · #in2(n))
  *
- * The denominator counts *structural* neighbors at each hop (whether or not
- * they appear in `ownActivation`) so an orphan node's denominator collapses
- * to 1 and `A == A_o`. Missing neighbors contribute 0 to the numerator.
+ * For each candidate slug `n`, BFS walks `incoming` adjacency to gather
+ * predecessors at distance 1, 2 (i.e. nodes from which a directed path of
+ * that length leads into `n`). The denominator counts those structural
+ * predecessors at each hop (whether or not they appear in `ownActivation`)
+ * so a pure source — no incoming edges — collapses to `A == A_o`. Missing
+ * predecessors contribute 0 to the numerator.
  *
  * Bounded in [0, 1]: with `A_o ∈ [0, 1]` and `k ∈ [0, 1]`, the numerator is
- * at most `1 + k · #1hop + k² · #2hop` — exactly the denominator — so the
+ * at most `1 + k · #in1 + k² · #in2` — exactly the denominator — so the
  * ratio is at most 1. `clampUnitInterval` guards against numerical drift
  * and out-of-range inputs.
  *
- * Pure function — no I/O. Builds an adjacency map once from `edgesIdx` and
- * runs a per-source BFS bounded by `hops`.
+ * Pure function — no I/O. Reads the precomputed `incoming` map from
+ * `edgeIndex` and runs a per-source BFS bounded by `hops`.
  */
 export function spreadActivation(
   ownActivation: ReadonlyMap<string, number>,
-  edgesIdx: EdgesIndex,
+  edgeIndex: EdgeIndex,
   k: number,
   hops: number,
-): Map<string, number> {
-  const result = new Map<string, number>();
-  if (ownActivation.size === 0) return result;
+): SpreadActivationResult {
+  const final = new Map<string, number>();
+  const contribution = new Map<string, number>();
+  if (ownActivation.size === 0) return { final, contribution };
 
   // Short-circuit: with no spread the formula collapses to A == A_o.
   if (hops <= 0 || k <= 0) {
     for (const [slug, ownValue] of ownActivation) {
-      result.set(slug, clampUnitInterval(ownValue));
+      final.set(slug, clampUnitInterval(ownValue));
+      contribution.set(slug, 0);
     }
-    return result;
+    return { final, contribution };
   }
 
-  const adjacency = buildAdjacency(edgesIdx);
-
   for (const [slug, ownValue] of ownActivation) {
-    // Single bounded BFS from `slug`. `distance` maps neighbor → hop count
-    // (1..hops). Source is excluded so it contributes hop-0 only via
-    // `numerator = ownValue`.
-    const distance = bfsDistances(adjacency, slug, hops);
+    // Single bounded BFS from `slug` over incoming edges. `distance` maps
+    // predecessor → hop count (1..hops). Source is excluded so it contributes
+    // hop-0 only via `numerator = ownValue`.
+    const distance = bfsPredecessorDistances(edgeIndex.incoming, slug, hops);
 
     let numerator = ownValue;
     let denominator = 1;
@@ -224,9 +289,9 @@ export function spreadActivation(
     // counts to weight by k^r, so bucket as we go.
     const ringCounts: number[] = new Array(hops + 1).fill(0);
     const ringSums: number[] = new Array(hops + 1).fill(0);
-    for (const [neighbor, hop] of distance) {
+    for (const [predecessor, hop] of distance) {
       ringCounts[hop] += 1;
-      ringSums[hop] += ownActivation.get(neighbor) ?? 0;
+      ringSums[hop] += ownActivation.get(predecessor) ?? 0;
     }
     for (let r = 1; r <= hops; r++) {
       kPow *= k;
@@ -235,10 +300,12 @@ export function spreadActivation(
       denominator += kPow * ringCounts[r];
     }
 
-    result.set(slug, clampUnitInterval(numerator / denominator));
+    const finalValue = clampUnitInterval(numerator / denominator);
+    final.set(slug, finalValue);
+    contribution.set(slug, finalValue - ownValue);
   }
 
-  return result;
+  return { final, contribution };
 }
 
 // ---------------------------------------------------------------------------
@@ -246,50 +313,29 @@ export function spreadActivation(
 // ---------------------------------------------------------------------------
 
 /**
- * Build a slug → neighbors map from a canonicalized undirected edges index.
- * Mirrors `edges.ts#buildAdjacency` but is local so `spreadActivation` can
- * stay independent of `edges.ts`'s currently-private helper.
- */
-function buildAdjacency(idx: EdgesIndex): Map<string, Set<string>> {
-  const adjacency = new Map<string, Set<string>>();
-  const ensure = (slug: string): Set<string> => {
-    let set = adjacency.get(slug);
-    if (!set) {
-      set = new Set<string>();
-      adjacency.set(slug, set);
-    }
-    return set;
-  };
-  for (const [a, b] of idx.edges) {
-    if (a === b) continue;
-    ensure(a).add(b);
-    ensure(b).add(a);
-  }
-  return adjacency;
-}
-
-/**
- * Bounded BFS that returns each reachable slug's hop-distance in [1, maxHops]
- * from `source`. The source itself is excluded.
+ * Bounded BFS over the *incoming* adjacency map. Returns each reachable
+ * predecessor's hop-distance in [1, maxHops] from `target` — i.e. nodes from
+ * which a directed path of that length leads into `target`. The target itself
+ * is excluded.
  */
-function bfsDistances(
-  adjacency: ReadonlyMap<string, ReadonlySet<string>>,
-  source: string,
+function bfsPredecessorDistances(
+  incoming: ReadonlyMap<string, ReadonlySet<string>>,
+  target: string,
   maxHops: number,
 ): Map<string, number> {
   const distance = new Map<string, number>();
-  let frontier: string[] = [source];
-  const visited = new Set<string>([source]);
+  let frontier: string[] = [target];
+  const visited = new Set<string>([target]);
   for (let hop = 1; hop <= maxHops && frontier.length > 0; hop++) {
     const next: string[] = [];
     for (const node of frontier) {
-      const neighbors = adjacency.get(node);
-      if (!neighbors) continue;
-      for (const neighbor of neighbors) {
-        if (visited.has(neighbor)) continue;
-        visited.add(neighbor);
-        distance.set(neighbor, hop);
-        next.push(neighbor);
+      const predecessors = incoming.get(node);
+      if (!predecessors) continue;
+      for (const predecessor of predecessors) {
+        if (visited.has(predecessor)) continue;
+        visited.add(predecessor);
+        distance.set(predecessor, hop);
+        next.push(predecessor);
       }
     }
     frontier = next;
@@ -410,24 +456,48 @@ export interface ComputeSkillActivationParams {
   config: AssistantConfig;
 }
 
+/**
+ * Per-skill breakdown of the raw similarity inputs, captured before any
+ * coefficient weighting. Skills have no decay term, so the breakdown is just
+ * the three raw sims. Surfaced for telemetry / inspector views.
+ */
+export interface SkillActivationBreakdown {
+  /** Raw `sim(user, skill)` similarity, before `c_user` weighting. */
+  simUser: number;
+  /** Raw `sim(assistant, skill)` similarity, before `c_assistant` weighting. */
+  simAssistant: number;
+  /** Raw `sim(now, skill)` similarity, before `c_now` weighting. */
+  simNow: number;
+}
+
+export interface ComputeSkillActivationResult {
+  /** Final clamped skill-activation value per id. */
+  activation: Map<string, number>;
+  /** Per-skill breakdown of the raw sim inputs that fed into `activation`. */
+  breakdown: Map<string, SkillActivationBreakdown>;
+}
+
 /**
  * Apply the skill-side activation formula (no decay carry-over, no spread):
  *   A_skill(s) = clamp01(c_user · sim_u + c_assistant · sim_a + c_now · sim_n)
  *
  * Reuses the activation coefficients from `config.memory.v2`. The three
  * `simSkillBatch` calls run concurrently — they hit independent named
- * vectors and embed independent query texts.
+ * vectors and embed independent query texts. Returns a per-skill breakdown
+ * of the raw sims alongside the activation map so callers can render
+ * contribution diagnostics without re-running the math.
  *
  * Empty candidates short-circuits to an empty map without touching the
  * embedding backend or Qdrant.
  */
 export async function computeSkillActivation(
   params: ComputeSkillActivationParams,
-): Promise<Map<string, number>> {
+): Promise<ComputeSkillActivationResult> {
   const { candidates, userText, assistantText, nowText, config } = params;
 
-  const result = new Map<string, number>();
-  if (candidates.size === 0) return result;
+  const activation = new Map<string, number>();
+  const breakdown = new Map<string, SkillActivationBreakdown>();
+  if (candidates.size === 0) return { activation, breakdown };
 
   const { c_user, c_assistant, c_now } = config.memory.v2;
   const idList = [...candidates];
@@ -439,14 +509,15 @@ export async function computeSkillActivation(
   ]);
 
   for (const id of idList) {
-    const value =
-      c_user * (simUser.get(id) ?? 0) +
-      c_assistant * (simAssistant.get(id) ?? 0) +
-      c_now * (simNow.get(id) ?? 0);
-    result.set(id, clampUnitInterval(value));
+    const simU = simUser.get(id) ?? 0;
+    const simA = simAssistant.get(id) ?? 0;
+    const simN = simNow.get(id) ?? 0;
+    const value = c_user * simU + c_assistant * simA + c_now * simN;
+    activation.set(id, clampUnitInterval(value));
+    breakdown.set(id, { simUser: simU, simAssistant: simA, simNow: simN });
   }
 
-  return result;
+  return { activation, breakdown };
 }
 
 export interface SelectSkillInjectionsParams {