@vellumai/assistant 0.8.6 → 0.8.7

package/src/memory/v3/needle.ts

@@ -0,0 +1,115 @@
+import type { LeafTree, Slug } from "./types.js";
+
+/**
+ * Sparse "needle" arm for memory-v3 routing: a lexical BM25 search over page
+ * titles, slug tokens, summaries, and the labels of the leaves each page
+ * belongs to. It augments topical (tree) routing by surfacing pages that share
+ * a literal term with the query even when topical routing would miss them.
+ *
+ * Implementation notes:
+ * - Hand-rolled Okapi BM25 (no dependency). The corpus is bounded (one doc per
+ *   page), so a plain inverted index is plenty.
+ * - The index is built once and held in memory. The orchestrator/plugin
+ *   lazy-inits it. Rebuilding on consolidation is a documented fast-follow and
+ *   intentionally out of scope here.
+ */
+
+/** Okapi BM25 term-frequency saturation parameter. */
+export const k1 = 1.5;
+/** Okapi BM25 length-normalization parameter. */
+export const b = 0.75;
+
+export interface NeedleIndex {
+  /** Returns up to `k` slugs ranked by BM25 score (descending, ties by slug). */
+  query(text: string, k: number): Slug[];
+}
+
+/** Lowercase, split on non-alphanumeric, drop empties. */
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length > 0);
+}
+
+interface Posting {
+  doc: number;
+  tf: number;
+}
+
+export async function buildNeedleIndex(
+  tree: LeafTree,
+  pageSummary: (slug: Slug) => Promise<string>,
+): Promise<NeedleIndex> {
+  const slugs: Slug[] = [...tree.byPage.keys()];
+
+  // term -> postings (doc index + term frequency in that doc)
+  const postings = new Map<string, Posting[]>();
+  const docLengths: number[] = new Array(slugs.length).fill(0);
+  let totalLength = 0;
+
+  for (let doc = 0; doc < slugs.length; doc++) {
+    const slug = slugs[doc]!;
+
+    // Title = last path segment of the slug; also index the slug tokens.
+    const segments = slug.split(/[/.]/);
+    const title = segments[segments.length - 1] ?? "";
+
+    const parts: string[] = [title, slug, await pageSummary(slug)];
+
+    for (const leafPath of tree.byPage.get(slug) ?? []) {
+      const leaf = tree.leaves.get(leafPath);
+      if (leaf) parts.push(leaf.description);
+    }
+
+    const tokens = tokenize(parts.join(" "));
+    docLengths[doc] = tokens.length;
+    totalLength += tokens.length;
+
+    const termFreqs = new Map<string, number>();
+    for (const token of tokens) {
+      termFreqs.set(token, (termFreqs.get(token) ?? 0) + 1);
+    }
+    for (const [term, tf] of termFreqs) {
+      let list = postings.get(term);
+      if (!list) {
+        list = [];
+        postings.set(term, list);
+      }
+      list.push({ doc, tf });
+    }
+  }
+
+  const docCount = slugs.length;
+  const avgDocLength = docCount > 0 ? totalLength / docCount : 0;
+
+  function query(text: string, k: number): Slug[] {
+    if (k <= 0 || docCount === 0) return [];
+
+    const queryTerms = new Set(tokenize(text));
+    const scores = new Map<number, number>();
+
+    // O(query-terms x matching-docs): walk only the postings of query terms.
+    for (const term of queryTerms) {
+      const list = postings.get(term);
+      if (!list) continue;
+
+      const idf = Math.log(
+        1 + (docCount - list.length + 0.5) / (list.length + 0.5),
+      );
+
+      for (const { doc, tf } of list) {
+        const norm = tf * (k1 + 1);
+        const denom = tf + k1 * (1 - b + b * (docLengths[doc]! / avgDocLength));
+        scores.set(doc, (scores.get(doc) ?? 0) + idf * (norm / denom));
+      }
+    }
+
+    return [...scores.entries()]
+      .sort((a, c) => c[1] - a[1] || slugs[a[0]]!.localeCompare(slugs[c[0]]!))
+      .slice(0, k)
+      .map(([doc]) => slugs[doc]!);
+  }
+
+  return { query };
+}

package/src/memory/v3/orchestrate.ts

@@ -0,0 +1,114 @@
+/**
+ * Memory v3 — orchestrator composing the four routing lanes into one turn.
+ *
+ * Each turn runs:
+ *   1. L1 topical routing (`routeL1`) and the lexical BM25 needle
+ *      (`NeedleIndex.query`) IN PARALLEL. Routing is the slow LLM arm; the
+ *      needle is a synchronous in-memory lookup, so we wrap it in a resolved
+ *      promise and let them settle together.
+ *   2. Open set = unique union of routed leaves ∪ always-on core leaves ∪ the
+ *      leaves that own each needle hit. Every lane only ever ADDS leaves — the
+ *      union is recall-safe by construction.
+ *   3. Bounded per-leaf L2 selection (`selectAcrossLeaves`) over the open set,
+ *      then dedup by slug (a page assigned to multiple opened leaves comes back
+ *      once per leaf) ORing the pinned flag so a page pinned anywhere stays
+ *      pinned.
+ *   4. Record each deduped selection into the carry-forward working set and
+ *      evict (core slugs, stale non-pinned entries, then the cap).
+ *   5. Final injection = unique union of this turn's selected slugs and the
+ *      working-set union, so pages selected on earlier turns carry forward even
+ *      when this turn does not re-select them.
+ */
+
+import type { NeedleIndex } from "./needle.js";
+import { routeL1 } from "./router.js";
+import type { SelectedPage } from "./selector.js";
+import { selectAcrossLeaves } from "./selector.js";
+import { coreSlugs, leavesOf } from "./tree.js";
+import type { LeafPath, LeafTree, Slug, TurnContext } from "./types.js";
+import { WorkingSet } from "./working-set.js";
+
+/** Default number of needle hits to fold into the open set when unspecified. */
+export const DEFAULT_NEEDLE_K = 10;
+
+export interface OrchestrateDeps {
+  tree: LeafTree;
+  core: Set<LeafPath>;
+  needle: NeedleIndex;
+  workingSet: WorkingSet;
+  pageSummary: (slug: Slug) => Promise<string>;
+  /** Number of BM25 needle hits to fold in. Defaults to {@link DEFAULT_NEEDLE_K}. */
+  needleK?: number;
+  /** Bounded fan-out for per-leaf L2 selection. */
+  l2Concurrency?: number;
+}
+
+export interface OrchestrateResult {
+  /** The unique open set: routed ∪ core ∪ needle-owning leaves. */
+  openedLeaves: LeafPath[];
+  /** This turn's L2 selections, deduped by slug (pinned flags ORed). */
+  currentSelections: SelectedPage[];
+  /** Snapshot of the working-set union after record + evict. */
+  workingSetUnion: Set<Slug>;
+  /** Slugs to inject: this turn's selections ∪ the carried-forward working set. */
+  finalInjection: Slug[];
+}
+
+/** Stable-order de-duplication preserving first occurrence. */
+function unique<T>(items: Iterable<T>): T[] {
+  return [...new Set(items)];
+}
+
+export async function orchestrate(
+  turn: TurnContext,
+  deps: OrchestrateDeps,
+): Promise<OrchestrateResult> {
+  // Step 1: routing (LLM) and needle (sync BM25) run in parallel.
+  const needleK = deps.needleK ?? DEFAULT_NEEDLE_K;
+  const [routed, needled] = await Promise.all([
+    routeL1(turn, deps.tree),
+    Promise.resolve(deps.needle.query(turn.currentMessage, needleK)),
+  ]);
+
+  // Step 2: open set = routed ∪ core ∪ leaves owning each needle hit.
+  const openedLeaves = unique<LeafPath>([
+    ...routed,
+    ...deps.core,
+    ...needled.flatMap((slug) => leavesOf(deps.tree, slug)),
+  ]);
+
+  // Step 3: per-leaf L2 selection, then dedup by slug ORing pinned flags.
+  const selected = await selectAcrossLeaves(
+    openedLeaves,
+    turn,
+    deps.tree,
+    deps.pageSummary,
+    deps.l2Concurrency,
+  );
+  const bySlug = new Map<Slug, SelectedPage>();
+  for (const page of selected) {
+    const existing = bySlug.get(page.slug);
+    bySlug.set(page.slug, {
+      slug: page.slug,
+      pinned: (existing?.pinned ?? false) || page.pinned,
+    });
+  }
+  const currentSelections = [...bySlug.values()];
+
+  // Step 4: record this turn's selections into the carry-forward working set.
+  for (const sel of currentSelections) {
+    deps.workingSet.recordSelection(sel.slug, turn.turnNumber, sel.pinned);
+  }
+
+  // Step 5: evict. Core slugs are owned by core, not the working set.
+  deps.workingSet.evict(turn.turnNumber, coreSlugs(deps.tree, deps.core));
+
+  // Step 6: final injection = this turn's selections ∪ carried-forward set.
+  const workingSetUnion = deps.workingSet.union();
+  const finalInjection = unique<Slug>([
+    ...currentSelections.map((s) => s.slug),
+    ...workingSetUnion,
+  ]);
+
+  return { openedLeaves, currentSelections, workingSetUnion, finalInjection };
+}

package/src/memory/v3/page-content.ts

@@ -0,0 +1,34 @@
+import { getWorkspaceDir } from "../../util/platform.js";
+import { readPage, renderPageContent } from "../v2/page-store.js";
+import { renderCapabilityContent } from "./capabilities.js";
+import type { Slug } from "./types.js";
+
+/**
+ * Render a selected page's full content for the v3 `<memory>` block. Mirrors
+ * the v2 dynamic-memory layout (`# memory/concepts/<slug>.md\n<frontmatter+body>`)
+ * so the working-set block reads like v2's. A missing page (or any read
+ * failure) degrades to "" — `renderMemoryBlock` still emits a line for the
+ * slug, and a blank section is preferable to throwing into the turn.
+ *
+ * Synthetic capability slugs (skills, `assistant` CLI commands) have no on-disk
+ * page; they resolve through {@link renderCapabilityContent} instead of
+ * `readPage`. A non-null result (including "") means the slug was a capability
+ * slug and was handled here.
+ *
+ * Shared by the live injector (`shadow-plugin.ts`) and the inspector
+ * selection-log store (`selection-log-store.ts`) so the inspector's rendered
+ * block is byte-identical to what live injection produces.
+ */
+export async function renderV3PageContent(slug: Slug): Promise<string> {
+  const capability = renderCapabilityContent(slug);
+  if (capability !== null) return capability;
+  try {
+    const page = await readPage(getWorkspaceDir(), slug);
+    if (!page) return "";
+    const content = renderPageContent(page).trim();
+    if (content.length === 0) return "";
+    return `# memory/concepts/${slug}.md\n${content}`;
+  } catch {
+    return "";
+  }
+}

package/src/memory/v3/provider-blocks.ts

@@ -0,0 +1,16 @@
+import type { ContentBlock } from "../../providers/types.js";
+
+/**
+ * Text content block carrying an ephemeral `cache_control` breakpoint. Our
+ * internal `TextContent` type omits the field (only the Anthropic provider
+ * transforms it onto the wire), so we reach through a `Record` cast — this
+ * keeps the core types provider-agnostic. Shared by the v3 router and selector,
+ * whose STATIC numbered blocks are stable across turns and so cache well.
+ */
+export function cachedTextBlock(text: string): ContentBlock {
+  const block: ContentBlock = { type: "text", text };
+  (block as unknown as Record<string, unknown>).cache_control = {
+    type: "ephemeral",
+  };
+  return block;
+}