@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/plugins/defaults/memory/context-search/agent-runner.ts

@@ -4,8 +4,8 @@ import type {
   ProviderResponse,
   ToolUseContent,
 } from "@vellumai/plugin-api";
+import { getConfiguredProvider } from "@vellumai/plugin-api";
 
-import { getConfiguredProvider } from "../../../../providers/provider-send-message.js";
 import { redactSecrets } from "../../../../security/secret-scanner.js";
 import {
   buildRecallAgentPromptBundle,

package/src/plugins/defaults/memory/context-search/sources/conversations.ts

@@ -1,16 +1,21 @@
 import { readSlackMetadata } from "../../../../../messaging/providers/slack/message-metadata.js";
 import { AUTO_ANALYSIS_SOURCE } from "../../../../../persistence/auto-analysis-constants.js";
+import { isLexicalBackfillComplete } from "../../../../../persistence/checkpoints.js";
 import {
-  buildFtsMatchQuery,
   buildRecallEvidenceExcerpt,
+  hasLexicalTokens,
 } from "../../../../../persistence/conversation-queries.js";
+import { searchMessageIdsLexical } from "../../../../../persistence/conversation-search-lexical.js";
 import { rawAll } from "../../../../../persistence/raw-query.js";
 import {
   parseExternalContentEnvelope,
   wrapUntrustedContent,
 } from "../../../../../security/untrusted-content.js";
+import { getLogger } from "../../../../../util/logger.js";
 import type { RecallSearchContext, RecallSearchResult } from "../types.js";
 
+const log = getLogger("recall-conversations-source");
+
 const SUBAGENT_SOURCE = "subagent";
 const NOTIFICATION_SOURCE = "notification";
 
@@ -24,7 +29,30 @@ interface ConversationEvidenceRow {
   title: string | null;
 }
 
-const CONVERSATION_SEARCH_PREFETCH_MULTIPLIER = 5;
+/**
+ * Qdrant candidate over-fetch multiplier for the lexical read path.
+ *
+ * The read fetches ranked message-id candidates first and filters them in SQL
+ * afterwards (Qdrant has no visibility filtering), so it must over-fetch
+ * enough candidates that excluded rows (the active conversation,
+ * subagent/auto-analysis/notification sources, private history) don't starve
+ * the post-filter pool. A generous candidate pool is cheap — the final
+ * consumer takes top-N after the app-side scorer anyway.
+ *
+ * This is a proportionate over-fetch, NOT a hard guarantee: a query whose
+ * visible matches all rank beyond the widened window can still be
+ * under-filled. A stronger fix would need pagination or Qdrant group-search.
+ */
+const QDRANT_RECALL_CANDIDATE_MULTIPLIER = 20;
+
+/**
+ * Floor for the Qdrant candidate pool, so small `max_results` requests still
+ * over-fetch a healthy number of candidates before SQL filtering. Recall's
+ * `max_results` is capped at `MAX_RECALL_MAX_RESULTS` (20), so the pool is
+ * bounded at 20 × 20 = 400 candidate ids — far under the SQLite bound-variable
+ * limit (32766), so the `WHERE m.id IN (...)` query needs no chunking.
+ */
+const QDRANT_RECALL_MIN_CANDIDATES = 200;
 
 const NON_SALIENT_RECALL_TERMS = new Set([
   "a",
@@ -86,30 +114,42 @@ export async function searchConversationSource(
     return { evidence: [] };
   }
 
-  const queryLimit = Math.max(
-    normalizedLimit,
-    normalizedLimit * CONVERSATION_SEARCH_PREFETCH_MULTIPLIER,
-  );
-  const ftsMatches = buildRecallFtsMatchQueries(trimmedQuery);
-  let rows: ConversationEvidenceRow[] = [];
-
-  for (const ftsMatch of ftsMatches) {
-    try {
-      rows = mergeConversationRows(
-        rows,
-        searchWithFts(ftsMatch, queryLimit, context.conversationId),
-      );
-    } catch {
-      // Try the next, broader query shape.
-    }
-
-    if (rows.length >= normalizedLimit) break;
+  // The Qdrant lexical index — the only source of conversation evidence — is
+  // populated unconditionally (host-owned message-search indexing), but until
+  // the one-time upgrade backfill has fully drained it holds only messages
+  // written since the write path went live. A qdrant read then would silently
+  // miss older content (an empty candidate set, not a throw), so the source
+  // yields no evidence instead of serving misleading partial results. The
+  // completion checkpoint is shared with the persistence read site.
+  if (!isLexicalBackfillComplete()) {
+    return { evidence: [] };
   }
 
-  if (rows.length === 0) {
-    rows = searchWithLike(trimmedQuery, queryLimit, context.conversationId);
+  // Short/punctuation-only queries (`C++`, CJK) produce no usable ≥2-char
+  // token. Content matching is index-only, so such queries yield no
+  // conversation evidence. The early return also keeps the sparse encoder
+  // honest: it still emits a 1-char token for these queries, so querying the
+  // index anyway would return noisy hits.
+  if (!hasLexicalTokens(trimmedQuery)) {
+    return { evidence: [] };
   }
 
+  // A brief post-edit staleness window (an edited message whose re-index job
+  // has not yet run, or a just-deleted message still present as a point) is
+  // an ACCEPTED consequence of async indexing. Recall is fuzzy evidence
+  // re-ranked by the app-side scorer, and the wide candidate pool dilutes a
+  // single stale hit; we do not re-verify candidate content against the query
+  // (a substring re-check would wrongly drop valid stemmed matches).
+  const qdrantCandidateLimit = Math.max(
+    normalizedLimit * QDRANT_RECALL_CANDIDATE_MULTIPLIER,
+    QDRANT_RECALL_MIN_CANDIDATES,
+  );
+  const rows = await gatherCandidateRowsFromQdrant(
+    trimmedQuery,
+    qdrantCandidateLimit,
+    context.conversationId,
+  );
+
   const sortedRows = rows
     .map((row) => ({
       row,
@@ -135,46 +175,61 @@ export async function searchConversationSource(
   };
 }
 
-function searchWithFts(
-  ftsMatch: string,
-  limit: number,
+/**
+ * Generate candidate rows via the Qdrant lexical index. Qdrant is
+ * candidate-generation only: it supplies over-fetched message-id candidates
+ * (ranked by sparse score) whose rows are then re-fetched with the
+ * source/type/excluded-conversation predicates applied in SQL
+ * ({@link searchByIds}). Final ordering stays with the app-side scorer.
+ *
+ * `candidateLimit` is the widened over-fetch count (see
+ * {@link QDRANT_RECALL_CANDIDATE_MULTIPLIER}) — it bounds both the Qdrant fetch
+ * and the post-filter SQL `LIMIT`, so surviving candidates aren't dropped
+ * before scoring. Filtering shrinks the pool but never grows it, so the final
+ * `LIMIT` is a no-op ceiling here; it exists only to bound the returned rows.
+ *
+ * Returns an empty array when the query tokenizes to no sparse terms (the
+ * lexical helper's empty guard) or when the Qdrant call throws (logged) — the
+ * source then yields no conversation evidence for the query.
+ */
+async function gatherCandidateRowsFromQdrant(
+  query: string,
+  candidateLimit: number,
   excludedConversationId: string,
-): ConversationEvidenceRow[] {
-  return rawAll<ConversationEvidenceRow>(
-    `
-    SELECT
-      m.id AS message_id,
-      m.conversation_id,
-      m.role,
-      m.content,
-      m.created_at,
-      m.metadata,
-      c.title
-    FROM messages_fts
-    JOIN messages m ON m.id = messages_fts.message_id
-    JOIN conversations c ON c.id = m.conversation_id
-    WHERE messages_fts MATCH ?
-      AND (c.source IS NULL OR c.source NOT IN (?, ?, ?))
-      AND c.id != ?
-      AND c.conversation_type != 'private'
-    ORDER BY bm25(messages_fts), m.created_at DESC
-    LIMIT ?
-    `,
-    ftsMatch,
-    SUBAGENT_SOURCE,
-    AUTO_ANALYSIS_SOURCE,
-    NOTIFICATION_SOURCE,
-    excludedConversationId,
-    limit,
-  );
+): Promise<ConversationEvidenceRow[]> {
+  let candidates: Array<{ messageId: string }>;
+  try {
+    candidates = await searchMessageIdsLexical(query, candidateLimit);
+  } catch (err) {
+    log.warn(
+      { err, query: query.slice(0, 80) },
+      "recall conversations source: Qdrant lexical query failed — no conversation evidence for this query",
+    );
+    return [];
+  }
+
+  const candidateIds = candidates.map((candidate) => candidate.messageId);
+  if (candidateIds.length === 0) {
+    return [];
+  }
+
+  return searchByIds(candidateIds, candidateLimit, excludedConversationId);
 }
 
-function searchWithLike(
-  query: string,
+/**
+ * Fetch evidence rows for an explicit set of candidate message ids, applying
+ * the source/type/excluded-conversation predicates in SQL (Qdrant has no
+ * visibility filtering). The app-side scorer determines final ordering, so
+ * the SQL tie-break falls back to recency.
+ */
+function searchByIds(
+  messageIds: readonly string[],
   limit: number,
   excludedConversationId: string,
 ): ConversationEvidenceRow[] {
+  const placeholders = messageIds.map(() => "?").join(", ");
   return rawAll<ConversationEvidenceRow>(
+    "convSearch:searchByIds",
     `
     SELECT
       m.id AS message_id,
@@ -186,14 +241,14 @@ function searchWithLike(
       c.title
     FROM messages m
     JOIN conversations c ON c.id = m.conversation_id
-    WHERE m.content LIKE ? ESCAPE '\\'
+    WHERE m.id IN (${placeholders})
       AND (c.source IS NULL OR c.source NOT IN (?, ?, ?))
       AND c.id != ?
       AND c.conversation_type != 'private'
     ORDER BY m.created_at DESC
     LIMIT ?
     `,
-    buildLikePattern(query),
+    ...messageIds,
     SUBAGENT_SOURCE,
     AUTO_ANALYSIS_SOURCE,
     NOTIFICATION_SOURCE,
@@ -228,7 +283,9 @@ function parseSlackRecallMetadata(rawMetadata: string | null): {
   displayName?: string;
   provenanceTrustClass?: string;
 } | null {
-  if (!rawMetadata) return null;
+  if (!rawMetadata) {
+    return null;
+  }
 
   let parsed: unknown;
   try {
@@ -242,9 +299,13 @@ function parseSlackRecallMetadata(rawMetadata: string | null): {
   }
 
   const metadata = parsed as Record<string, unknown>;
-  if (typeof metadata.slackMeta !== "string") return null;
+  if (typeof metadata.slackMeta !== "string") {
+    return null;
+  }
   const slackMeta = readSlackMetadata(metadata.slackMeta);
-  if (!slackMeta) return null;
+  if (!slackMeta) {
+    return null;
+  }
 
   return {
     ...(slackMeta.displayName ? { displayName: slackMeta.displayName } : {}),
@@ -254,35 +315,6 @@ function parseSlackRecallMetadata(rawMetadata: string | null): {
   };
 }
 
-function buildRecallFtsMatchQueries(query: string): string[] {
-  const queries: string[] = [];
-  const exact = buildFtsMatchQuery(query);
-  if (exact) {
-    queries.push(exact);
-  }
-
-  const salientTerms = tokenizeSalientRecallTerms(query);
-  if (salientTerms.length > 0) {
-    const salientAnd = salientTerms.map(quoteFtsToken).join(" ");
-    if (salientAnd && !queries.includes(salientAnd)) {
-      queries.push(salientAnd);
-    }
-
-    if (salientTerms.length > 1) {
-      const salientOr = salientTerms.map(quoteFtsToken).join(" OR ");
-      if (!queries.includes(salientOr)) {
-        queries.push(salientOr);
-      }
-    }
-  }
-
-  return queries;
-}
-
-function quoteFtsToken(token: string): string {
-  return `"${token.replace(/"/g, '""')}"`;
-}
-
 function tokenizeSalientRecallTerms(text: string): string[] {
   const terms = (text.toLowerCase().match(/[a-z0-9_]+/g) ?? []).filter(
     (term) => term.length >= 2 && !NON_SALIENT_RECALL_TERMS.has(term),
@@ -290,22 +322,6 @@ function tokenizeSalientRecallTerms(text: string): string[] {
   return [...new Set(terms)].slice(0, 12);
 }
 
-function mergeConversationRows(
-  existing: readonly ConversationEvidenceRow[],
-  next: readonly ConversationEvidenceRow[],
-): ConversationEvidenceRow[] {
-  const seen = new Set(existing.map((row) => row.message_id));
-  const merged = [...existing];
-  for (const row of next) {
-    if (seen.has(row.message_id)) {
-      continue;
-    }
-    seen.add(row.message_id);
-    merged.push(row);
-  }
-  return merged;
-}
-
 function scoreConversationRow(
   row: ConversationEvidenceRow,
   query: string,
@@ -329,13 +345,8 @@ function compareScoredConversationRows(
   b: { row: ConversationEvidenceRow; score: number },
 ): number {
   const scoreCompare = b.score - a.score;
-  if (scoreCompare !== 0) return scoreCompare;
+  if (scoreCompare !== 0) {
+    return scoreCompare;
+  }
   return b.row.created_at - a.row.created_at;
 }
-
-function buildLikePattern(query: string): string {
-  return `%${query
-    .replace(/\\/g, "\\\\")
-    .replace(/%/g, "\\%")
-    .replace(/_/g, "\\_")}%`;
-}

package/src/plugins/defaults/memory/embeddings.ts

@@ -0,0 +1,77 @@
+import { getConfig } from "../../../config/loader.js";
+import type { AssistantConfig } from "../../../config/types.js";
+import type {
+  EmbeddingInput,
+  EmbeddingRequestOptions,
+} from "../../../persistence/embeddings/embedding-types.js";
+import { resolveQdrantUrl as resolveQdrantUrlWithConfig } from "../../../persistence/embeddings/qdrant-client.js";
+
+/**
+ * Memory-internal accessor for the shared embeddings / vector subsystem.
+ *
+ * The embeddings operations live in `persistence/embeddings` (and
+ * `persistence/job-utils`) and take the full `AssistantConfig` as their first
+ * argument — they read both the `memory` slice (Qdrant collection and vector
+ * settings) and the `llm` slice (embedding-backend selection). Memory code
+ * reaches those operations through this accessor: the self-contained ones
+ * (`embedAndUpsert`, `selectedBackendSupportsMultimodal`, `resolveQdrantUrl`)
+ * resolve the live config internally, so their call sites need not hold it.
+ * `embedWithBackend` keeps its `config` parameter — it is a primitive whose
+ * vectors the caller stores alongside its own config-derived metadata (cache
+ * keys, vector-size checks, Qdrant collection), so it must embed with the
+ * caller's exact config snapshot rather than a re-read that could diverge from
+ * that metadata mid-operation.
+ *
+ * The embed operations are loaded via dynamic `import()` inside each wrapper so
+ * that importing this module for a single operation does not eagerly pull the
+ * whole embed/vector import graph (`job-utils`, `embedding-backend`) into the
+ * consumer. An eager pull would force every one of those modules' named exports
+ * to resolve at instantiation, which breaks the intentional partial module
+ * mocks in memory tests (a store that mocks only the exports it uses). Only the
+ * synchronous `resolveQdrantUrl` is imported statically.
+ */
+
+type EmbeddingTargetType = Parameters<
+  typeof import("../../../persistence/job-utils.js").embedAndUpsert
+>[1];
+
+/** Embed a target and upsert its vector to Qdrant. */
+export async function embedAndUpsert(
+  targetType: EmbeddingTargetType,
+  targetId: string,
+  input: EmbeddingInput,
+  extraPayload?: Record<string, unknown>,
+): Promise<void> {
+  const { embedAndUpsert: withConfig } =
+    await import("../../../persistence/job-utils.js");
+  return withConfig(getConfig(), targetType, targetId, input, extraPayload);
+}
+
+/** Embed one or more inputs via the selected embedding backend. */
+export async function embedWithBackend(
+  config: AssistantConfig,
+  inputs: EmbeddingInput[],
+  options?: EmbeddingRequestOptions,
+): Promise<
+  Awaited<
+    ReturnType<
+      typeof import("../../../persistence/embeddings/embedding-backend.js").embedWithBackend
+    >
+  >
+> {
+  const { embedWithBackend: withConfig } =
+    await import("../../../persistence/embeddings/embedding-backend.js");
+  return withConfig(config, inputs, options);
+}
+
+/** Whether the active embedding backend handles multimodal inputs. */
+export async function selectedBackendSupportsMultimodal(): Promise<boolean> {
+  const { selectedBackendSupportsMultimodal: withConfig } =
+    await import("../../../persistence/embeddings/embedding-backend.js");
+  return withConfig(getConfig());
+}
+
+/** Resolve the Qdrant base URL for this process. */
+export function resolveQdrantUrl(): string {
+  return resolveQdrantUrlWithConfig(getConfig());
+}

package/src/plugins/defaults/memory/find-most-recent-retrospective-for.ts

@@ -0,0 +1,66 @@
+import { and, desc, eq, inArray } from "drizzle-orm";
+
+import { getDb } from "../../../persistence/db-connection.js";
+import { conversations } from "../../../persistence/schema/index.js";
+import { MEMORY_RETROSPECTIVE_SOURCES } from "./memory-retrospective-constants.js";
+
+const MAX_FORK_CHAIN_DEPTH = 16;
+
+/**
+ * Find the most recent memory-retrospective background conversation rooted
+ * at `parentConversationId`. Used by the memory-retrospective job handler
+ * to load the prior retrospective's `remember` calls into the new run's
+ * `<already_remembered>` block — bounded source-of-truth for "what the
+ * prior pass already saved" that scales as the source conversation grows.
+ *
+ * Walks up `forkParentConversationId` when no retrospective exists at the
+ * current level. This lets a forked conversation inherit dedup context from
+ * its source's most recent retro on the fork's *first* retrospective —
+ * otherwise the fork would re-save every fact the source already retro'd.
+ * Once the fork accumulates its own retros, those are found at the first
+ * iteration and we never walk up.
+ *
+ * The returned `forkParentConversationId` is the conversation the
+ * retrospective row is rooted at — `parentConversationId` itself when it has
+ * its own retros, or an ancestor when the chain walk found the row higher
+ * up. Callers that mutate the prior (e.g. GC of superseded runs) must check
+ * it against the source conversation: an ancestor's row is that ancestor's
+ * dedup baseline, not the caller's to delete.
+ *
+ * Returns `null` when no prior retrospective exists anywhere in the fork
+ * chain (true first-run case).
+ *
+ * Hits `idx_conversations_fork_parent_conversation_id` for the
+ * `forkParentConversationId` lookup.
+ */
+export function findMostRecentRetrospectiveFor(
+  parentConversationId: string,
+): { id: string; forkParentConversationId: string } | null {
+  const db = getDb();
+  let currentId: string | null = parentConversationId;
+  for (let depth = 0; depth < MAX_FORK_CHAIN_DEPTH && currentId; depth++) {
+    const row = db
+      .select({ id: conversations.id })
+      .from(conversations)
+      .where(
+        and(
+          inArray(conversations.source, MEMORY_RETROSPECTIVE_SOURCES),
+          eq(conversations.forkParentConversationId, currentId),
+        ),
+      )
+      .orderBy(desc(conversations.createdAt))
+      .limit(1)
+      .get();
+    if (row) return { id: row.id, forkParentConversationId: currentId };
+
+    const parent = db
+      .select({
+        forkParentConversationId: conversations.forkParentConversationId,
+      })
+      .from(conversations)
+      .where(eq(conversations.id, currentId))
+      .get();
+    currentId = parent?.forkParentConversationId ?? null;
+  }
+  return null;
+}

package/src/plugins/defaults/memory/frontmatter.ts

@@ -0,0 +1,50 @@
+/**
+ * Frontmatter parsing for memory's concept-page and card `.md` files.
+ *
+ * Frontmatter is a YAML block delimited by `---` at the top of a file. Memory
+ * owns this parser rather than importing the host `skills/` copy so the plugin
+ * depends only on its own files, `@vellumai/plugin-api`, and external packages.
+ */
+
+import { parse as parseYaml } from "yaml";
+
+import { getLogger } from "../../../util/logger.js";
+
+const log = getLogger("memory-frontmatter");
+
+/** Matches a `---` delimited frontmatter block at the start of a file. */
+export const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+
+interface FrontmatterParseResult {
+  /** Key-value pairs extracted from the frontmatter block. */
+  fields: Record<string, unknown>;
+  /** The remaining file content after the frontmatter block. */
+  body: string;
+}
+
+/**
+ * Parse frontmatter fields from file content. Extracts key-value pairs from the
+ * `---` delimited block at the top of the file via a YAML parser, handling
+ * nested objects, arrays, quoted strings, and escape sequences natively.
+ * Returns `null` if no frontmatter block is found.
+ */
+export function parseFrontmatterFields(
+  content: string,
+): FrontmatterParseResult | null {
+  const match = content.match(FRONTMATTER_REGEX);
+  if (!match) return null;
+
+  const frontmatter = match[1];
+  const body = content.slice(match[0].length);
+
+  try {
+    const parsed = parseYaml(frontmatter);
+    if (parsed == null || typeof parsed !== "object") {
+      return { fields: {}, body };
+    }
+    return { fields: parsed as Record<string, unknown>, body };
+  } catch (err) {
+    log.warn({ err }, "Failed to parse YAML frontmatter");
+    return null;
+  }
+}