@vellumai/assistant 0.6.6 → 0.7.0

package/src/memory/graph/tools.ts

@@ -1,72 +1,52 @@
 // ---------------------------------------------------------------------------
-// Memory Graph — Tool definitions for recall and remember
-//
-// These replace memory_recall and memory_manage from the old system.
+// Memory Tool definitions for agentic recall and remember.
 // ---------------------------------------------------------------------------
 
 import type { ToolDefinition } from "../../providers/types.js";
+import {
+  ALL_RECALL_SOURCES,
+  MAX_RECALL_MAX_RESULTS,
+  MIN_RECALL_MAX_RESULTS,
+} from "../context-search/limits.js";
+
+const RECALL_DEPTHS = ["fast", "standard", "deep"] as const;
 
 /**
- * Explicit memory search across the living graph or raw archive.
- *
- * Auto-injected context covers common cases, but the assistant should
- * proactively recall when uncertain — search first, ask second.
+ * Explicit local information search across memory, PKB, conversations, and
+ * workspace files.
  */
 export const graphRecallDefinition: ToolDefinition = {
   name: "recall",
   description:
-    "Search your memory for specific information. Use this proactively — if you're uncertain about something, look it up before asking. Auto-injected context covers common cases, but actively recall when: you're about to ask a question that memory might answer, the user references something you should already know, you need details about a past conversation or event, or you want to search by a specific feeling, time period, or person. When in doubt, search first, ask second. Be specific in your query for best results.",
+    'Search local information the moment you feel uncertain. Use recall for memory, the personal knowledge base, past conversations, and workspace files — before you guess, before you ask, before you hedge. Auto-injection is incomplete by design; it surfaces patterns, not the specifics you need to answer well. If you catch yourself reaching for "I think", "I believe", "if I remember", "didn\'t we", "last time" — that\'s the signal. Recall. If the user references someone, a place, a decision, a document, or prior work you should be able to find locally — recall. Call it multiple times per conversation if the turn warrants it. Be specific in your query for best results.',
   input_schema: {
     type: "object",
     properties: {
       query: {
         type: "string",
         description:
-          "What you're looking for — be specific and descriptive. Can be a topic, feeling, time period, or person.",
+          "What you're looking for. Be specific and descriptive: include the topic, person, project, decision, time period, or file clues when known.",
       },
-      num_results: {
-        type: "integer",
+      sources: {
+        type: "array",
+        items: {
+          type: "string",
+          enum: [...ALL_RECALL_SOURCES],
+        },
         description:
-          "Maximum number of results to return (default 20, max 50).",
+          "Optional local sources to search. Omit to search memory, PKB, conversations, and workspace files.",
       },
-      mode: {
+      max_results: {
+        type: "integer",
+        minimum: MIN_RECALL_MAX_RESULTS,
+        maximum: MAX_RECALL_MAX_RESULTS,
+        description: "Maximum number of evidence items to return.",
+      },
+      depth: {
         type: "string",
-        enum: ["memory", "archive"],
+        enum: [...RECALL_DEPTHS],
         description:
-          '"memory" searches the living memory graph using semantic similarity (default). "archive" searches raw conversation transcripts using keyword matching. Supports FTS5 syntax: use "quoted phrases" for exact matching, AND/OR for boolean logic, NEAR(word1 word2, N) for proximity. Without operators, all keywords must appear (implicit AND). Short words like "I" and "a" are ignored. Prefer "memory" for conceptual/emotional queries, "archive" for finding specific wording.',
-      },
-      filters: {
-        type: "object",
-        description: "Optional filters to narrow results",
-        properties: {
-          types: {
-            type: "array",
-            items: {
-              type: "string",
-              enum: [
-                "episodic",
-                "semantic",
-                "procedural",
-                "emotional",
-                "prospective",
-                "behavioral",
-                "narrative",
-                "shared",
-              ],
-            },
-            description: "Only return memories of these types",
-          },
-          after: {
-            type: "string",
-            description:
-              "Only return memories created after this date (ISO 8601)",
-          },
-          before: {
-            type: "string",
-            description:
-              "Only return memories created before this date (ISO 8601)",
-          },
-        },
+          "Search effort. Use fast for quick lookups, standard by default, and deep when the answer may require multiple local searches.",
       },
     },
     required: ["query"],
@@ -74,15 +54,17 @@ export const graphRecallDefinition: ToolDefinition = {
 };
 
 /**
- * Save a fact to the personal knowledge base. The fact is appended to
- * buffer.md (immediately available in the next conversation) and the
- * daily archive (permanent date-indexed record). Filing into topic
- * files happens during the periodic filing job.
+ * Save a fact to the assistant's knowledge base. The fact is appended to
+ * `buffer.md` (immediately available in the next conversation) and the daily
+ * archive (permanent date-indexed record). With the `memory-v2-enabled`
+ * feature flag on, writes go under `memory/`; otherwise they go under
+ * `pkb/`. Consolidation of the buffer into longer-form storage runs as a
+ * separate periodic job in both modes.
  */
 export const graphRememberDefinition: ToolDefinition = {
   name: "remember",
   description:
-    "Save a fact to your knowledge base. Call this AGGRESSIVELY — capture anything concrete about their life: preferences, locations, names, dates, habits, opinions, health details, plans, relationship facts, routines, commitments. Default to remembering; only skip obvious noise (small talk, hypotheticals, things they're just musing about). Don't judge importance — filing decides that later. Examples: 'Prefers UberEats over DoorDash', 'Lives in NYC, from Texas', 'Takes daily medication, tapering dose', 'Partner Alex lives in Austin', 'Watches a weekly show on Saturday nights', 'Conference in May'. Call this multiple times per conversation — it's cheap (one line appended to a file). Don't wait until the end. Don't batch. Every new fact, immediately. Remembering too much is infinitely better than forgetting something that mattered. CORRECTIONS are the highest priority — when the user corrects a fact you had wrong, `remember` the correction immediately. The wrong version is already propagated in your prior turns and memory graph; skipping a correction means future-you keeps operating on the old value. Never skip a correction even if you'd skip the equivalent fresh fact.",
+    "Remember anything concrete: facts, preferences, corrections, plans, felt moments, names, dates, decisions. Default to remembering. Never wait until end of conversation. Corrections are highest priority — call remember the same turn the correction lands. **CRITICAL:** You should be calling remember on almost every turn. This should be your most frequently used tool.",
   input_schema: {
     type: "object",
     properties: {

package/src/memory/group-crud.ts

@@ -8,8 +8,7 @@
 import { v4 as uuid } from "uuid";
 
 import { ensureGroupMigration } from "./conversation-group-migration.js";
-import { rawAll, rawExec, rawGet, rawRun } from "./db.js";
-
+import { rawAll, rawExec, rawGet, rawRun } from "./raw-query.js";
 export interface ConversationGroupRow {
   id: string;
   name: string;

package/src/memory/guardian-action-store.ts

@@ -11,7 +11,8 @@ import { and, desc, eq, inArray, lt } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
 import { getLogger } from "../util/logger.js";
-import { getDb, rawChanges } from "./db.js";
+import { getDb } from "./db-connection.js";
+import { rawChanges } from "./raw-query.js";
 import { guardianActionDeliveries, guardianActionRequests } from "./schema.js";
 
 const log = getLogger("guardian-action-store");

package/src/memory/guardian-approvals.ts

@@ -9,7 +9,7 @@
 import { and, desc, eq, gt, lte } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
-import { getDb } from "./db.js";
+import { getDb } from "./db-connection.js";
 import { channelGuardianApprovalRequests } from "./schema.js";
 
 // ---------------------------------------------------------------------------

package/src/memory/guardian-rate-limits.ts

@@ -8,7 +8,7 @@
 import { and, eq } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
 
-import { getDb } from "./db.js";
+import { getDb } from "./db-connection.js";
 import { channelGuardianRateLimits } from "./schema.js";
 
 // ---------------------------------------------------------------------------

package/src/memory/indexer.ts

@@ -9,7 +9,7 @@ import { getLogger } from "../util/logger.js";
 import { enqueueAutoAnalysisIfEnabled } from "./auto-analysis-enqueue.js";
 import { isAutoAnalysisConversation } from "./auto-analysis-guard.js";
 import { getMemoryCheckpoint, setMemoryCheckpoint } from "./checkpoints.js";
-import { getDb } from "./db.js";
+import { getDb } from "./db-connection.js";
 import { selectedBackendSupportsMultimodal } from "./embedding-backend.js";
 import { enqueueMemoryJob, upsertDebouncedJob } from "./jobs-store.js";
 import {
@@ -193,15 +193,52 @@ export async function indexMessageNow(
       // Routing both paths through `upsertDebouncedJob` ensures the
       // row's `runAfter` reflects whichever trigger ran last, so a
       // batch crossing always takes effect immediately.
+      const extractRunAfter = graphBatchFired
+        ? Date.now()
+        : Date.now() + idleTimeoutMs;
       upsertDebouncedJob(
         "graph_extract",
         {
           conversationId: input.conversationId,
           scopeId: input.scopeId ?? "default",
         },
-        graphBatchFired ? Date.now() : Date.now() + idleTimeoutMs,
+        extractRunAfter,
       );
 
+      // Reading config here is best-effort: feature-gated triggers below
+      // (memory v2 sweep, auto-analyze batch) skip when it fails — the
+      // idle-debounced enqueues above are unaffected.
+      let triggerConfig: ReturnType<typeof getConfig> | null = null;
+      try {
+        triggerConfig = getConfig();
+      } catch (err) {
+        log.debug(
+          { err, conversationId: input.conversationId },
+          "Skipping feature-gated extraction triggers: failed to load config",
+        );
+      }
+
+      // Memory v2 sweep mirrors graph_extract's debounce: when the v2
+      // flag + config are on AND `sweep_enabled` is set, every extraction
+      // trigger also enqueues a sweep. The sweep itself reads recent
+      // messages globally, so the `conversationId` here is just the dedup
+      // key — one pending row per active conversation. All three gates
+      // (feature flag, v2 master toggle, sweep_enabled) must be true.
+      // `sweep_enabled` defaults to false because `remember()` is the
+      // primary capture path; the sweep is opt-in.
+      if (
+        triggerConfig != null &&
+        isAssistantFeatureFlagEnabled("memory-v2-enabled", triggerConfig) &&
+        triggerConfig.memory.v2.enabled &&
+        triggerConfig.memory.v2.sweep_enabled
+      ) {
+        upsertDebouncedJob(
+          "memory_v2_sweep",
+          { conversationId: input.conversationId },
+          extractRunAfter,
+        );
+      }
+
       // ── Auto-analysis triggers ─────────────────────────────────────
       // Immediate triggers (batch, compaction) and debounced triggers
       // (idle, lifecycle) write to separate rows keyed by triggerGroup
@@ -218,23 +255,12 @@ export async function indexMessageNow(
       // Gated behind the `auto-analyze` feature flag so the counter
       // does not accumulate stale counts while the flag is off — if it
       // did, flipping the flag on would trigger an immediate batch from
-      // messages buffered during the disabled period. Reading config
-      // here is best-effort: if it fails we skip the batch trigger
-      // (the idle-debounced enqueue above still runs).
-      let analysisConfig: ReturnType<typeof getConfig> | null = null;
-      try {
-        analysisConfig = getConfig();
-      } catch (err) {
-        log.debug(
-          { err, conversationId: input.conversationId },
-          "Skipping auto-analysis batch trigger: failed to load config",
-        );
-      }
+      // messages buffered during the disabled period.
       if (
-        analysisConfig != null &&
-        isAssistantFeatureFlagEnabled("auto-analyze", analysisConfig)
+        triggerConfig != null &&
+        isAssistantFeatureFlagEnabled("auto-analyze", triggerConfig)
       ) {
-        const analysisBatchSize = analysisConfig.analysis.batchSize;
+        const analysisBatchSize = triggerConfig.analysis.batchSize;
         const analysisPendingKey = `conversation_analyze:${input.conversationId}:pending_count`;
         const analysisCurrentVal = getMemoryCheckpoint(analysisPendingKey);
         const analysisPendingCount =

package/src/memory/invite-store.ts

@@ -10,7 +10,7 @@ import { createHash, randomBytes, randomUUID } from "node:crypto";
 
 import { and, desc, eq, gt } from "drizzle-orm";
 
-import { getDb } from "./db.js";
+import { getDb } from "./db-connection.js";
 import { assistantIngressInvites } from "./schema.js";
 
 // ---------------------------------------------------------------------------

package/src/memory/job-handlers/backfill.ts

@@ -11,7 +11,7 @@ import {
   getConversationMemoryScopeId,
   messageMetadataSchema,
 } from "../conversation-crud.js";
-import { getDb } from "../db.js";
+import { getDb } from "../db-connection.js";
 import { indexMessageNow } from "../indexer.js";
 import { enqueueMemoryJob, type MemoryJob } from "../jobs-store.js";
 import { messages } from "../schema.js";

package/src/memory/job-handlers/cleanup.ts

@@ -1,7 +1,8 @@
 import type { AssistantConfig } from "../../config/types.js";
 import { getLogger } from "../../util/logger.js";
-import { getDb, rawAll, rawChanges, rawRun } from "../db.js";
+import { getDb } from "../db-connection.js";
 import { enqueueMemoryJob, type MemoryJob } from "../jobs-store.js";
+import { rawAll, rawChanges, rawRun } from "../raw-query.js";
 
 const log = getLogger("memory-jobs-worker");
 

package/src/memory/job-handlers/conversation-starters.ts

@@ -19,7 +19,11 @@ import {
 } from "../../providers/provider-send-message.js";
 import { getLogger } from "../../util/logger.js";
 import { truncate } from "../../util/truncate.js";
-import { getDb } from "../db.js";
+import {
+  buildConversationStarterValidationContext,
+  isValidConversationStarterText,
+} from "../conversation-starter-validation.js";
+import { getDb } from "../db-connection.js";
 import { asString } from "../job-utils.js";
 import type { MemoryJob } from "../jobs-store.js";
 import { rawAll, rawGet } from "../raw-query.js";
@@ -41,7 +45,7 @@ const CK_LAST_GEN_AT = "conversation_starters:last_gen_at";
 
 // ── Rollup construction ───────────────────────────────────────────
 
-export function buildMemoryRollup(scopeId: string): string {
+function buildMemoryRollup(scopeId: string): string {
   let rows: Array<{
     type: string;
     content: string;
@@ -129,7 +133,7 @@ function buildNewItemsDiff(scopeId: string): string {
   );
 }
 
-export function buildSkillsSummary(): string {
+function buildSkillsSummary(): string {
   try {
     const catalog = loadSkillCatalog();
     if (catalog.length === 0) return "";
@@ -153,7 +157,7 @@ export function buildSkillsSummary(): string {
 // ── LLM generation ────────────────────────────────────────────────
 
 /** Capability categories matching the Intelligence page taxonomy. */
-export const CONVERSATION_STARTER_CATEGORIES = [
+const CONVERSATION_STARTER_CATEGORIES = [
   "communication",
   "productivity",
   "development",
@@ -253,13 +257,13 @@ Favor what is live over what is merely true. Recent changes matter more than old
 ## Output format
 
 Each starter has:
-- label: 3-6 words, max 40 chars, starts with a verb. Written in the user's voice — something they'd want to do, not something the assistant is offering. MUST be a grammatically complete phrase: if it uses an adjective ("quarterly", "weekly"), include the noun it modifies ("quarterly review", "weekly sync"). Never end on a dangling modifier, preposition, or trailing "the/my/a". Prefer completeness over tightness when you have room under 40 chars.
-- prompt: 1-2 natural sentences, as the user would actually say them.
+- label: 3-6 words, max 40 chars, starts with a verb. Written in the user's voice — first-person about themselves, never referring to the user by name or in the third person. Something they'd want to do, not something the assistant is offering. MUST be a grammatically complete phrase: if it uses an adjective ("quarterly", "weekly"), include the noun it modifies ("quarterly review", "weekly sync"). Never end on a dangling modifier, preposition, or trailing "the/my/a". Prefer completeness over tightness when you have room under 40 chars.
+- prompt: 1-2 natural sentences in the user's voice — what they'd type to the assistant. First-person about themselves (I/me/my), second-person to the assistant (you/your). Never refer to the user by name or in the third person, and never narrate what the assistant will do.
 - category: one of ${CONVERSATION_STARTER_CATEGORIES.join(", ")}
 
 ## Constraints
 
-**Voice**: The user clicks these chips to send a message. Every label must read as something the user is asking to do, never something the assistant is saying to the user.
+**Voice**: The user clicks these chips to send a message to the assistant. Both the label AND the prompt must read as something the user is typing — first-person (I/me/my) about themselves, second-person (you/your) to the assistant. Never refer to the user by name or in the third person ("him", "her", "they", or their actual name) — that's the assistant's voice, not the user's. Never narrate what the assistant will do ("Let me check…", "I'll see what he's been up to…").
 
 **Coherence**: The top 4 starters should feel like one set — similar abstraction level, no jarring mix of mundane chores and life strategy. The remaining 4 fallbacks may branch into adjacent topics.
 
@@ -280,6 +284,11 @@ Bad → Good (ticket-speak → natural):
 Bad → Good (assistant voice → user voice):
 - "You've got a busy week ahead" → "Plan my week ahead"
 - "Let me check your calendar" → "Check my Thursday schedule"
+- "Catch up with <user's own name> today" → "Catch me up today" (the user's own name becomes me/my/I, never "you"; third-party names like a colleague or friend stay as written)
+
+Bad → Good (prompt in assistant's voice → prompt in user's voice):
+- "It's Saturday morning and I haven't connected with <user's own name> yet. Let me see what they've been up to." → "Let's catch up this morning; can you help me sort through what matters today?" (assistant narrating about the user → user speaking to assistant; only the user's own name becomes me/my/I, names of other people are preserved)
+- "<User's own name> has had a busy week — I should check in on how they're feeling." → "I've had a busy week — can we talk through how it went?"
 
 Bad → Good (incomplete phrase → complete):
 - "Prep for Friday's quarterly" → "Prep for Friday's quarterly review"
@@ -359,14 +368,13 @@ Bad → Good (incomplete phrase → complete):
       return [];
     }
 
+    const validationContext = buildConversationStarterValidationContext();
     return input.starters
       .filter(
         (s) =>
           typeof s.label === "string" &&
-          s.label.length > 0 &&
-          s.label.length <= 40 &&
           typeof s.prompt === "string" &&
-          s.prompt.length > 0,
+          isValidConversationStarterText(s, validationContext),
       )
       .slice(0, 4)
       .map((s) => ({

package/src/memory/job-handlers/embedding.test.ts

@@ -42,7 +42,8 @@ mock.module("../job-utils.js", () => ({
 
 import { DEFAULT_CONFIG } from "../../config/defaults.js";
 import type { AssistantConfig } from "../../config/types.js";
-import { getDb, initializeDb, resetDb } from "../db.js";
+import { getDb, resetDb } from "../db-connection.js";
+import { initializeDb } from "../db-init.js";
 import type { MemoryJob } from "../jobs-store.js";
 import { mediaAssets } from "../schema.js";
 import { embedMediaJob } from "./embedding.js";

package/src/memory/job-handlers/embedding.ts

@@ -4,7 +4,7 @@ import { eq } from "drizzle-orm";
 
 import type { AssistantConfig } from "../../config/types.js";
 import { getConversationMemoryScopeId } from "../conversation-crud.js";
-import { getDb } from "../db.js";
+import { getDb } from "../db-connection.js";
 import type { EmbeddingInput } from "../embedding-types.js";
 import { asString, embedAndUpsert } from "../job-utils.js";
 import type { MemoryJob } from "../jobs-store.js";

package/src/memory/job-handlers/index-maintenance.ts

@@ -2,7 +2,7 @@ import { eq, isNotNull, like, ne } from "drizzle-orm";
 
 import { getConfig } from "../../config/loader.js";
 import { getLogger } from "../../util/logger.js";
-import { getDb } from "../db.js";
+import { getDb } from "../db-connection.js";
 import { selectedBackendSupportsMultimodal } from "../embedding-backend.js";
 import { asString, BackendUnavailableError } from "../job-utils.js";
 import { enqueueMemoryJob, type MemoryJob } from "../jobs-store.js";

package/src/memory/job-handlers/summarization.ts

@@ -11,7 +11,7 @@ import {
 } from "../../providers/provider-send-message.js";
 import { getLogger } from "../../util/logger.js";
 import { getConversationMemoryScopeId } from "../conversation-crud.js";
-import { getDb } from "../db.js";
+import { getDb } from "../db-connection.js";
 import { asString, truncate } from "../job-utils.js";
 import { enqueueMemoryJob, type MemoryJob } from "../jobs-store.js";
 import { memorySegments, memorySummaries } from "../schema.js";
@@ -91,8 +91,8 @@ export async function buildConversationSummaryJob(
     "conversation",
   );
 
-  // Inherit the conversation's memory scope so private conversation
-  // summaries stay isolated from default-scope retrieval.
+  // Inherit the conversation's memory scope so summaries stay aligned with
+  // the retrieval scope used by the source conversation.
   const scopeId = getConversationMemoryScopeId(conversationId);
 
   const now = Date.now();

package/src/memory/job-utils.ts

@@ -5,7 +5,7 @@ import { and, eq } from "drizzle-orm";
 import type { AssistantConfig } from "../config/types.js";
 import { BackendUnavailableError } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
-import { getDb } from "./db.js";
+import { getDb } from "./db-connection.js";
 import {
   embedWithBackend,
   generateSparseEmbedding,
@@ -42,8 +42,8 @@ export function blobToVector(buf: Buffer | Uint8Array): number[] {
 
 export type ErrorCategory = "retryable" | "fatal";
 
-export const RETRY_BASE_DELAY_MS = 5_000;
-export const RETRY_MAX_DELAY_MS = 5 * 60 * 1000;
+const RETRY_BASE_DELAY_MS = 5_000;
+const RETRY_MAX_DELAY_MS = 5 * 60 * 1000;
 export const RETRY_MAX_ATTEMPTS = 8;
 
 /**