@vellumai/assistant 0.5.16 → 0.6.0

package/src/memory/migrations/202-memory-graph-tables.ts

@@ -0,0 +1,130 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+/**
+ * Create the memory graph tables: nodes, edges, and triggers.
+ *
+ * Uses CREATE TABLE IF NOT EXISTS so this is inherently idempotent
+ * and does not need a registry entry.
+ */
+export function migrateCreateMemoryGraphTables(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+
+  // -- Nodes --
+  raw.exec(`
+    CREATE TABLE IF NOT EXISTS memory_graph_nodes (
+      id                    TEXT PRIMARY KEY,
+      content               TEXT NOT NULL,
+      type                  TEXT NOT NULL,
+      created               INTEGER NOT NULL,
+      last_accessed         INTEGER NOT NULL,
+      last_consolidated     INTEGER NOT NULL,
+      emotional_charge      TEXT NOT NULL,
+      fidelity              TEXT NOT NULL DEFAULT 'vivid',
+      confidence            REAL NOT NULL,
+      significance          REAL NOT NULL,
+      stability             REAL NOT NULL DEFAULT 14,
+      reinforcement_count   INTEGER NOT NULL DEFAULT 0,
+      last_reinforced       INTEGER NOT NULL,
+      source_conversations  TEXT NOT NULL DEFAULT '[]',
+      source_type           TEXT NOT NULL DEFAULT 'inferred',
+      narrative_role        TEXT,
+      part_of_story         TEXT,
+      scope_id              TEXT NOT NULL DEFAULT 'default'
+    )
+  `);
+
+  // -- Edges --
+  raw.exec(`
+    CREATE TABLE IF NOT EXISTS memory_graph_edges (
+      id              TEXT PRIMARY KEY,
+      source_node_id  TEXT NOT NULL REFERENCES memory_graph_nodes(id) ON DELETE CASCADE,
+      target_node_id  TEXT NOT NULL REFERENCES memory_graph_nodes(id) ON DELETE CASCADE,
+      relationship    TEXT NOT NULL,
+      weight          REAL NOT NULL DEFAULT 1.0,
+      created         INTEGER NOT NULL
+    )
+  `);
+
+  // -- Triggers --
+  raw.exec(`
+    CREATE TABLE IF NOT EXISTS memory_graph_triggers (
+      id                   TEXT PRIMARY KEY,
+      node_id              TEXT NOT NULL REFERENCES memory_graph_nodes(id) ON DELETE CASCADE,
+      type                 TEXT NOT NULL,
+      schedule             TEXT,
+      condition            TEXT,
+      condition_embedding  BLOB,
+      threshold            REAL,
+      event_date           INTEGER,
+      ramp_days            INTEGER,
+      follow_up_days       INTEGER,
+      recurring            INTEGER NOT NULL DEFAULT 0,
+      consumed             INTEGER NOT NULL DEFAULT 0,
+      cooldown_ms          INTEGER,
+      last_fired           INTEGER
+    )
+  `);
+
+  // -- Indexes (IF NOT EXISTS for idempotency) --
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_graph_nodes_scope_id ON memory_graph_nodes(scope_id)`,
+  );
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_graph_nodes_type ON memory_graph_nodes(type)`,
+  );
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_graph_nodes_fidelity ON memory_graph_nodes(fidelity)`,
+  );
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_graph_nodes_created ON memory_graph_nodes(created)`,
+  );
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_graph_nodes_significance ON memory_graph_nodes(significance)`,
+  );
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_graph_edges_source ON memory_graph_edges(source_node_id)`,
+  );
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_graph_edges_target ON memory_graph_edges(target_node_id)`,
+  );
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_graph_triggers_node_id ON memory_graph_triggers(node_id)`,
+  );
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_graph_triggers_type ON memory_graph_triggers(type)`,
+  );
+
+  // -- Add event_date column to nodes (idempotent) --
+  try {
+    raw.exec(
+      `ALTER TABLE memory_graph_nodes ADD COLUMN event_date INTEGER`,
+    );
+  } catch {
+    // Column already exists — safe to ignore.
+  }
+
+  raw.exec(
+    `CREATE INDEX IF NOT EXISTS idx_graph_nodes_event_date ON memory_graph_nodes(event_date)`,
+  );
+
+  // -- Backfill event_date from existing event triggers --
+  raw.exec(`
+    UPDATE memory_graph_nodes
+    SET event_date = (
+      SELECT t.event_date
+      FROM memory_graph_triggers t
+      WHERE t.node_id = memory_graph_nodes.id
+        AND t.type = 'event'
+        AND t.event_date IS NOT NULL
+      LIMIT 1
+    )
+    WHERE event_date IS NULL
+      AND id IN (
+        SELECT t2.node_id
+        FROM memory_graph_triggers t2
+        WHERE t2.type = 'event'
+          AND t2.event_date IS NOT NULL
+      )
+  `);
+}

package/src/memory/migrations/203-drop-memory-items-tables.ts

@@ -0,0 +1,23 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+/**
+ * Drop the legacy memory_items and memory_item_sources tables.
+ *
+ * All consumers have been migrated to memory_graph_nodes (#22698).
+ * These tables are now dead weight.
+ */
+export function migrateDropMemoryItemsTables(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+
+  // Drop indexes first (idempotent — IF EXISTS).
+  raw.exec(
+    /*sql*/ `DROP INDEX IF EXISTS idx_memory_item_sources_memory_item_id`
+  );
+  raw.exec(/*sql*/ `DROP INDEX IF EXISTS idx_memory_items_scope_id`);
+  raw.exec(/*sql*/ `DROP INDEX IF EXISTS idx_memory_items_fingerprint`);
+
+  // Drop tables (idempotent — IF EXISTS). Child table first.
+  raw.exec(/*sql*/ `DROP TABLE IF EXISTS memory_item_sources`);
+  raw.exec(/*sql*/ `DROP TABLE IF EXISTS memory_items`);
+}

package/src/memory/migrations/204-rename-memory-graph-type-values.ts

@@ -0,0 +1,46 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+/**
+ * One-shot migration: rename legacy memory graph node type values.
+ *
+ * The PR that introduced the memory graph used "style" and "relationship"
+ * as type values.  These were renamed to "behavioral" and "semantic" in
+ * code, but existing rows in the database still carry the old values.
+ */
+export function migrateRenameMemoryGraphTypeValues(database: DrizzleDb): void {
+  withCrashRecovery(
+    database,
+    "migration_rename_memory_graph_type_values_v1",
+    () => {
+      const raw = getSqliteFrom(database);
+      raw
+        .prepare(
+          /*sql*/ `UPDATE memory_graph_nodes SET type = 'behavioral' WHERE type = 'style'`,
+        )
+        .run();
+      raw
+        .prepare(
+          /*sql*/ `UPDATE memory_graph_nodes SET type = 'semantic' WHERE type = 'relationship'`,
+        )
+        .run();
+    },
+  );
+}
+
+/**
+ * Reverse: no-op.
+ *
+ * A blanket revert (`behavioral` → `style`, `semantic` → `relationship`) is
+ * unsafe because normal runtime may have created new `behavioral` / `semantic`
+ * nodes after the forward migration ran.  Those nodes were never `style` /
+ * `relationship` and reverting them would corrupt data.  Since the forward
+ * migration is idempotent and the old type values are no longer referenced in
+ * code, a no-op rollback is the safest option.
+ */
+export function migrateRenameMemoryGraphTypeValuesDown(
+  _database: DrizzleDb,
+): void {
+  // intentional no-op — see comment above
+}

package/src/memory/migrations/205-memory-graph-image-refs.ts

@@ -0,0 +1,11 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+
+export function migrateMemoryGraphImageRefs(database: DrizzleDb): void {
+  const raw = getSqliteFrom(database);
+  try {
+    raw.exec(`ALTER TABLE memory_graph_nodes ADD COLUMN image_refs TEXT`);
+  } catch {
+    // Column already exists — idempotent
+  }
+}

package/src/memory/migrations/index.ts

@@ -142,6 +142,10 @@ export { migrateGuardianRequestEnrichmentColumns } from "./199-guardian-request-
 export { migrateUsageLlmCallCount } from "./200-usage-llm-call-count.js";
 export { migrateOAuthProvidersFeatureFlag } from "./201-oauth-providers-feature-flag.js";
 export { migrateDropCallbackTransportColumn } from "./202-drop-callback-transport-column.js";
+export { migrateCreateMemoryGraphTables } from "./202-memory-graph-tables.js";
+export { migrateDropMemoryItemsTables } from "./203-drop-memory-items-tables.js";
+export { migrateRenameMemoryGraphTypeValues } from "./204-rename-memory-graph-type-values.js";
+export { migrateMemoryGraphImageRefs } from "./205-memory-graph-image-refs.js";
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/memory/migrations/registry.ts

@@ -39,6 +39,7 @@ import { migrateRenameThreadStartersCheckpointsDown } from "./181-rename-thread-
 import { migrateBackfillAudioAttachmentMimeTypesDown } from "./191-backfill-audio-attachment-mime-types.js";
 import { migrateAddSourceTypeColumnsDown } from "./193-add-source-type-columns.js";
 import { migrateStripIntegrationPrefixFromProviderKeysDown } from "./196-strip-integration-prefix-from-provider-keys.js";
+import { migrateRenameMemoryGraphTypeValuesDown } from "./204-rename-memory-graph-type-values.js";
 
 export interface MigrationRegistryEntry {
   /** The checkpoint key written to memory_checkpoints on completion. */
@@ -341,6 +342,13 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
       "Strip integration: prefix from provider_key across oauth_providers, oauth_apps, and oauth_connections",
     down: migrateStripIntegrationPrefixFromProviderKeysDown,
   },
+  {
+    key: "migration_rename_memory_graph_type_values_v1",
+    version: 39,
+    description:
+      "Rename legacy memory graph node type values: style → behavioral, relationship → semantic",
+    down: migrateRenameMemoryGraphTypeValuesDown,
+  },
 ];
 
 export function getMaxMigrationVersion(): number {

package/src/memory/qdrant-client.ts

@@ -20,7 +20,7 @@ export interface QdrantClientConfig {
 }
 
 export interface QdrantPointPayload {
-  target_type: "segment" | "item" | "summary" | "media";
+  target_type: "segment" | "item" | "summary" | "media" | "graph_node";
   target_id: string;
   text: string;
   kind?: string;
@@ -47,14 +47,14 @@ let _instance: VellumQdrantClient | null = null;
 export function getQdrantClient(): VellumQdrantClient {
   if (!_instance) {
     throw new Error(
-      "Qdrant client not initialized. Call initQdrantClient() first.",
+      "Qdrant client not initialized. Call initQdrantClient() first."
     );
   }
   return _instance;
 }
 
 export function initQdrantClient(
-  config: QdrantClientConfig,
+  config: QdrantClientConfig
 ): VellumQdrantClient {
   _instance = new VellumQdrantClient(config);
   return _instance;
@@ -125,7 +125,7 @@ export class VellumQdrantClient {
                 currentSize,
                 expectedSize: this.vectorSize,
               },
-              "Qdrant collection uses unnamed vectors (legacy) — deleting and recreating with named vectors. Embeddings will be re-indexed.",
+              "Qdrant collection uses unnamed vectors (legacy) — deleting and recreating with named vectors. Embeddings will be re-indexed."
             );
             await this.client.deleteCollection(this.collection);
             migrated = true;
@@ -138,7 +138,7 @@ export class VellumQdrantClient {
                 expectedSize: this.vectorSize,
                 modelMismatch,
               },
-              "Qdrant collection incompatible (dimension or model change) — deleting and recreating. Embeddings will be regenerated on demand.",
+              "Qdrant collection incompatible (dimension or model change) — deleting and recreating. Embeddings will be regenerated on demand."
             );
             await this.client.deleteCollection(this.collection);
             migrated = true;
@@ -152,7 +152,7 @@ export class VellumQdrantClient {
         } catch (err) {
           log.warn(
             { err },
-            "Failed to verify collection compatibility, assuming compatible",
+            "Failed to verify collection compatibility, assuming compatible"
           );
           if (await this.ensurePayloadIndexesSafe()) {
             this.collectionReady = true;
@@ -166,7 +166,7 @@ export class VellumQdrantClient {
 
     log.info(
       { collection: this.collection, vectorSize: this.vectorSize },
-      "Creating Qdrant collection with named vectors (dense + sparse)",
+      "Creating Qdrant collection with named vectors (dense + sparse)"
     );
 
     try {
@@ -222,7 +222,7 @@ export class VellumQdrantClient {
       this.collectionReady = true;
       log.info(
         { collection: this.collection },
-        "Qdrant collection created with payload indexes",
+        "Qdrant collection created with payload indexes"
       );
     }
 
@@ -230,11 +230,11 @@ export class VellumQdrantClient {
   }
 
   async upsert(
-    targetType: "segment" | "item" | "summary" | "media",
+    targetType: QdrantPointPayload["target_type"],
     targetId: string,
     vector: number[],
     payload: Omit<QdrantPointPayload, "target_type" | "target_id">,
-    sparseVector?: QdrantSparseVector,
+    sparseVector?: QdrantSparseVector
   ): Promise<string> {
     await this.ensureCollection();
 
@@ -289,7 +289,7 @@ export class VellumQdrantClient {
   async search(
     vector: number[],
     limit: number,
-    filter?: Record<string, unknown>,
+    filter?: Record<string, unknown>
   ): Promise<QdrantSearchResult[]> {
     await this.ensureCollection();
 
@@ -317,7 +317,7 @@ export class VellumQdrantClient {
     return results.map((result) => ({
       id: typeof result.id === "string" ? result.id : String(result.id),
       score: result.score,
-      payload: result.payload as unknown as QdrantPointPayload,
+      payload: (result.payload as unknown) as QdrantPointPayload,
     }));
   }
 
@@ -326,7 +326,7 @@ export class VellumQdrantClient {
     limit: number,
     targetTypes: Array<"segment" | "item" | "summary" | "media">,
     excludeMessageIds?: string[],
-    scopeIds?: string[],
+    scopeIds?: string[]
   ): Promise<QdrantSearchResult[]> {
     const mustConditions: Array<Record<string, unknown>> = [
       {
@@ -403,7 +403,7 @@ export class VellumQdrantClient {
     const queryParams = {
       prefetch: [
         {
-          query: denseVector as unknown as number[],
+          query: (denseVector as unknown) as number[],
           using: "dense",
           limit: effectivePrefetchLimit,
         },
@@ -438,7 +438,7 @@ export class VellumQdrantClient {
     return (results.points ?? []).map((point) => ({
       id: typeof point.id === "string" ? point.id : String(point.id),
       score: point.score ?? 0,
-      payload: point.payload as unknown as QdrantPointPayload,
+      payload: (point.payload as unknown) as QdrantPointPayload,
     }));
   }
 
@@ -469,6 +469,33 @@ export class VellumQdrantClient {
     }
   }
 
+  /**
+   * Delete all vectors matching a given target_type (bulk cleanup).
+   */
+  async deleteByTargetType(targetType: string): Promise<void> {
+    await this.ensureCollection();
+
+    const doDelete = () =>
+      this.client.delete(this.collection, {
+        wait: true,
+        filter: {
+          must: [{ key: "target_type", match: { value: targetType } }],
+        },
+      });
+
+    try {
+      await doDelete();
+    } catch (err) {
+      if (this.isCollectionMissing(err)) {
+        this.collectionReady = false;
+        await this.ensureCollection();
+        await doDelete();
+      } else {
+        throw err;
+      }
+    }
+  }
+
   async count(): Promise<number> {
     await this.ensureCollection();
 
@@ -498,7 +525,7 @@ export class VellumQdrantClient {
     } catch (err) {
       log.warn(
         { err, collection: this.collection },
-        "Failed to delete Qdrant collection",
+        "Failed to delete Qdrant collection"
       );
       return false;
     }
@@ -615,7 +642,7 @@ export class VellumQdrantClient {
 
   private async findByTarget(
     targetType: string,
-    targetId: string,
+    targetId: string
   ): Promise<string | null> {
     try {
       const results = await this.client.scroll(this.collection, {

package/src/memory/schema/index.ts

@@ -4,6 +4,7 @@ export * from "./conversations.js";
 export * from "./guardian.js";
 export * from "./infrastructure.js";
 export * from "./memory-core.js";
+export * from "./memory-graph.js";
 export * from "./notifications.js";
 export * from "./oauth.js";
 export * from "./tasks.js";

package/src/memory/schema/memory-graph.ts

@@ -0,0 +1,139 @@
+import {
+  blob,
+  index,
+  integer,
+  real,
+  sqliteTable,
+  text,
+} from "drizzle-orm/sqlite-core";
+
+// ---------------------------------------------------------------------------
+// Memory Graph — Drizzle ORM schema
+// ---------------------------------------------------------------------------
+
+export const memoryGraphNodes = sqliteTable(
+  "memory_graph_nodes",
+  {
+    id: text("id").primaryKey(),
+
+    /** First-person prose — how the assistant naturally remembers this. */
+    content: text("content").notNull(),
+    /** Memory type: episodic, semantic, procedural, emotional, prospective, behavioral, narrative, shared. */
+    type: text("type").notNull(),
+
+    // -- Temporal --
+    /** Epoch ms. Hour/dayOfWeek/month derived at query time via Date. */
+    created: integer("created").notNull(),
+    /** Epoch ms. Decay-rate modifier only — NOT a retrieval signal. */
+    lastAccessed: integer("last_accessed").notNull(),
+    /** Epoch ms of last consolidation pass. */
+    lastConsolidated: integer("last_consolidated").notNull(),
+    /** Epoch ms of the event this memory describes (null for non-event memories). */
+    eventDate: integer("event_date"),
+
+    // -- Energy --
+    /** JSON-serialized EmotionalCharge object. Read/written atomically. */
+    emotionalCharge: text("emotional_charge").notNull(),
+    /** vivid | clear | faded | gist | gone */
+    fidelity: text("fidelity").notNull().default("vivid"),
+    /** 0–1. How sure the assistant is this is accurate. */
+    confidence: real("confidence").notNull(),
+    /** 0–1. How important. Subject to Ebbinghaus decay. */
+    significance: real("significance").notNull(),
+
+    // -- Reinforcement --
+    /** Resistance to decay. Grows ×1.5 per reinforcement. */
+    stability: real("stability").notNull().default(14),
+    /** How many times confirmed/reinforced. */
+    reinforcementCount: integer("reinforcement_count").notNull().default(0),
+    /** Epoch ms. */
+    lastReinforced: integer("last_reinforced").notNull(),
+
+    // -- Provenance --
+    /** JSON array of conversation IDs. */
+    sourceConversations: text("source_conversations").notNull().default("[]"),
+    /** direct | inferred | observed | told-by-other */
+    sourceType: text("source_type").notNull().default("inferred"),
+
+    // -- Narrative --
+    narrativeRole: text("narrative_role"),
+    partOfStory: text("part_of_story"),
+
+    /** Memory scope for multi-scope isolation. */
+    scopeId: text("scope_id").notNull().default("default"),
+
+    /** JSON array of ImageRef objects — images attached to this memory. */
+    imageRefs: text("image_refs"),
+  },
+  (table) => [
+    index("idx_graph_nodes_scope_id").on(table.scopeId),
+    index("idx_graph_nodes_type").on(table.type),
+    index("idx_graph_nodes_fidelity").on(table.fidelity),
+    index("idx_graph_nodes_created").on(table.created),
+    index("idx_graph_nodes_significance").on(table.significance),
+    index("idx_graph_nodes_event_date").on(table.eventDate),
+  ],
+);
+
+export const memoryGraphEdges = sqliteTable(
+  "memory_graph_edges",
+  {
+    id: text("id").primaryKey(),
+    sourceNodeId: text("source_node_id")
+      .notNull()
+      .references(() => memoryGraphNodes.id, { onDelete: "cascade" }),
+    targetNodeId: text("target_node_id")
+      .notNull()
+      .references(() => memoryGraphNodes.id, { onDelete: "cascade" }),
+    /** caused-by | reminds-of | contradicts | depends-on | part-of | supersedes | resolved-by */
+    relationship: text("relationship").notNull(),
+    /** Connection strength 0–1. */
+    weight: real("weight").notNull().default(1.0),
+    /** Epoch ms. */
+    created: integer("created").notNull(),
+  },
+  (table) => [
+    index("idx_graph_edges_source").on(table.sourceNodeId),
+    index("idx_graph_edges_target").on(table.targetNodeId),
+  ],
+);
+
+export const memoryGraphTriggers = sqliteTable(
+  "memory_graph_triggers",
+  {
+    id: text("id").primaryKey(),
+    nodeId: text("node_id")
+      .notNull()
+      .references(() => memoryGraphNodes.id, { onDelete: "cascade" }),
+    /** temporal | semantic | event */
+    type: text("type").notNull(),
+
+    // -- Temporal --
+    schedule: text("schedule"),
+
+    // -- Semantic --
+    condition: text("condition"),
+    /** Pre-computed embedding stored as binary blob. */
+    conditionEmbedding: blob("condition_embedding"),
+    /** Cosine similarity threshold (0–1). */
+    threshold: real("threshold"),
+
+    // -- Event --
+    /** Epoch ms of the event date. */
+    eventDate: integer("event_date"),
+    rampDays: integer("ramp_days"),
+    followUpDays: integer("follow_up_days"),
+
+    // -- State --
+    recurring: integer("recurring", { mode: "boolean" })
+      .notNull()
+      .default(false),
+    consumed: integer("consumed", { mode: "boolean" }).notNull().default(false),
+    cooldownMs: integer("cooldown_ms"),
+    lastFired: integer("last_fired"),
+  },
+  (table) => [
+    index("idx_graph_triggers_node_id").on(table.nodeId),
+    index("idx_graph_triggers_type").on(table.type),
+  ],
+);