@vellumai/assistant 0.5.16 → 0.6.1

package/src/memory/graph/decay.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, test } from "bun:test";
+
+import { computeDecayedIntensity, computeFidelityLevel } from "./decay.js";
+import type { EmotionalCharge } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeCharge(overrides: Partial<EmotionalCharge> = {}): EmotionalCharge {
+  return {
+    valence: 0.5,
+    intensity: 0.8,
+    decayCurve: "linear",
+    decayRate: 0.05,
+    originalIntensity: 0.8,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// computeDecayedIntensity
+// ---------------------------------------------------------------------------
+
+describe("computeDecayedIntensity", () => {
+  test("returns current intensity when no time has elapsed", () => {
+    const charge = makeCharge({ intensity: 0.8 });
+    expect(computeDecayedIntensity(charge, 0)).toBe(0.8);
+  });
+
+  test("returns current intensity for negative elapsed time", () => {
+    const charge = makeCharge({ intensity: 0.8 });
+    expect(computeDecayedIntensity(charge, -5)).toBe(0.8);
+  });
+
+  // --- Linear ---
+
+  test("linear: decays at constant rate per day", () => {
+    const charge = makeCharge({
+      decayCurve: "linear",
+      decayRate: 0.1,
+      originalIntensity: 1.0,
+    });
+    // After 5 days: 1.0 - 0.1 × 5 = 0.5
+    expect(computeDecayedIntensity(charge, 5)).toBeCloseTo(0.5, 5);
+  });
+
+  test("linear: floors at 0", () => {
+    const charge = makeCharge({
+      decayCurve: "linear",
+      decayRate: 0.1,
+      originalIntensity: 0.5,
+    });
+    // After 10 days: 0.5 - 0.1 × 10 = -0.5 → clamped to 0
+    expect(computeDecayedIntensity(charge, 10)).toBe(0);
+  });
+
+  test("linear: fully decayed after enough time", () => {
+    const charge = makeCharge({
+      decayCurve: "linear",
+      decayRate: 0.05,
+      originalIntensity: 0.8,
+    });
+    // After 20 days: 0.8 - 0.05 × 20 = -0.2 → 0
+    expect(computeDecayedIntensity(charge, 20)).toBe(0);
+  });
+
+  // --- Logarithmic ---
+
+  test("logarithmic: sharp initial drop, long tail", () => {
+    const charge = makeCharge({
+      decayCurve: "logarithmic",
+      decayRate: 0.5,
+      originalIntensity: 1.0,
+    });
+    const at1 = computeDecayedIntensity(charge, 1);
+    const at10 = computeDecayedIntensity(charge, 10);
+    const at100 = computeDecayedIntensity(charge, 100);
+
+    // Sharp drop initially
+    expect(at1).toBeLessThan(1.0);
+    // But long tail — never reaches 0
+    expect(at10).toBeGreaterThan(0);
+    expect(at100).toBeGreaterThan(0);
+    // Monotonic decay
+    expect(at1).toBeGreaterThan(at10);
+    expect(at10).toBeGreaterThan(at100);
+  });
+
+  test("logarithmic: formula I₀ / (1 + rate × ln(1 + t))", () => {
+    const charge = makeCharge({
+      decayCurve: "logarithmic",
+      decayRate: 0.5,
+      originalIntensity: 0.8,
+    });
+    const days = 10;
+    const expected = 0.8 / (1 + 0.5 * Math.log(1 + days));
+    expect(computeDecayedIntensity(charge, days)).toBeCloseTo(expected, 10);
+  });
+
+  // --- Transformative ---
+
+  test("transformative: decays but floors at 20% of original", () => {
+    const charge = makeCharge({
+      decayCurve: "transformative",
+      decayRate: 0.1,
+      originalIntensity: 1.0,
+    });
+    const atInfinity = computeDecayedIntensity(charge, 10000);
+    // Floor is 20% of original = 0.2
+    expect(atInfinity).toBeCloseTo(0.2, 5);
+  });
+
+  test("transformative: exponential decay above the floor", () => {
+    const charge = makeCharge({
+      decayCurve: "transformative",
+      decayRate: 0.1,
+      originalIntensity: 1.0,
+    });
+    const at5 = computeDecayedIntensity(charge, 5);
+    const at10 = computeDecayedIntensity(charge, 10);
+
+    expect(at5).toBeGreaterThan(at10);
+    // at5: max(0.2, 1.0 × e^(-0.1×5)) = max(0.2, 0.607) = 0.607
+    expect(at5).toBeCloseTo(Math.exp(-0.5), 3);
+    // at10: max(0.2, 1.0 × e^(-0.1×10)) = max(0.2, 0.368) = 0.368
+    expect(at10).toBeCloseTo(Math.exp(-1), 3);
+  });
+
+  // --- Permanent ---
+
+  test("permanent: no decay at all", () => {
+    const charge = makeCharge({
+      decayCurve: "permanent",
+      decayRate: 0.5, // ignored
+      originalIntensity: 0.9,
+      intensity: 0.9,
+    });
+    // At elapsed=0, returns charge.intensity (the early return)
+    expect(computeDecayedIntensity(charge, 0)).toBe(0.9);
+    // For any elapsed > 0, returns originalIntensity (permanent never decays)
+    expect(computeDecayedIntensity(charge, 100)).toBe(0.9);
+    expect(computeDecayedIntensity(charge, 10000)).toBe(0.9);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// computeFidelityLevel
+// ---------------------------------------------------------------------------
+
+describe("computeFidelityLevel", () => {
+  test("stays vivid within the first 7 days", () => {
+    expect(computeFidelityLevel("vivid", 3, 0.5)).toBe("vivid");
+    expect(computeFidelityLevel("vivid", 6, 0.5)).toBe("vivid");
+  });
+
+  test("downgrades vivid → clear after 7 days", () => {
+    expect(computeFidelityLevel("vivid", 8, 0.5)).toBe("clear");
+  });
+
+  test("downgrades clear → faded after 37 days (7 vivid + 30 clear)", () => {
+    expect(computeFidelityLevel("vivid", 38, 0.5)).toBe("faded");
+  });
+
+  test("downgrades faded → gist after 127 days (7+30+90)", () => {
+    expect(computeFidelityLevel("vivid", 130, 0.5)).toBe("gist");
+  });
+
+  test("never auto-downgrades to gone", () => {
+    // Even after 500 days, should cap at gist (gone is consolidation's job)
+    expect(computeFidelityLevel("vivid", 500, 0.5)).toBe("gist");
+    expect(computeFidelityLevel("gist", 5000, 0.5)).toBe("gist");
+  });
+
+  test("never upgrades fidelity", () => {
+    // If currently at "faded", should stay at "faded" even if time says "vivid"
+    expect(computeFidelityLevel("faded", 1, 0.5)).toBe("faded");
+    expect(computeFidelityLevel("clear", 1, 0.5)).toBe("clear");
+    expect(computeFidelityLevel("gist", 1, 0.5)).toBe("gist");
+    expect(computeFidelityLevel("gone", 1, 0.5)).toBe("gone");
+  });
+
+  test("high significance (0.8+) doubles thresholds", () => {
+    // vivid threshold at sig 0.8: 7 × 2 = 14 days
+    expect(computeFidelityLevel("vivid", 10, 0.8)).toBe("vivid");
+    expect(computeFidelityLevel("vivid", 15, 0.8)).toBe("clear");
+
+    // vivid+clear at sig 0.8: (7+30) × 2 = 74 days
+    expect(computeFidelityLevel("vivid", 70, 0.8)).toBe("clear");
+    expect(computeFidelityLevel("vivid", 75, 0.8)).toBe("faded");
+  });
+
+  test("very high significance (0.9+) triples thresholds", () => {
+    // vivid threshold at sig 0.9: 7 × 3 = 21 days
+    expect(computeFidelityLevel("vivid", 15, 0.9)).toBe("vivid");
+    expect(computeFidelityLevel("vivid", 22, 0.9)).toBe("clear");
+
+    // vivid+clear at sig 0.9: (7+30) × 3 = 111 days
+    expect(computeFidelityLevel("vivid", 100, 0.9)).toBe("clear");
+    expect(computeFidelityLevel("vivid", 112, 0.9)).toBe("faded");
+  });
+
+  test("low significance uses normal thresholds", () => {
+    // No resistance factor for sig < 0.8
+    expect(computeFidelityLevel("vivid", 8, 0.3)).toBe("clear");
+    expect(computeFidelityLevel("vivid", 8, 0.79)).toBe("clear");
+  });
+});

package/src/memory/graph/decay.ts

@@ -0,0 +1,195 @@
+// ---------------------------------------------------------------------------
+// Memory Graph — Mechanical decay engine
+//
+// Runs on an hourly tick. No LLM calls — purely mathematical decay
+// of emotional intensity, significance, and fidelity. Prose content
+// updates (keeping content in sync with decayed values) happen during
+// the LLM-based consolidation process, not here.
+// ---------------------------------------------------------------------------
+
+import { and, eq, sql } from "drizzle-orm";
+
+import { getDb } from "../db.js";
+import { memoryGraphNodes } from "../schema.js";
+import type { EmotionalCharge, Fidelity } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Emotional intensity decay
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the decayed emotional intensity for a node.
+ * Each decay curve behaves differently:
+ *
+ * - linear: constant rate of decay
+ * - logarithmic: sharp initial drop, long tail (negative events)
+ * - transformative: feeling changes shape — intensity drops but doesn't reach 0
+ * - permanent: no decay at all
+ */
+export function computeDecayedIntensity(
+  charge: EmotionalCharge,
+  elapsedDays: number,
+): number {
+  if (elapsedDays <= 0) return charge.intensity;
+
+  switch (charge.decayCurve) {
+    case "permanent":
+      return charge.originalIntensity;
+
+    case "linear":
+      return Math.max(
+        0,
+        charge.originalIntensity - charge.decayRate * elapsedDays,
+      );
+
+    case "logarithmic":
+      // Sharp initial drop, long tail: I(t) = I₀ / (1 + rate × ln(1 + t))
+      return (
+        charge.originalIntensity /
+        (1 + charge.decayRate * Math.log(1 + elapsedDays))
+      );
+
+    case "transformative":
+      // Intensity drops but floors at 20% of original — the feeling transforms, doesn't vanish
+      const floor = charge.originalIntensity * 0.2;
+      const decayed =
+        charge.originalIntensity * Math.exp(-charge.decayRate * elapsedDays);
+      return Math.max(floor, decayed);
+
+    default:
+      return charge.intensity;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fidelity downgrade
+// ---------------------------------------------------------------------------
+
+/** Thresholds in days for fidelity transitions (from creation or last consolidation). */
+const FIDELITY_THRESHOLDS: Record<Fidelity, number> = {
+  vivid: 7, // vivid for ~1 week
+  clear: 30, // clear for ~1 month
+  faded: 90, // faded for ~3 months
+  gist: 365, // gist for ~1 year, then gone
+  gone: Infinity,
+};
+
+const FIDELITY_ORDER: Fidelity[] = ["vivid", "clear", "faded", "gist", "gone"];
+
+/**
+ * Compute what fidelity level a node should be at based on elapsed time.
+ * Returns null if no downgrade is needed.
+ */
+export function computeFidelityLevel(
+  currentFidelity: Fidelity,
+  elapsedDays: number,
+  significance: number,
+): Fidelity {
+  // High-significance memories resist fidelity decay:
+  // significance 0.8+ → thresholds doubled
+  // significance 0.9+ → thresholds tripled
+  const resistanceFactor =
+    significance >= 0.9 ? 3 : significance >= 0.8 ? 2 : 1;
+
+  let targetFidelity: Fidelity = "vivid";
+  let accumulated = 0;
+
+  for (const level of FIDELITY_ORDER) {
+    if (level === "gone") {
+      targetFidelity = "gist"; // don't auto-downgrade to gone — consolidation decides
+      break;
+    }
+    accumulated += FIDELITY_THRESHOLDS[level] * resistanceFactor;
+    if (elapsedDays < accumulated) {
+      targetFidelity = level;
+      break;
+    }
+    targetFidelity =
+      FIDELITY_ORDER[FIDELITY_ORDER.indexOf(level) + 1] ?? "gist";
+  }
+
+  // Never upgrade fidelity — only downgrade
+  const currentIdx = FIDELITY_ORDER.indexOf(currentFidelity);
+  const targetIdx = FIDELITY_ORDER.indexOf(targetFidelity);
+  return targetIdx > currentIdx ? targetFidelity : currentFidelity;
+}
+
+// ---------------------------------------------------------------------------
+// Decay tick — processes all non-gone nodes in a scope
+// ---------------------------------------------------------------------------
+
+export interface DecayTickResult {
+  nodesProcessed: number;
+  emotionalDecays: number;
+  fidelityDowngrades: number;
+}
+
+/**
+ * Run a single decay tick. Processes all non-gone nodes in the given scope,
+ * applying mechanical decay to emotional intensity and fidelity.
+ *
+ * Significance decay is computed at retrieval time (not stored) via
+ * computeEffectiveSignificance in scoring.ts, so it's not applied here.
+ */
+export function runDecayTick(scopeId: string): DecayTickResult {
+  const db = getDb();
+  const result: DecayTickResult = {
+    nodesProcessed: 0,
+    emotionalDecays: 0,
+    fidelityDowngrades: 0,
+  };
+
+  const rows = db
+    .select()
+    .from(memoryGraphNodes)
+    .where(
+      and(
+        eq(memoryGraphNodes.scopeId, scopeId),
+        sql`${memoryGraphNodes.fidelity} != 'gone'`,
+      ),
+    )
+    .all();
+
+  const now = Date.now();
+  const msPerDay = 1000 * 60 * 60 * 24;
+
+  for (const row of rows) {
+    result.nodesProcessed++;
+    const updates: Record<string, unknown> = {};
+
+    // -- Emotional intensity decay --
+    const charge: EmotionalCharge = JSON.parse(row.emotionalCharge);
+    const emotionalElapsedDays = (now - row.created) / msPerDay;
+    const newIntensity = computeDecayedIntensity(charge, emotionalElapsedDays);
+
+    if (Math.abs(newIntensity - charge.intensity) > 0.001) {
+      charge.intensity = newIntensity;
+      updates.emotionalCharge = JSON.stringify(charge);
+      result.emotionalDecays++;
+    }
+
+    // -- Fidelity downgrade --
+    const currentFidelity = row.fidelity as Fidelity;
+    const fidelityElapsedDays = (now - row.lastConsolidated) / msPerDay;
+    const newFidelity = computeFidelityLevel(
+      currentFidelity,
+      fidelityElapsedDays,
+      row.significance,
+    );
+
+    if (newFidelity !== currentFidelity) {
+      updates.fidelity = newFidelity;
+      result.fidelityDowngrades++;
+    }
+
+    // Apply updates if anything changed
+    if (Object.keys(updates).length > 0) {
+      db.update(memoryGraphNodes)
+        .set(updates)
+        .where(eq(memoryGraphNodes.id, row.id))
+        .run();
+    }
+  }
+
+  return result;
+}

package/src/memory/graph/extraction-job.ts

@@ -0,0 +1,74 @@
+// ---------------------------------------------------------------------------
+// Memory Graph — Extraction job handler
+//
+// Wraps runGraphExtraction for the jobs worker. Handles both:
+// - Mid-conversation batch extraction (incremental, from checkpoint)
+// - End-of-conversation extraction (full transcript)
+// ---------------------------------------------------------------------------
+
+import type { AssistantConfig } from "../../config/types.js";
+import { getLogger } from "../../util/logger.js";
+import { getMemoryCheckpoint, setMemoryCheckpoint } from "../checkpoints.js";
+import { asString } from "../job-utils.js";
+import type { MemoryJob } from "../jobs-store.js";
+import { runGraphExtraction } from "./extraction.js";
+
+const log = getLogger("graph-extraction-job");
+
+/**
+ * Job handler for `graph_extract`. Runs incremental or full extraction
+ * depending on whether a checkpoint exists for this conversation.
+ *
+ * Checkpoint key: `graph_extract:<conversationId>:last_ts`
+ * Value: epoch ms of the most recent message processed.
+ *
+ * Trigger sources:
+ * - Indexer after batchSize messages (default 10)
+ * - Indexer idle debounce (default 300s)
+ * - Conversation dispose (end of conversation)
+ */
+export async function graphExtractJob(
+  job: MemoryJob,
+  config: AssistantConfig,
+): Promise<void> {
+  const conversationId = asString(job.payload.conversationId);
+  const scopeId = asString(job.payload.scopeId) || "default";
+  if (!conversationId) return;
+
+  // Read checkpoint for incremental extraction
+  const checkpointKey = `graph_extract:${conversationId}:last_ts`;
+  const lastTs = getMemoryCheckpoint(checkpointKey);
+  const afterTimestamp = lastTs ? parseInt(lastTs, 10) : undefined;
+
+  const activeContextNodeIds = Array.isArray(job.payload.activeContextNodeIds)
+    ? (job.payload.activeContextNodeIds as string[])
+    : undefined;
+
+  try {
+    const result = await runGraphExtraction(conversationId, scopeId, config, {
+      afterTimestamp,
+      activeContextNodeIds,
+    });
+
+    // Update checkpoint to the newest message actually processed — using
+    // Date.now() could skip messages that arrived during extraction.
+    if (result.lastProcessedTimestamp) {
+      setMemoryCheckpoint(checkpointKey, String(result.lastProcessedTimestamp));
+    }
+
+    log.info(
+      {
+        conversationId,
+        incremental: !!afterTimestamp,
+        ...result,
+      },
+      "Graph extraction job complete",
+    );
+  } catch (err) {
+    log.error(
+      { conversationId, err: err instanceof Error ? err.message : String(err) },
+      "Graph extraction job failed",
+    );
+    throw err;
+  }
+}