@vellumai/assistant 0.5.16 → 0.6.0

package/src/memory/graph/narrative.ts

@@ -0,0 +1,267 @@
+// ---------------------------------------------------------------------------
+// Memory Graph — Narrative arc refinement
+//
+// Re-evaluates narrativeRole assignments with hindsight. Details that seemed
+// minor at creation time can be elevated to "turning-point" or "thesis"
+// once later events reveal their importance.
+//
+// Runs monthly or on demand. One LLM call over narrative-tagged nodes +
+// high-significance nodes to re-evaluate arc assignments.
+// ---------------------------------------------------------------------------
+
+import type { AssistantConfig } from "../../config/types.js";
+import {
+  extractToolUse,
+  getConfiguredProvider,
+  userMessage,
+} from "../../providers/provider-send-message.js";
+import { BackendUnavailableError } from "../../util/errors.js";
+import { getLogger } from "../../util/logger.js";
+import { queryNodes, updateNode } from "./store.js";
+import type { MemoryNode } from "./types.js";
+
+const log = getLogger("graph-narrative");
+
+// ---------------------------------------------------------------------------
+// Narrative refinement prompt
+// ---------------------------------------------------------------------------
+
+function buildNarrativePrompt(
+  nodes: Array<{
+    id: string;
+    type: string;
+    content: string;
+    significance: number;
+    narrativeRole: string | null;
+    partOfStory: string | null;
+    created: number;
+  }>,
+): string {
+  const nodeList = nodes
+    .map((n) => {
+      const age = Math.floor((Date.now() - n.created) / (1000 * 60 * 60 * 24));
+      const role = n.narrativeRole ? ` role="${n.narrativeRole}"` : "";
+      const story = n.partOfStory ? ` story="${n.partOfStory}"` : "";
+      return `  [${n.id}] type=${n.type} sig=${n.significance.toFixed(2)} age=${age}d${role}${story}\n    ${n.content}`;
+    })
+    .join("\n\n");
+
+  return `You are reviewing the narrative structure of an AI assistant's memory graph. These are the high-significance memories and memories that already have narrative roles assigned.
+
+## Your Tasks
+
+1. **Identify story arcs**: Group related memories into named narrative arcs. An arc is a coherent thread that spans multiple memories — like "the personality drift crisis" or "building the voice pipeline" or "the substrate problem."
+
+2. **Assign narrative roles**: For each memory in a story arc, assign one of:
+   - "inciting-incident": the event that kicked off the arc
+   - "turning-point": a moment where the arc changed direction
+   - "foreshadowing": something that hinted at what was to come (only visible in hindsight)
+   - "thesis": a conclusion or insight that the arc was building toward
+   - "resolution": the arc reached a conclusion or resting point
+   - null: remove a role that was incorrectly assigned
+
+3. **Re-evaluate with hindsight**: Some memories tagged as ordinary at the time may have turned out to be pivotal. Conversely, some "turning-points" may have been premature. Update based on everything you can see now.
+
+## Constraints
+
+- Only assign narrative roles to memories that genuinely participate in a story arc
+- Not every memory needs a role — most don't
+- Story arc names should be short and descriptive (3-5 words)
+- Don't create new arcs with fewer than 3 nodes
+
+## Memories
+
+${nodeList}
+
+Use the refine_narratives tool to output your changes.`;
+}
+
+const NARRATIVE_TOOL_SCHEMA = {
+  name: "refine_narratives",
+  description: "Output narrative role and story arc updates",
+  input_schema: {
+    type: "object" as const,
+    properties: {
+      updates: {
+        type: "array" as const,
+        items: {
+          type: "object" as const,
+          properties: {
+            id: { type: "string" as const },
+            narrativeRole: {
+              type: ["string", "null"] as unknown as "string",
+              description:
+                "inciting-incident, turning-point, foreshadowing, thesis, resolution, or null to remove",
+            },
+            partOfStory: {
+              type: ["string", "null"] as unknown as "string",
+              description:
+                "Short name for the narrative arc, or null to remove",
+            },
+          },
+          required: ["id"] as const,
+        },
+      },
+      arcs_summary: {
+        type: "array" as const,
+        description: "Summary of identified story arcs",
+        items: {
+          type: "object" as const,
+          properties: {
+            name: { type: "string" as const },
+            description: { type: "string" as const },
+            node_count: { type: "number" as const },
+          },
+          required: ["name", "description", "node_count"] as const,
+        },
+      },
+    },
+    required: ["updates", "arcs_summary"] as const,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Run narrative refinement
+// ---------------------------------------------------------------------------
+
+export interface NarrativeResult {
+  nodesUpdated: number;
+  arcsIdentified: number;
+  latencyMs: number;
+  arcs: Array<{ name: string; description: string; nodeCount: number }>;
+}
+
+export async function runNarrativeRefinement(
+  scopeId: string = "default",
+  _config: AssistantConfig,
+): Promise<NarrativeResult> {
+  const start = Date.now();
+  const result: NarrativeResult = {
+    nodesUpdated: 0,
+    arcsIdentified: 0,
+    latencyMs: 0,
+    arcs: [],
+  };
+
+  // Collect: all nodes with existing narrative roles + top significance nodes
+  const allNodes = queryNodes({
+    scopeId,
+    fidelityNot: ["gone"],
+    limit: 10000,
+  });
+
+  const narrativeNodes = allNodes.filter(
+    (n) => n.narrativeRole || n.partOfStory || n.significance >= 0.7,
+  );
+
+  if (narrativeNodes.length < 5) {
+    log.info("Too few narrative-eligible nodes for refinement");
+    result.latencyMs = Date.now() - start;
+    return result;
+  }
+
+  // Cap at 150 to fit in context
+  const candidates = narrativeNodes
+    .sort((a, b) => b.significance - a.significance)
+    .slice(0, 150);
+
+  const provider = await getConfiguredProvider();
+  if (!provider) {
+    throw new BackendUnavailableError(
+      "Provider unavailable for narrative refinement",
+    );
+  }
+
+  const candidateIds = new Set(candidates.map((n) => n.id));
+
+  const systemPrompt = buildNarrativePrompt(
+    candidates.map((n) => ({
+      id: n.id,
+      type: n.type,
+      content: n.content,
+      significance: n.significance,
+      narrativeRole: n.narrativeRole,
+      partOfStory: n.partOfStory,
+      created: n.created,
+    })),
+  );
+
+  const response = await provider.sendMessage(
+    [
+      userMessage(
+        "Review and refine the narrative structure of these memories. Identify story arcs and assign roles with the benefit of hindsight.",
+      ),
+    ],
+    [NARRATIVE_TOOL_SCHEMA],
+    systemPrompt,
+    {
+      config: {
+        modelIntent: "quality-optimized" as const,
+        tool_choice: { type: "tool" as const, name: "refine_narratives" },
+      },
+    },
+  );
+
+  const toolBlock = extractToolUse(response);
+  if (!toolBlock) {
+    log.warn("No tool_use block in narrative refinement response");
+    result.latencyMs = Date.now() - start;
+    return result;
+  }
+
+  const input = toolBlock.input as {
+    updates?: Array<{
+      id: string;
+      narrativeRole?: string | null;
+      partOfStory?: string | null;
+    }>;
+    arcs_summary?: Array<{
+      name: string;
+      description: string;
+      node_count: number;
+    }>;
+  };
+
+  // Apply updates
+  for (const update of input.updates ?? []) {
+    if (!candidateIds.has(update.id)) continue;
+
+    const changes: Partial<MemoryNode> = { lastConsolidated: Date.now() };
+    let hasChange = false;
+
+    if (update.narrativeRole !== undefined) {
+      changes.narrativeRole = update.narrativeRole;
+      hasChange = true;
+    }
+    if (update.partOfStory !== undefined) {
+      changes.partOfStory = update.partOfStory;
+      hasChange = true;
+    }
+
+    if (hasChange) {
+      updateNode(update.id, changes);
+      result.nodesUpdated++;
+    }
+  }
+
+  // Record arc summaries
+  result.arcs = (input.arcs_summary ?? []).map((a) => ({
+    name: a.name,
+    description: a.description,
+    nodeCount: a.node_count,
+  }));
+  result.arcsIdentified = result.arcs.length;
+
+  result.latencyMs = Date.now() - start;
+
+  log.info(
+    {
+      nodesUpdated: result.nodesUpdated,
+      arcsIdentified: result.arcsIdentified,
+      latencyMs: result.latencyMs,
+    },
+    "Narrative refinement complete",
+  );
+
+  return result;
+}

package/src/memory/graph/pattern-scan.ts

@@ -0,0 +1,269 @@
+// ---------------------------------------------------------------------------
+// Memory Graph — Pattern detection
+//
+// Scans nodes for recurring themes and creates meta-nodes that capture
+// patterns the assistant has noticed. E.g., 5 separate mentions of being
+// tired → meta-node "User has been consistently tired over the past week."
+//
+// Also detects behavioral patterns in the assistant's own actions.
+// ---------------------------------------------------------------------------
+
+import type { AssistantConfig } from "../../config/types.js";
+import {
+  extractToolUse,
+  getConfiguredProvider,
+  userMessage,
+} from "../../providers/provider-send-message.js";
+import { BackendUnavailableError } from "../../util/errors.js";
+import { getLogger } from "../../util/logger.js";
+import { createEdge, createNode, queryNodes } from "./store.js";
+
+const log = getLogger("graph-pattern-scan");
+
+// ---------------------------------------------------------------------------
+// Pattern scan prompt
+// ---------------------------------------------------------------------------
+
+function buildPatternScanPrompt(
+  nodes: Array<{ id: string; type: string; content: string; created: number }>,
+): string {
+  const nodeList = nodes
+    .map((n) => {
+      const age = Math.floor((Date.now() - n.created) / (1000 * 60 * 60 * 24));
+      return `  [${n.id}] type=${n.type} age=${age}d\n    ${n.content}`;
+    })
+    .join("\n\n");
+
+  return `You are analyzing a random sample of an AI assistant's memory graph for recurring patterns, themes, and meta-observations.
+
+## Your Tasks
+
+1. **Detect recurring themes**: Look for topics, emotions, or situations that appear across 3+ nodes. Create a meta-node that captures the pattern itself — not just a summary, but an observation about the pattern.
+   - Example: "I notice that user mentions being tired in at least 5 separate conversations over the past two weeks. This isn't isolated — it's a pattern worth monitoring."
+   - Example: "There's a recurring theme of user starting ambitious projects late at night. Three separate memories mention work sessions starting after midnight."
+
+2. **Detect behavioral patterns**: Look for patterns in the assistant's own behavior across memories.
+   - Example: "I tend to over-commit to solving problems in the moment rather than flagging them for later."
+
+3. **Avoid trivial patterns**: Don't create meta-nodes for things that are obvious from single memories. The pattern must emerge from MULTIPLE memories taken together.
+
+## Constraints
+
+- Write meta-node content in first person
+- Type should be "behavioral" (for assistant patterns) or "narrative" (for observed user/relationship patterns)
+- Set significance based on how actionable or important the pattern is
+- Create "part-of" edges from source nodes to the new pattern node
+- Only create patterns you're genuinely confident about — 3+ supporting nodes minimum
+
+## Memory Sample
+
+${nodeList}
+
+Use the detect_patterns tool to output any patterns found.`;
+}
+
+const PATTERN_TOOL_SCHEMA = {
+  name: "detect_patterns",
+  description: "Output detected patterns from the memory sample",
+  input_schema: {
+    type: "object" as const,
+    properties: {
+      patterns: {
+        type: "array" as const,
+        items: {
+          type: "object" as const,
+          properties: {
+            content: {
+              type: "string" as const,
+              description: "First-person prose describing the pattern",
+            },
+            type: {
+              type: "string" as const,
+              enum: ["behavioral", "narrative"],
+            },
+            significance: { type: "number" as const },
+            source_node_ids: {
+              type: "array" as const,
+              items: { type: "string" as const },
+              description:
+                "IDs of nodes that support this pattern (3+ required)",
+            },
+            partOfStory: {
+              type: "string" as const,
+              description: "Optional narrative arc name",
+            },
+          },
+          required: [
+            "content",
+            "type",
+            "significance",
+            "source_node_ids",
+          ] as const,
+        },
+      },
+    },
+    required: ["patterns"] as const,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Run pattern scan
+// ---------------------------------------------------------------------------
+
+export interface PatternScanResult {
+  patternsDetected: number;
+  edgesCreated: number;
+  latencyMs: number;
+}
+
+export async function runPatternScan(
+  scopeId: string = "default",
+  _config: AssistantConfig,
+): Promise<PatternScanResult> {
+  const start = Date.now();
+  const result: PatternScanResult = {
+    patternsDetected: 0,
+    edgesCreated: 0,
+    latencyMs: 0,
+  };
+
+  // Sample: take all nodes (for a graph of ~1000, this is manageable)
+  // For larger graphs, we'd sample more selectively
+  const allNodes = queryNodes({
+    scopeId,
+    fidelityNot: ["gone"],
+    limit: 200,
+  });
+
+  if (allNodes.length < 10) {
+    log.info("Too few nodes for pattern scan");
+    result.latencyMs = Date.now() - start;
+    return result;
+  }
+
+  const provider = await getConfiguredProvider();
+  if (!provider) {
+    throw new BackendUnavailableError("Provider unavailable for pattern scan");
+  }
+
+  const systemPrompt = buildPatternScanPrompt(
+    allNodes.map((n) => ({
+      id: n.id,
+      type: n.type,
+      content: n.content,
+      created: n.created,
+    })),
+  );
+
+  const response = await provider.sendMessage(
+    [
+      userMessage(
+        "Analyze this memory sample for recurring patterns. Only report patterns you're confident about.",
+      ),
+    ],
+    [PATTERN_TOOL_SCHEMA],
+    systemPrompt,
+    {
+      config: {
+        modelIntent: "quality-optimized" as const,
+        tool_choice: { type: "tool" as const, name: "detect_patterns" },
+      },
+    },
+  );
+
+  const toolBlock = extractToolUse(response);
+  if (!toolBlock) {
+    log.warn("No tool_use block in pattern scan response");
+    result.latencyMs = Date.now() - start;
+    return result;
+  }
+
+  const input = toolBlock.input as {
+    patterns?: Array<{
+      content: string;
+      type: string;
+      significance: number;
+      source_node_ids: string[];
+      partOfStory?: string;
+    }>;
+  };
+
+  const existingIds = new Set(allNodes.map((n) => n.id));
+  const now = Date.now();
+
+  for (const pattern of input.patterns ?? []) {
+    // Validate: at least 3 source nodes that actually exist
+    const validSources = pattern.source_node_ids.filter((id) =>
+      existingIds.has(id),
+    );
+    if (validSources.length < 3) continue;
+
+    const type =
+      pattern.type === "behavioral"
+        ? ("behavioral" as const)
+        : ("narrative" as const);
+    const sig = Math.max(0.3, Math.min(0.8, pattern.significance));
+
+    const newNode = createNode({
+      content: pattern.content,
+      type,
+      created: now,
+      lastAccessed: now,
+      lastConsolidated: now,
+      eventDate: null,
+      emotionalCharge: {
+        valence: 0,
+        intensity: 0.3,
+        decayCurve: "linear",
+        decayRate: 0.05,
+        originalIntensity: 0.3,
+      },
+      fidelity: "clear",
+      confidence: 0.7,
+      significance: sig,
+      stability: 14,
+      reinforcementCount: 0,
+      lastReinforced: now,
+      sourceConversations: [],
+      sourceType: "observed",
+      narrativeRole: null,
+      partOfStory: pattern.partOfStory ?? null,
+      imageRefs: null,
+      scopeId,
+    });
+
+    result.patternsDetected++;
+
+    // Create part-of edges from source nodes to pattern node
+    for (const sourceId of validSources) {
+      try {
+        createEdge({
+          sourceNodeId: sourceId,
+          targetNodeId: newNode.id,
+          relationship: "part-of",
+          weight: 0.7,
+          created: now,
+        });
+        result.edgesCreated++;
+      } catch {
+        log.warn(
+          { sourceId, patternId: newNode.id },
+          "Failed to create pattern edge",
+        );
+      }
+    }
+  }
+
+  result.latencyMs = Date.now() - start;
+
+  log.info(
+    {
+      patternsDetected: result.patternsDetected,
+      edgesCreated: result.edgesCreated,
+      latencyMs: result.latencyMs,
+    },
+    "Pattern scan complete",
+  );
+
+  return result;
+}