@vellumai/assistant 0.5.16 → 0.6.1

package/src/memory/graph/types.ts

@@ -0,0 +1,295 @@
+// ---------------------------------------------------------------------------
+// Memory Graph — Core type definitions
+// ---------------------------------------------------------------------------
+
+/** Classification of what kind of memory a node represents. */
+export type MemoryType =
+  | "episodic" // specific moments, conversations, events
+  | "semantic" // facts, knowledge, understanding
+  | "procedural" // learned skills, how-to knowledge
+  | "emotional" // feelings attached to memories
+  | "prospective" // future-oriented, things to remember to do
+  | "behavioral" // things that change how the assistant acts going forward
+  | "narrative" // the story a memory becomes over time
+  | "shared"; // memories that belong to a relationship, not either party
+
+/** How detailed the memory is — degrades over time via consolidation. */
+export type Fidelity = "vivid" | "clear" | "faded" | "gist" | "gone";
+
+/** Shape of emotional intensity decay over time. */
+export type DecayCurve =
+  | "linear" // constant rate of decay
+  | "logarithmic" // sharp initial drop, long tail (negative events)
+  | "transformative" // feeling changes shape, not just intensity (positive milestones)
+  | "permanent"; // no decay (core identity markers)
+
+/** How the memory was originally acquired. */
+export type SourceType =
+  | "direct" // user explicitly stated it
+  | "inferred" // assistant derived it from context
+  | "observed" // assistant noticed a pattern
+  | "told-by-other"; // third party provided it
+
+/** Reference to an image stored in a conversation message. */
+export interface ImageRef {
+  /** Message ID containing the image. */
+  messageId: string;
+  /** Index of the image ContentBlock within the message's content array. */
+  blockIndex: number;
+  /** LLM-generated description of what the image shows. */
+  description: string;
+  /** MIME type (image/png, image/jpeg, etc). */
+  mimeType: string;
+}
+
+/** Emotional charge attached to a memory — decays independently from the memory itself. */
+export interface EmotionalCharge {
+  /** Positive vs negative sentiment (-1 to 1). */
+  valence: number;
+  /** Current emotional intensity (0 to 1). Decays per the curve. */
+  intensity: number;
+  /** Shape of the decay function. */
+  decayCurve: DecayCurve;
+  /** Rate parameter for decay (higher = faster). */
+  decayRate: number;
+  /** What the intensity was when the memory was created. */
+  originalIntensity: number;
+}
+
+// ---------------------------------------------------------------------------
+// Graph primitives
+// ---------------------------------------------------------------------------
+
+export interface MemoryNode {
+  id: string;
+
+  /** First-person prose — how the assistant naturally remembers this. */
+  content: string;
+  type: MemoryType;
+
+  // -- Temporal --
+  /** Epoch ms when the memory was created. Hour/day/month are derived at query time. */
+  created: number;
+  /** Epoch ms — used ONLY as a decay-rate modifier, NOT a retrieval signal. */
+  lastAccessed: number;
+  /** Epoch ms of last consolidation pass that touched this node. */
+  lastConsolidated: number;
+  /** Epoch ms of the event this memory describes (null for non-event memories). */
+  eventDate: number | null;
+
+  // -- Energy --
+  emotionalCharge: EmotionalCharge;
+  fidelity: Fidelity;
+  /** How sure the assistant is this memory is accurate (0–1). */
+  confidence: number;
+  /** How important this memory is (0–1). Subject to Ebbinghaus decay. */
+  significance: number;
+
+  // -- Reinforcement (Ebbinghaus forgetting curve) --
+  /** Resistance to significance decay. Grows with reinforcement (×1.5 per reinforcement). */
+  stability: number;
+  /** How many times this memory has been confirmed/reinforced. */
+  reinforcementCount: number;
+  /** Epoch ms of last reinforcement event. */
+  lastReinforced: number;
+
+  // -- Provenance --
+  /** Conversation IDs that contributed to this memory. */
+  sourceConversations: string[];
+  sourceType: SourceType;
+
+  // -- Narrative --
+  /** Role in a larger story arc (e.g. "turning-point", "foreshadowing"). */
+  narrativeRole: string | null;
+  /** Which story arc this belongs to. */
+  partOfStory: string | null;
+
+  /** Image references attached to this memory (null if text-only). */
+  imageRefs: ImageRef[] | null;
+
+  /** Memory scope for multi-scope isolation. */
+  scopeId: string;
+}
+
+/**
+ * Whether a node is an auto-seeded capability (skill or CLI command) rather
+ * than an organically-extracted procedural memory. Capability nodes are
+ * created by the seeding systems at startup; organic procedural nodes are
+ * extracted from conversations (e.g. "FFmpeg needs -ac 2 for stereo").
+ *
+ * Only capability nodes should be reserved/excluded from normal retrieval
+ * and consolidation — organic procedural nodes participate normally.
+ */
+export function isCapabilityNode(node: MemoryNode): boolean {
+  if (node.type !== "procedural") return false;
+  // Old seeding systems: content starts with "skill:{id}\n" or "cli:{name}\n"
+  if (node.content.startsWith("skill:") || node.content.startsWith("cli:"))
+    return true;
+  // New seeding system (capability-seed.ts): content matches
+  // 'The "{name}" skill ({id}) is available.' or
+  // 'The "assistant {name}" CLI command is available.'
+  if (
+    node.content.startsWith('The "') &&
+    node.content.includes(" is available.")
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/** Relationship type between two memory nodes. */
+export type EdgeRelationship =
+  | "caused-by"
+  | "reminds-of"
+  | "contradicts"
+  | "depends-on"
+  | "part-of"
+  | "supersedes"
+  | "resolved-by";
+
+export interface MemoryEdge {
+  id: string;
+  sourceNodeId: string;
+  targetNodeId: string;
+  relationship: EdgeRelationship;
+  /** Connection strength (0–1). */
+  weight: number;
+  /** Epoch ms. */
+  created: number;
+}
+
+/** Trigger type determines how the trigger condition is evaluated. */
+export type TriggerType = "temporal" | "semantic" | "event";
+
+export interface MemoryTrigger {
+  id: string;
+  /** Which memory node this trigger belongs to. */
+  nodeId: string;
+  type: TriggerType;
+
+  // -- Temporal triggers --
+  /** Cron-like pattern: "day-of-week:monday", "date:04-08", "time:morning". */
+  schedule: string | null;
+
+  // -- Semantic triggers --
+  /** Natural language condition: "user graduates", "topic of cooking comes up". */
+  condition: string | null;
+  /** Pre-computed embedding of the condition text for fast cosine similarity. */
+  conditionEmbedding: Float32Array | null;
+  /** Cosine similarity threshold to fire (0–1). */
+  threshold: number | null;
+
+  // -- Event triggers --
+  /** Epoch ms of the event date. */
+  eventDate: number | null;
+  /** Days before the event to start ramping relevance. */
+  rampDays: number | null;
+  /** Days after the event to maintain elevated relevance. */
+  followUpDays: number | null;
+
+  // -- State --
+  /** Whether this trigger fires repeatedly or is consumed on first fire. */
+  recurring: boolean;
+  /** Whether a one-shot trigger has already fired. */
+  consumed: boolean;
+  /** Minimum ms between firings for recurring triggers. */
+  cooldownMs: number | null;
+  /** Epoch ms of last firing. */
+  lastFired: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// Diff — the extraction/consolidation output format
+// ---------------------------------------------------------------------------
+
+/** A node to be created (id assigned by store). */
+export type NewNode = Omit<MemoryNode, "id">;
+
+/** Partial update to an existing node. */
+export interface NodeUpdate {
+  id: string;
+  changes: Partial<Omit<MemoryNode, "id">>;
+}
+
+/** A new edge to create (id assigned by store). */
+export type NewEdge = Omit<MemoryEdge, "id">;
+
+/** A new trigger to create (id assigned by store). */
+export type NewTrigger = Omit<MemoryTrigger, "id">;
+
+/**
+ * The atomic diff that extraction/consolidation produces.
+ * Applied transactionally to the graph store.
+ */
+export interface MemoryDiff {
+  createNodes: NewNode[];
+  updateNodes: NodeUpdate[];
+  deleteNodeIds: string[];
+  createEdges: NewEdge[];
+  deleteEdgeIds: string[];
+  createTriggers: NewTrigger[];
+  deleteTriggerIds: string[];
+  /** Node IDs that were reinforced (confirmed/validated) by this extraction. */
+  reinforceNodeIds: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Scored candidates — used by retrieval pipeline
+// ---------------------------------------------------------------------------
+
+export interface ScoredNode {
+  node: MemoryNode;
+  /** Combined retrieval score (higher = more relevant right now). */
+  score: number;
+  /** Breakdown of score components for debugging/inspection. */
+  scoreBreakdown: {
+    semanticSimilarity: number;
+    effectiveSignificance: number;
+    emotionalIntensity: number;
+    temporalBoost: number;
+    recencyBoost: number;
+    triggerBoost: number;
+    activationBoost: number;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Retrieval Metrics
+// ---------------------------------------------------------------------------
+
+export interface RetrievalMetrics {
+  semanticHits: number;
+  mergedCount: number;
+  selectedCount: number;
+  tier1Count: number;
+  tier2Count: number;
+  hybridSearchLatencyMs: number;
+  sparseVectorUsed: boolean;
+  embeddingProvider: string | null;
+  embeddingModel: string | null;
+  queryContext: string | null;
+  topCandidates: Array<{
+    nodeId: string;
+    type: string;
+    score: number;
+    semanticSimilarity: number;
+    recencyBoost: number;
+  }>;
+}
+
+// ---------------------------------------------------------------------------
+// Results
+// ---------------------------------------------------------------------------
+
+export interface ApplyDiffResult {
+  nodesCreated: number;
+  nodesUpdated: number;
+  nodesDeleted: number;
+  edgesCreated: number;
+  edgesDeleted: number;
+  triggersCreated: number;
+  triggersDeleted: number;
+  nodesReinforced: number;
+  /** IDs of newly created nodes (in order of diff.createNodes). */
+  createdNodeIds: string[];
+}

package/src/memory/group-crud.ts

@@ -0,0 +1,191 @@
+/**
+ * CRUD operations for conversation groups.
+ *
+ * All functions call ensureGroupMigration() before any DB access
+ * to guarantee the conversation_groups table exists.
+ */
+
+import { v4 as uuid } from "uuid";
+
+import { ensureGroupMigration } from "./conversation-group-migration.js";
+import { rawAll, rawExec, rawGet, rawRun } from "./db.js";
+
+export interface ConversationGroupRow {
+  id: string;
+  name: string;
+  sortPosition: number;
+  isSystemGroup: boolean;
+  createdAt?: number;
+  updatedAt?: number;
+}
+
+// ---------------------------------------------------------------------------
+// List
+// ---------------------------------------------------------------------------
+
+export function listGroups(): ConversationGroupRow[] {
+  ensureGroupMigration();
+  const rows = rawAll<{
+    id: string;
+    name: string;
+    sort_position: number;
+    is_system_group: number;
+    created_at: number;
+    updated_at: number;
+  }>(
+    "SELECT id, name, sort_position, is_system_group, created_at, updated_at FROM conversation_groups WHERE id != '_backfill_complete' ORDER BY sort_position ASC",
+  );
+  return rows.map((r) => ({
+    id: r.id,
+    name: r.name,
+    sortPosition: r.sort_position,
+    isSystemGroup: r.is_system_group === 1,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Get
+// ---------------------------------------------------------------------------
+
+export function getGroup(groupId: string): ConversationGroupRow | null {
+  ensureGroupMigration();
+  const row = rawGet<{
+    id: string;
+    name: string;
+    sort_position: number;
+    is_system_group: number;
+    created_at: number;
+    updated_at: number;
+  }>(
+    "SELECT id, name, sort_position, is_system_group, created_at, updated_at FROM conversation_groups WHERE id = ?",
+    groupId,
+  );
+  if (!row) return null;
+  return {
+    id: row.id,
+    name: row.name,
+    sortPosition: row.sort_position,
+    isSystemGroup: row.is_system_group === 1,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Create
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a custom group. Server assigns sort_position as max(custom) + 1.
+ * System groups occupy positions 0 (pinned), 1 (scheduled), 2 (background).
+ * First custom group gets position 3. Fallback ?? 2 ensures 2 + 1 = 3 when
+ * no custom groups exist.
+ */
+export function createGroup(name: string): ConversationGroupRow {
+  ensureGroupMigration();
+  const maxPos =
+    rawGet<{ max: number | null }>(
+      "SELECT MAX(sort_position) as max FROM conversation_groups WHERE is_system_group = 0",
+    )?.max ?? 2;
+  const sortPosition = maxPos + 1;
+  const id = uuid();
+  const now = Math.floor(Date.now() / 1000);
+  rawRun(
+    "INSERT INTO conversation_groups (id, name, sort_position, is_system_group, created_at, updated_at) VALUES (?, ?, ?, 0, ?, ?)",
+    id,
+    name,
+    sortPosition,
+    now,
+    now,
+  );
+  return {
+    id,
+    name,
+    sortPosition,
+    isSystemGroup: false,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Update
+// ---------------------------------------------------------------------------
+
+export function updateGroup(
+  groupId: string,
+  updates: { name?: string; sortPosition?: number },
+): ConversationGroupRow | null {
+  ensureGroupMigration();
+  const existing = getGroup(groupId);
+  if (!existing) return null;
+
+  const fields: string[] = [];
+  const values: (string | number)[] = [];
+
+  if (updates.name !== undefined) {
+    fields.push("name = ?");
+    values.push(updates.name);
+  }
+  if (updates.sortPosition !== undefined) {
+    fields.push("sort_position = ?");
+    values.push(updates.sortPosition);
+  }
+
+  if (fields.length === 0) return existing;
+
+  fields.push("updated_at = ?");
+  const now = Math.floor(Date.now() / 1000);
+  values.push(now);
+  values.push(groupId);
+
+  rawRun(
+    `UPDATE conversation_groups SET ${fields.join(", ")} WHERE id = ?`,
+    ...values,
+  );
+
+  return getGroup(groupId);
+}
+
+// ---------------------------------------------------------------------------
+// Delete
+// ---------------------------------------------------------------------------
+
+// Relies on PRAGMA foreign_keys = ON (set at connection time) so that
+// ON DELETE SET NULL fires and clears group_id on conversations when
+// a group is deleted. If FK enforcement is ever disabled, orphaned
+// group_id values would persist and conversations would appear in a
+// non-existent group.
+export function deleteGroup(groupId: string): boolean {
+  ensureGroupMigration();
+  rawRun("DELETE FROM conversation_groups WHERE id = ?", groupId);
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Reorder
+// ---------------------------------------------------------------------------
+
+export function reorderGroups(
+  updates: Array<{ groupId: string; sortPosition: number }>,
+): void {
+  ensureGroupMigration();
+  const now = Math.floor(Date.now() / 1000);
+  rawExec("BEGIN");
+  try {
+    for (const update of updates) {
+      rawRun(
+        "UPDATE conversation_groups SET sort_position = ?, updated_at = ? WHERE id = ?",
+        update.sortPosition,
+        now,
+        update.groupId,
+      );
+    }
+    rawExec("COMMIT");
+  } catch (err) {
+    rawExec("ROLLBACK");
+    throw err;
+  }
+}

package/src/memory/indexer.ts

@@ -149,33 +149,47 @@ export async function indexMessageNow(
         tx,
       );
     }
-
   });
 
   // ── Batch extraction tracking ──────────────────────────────────────
   // Instead of per-message extraction, track pending unextracted messages
   // and trigger batch extraction when the threshold is reached or after idle.
-  if (shouldExtract && isTrustedActor && !input.automated && config.extraction.useLLM) {
-    const pendingKey = `batch_extract:${input.conversationId}:pending_count`;
-    const currentVal = getMemoryCheckpoint(pendingKey);
-    const pendingCount = (currentVal ? parseInt(currentVal, 10) : 0) + 1;
-    setMemoryCheckpoint(pendingKey, String(pendingCount));
-
+  if (
+    shouldExtract &&
+    isTrustedActor &&
+    !input.automated &&
+    config.extraction.useLLM
+  ) {
     const batchSize = config.extraction.batchSize ?? 10;
     const idleTimeoutMs = config.extraction.idleTimeoutMs ?? 300_000;
 
-    if (pendingCount >= batchSize) {
-      // Threshold reached — trigger immediate batch extraction
-      enqueueMemoryJob("batch_extract", {
+    // ── Graph extraction ────────────────────────────────────────────
+    const graphPendingKey = `graph_extract:${input.conversationId}:pending_count`;
+    const graphCurrentVal = getMemoryCheckpoint(graphPendingKey);
+    const graphPendingCount =
+      (graphCurrentVal ? parseInt(graphCurrentVal, 10) : 0) + 1;
+    setMemoryCheckpoint(graphPendingKey, String(graphPendingCount));
+
+    if (graphPendingCount >= batchSize) {
+      enqueueMemoryJob("graph_extract", {
         conversationId: input.conversationId,
         scopeId: input.scopeId ?? "default",
       });
+      setMemoryCheckpoint(graphPendingKey, "0");
     }
 
-    // Also maintain idle debounce: enqueue a delayed batch_extract that fires
-    // if no new messages arrive within the idle timeout window.
     upsertDebouncedJob(
-      "batch_extract",
+      "graph_extract",
+      { conversationId: input.conversationId },
+      Date.now() + idleTimeoutMs,
+    );
+
+    // ── Conversation summarization (independent of extraction) ────────
+    // Summaries feed the graph retrieval pipeline via fetchRecentSummaries().
+    // Debounced on the same idle timeout — no threshold trigger needed since
+    // summaries compress the whole conversation, not incremental batches.
+    upsertDebouncedJob(
+      "build_conversation_summary",
       { conversationId: input.conversationId },
       Date.now() + idleTimeoutMs,
     );
@@ -203,15 +217,19 @@ export async function indexMessageNow(
     log.info("Skipping extraction jobs for automated message");
   }
 
-  if (!config.extraction.useLLM && shouldExtract && isTrustedActor && !input.automated) {
-    log.info("Skipping extraction job: LLM extraction is disabled (useLLM=false)");
+  if (
+    !config.extraction.useLLM &&
+    shouldExtract &&
+    isTrustedActor &&
+    !input.automated
+  ) {
+    log.info(
+      "Skipping extraction job: LLM extraction is disabled (useLLM=false)",
+    );
   }
 
   const storedSegments = segments.length - skippedShortSegments;
-  const enqueuedJobs =
-    storedSegments -
-    skippedEmbedJobs +
-    mediaBlocks.length;
+  const enqueuedJobs = storedSegments - skippedEmbedJobs + mediaBlocks.length;
   return {
     indexedSegments: storedSegments,
     enqueuedJobs,

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

@@ -1,65 +1,55 @@
-import { and, asc, eq, inArray, lt } from "drizzle-orm";
-
 import type { AssistantConfig } from "../../config/types.js";
 import { getLogger } from "../../util/logger.js";
-import { getDb, rawAll, rawRun } from "../db.js";
-import { asPositiveMs } from "../job-utils.js";
+import { getDb, rawAll, rawChanges, rawRun } from "../db.js";
 import { enqueueMemoryJob, type MemoryJob } from "../jobs-store.js";
-import { memoryEmbeddings, memoryItems } from "../schema.js";
 
 const log = getLogger("memory-jobs-worker");
 
-const CLEANUP_BATCH_LIMIT = 250;
+const PRUNE_BATCH_LIMIT = 100;
+const PRUNE_LOG_BATCH_LIMIT = 1000;
 
-export function cleanupStaleSupersededItemsJob(
+/**
+ * Delete LLM request/response logs older than the configured retention period.
+ * Processes in batches to avoid long DB locks and excessive WAL growth.
+ * Re-enqueues itself if more rows remain.
+ */
+export function pruneOldLlmRequestLogsJob(
   job: MemoryJob,
   config: AssistantConfig,
 ): void {
-  const db = getDb();
   const retentionMs =
-    asPositiveMs(job.payload.retentionMs) ??
-    config.memory.cleanup.supersededItemRetentionMs;
-  const cutoff = Date.now() - retentionMs;
-  const stale = db
-    .select({ id: memoryItems.id })
-    .from(memoryItems)
-    .where(
-      and(
-        eq(memoryItems.status, "superseded"),
-        lt(memoryItems.invalidAt, cutoff),
-      ),
-    )
-    .orderBy(asc(memoryItems.invalidAt), asc(memoryItems.id))
-    .limit(CLEANUP_BATCH_LIMIT)
-    .all();
-  if (stale.length === 0) return;
+    typeof job.payload.retentionMs === "number" &&
+    Number.isFinite(job.payload.retentionMs) &&
+    job.payload.retentionMs >= 0
+      ? job.payload.retentionMs
+      : config.memory.cleanup.llmRequestLogRetentionMs;
+
+  // 0 means disabled
+  if (retentionMs === 0) return;
 
-  const ids = stale.map((row) => row.id);
-  db.delete(memoryEmbeddings)
-    .where(
-      and(
-        eq(memoryEmbeddings.targetType, "item"),
-        inArray(memoryEmbeddings.targetId, ids),
-      ),
-    )
-    .run();
-  db.delete(memoryItems).where(inArray(memoryItems.id, ids)).run();
-  if (stale.length === CLEANUP_BATCH_LIMIT) {
-    enqueueMemoryJob("cleanup_stale_superseded_items", { retentionMs });
+  const cutoffMs = Date.now() - retentionMs;
+
+  rawRun(
+    `DELETE FROM llm_request_logs WHERE rowid IN (SELECT rowid FROM llm_request_logs WHERE created_at < ? LIMIT ?)`,
+    cutoffMs,
+    PRUNE_LOG_BATCH_LIMIT,
+  );
+  const deleted = rawChanges();
+
+  if (deleted >= PRUNE_LOG_BATCH_LIMIT) {
+    enqueueMemoryJob("prune_old_llm_request_logs", { retentionMs });
   }
 
-  log.debug(
+  log.info(
     {
-      removedItems: stale.length,
+      deleted,
       retentionMs,
-      cutoff,
+      cutoffMs,
     },
-    "Cleaned up stale superseded memory items",
+    "Pruned old LLM request logs",
   );
 }
 
-const PRUNE_BATCH_LIMIT = 100;
-
 /**
  * Delete conversations that have had no activity (updatedAt) for longer than
  * the configured retention period. Processes in batches so a single job doesn't