@vellumai/assistant 0.7.2 → 0.7.3

package/src/memory/memory-v2-activation-log-store.ts

@@ -12,20 +12,37 @@ export interface MemoryV2ConceptRowRecord {
   simUser: number;
   simAssistant: number;
   simNow: number;
+  /**
+   * Cross-encoder rerank delta in raw rerank space (`alpha · r_norm_u`)
+   * for the user channel. Zero when rerank is disabled or the slug fell
+   * outside the unified top-K-by-pre-rerank-A_o window. Applied
+   * additively to A_o weighted by `c_user` — `simUser` itself is the
+   * raw fused score and never carries the boost. Stored as a JSON field,
+   * so older log rows pre-date this addition and decode with `undefined`;
+   * readers should fall back to 0.
+   */
+  simUserRerankBoost: number;
+  /**
+   * Cross-encoder rerank delta for the assistant channel. Same semantics
+   * as `simUserRerankBoost`, weighted by `c_assistant` when applied to
+   * A_o. The NOW channel intentionally bypasses rerank, so there is no
+   * `simNowRerankBoost`.
+   */
+  simAssistantRerankBoost: number;
+  /**
+   * True when rerank ran and this slug landed in the unified
+   * top-K-by-pre-rerank-A_o pool. Distinguishes "cross-encoder evaluated
+   * this and chose 0" from "rerank skipped this slug" so the inspector
+   * can keep the rerank rows visible at `+0.000` instead of silently
+   * dropping them. Older log rows pre-date this field and decode with
+   * `undefined`; readers should fall back to `false`.
+   */
+  inRerankPool: boolean;
   spreadContribution: number;
   source: "prior_state" | "ann_top50" | "both";
   status: "in_context" | "injected" | "not_injected" | "page_missing";
 }
 
-export interface MemoryV2SkillRowRecord {
-  id: string;
-  activation: number;
-  simUser: number;
-  simAssistant: number;
-  simNow: number;
-  status: "injected" | "not_injected";
-}
-
 export interface MemoryV2ConfigSnapshot {
   d: number;
   c_user: number;
@@ -34,7 +51,6 @@ export interface MemoryV2ConfigSnapshot {
   k: number;
   hops: number;
   top_k: number;
-  top_k_skills: number;
   epsilon: number;
 }
 
@@ -43,7 +59,6 @@ export interface RecordMemoryV2ActivationLogParams {
   turn: number;
   mode: "context-load" | "per-turn";
   concepts: MemoryV2ConceptRowRecord[];
-  skills: MemoryV2SkillRowRecord[];
   config: MemoryV2ConfigSnapshot;
 }
 
@@ -51,6 +66,11 @@ export function recordMemoryV2ActivationLog(
   params: RecordMemoryV2ActivationLogParams,
 ): void {
   const db = getDb();
+  // Skills now live as concept rows under `slug: "skills/<id>"`, so the
+  // separate `skills_json` column is always written empty. The column itself
+  // remains in the schema for backwards-compat with prior log rows; the
+  // reader drops it. A future migration can DROP the column once those rows
+  // age out of relevance.
   db.insert(memoryV2ActivationLogs)
     .values({
       id: uuid(),
@@ -59,7 +79,7 @@ export function recordMemoryV2ActivationLog(
       turn: params.turn,
       mode: params.mode,
       conceptsJson: JSON.stringify(params.concepts),
-      skillsJson: JSON.stringify(params.skills),
+      skillsJson: "[]",
       configJson: JSON.stringify(params.config),
       createdAt: Date.now(),
     })
@@ -87,7 +107,6 @@ export interface MemoryV2ActivationLog {
   turn: number;
   mode: "context-load" | "per-turn";
   concepts: MemoryV2ConceptRowRecord[];
-  skills: MemoryV2SkillRowRecord[];
   config: MemoryV2ConfigSnapshot;
 }
 
@@ -109,7 +128,6 @@ export function getMemoryV2ActivationLogByMessageIds(
     turn: row.turn,
     mode: row.mode as "context-load" | "per-turn",
     concepts: JSON.parse(row.conceptsJson) as MemoryV2ConceptRowRecord[],
-    skills: JSON.parse(row.skillsJson) as MemoryV2SkillRowRecord[],
     config: JSON.parse(row.configJson) as MemoryV2ConfigSnapshot,
   };
 }

package/src/memory/memory-v2-concept-frequency.ts

@@ -0,0 +1,169 @@
+import type { MemoryV2ConceptRowRecord } from "./memory-v2-activation-log-store.js";
+import { rawAll, rawGet } from "./raw-query.js";
+import { listPages } from "./v2/page-store.js";
+
+type ConceptStatus = MemoryV2ConceptRowRecord["status"];
+
+export type ConceptFrequencyCounts = Record<ConceptStatus, number>;
+
+export interface ConceptFrequencyRow {
+  slug: string;
+  counts: ConceptFrequencyCounts;
+  totalEvaluations: number;
+  lastInjectedAt: number | null;
+  /** Whether the slug currently has a markdown page on disk. */
+  onDisk: boolean;
+}
+
+export interface ConceptFrequencyResponse {
+  filters: {
+    conversationId: string | null;
+    sinceMs: number | null;
+  };
+  totals: {
+    /** Activation log rows scanned (turns of evaluation in the window). */
+    logCount: number;
+    /** Sum of per-row concept evaluations across all log rows in the window. */
+    conceptOccurrences: number;
+  };
+  /** Per-slug aggregates, sorted by `totalEvaluations` desc, then slug asc. */
+  concepts: ConceptFrequencyRow[];
+  /**
+   * Slugs present on disk that never appeared in any activation log row in
+   * the window — i.e. retrieval never even scored them as a candidate.
+   */
+  neverEvaluatedSlugs: string[];
+}
+
+export interface GetConceptFrequencyFilters {
+  conversationId?: string;
+  sinceMs?: number;
+}
+
+interface AggRow {
+  slug: string | null;
+  status: ConceptStatus | string | null;
+  count: number;
+  last_seen: number;
+}
+
+const ZERO_COUNTS: ConceptFrequencyCounts = {
+  injected: 0,
+  in_context: 0,
+  not_injected: 0,
+  page_missing: 0,
+};
+
+interface CountRow {
+  count: number;
+}
+
+export async function getConceptFrequencySummary(
+  workspaceDir: string,
+  filters: GetConceptFrequencyFilters = {},
+): Promise<ConceptFrequencyResponse> {
+  const conversationId = filters.conversationId ?? null;
+  const sinceMs = filters.sinceMs ?? null;
+
+  // Kick off the on-disk page walk in parallel with the (synchronous) SQL
+  // queries below — listPages does fs.readdir, rawAll/rawGet are sync.
+  const onDiskSlugsPromise = listPages(workspaceDir);
+
+  const aggRows = rawAll<AggRow>(
+    `SELECT
+       json_extract(c.value, '$.slug')   AS slug,
+       json_extract(c.value, '$.status') AS status,
+       COUNT(*)                          AS count,
+       MAX(l.created_at)                 AS last_seen
+     FROM memory_v2_activation_logs l, json_each(l.concepts_json) c
+     WHERE (? IS NULL OR l.conversation_id = ?)
+       AND (? IS NULL OR l.created_at >= ?)
+     GROUP BY slug, status`,
+    conversationId,
+    conversationId,
+    sinceMs,
+    sinceMs,
+  );
+
+  const logCountRow = rawGet<CountRow>(
+    `SELECT COUNT(*) AS count
+       FROM memory_v2_activation_logs
+       WHERE (? IS NULL OR conversation_id = ?)
+         AND (? IS NULL OR created_at >= ?)`,
+    conversationId,
+    conversationId,
+    sinceMs,
+    sinceMs,
+  );
+
+  const bySlug = new Map<string, ConceptFrequencyRow>();
+  let conceptOccurrences = 0;
+
+  for (const row of aggRows) {
+    if (!row.slug) continue;
+    let entry = bySlug.get(row.slug);
+    if (!entry) {
+      entry = {
+        slug: row.slug,
+        counts: { ...ZERO_COUNTS },
+        totalEvaluations: 0,
+        lastInjectedAt: null,
+        onDisk: false,
+      };
+      bySlug.set(row.slug, entry);
+    }
+
+    switch (row.status) {
+      case "injected":
+        entry.counts.injected += row.count;
+        entry.lastInjectedAt =
+          entry.lastInjectedAt === null
+            ? row.last_seen
+            : Math.max(entry.lastInjectedAt, row.last_seen);
+        break;
+      case "in_context":
+        entry.counts.in_context += row.count;
+        break;
+      case "not_injected":
+        entry.counts.not_injected += row.count;
+        break;
+      case "page_missing":
+        entry.counts.page_missing += row.count;
+        break;
+      default:
+        // Forward-compat: unknown status values are ignored, not summed into
+        // totalEvaluations. The activation pipeline produces a closed enum.
+        continue;
+    }
+    entry.totalEvaluations += row.count;
+    conceptOccurrences += row.count;
+  }
+
+  const onDiskSlugs = new Set(await onDiskSlugsPromise);
+  for (const entry of bySlug.values()) {
+    entry.onDisk = onDiskSlugs.has(entry.slug);
+  }
+
+  const neverEvaluatedSlugs: string[] = [];
+  for (const slug of onDiskSlugs) {
+    if (!bySlug.has(slug)) neverEvaluatedSlugs.push(slug);
+  }
+  neverEvaluatedSlugs.sort();
+
+  const concepts = [...bySlug.values()].sort((a, b) => {
+    if (b.totalEvaluations !== a.totalEvaluations) {
+      return b.totalEvaluations - a.totalEvaluations;
+    }
+    return a.slug.localeCompare(b.slug);
+  });
+
+  return {
+    filters: { conversationId, sinceMs },
+    totals: {
+      logCount: logCountRow?.count ?? 0,
+      conceptOccurrences,
+    },
+    concepts,
+    neverEvaluatedSlugs,
+  };
+}

package/src/memory/migrations/239-trace-events-created-at-index.ts

@@ -0,0 +1,18 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_trace_events_created_at_index_v1";
+
+/**
+ * Add an index on `trace_events.created_at` so the periodic prune job
+ * can locate expired rows without a full table scan.
+ */
+export function migrateTraceEventsCreatedAtIndex(database: DrizzleDb): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    const raw = getSqliteFrom(database);
+    raw.exec(
+      `CREATE INDEX IF NOT EXISTS idx_trace_events_created_at ON trace_events(created_at)`,
+    );
+  });
+}

package/src/memory/migrations/index.ts

@@ -200,6 +200,7 @@ export {
   migrateHeartbeatRuns,
 } from "./237-heartbeat-runs.js";
 export { migrateScheduleRetryPolicy } from "./238-schedule-retry-policy.js";
+export { migrateTraceEventsCreatedAtIndex } from "./239-trace-events-created-at-index.js";
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/memory/pkb/pkb-search.test.ts

@@ -1,6 +1,12 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { makeMockLogger } from "../../__tests__/helpers/mock-logger.js";
+import { _setOverridesForTesting } from "../../config/assistant-feature-flags.js";
+
+// This test exercises the v1 PKB search path. The `memory-v2-enabled` flag
+// (registry default `true`) makes pkb-search short-circuit to keep traffic
+// off the legacy collection — disable it so the v1 path stays under test.
+_setOverridesForTesting({ "memory-v2-enabled": false });
 
 mock.module("../../util/logger.js", () => ({
   getLogger: () => makeMockLogger(),

package/src/memory/qdrant-client.ts

@@ -388,7 +388,6 @@ export class VellumQdrantClient {
     limit: number,
     targetTypes: Array<"segment" | "item" | "summary" | "media">,
     excludeMessageIds?: string[],
-    scopeIds?: string[],
   ): Promise<QdrantSearchResult[]> {
     const mustConditions: Array<Record<string, unknown>> = [
       {
@@ -415,18 +414,6 @@ export class VellumQdrantClient {
       });
     }
 
-    // Scope filtering: accept points whose memory_scope_id matches one of the
-    // allowed scopes, OR points that lack the field entirely (legacy data).
-    // Post-query DB filtering remains as defense-in-depth for legacy points.
-    if (scopeIds && scopeIds.length > 0) {
-      mustConditions.push({
-        should: [
-          { key: "memory_scope_id", match: { any: scopeIds } },
-          { is_empty: { key: "memory_scope_id" } },
-        ],
-      });
-    }
-
     const mustNotConditions: Array<Record<string, unknown>> = [
       { key: "_meta", match: { value: true } },
     ];

package/src/memory/rerank-local.ts

@@ -0,0 +1,374 @@
+/** Local cross-encoder rerank backend — drives the rerank-worker subprocess. */
+import { existsSync } from "node:fs";
+
+import type { RerankDtype } from "../config/schemas/memory-v2.js";
+import { getLogger } from "../util/logger.js";
+import { getEmbeddingModelsDir } from "../util/platform.js";
+import { PromiseGuard } from "../util/promise-guard.js";
+import { EmbeddingRuntimeManager } from "./embedding-runtime-manager.js";
+
+const log = getLogger("memory-rerank-local");
+
+interface WorkerResponse {
+  id?: number;
+  type?: string;
+  scores?: number[];
+  error?: string;
+}
+
+export class LocalRerankBackend {
+  readonly model: string;
+  readonly dtype: RerankDtype;
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private workerProc: any = null;
+  private stdoutBuffer = "";
+  private requestCounter = 0;
+  private pendingRequests = new Map<
+    number,
+    { resolve: (response: WorkerResponse) => void }
+  >();
+  private stdoutReaderActive = false;
+  private activeRequests = 0;
+  private disposeRequested = false;
+
+  private readyResolve: (() => void) | null = null;
+  private readyReject: ((err: Error) => void) | null = null;
+
+  private readonly initGuard = new PromiseGuard<void>();
+
+  constructor(model: string, dtype: RerankDtype) {
+    this.model = model;
+    this.dtype = dtype;
+  }
+
+  /**
+   * Score paired `(queries[i], passages[i])` tuples in one batched ONNX
+   * inference call. Multiple distinct queries can ride in a single batch
+   * so callers can score the user-channel and assistant-channel queries
+   * against a shared candidate set in one tokenizer + forward pass.
+   */
+  async score(queries: string[], passages: string[]): Promise<number[]> {
+    if (this.disposeRequested) {
+      throw new Error("Local rerank backend is shutting down");
+    }
+    if (passages.length === 0) return [];
+    if (queries.length !== passages.length) {
+      throw new Error(
+        `Rerank backend got ${queries.length} queries for ${passages.length} passages`,
+      );
+    }
+
+    this.activeRequests++;
+    try {
+      await this.ensureInitialized();
+      const response = await this.sendRequest({ queries, passages });
+      if (response.error) {
+        throw new Error(`Rerank worker error: ${response.error}`);
+      }
+      if (!response.scores) {
+        throw new Error("Rerank worker returned no scores");
+      }
+      if (response.scores.length !== passages.length) {
+        throw new Error(
+          `Rerank worker returned ${response.scores.length} scores for ${passages.length} passages`,
+        );
+      }
+      return response.scores;
+    } finally {
+      this.activeRequests--;
+      this.disposeIfIdle();
+    }
+  }
+
+  dispose(): void {
+    this.disposeRequested = true;
+    this.disposeIfIdle();
+  }
+
+  private sendRequest(payload: {
+    queries: string[];
+    passages: string[];
+  }): Promise<WorkerResponse> {
+    const id = ++this.requestCounter;
+    return new Promise((resolve) => {
+      if (!this.workerProc) {
+        resolve({ error: "Worker not initialized" });
+        return;
+      }
+      this.pendingRequests.set(id, { resolve });
+      this.workerProc.stdin.write(JSON.stringify({ id, ...payload }) + "\n");
+      try {
+        this.workerProc.stdin.flush();
+      } catch {
+        // Worker may have exited — stdout reader cleanup resolves pending requests.
+      }
+    });
+  }
+
+  private async ensureInitialized(): Promise<void> {
+    if (this.workerProc) return;
+    await this.initGuard.run(() => this.initialize());
+  }
+
+  private async initialize(): Promise<void> {
+    log.info({ model: this.model }, "Initializing local rerank backend");
+
+    const runtimeManager = new EmbeddingRuntimeManager();
+    if (!runtimeManager.isReady()) {
+      log.info("Embedding runtime not yet available, waiting for download...");
+      await runtimeManager.ensureInstalled();
+    }
+
+    const bunPath = runtimeManager.getBunPath();
+    const workerPath = runtimeManager.getRerankWorkerPath();
+
+    if (!bunPath) {
+      throw new Error("Local rerank backend unavailable: no bun binary found");
+    }
+    if (!existsSync(workerPath)) {
+      throw new Error(
+        `Local rerank backend unavailable: worker script not found at ${workerPath}`,
+      );
+    }
+
+    await this.startWorker(bunPath, workerPath);
+  }
+
+  private async startWorker(
+    bunPath: string,
+    workerPath: string,
+  ): Promise<void> {
+    const embeddingModelsDir = getEmbeddingModelsDir();
+    const modelCacheDir = `${embeddingModelsDir}/model-cache`;
+
+    log.info(
+      { bunPath, workerPath, model: this.model, dtype: this.dtype },
+      "Spawning rerank worker process",
+    );
+
+    const proc = Bun.spawn({
+      cmd: [
+        bunPath,
+        "--smol",
+        workerPath,
+        this.model,
+        modelCacheDir,
+        this.dtype,
+      ],
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+      cwd: embeddingModelsDir,
+    });
+
+    this.workerProc = proc;
+    this.startStdoutReader();
+
+    try {
+      await this.waitForReady();
+    } catch (err) {
+      this.workerProc = null;
+      this.stdoutReaderActive = false;
+      try {
+        proc.kill();
+      } catch {
+        /* may already be dead */
+      }
+      const exitCode = await proc.exited.catch(() => undefined);
+      const stderr = await new Response(proc.stderr).text().catch(() => "");
+      if (stderr.trim()) {
+        log.warn({ stderr: stderr.trim(), exitCode }, "Rerank worker stderr");
+      }
+      throw new Error(
+        `Rerank worker exited (code ${exitCode ?? "unknown"}): ${
+          stderr.trim() || (err instanceof Error ? err.message : String(err))
+        }`,
+      );
+    }
+
+    this.drainStderr(proc.stderr);
+    log.info(
+      { pid: proc.pid, model: this.model },
+      "Rerank worker process started",
+    );
+    this.disposeIfIdle();
+  }
+
+  private drainStderr(stderr: ReadableStream<Uint8Array>): void {
+    const reader = stderr.getReader();
+    const decoder = new TextDecoder();
+    (async () => {
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          const text = decoder.decode(value, { stream: true }).trim();
+          if (text) log.debug({ workerStderr: text }, "Rerank worker stderr");
+        }
+      } catch {
+        /* expected on shutdown */
+      }
+    })();
+  }
+
+  private startStdoutReader(): void {
+    if (this.stdoutReaderActive || !this.workerProc) return;
+    this.stdoutReaderActive = true;
+
+    const proc = this.workerProc;
+    const reader = proc.stdout.getReader();
+    const decoder = new TextDecoder();
+
+    (async () => {
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          this.stdoutBuffer += decoder.decode(value, { stream: true });
+          this.processStdoutBuffer();
+        }
+      } catch {
+        /* reader cancelled or stream errored */
+      }
+
+      if (this.workerProc === proc) {
+        for (const pending of this.pendingRequests.values()) {
+          pending.resolve({
+            error: "Rerank worker process exited unexpectedly",
+          });
+        }
+        this.pendingRequests.clear();
+        this.workerProc = null;
+        this.stdoutReaderActive = false;
+        this.stdoutBuffer = "";
+        this.initGuard.reset();
+      }
+    })();
+  }
+
+  private processStdoutBuffer(): void {
+    let idx: number;
+    while ((idx = this.stdoutBuffer.indexOf("\n")) !== -1) {
+      const line = this.stdoutBuffer.slice(0, idx);
+      this.stdoutBuffer = this.stdoutBuffer.slice(idx + 1);
+      if (!line.trim()) continue;
+
+      let msg: WorkerResponse;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue;
+      }
+
+      if (msg.type === "ready") {
+        this.readyResolve?.();
+        this.readyResolve = null;
+        this.readyReject = null;
+        continue;
+      }
+      if (msg.type === "error" && this.readyReject) {
+        this.readyReject(
+          new Error(msg.error ?? "Worker initialization failed"),
+        );
+        this.readyResolve = null;
+        this.readyReject = null;
+        continue;
+      }
+
+      if (msg.id !== undefined) {
+        const pending = this.pendingRequests.get(msg.id);
+        if (pending) {
+          this.pendingRequests.delete(msg.id);
+          pending.resolve(msg);
+          this.disposeIfIdle();
+        }
+      }
+    }
+  }
+
+  private waitForReady(): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      // First-call timeout. Generous because the first run downloads the
+      // ONNX weights (~280 MB to ~1 GB depending on model) before loading.
+      const timeout = setTimeout(() => {
+        this.readyResolve = null;
+        this.readyReject = null;
+        reject(new Error("Rerank worker timed out waiting for model to load"));
+      }, 120_000);
+
+      this.readyResolve = () => {
+        clearTimeout(timeout);
+        resolve();
+      };
+      this.readyReject = (err: Error) => {
+        clearTimeout(timeout);
+        reject(err);
+      };
+
+      this.workerProc?.exited.then(() => {
+        if (this.readyResolve) {
+          clearTimeout(timeout);
+          this.readyResolve = null;
+          this.readyReject = null;
+          reject(
+            new Error("Rerank worker process exited before becoming ready"),
+          );
+        }
+      });
+    });
+  }
+
+  private disposeIfIdle(): void {
+    if (!this.disposeRequested) return;
+    if (this.activeRequests > 0) return;
+    if (this.pendingRequests.size > 0) return;
+    if (this.readyResolve || this.readyReject) return;
+
+    const proc = this.workerProc;
+    this.workerProc = null;
+    this.stdoutReaderActive = false;
+    this.stdoutBuffer = "";
+    this.initGuard.reset();
+
+    if (!proc) return;
+
+    try {
+      proc.kill();
+    } catch {
+      /* may already be exiting */
+    }
+  }
+}
+
+// ── Module-level singleton management ─────────────────────────────────
+
+let _backend: LocalRerankBackend | null = null;
+
+export function getOrCreateRerankBackend(
+  model: string,
+  dtype: RerankDtype,
+): LocalRerankBackend {
+  if (_backend?.model === model && _backend.dtype === dtype) return _backend;
+  if (_backend) {
+    try {
+      _backend.dispose();
+    } catch {
+      /* best effort */
+    }
+  }
+  _backend = new LocalRerankBackend(model, dtype);
+  return _backend;
+}
+
+/** @internal Test-only: reset the cached backend. */
+export function _resetRerankBackendForTests(): void {
+  if (_backend) {
+    try {
+      _backend.dispose();
+    } catch {
+      /* best effort */
+    }
+  }
+  _backend = null;
+}