@vellumai/assistant 0.7.0 → 0.7.2

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.
 //
@@ -28,33 +32,38 @@
 //     for the next turn and drop below `epsilon` if no longer relevant.
 
 import type { AssistantConfig } from "../../config/types.js";
+import { applyCorrectionIfCalibrated } from "../anisotropy.js";
 import {
   embedWithBackend,
   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
- * concept-page collection. The design doc fixes this at 50 — small enough to
- * keep the per-turn round-trip cheap, large enough to surface relevant pages
- * outside the prior active set.
+ * Sentinel passed to Qdrant when `config.memory.v2.ann_candidate_limit` is
+ * `null` (unlimited). Qdrant's query API requires an explicit numeric
+ * `limit`, so unlimited is represented as a number large enough that any
+ * realistic concept-page collection is returned in full.
+ *
+ * Why not `Number.MAX_SAFE_INTEGER`: Qdrant's sparse-vector `SearchContext`
+ * pre-allocates `limit * 16` bytes per query, so passing `MAX_SAFE_INTEGER`
+ * triggers a ~144 PB allocation and SIGABRTs the Qdrant process. 1_000_000
+ * is ~16 MB of pre-allocation in Qdrant — generous headroom over realistic
+ * concept-page counts (low thousands today) while staying well clear of
+ * the OOM cliff. Bump explicitly via `ann_candidate_limit` if you ever
+ * outgrow it.
  */
-const ANN_CANDIDATE_LIMIT = 50;
+const UNLIMITED_ANN_CANDIDATE_LIMIT = 1_000_000;
 
 // ---------------------------------------------------------------------------
 // Candidate selection
 // ---------------------------------------------------------------------------
 
-export interface SelectCandidatesParams {
+interface SelectCandidatesParams {
   /**
    * Prior-turn activation snapshot. Slugs with activation strictly greater
    * than `config.memory.v2.epsilon` are carried forward as candidates so the
@@ -70,27 +79,41 @@ export interface SelectCandidatesParams {
   config: AssistantConfig;
 }
 
+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);
     }
   }
 
@@ -103,24 +126,28 @@ export async function selectCandidates(
 
   if (annQueryText.length > 0) {
     const denseResult = await embedWithBackend(config, [annQueryText]);
-    const dense = denseResult.vectors[0];
-    const sparse = generateSparseEmbedding(annQueryText);
-    const hits = await hybridQueryConceptPages(
-      dense,
-      sparse,
-      ANN_CANDIDATE_LIMIT,
+    const dense = await applyCorrectionIfCalibrated(
+      denseResult.vectors[0],
+      denseResult.provider,
+      denseResult.model,
     );
-    for (const hit of hits) candidates.add(hit.slug);
+    const sparse = generateSparseEmbedding(annQueryText);
+    const limit =
+      config.memory.v2.ann_candidate_limit ?? UNLIMITED_ANN_CANDIDATE_LIMIT;
+    const hits = await hybridQueryConceptPages(dense, sparse, limit);
+    for (const hit of hits) fromAnn.add(hit.slug);
   }
 
-  return candidates;
+  const candidates = new Set<string>([...fromPrior, ...fromAnn]);
+
+  return { candidates, fromPrior, fromAnn };
 }
 
 // ---------------------------------------------------------------------------
 // Own activation
 // ---------------------------------------------------------------------------
 
-export interface ComputeOwnActivationParams {
+interface ComputeOwnActivationParams {
   candidates: ReadonlySet<string>;
   priorState: ActivationState | null;
   userText: string;
@@ -129,24 +156,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.
+ */
+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;
+}
+
+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,86 +212,121 @@ 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
 // ---------------------------------------------------------------------------
 
+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) + Σ_{r: |active_inR(n)| > 0} k^r · L2(active_inR(n)) ]
+ *        / [ 1     + Σ_{r: |active_inR(n)| > 0} k^r ]
  *
- * 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.
+ * `active_inR(n)` is the subset of structural predecessors at hop `r` that
+ * also appear in `ownActivation` (i.e. made the candidate set). `L2(.)` is
+ * the quadratic mean √(mean(A_o²)) — a mild bias toward strong outliers
+ * compared to the arithmetic mean, without letting a single high-cosine
+ * predecessor dominate the way `max` would.
  *
- * 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
- * ratio is at most 1. `clampUnitInterval` guards against numerical drift
- * and out-of-range inputs.
+ * Hops with **no** active predecessors are dropped from BOTH numerator and
+ * denominator so a high-in-degree hub with mostly-inactive neighbors stays
+ * near `A_o` instead of being crushed by the structural count. A pure
+ * source (no incoming edges, or every edge points at a non-candidate)
+ * collapses to `A == A_o`.
  *
- * Pure function — no I/O. Builds an adjacency map once from `edgesIdx` and
- * runs a per-source BFS bounded by `hops`.
+ * Bounded in [0, 1]: every `L2` term ≤ max active A_o ≤ 1, so the numerator
+ * is at most `1 + Σ k^r` — 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. 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);
+
+    // Bucket only predecessors that are in `ownActivation` (the candidate
+    // set). Structural predecessors that didn't make the cut contribute
+    // nothing — neither to the numerator nor the denominator — so hub
+    // in-degree alone never penalizes a node.
+    const ringActiveCounts: number[] = new Array(hops + 1).fill(0);
+    const ringSquareSums: number[] = new Array(hops + 1).fill(0);
+    for (const [predecessor, hop] of distance) {
+      const predValue = ownActivation.get(predecessor);
+      if (predValue === undefined) continue;
+      ringActiveCounts[hop] += 1;
+      ringSquareSums[hop] += predValue * predValue;
+    }
 
     let numerator = ownValue;
     let denominator = 1;
     let kPow = 1;
-    // Accumulate per-hop contributions in a single pass. We need per-hop
-    // 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) {
-      ringCounts[hop] += 1;
-      ringSums[hop] += ownActivation.get(neighbor) ?? 0;
-    }
     for (let r = 1; r <= hops; r++) {
       kPow *= k;
-      if (ringCounts[r] === 0) continue;
-      numerator += kPow * ringSums[r];
-      denominator += kPow * ringCounts[r];
+      if (ringActiveCounts[r] === 0) continue;
+      const rms = Math.sqrt(ringSquareSums[r] / ringActiveCounts[r]);
+      numerator += kPow * rms;
+      denominator += kPow;
     }
 
-    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 +334,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.
+ * 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 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.
- */
-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;
@@ -301,7 +368,7 @@ function bfsDistances(
 // Injection selection
 // ---------------------------------------------------------------------------
 
-export interface SelectInjectionsParams {
+interface SelectInjectionsParams {
   /** Final activation map after spread. */
   A: ReadonlyMap<string, number>;
   /** Slugs already attached to a prior user message (with their turn). */
@@ -310,7 +377,7 @@ export interface SelectInjectionsParams {
   topK: number;
 }
 
-export interface SelectInjectionsResult {
+interface SelectInjectionsResult {
   /** Top-K slugs by activation (descending), used for the cached top-now view. */
   topNow: string[];
   /**
@@ -362,52 +429,33 @@ export function selectInjections(
 // c_assistant, c_now}` — the design doc (§9) deliberately shares them with
 // concept-page activation rather than introducing parallel knobs.
 
-export interface SelectSkillCandidatesParams {
+interface ComputeSkillActivationParams {
+  candidates: ReadonlySet<string>;
   userText: string;
   assistantText: string;
   nowText: string;
   config: AssistantConfig;
-  /** Top-K size for the ANN query against `memory_v2_skills`. */
-  topK: number;
 }
 
 /**
- * ANN top-K against the skills collection using the concatenated turn text.
- * Runs a single embedding pass over `concat(user, assistant, now)` and a
- * single hybrid Qdrant query — there is no prior-state carry-forward (skills
- * are stateless).
- *
- * Returns a `Set<string>` of skill ids that hit either channel. Empty when
- * the joined text is empty or `topK <= 0`.
+ * 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 async function selectSkillCandidates(
-  params: SelectSkillCandidatesParams,
-): Promise<Set<string>> {
-  const { userText, assistantText, nowText, config, topK } = params;
-
-  const candidates = new Set<string>();
-  if (topK <= 0) return candidates;
-
-  const annQueryText = [userText, assistantText, nowText]
-    .filter((s) => s.length > 0)
-    .join("\n");
-  if (annQueryText.length === 0) return candidates;
-
-  const denseResult = await embedWithBackend(config, [annQueryText]);
-  const dense = denseResult.vectors[0];
-  const sparse = generateSparseEmbedding(annQueryText);
-  const hits = await hybridQuerySkills(dense, sparse, topK);
-  for (const hit of hits) candidates.add(hit.id);
-
-  return candidates;
+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 ComputeSkillActivationParams {
-  candidates: ReadonlySet<string>;
-  userText: string;
-  assistantText: string;
-  nowText: string;
-  config: AssistantConfig;
+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>;
 }
 
 /**
@@ -416,18 +464,21 @@ export interface ComputeSkillActivationParams {
  *
  * 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,24 +490,25 @@ 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 {
+interface SelectSkillInjectionsParams {
   /** Final skill activation map. */
   A: ReadonlyMap<string, number>;
   /** Cap on the per-turn skill slate, e.g. `config.memory.v2.skills_top_k`. */
   topK: number;
 }
 
-export interface SelectSkillInjectionsResult {
+interface SelectSkillInjectionsResult {
   /**
    * Top-K skill ids by activation (descending), tie-broken lexicographically.
    * Skills are re-presented every turn — no `toInject` delta — so the caller