@vellumai/assistant 0.5.16 → 0.6.1

package/src/memory/graph/tool-handlers.ts

@@ -0,0 +1,301 @@
+// ---------------------------------------------------------------------------
+// Memory Graph — Tool handlers for recall and remember
+//
+// recall: search the living graph or raw archive
+// remember: save facts to the PKB (buffer.md + daily archive)
+// ---------------------------------------------------------------------------
+
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import type { AssistantConfig } from "../../config/types.js";
+import { getLogger } from "../../util/logger.js";
+import { getWorkspaceDir } from "../../util/platform.js";
+import { buildExcerpt, buildFtsMatchQuery } from "../conversation-queries.js";
+import { embedWithRetry } from "../embed.js";
+import { generateSparseEmbedding } from "../embedding-backend.js";
+import { searchGraphNodes } from "./graph-search.js";
+import { getNodesByIds } from "./store.js";
+
+const log = getLogger("graph-tool-handlers");
+
+// ---------------------------------------------------------------------------
+// recall handler
+// ---------------------------------------------------------------------------
+
+export interface RecallInput {
+  query: string;
+  mode?: "memory" | "archive";
+  num_results?: number;
+  filters?: {
+    types?: string[];
+    after?: string;
+    before?: string;
+  };
+}
+
+export interface RecallResult {
+  results: Array<{
+    id: string;
+    content: string;
+    type: string;
+    confidence: number;
+    significance: number;
+    score: number;
+    created: number;
+  }>;
+  mode: "memory" | "archive";
+  query: string;
+}
+
+export async function handleRecall(
+  input: RecallInput,
+  config: AssistantConfig,
+  scopeId: string,
+): Promise<RecallResult> {
+  const mode = input.mode ?? "memory";
+
+  if (mode === "archive") {
+    return handleArchiveRecall(input, scopeId);
+  }
+
+  return handleMemoryRecall(input, config, scopeId);
+}
+
+async function handleMemoryRecall(
+  input: RecallInput,
+  config: AssistantConfig,
+  scopeId: string,
+): Promise<RecallResult> {
+  // Embed the query
+  let queryVector: number[] | null = null;
+  try {
+    const result = await embedWithRetry(config, [input.query]);
+    queryVector = result.vectors[0] ?? null;
+  } catch (err) {
+    log.warn({ err }, "Failed to embed recall query");
+    return { results: [], mode: "memory", query: input.query };
+  }
+
+  if (!queryVector) {
+    return { results: [], mode: "memory", query: input.query };
+  }
+
+  // Generate sparse embedding for hybrid search (dense + sparse with RRF fusion)
+  const sparseVector = generateSparseEmbedding(input.query);
+
+  // Build date range filter for Qdrant-level filtering
+  const dateRange: { afterMs?: number; beforeMs?: number } = {};
+  if (input.filters?.after) {
+    const afterMs = new Date(input.filters.after).getTime();
+    if (!isNaN(afterMs)) dateRange.afterMs = afterMs;
+  }
+  if (input.filters?.before) {
+    const beforeMs = new Date(input.filters.before).getTime();
+    if (!isNaN(beforeMs)) dateRange.beforeMs = beforeMs;
+  }
+
+  // Search graph nodes
+  const limit = Math.max(1, Math.min(input.num_results ?? 20, 50));
+  const searchResults = await searchGraphNodes(
+    queryVector,
+    limit,
+    [scopeId],
+    sparseVector,
+    dateRange.afterMs != null || dateRange.beforeMs != null
+      ? dateRange
+      : undefined,
+  );
+  if (searchResults.length === 0) {
+    return { results: [], mode: "memory", query: input.query };
+  }
+
+  // Hydrate
+  const nodes = getNodesByIds(searchResults.map((r) => r.nodeId));
+  const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+
+  // Apply filters
+  const results = searchResults.flatMap((r) => {
+    const node = nodeMap.get(r.nodeId);
+    if (!node || node.fidelity === "gone") return [];
+
+    // Type filter
+    if (input.filters?.types && input.filters.types.length > 0) {
+      if (!input.filters.types.includes(node.type)) return [];
+    }
+
+    return [
+      {
+        id: node.id,
+        content: node.content,
+        type: node.type,
+        confidence: node.confidence,
+        significance: node.significance,
+        score: r.score,
+        created: node.created,
+      },
+    ];
+  });
+
+  return { results, mode: "memory", query: input.query };
+}
+
+async function handleArchiveRecall(
+  input: RecallInput,
+  scopeId: string,
+): Promise<RecallResult> {
+  // Archive mode: search raw conversation transcripts via messages FTS
+  // This is a simple text search — no embedding needed
+  const { rawAll } = await import("../db.js");
+
+  try {
+    const limit = Math.max(1, Math.min(input.num_results ?? 20, 50));
+    const ftsMatch = buildFtsMatchQuery(input.query.trim(), {
+      allowFts5Syntax: true,
+    });
+
+    const afterMs = input.filters?.after
+      ? new Date(input.filters.after).getTime()
+      : NaN;
+    const beforeMs = input.filters?.before
+      ? new Date(input.filters.before).getTime()
+      : NaN;
+    const dateConditions: string[] = [];
+    const dateParams: number[] = [];
+    if (!isNaN(afterMs)) {
+      dateConditions.push("m.created_at >= ?");
+      dateParams.push(afterMs);
+    }
+    if (!isNaN(beforeMs)) {
+      dateConditions.push("m.created_at <= ?");
+      dateParams.push(beforeMs);
+    }
+    const dateClause =
+      dateConditions.length > 0 ? " AND " + dateConditions.join(" AND ") : "";
+
+    type ArchiveRow = {
+      id: string;
+      content: string;
+      role: string;
+      created_at: number;
+      conversation_id: string;
+    };
+
+    let rows: ArchiveRow[];
+
+    if (ftsMatch) {
+      // Use SQLite FTS on messages table, scoped to the active memory scope
+      rows = rawAll<ArchiveRow>(
+        `SELECT m.id, m.content, m.role, m.created_at, c.id as conversation_id
+         FROM messages_fts fts
+         JOIN messages m ON m.id = fts.message_id
+         JOIN conversations c ON c.id = m.conversation_id
+         WHERE messages_fts MATCH ?
+           AND c.memory_scope_id = ?${dateClause}
+         ORDER BY rank
+         LIMIT ?`,
+        ftsMatch,
+        scopeId,
+        ...dateParams,
+        limit,
+      );
+    } else if (!input.query.trim()) {
+      // Empty or whitespace-only query — return nothing rather than matching
+      // every message via a `%%` LIKE pattern.
+      rows = [];
+    } else {
+      // All FTS tokens dropped (non-ASCII, single-char, etc.) — fall back to
+      // LIKE-based search so queries like CJK characters still match.
+      const likePattern = `%${input.query
+        .replace(/\\/g, "\\\\")
+        .replace(/%/g, "\\%")
+        .replace(/_/g, "\\_")}%`;
+      rows = rawAll<ArchiveRow>(
+        `SELECT m.id, m.content, m.role, m.created_at, c.id as conversation_id
+         FROM messages m
+         JOIN conversations c ON c.id = m.conversation_id
+         WHERE m.content LIKE ? ESCAPE '\\' AND c.memory_scope_id = ?${dateClause}
+         ORDER BY m.created_at DESC
+         LIMIT ?`,
+        likePattern,
+        scopeId,
+        ...dateParams,
+        limit,
+      );
+    }
+
+    return {
+      results: rows.map((r) => ({
+        id: r.id,
+        content: buildExcerpt(r.content, input.query),
+        type: "archive",
+        confidence: 0,
+        significance: 0,
+        score: 0,
+        created: r.created_at,
+      })),
+      mode: "archive",
+      query: input.query,
+    };
+  } catch (err) {
+    log.warn({ err }, "Archive recall FTS failed");
+    return { results: [], mode: "archive", query: input.query };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// remember handler — writes to PKB buffer + daily archive
+// ---------------------------------------------------------------------------
+
+export interface RememberInput {
+  content: string;
+}
+
+export interface RememberResult {
+  success: boolean;
+  message: string;
+}
+
+export function handleRemember(
+  input: RememberInput,
+  _conversationId: string,
+  _scopeId: string,
+): RememberResult {
+  if (!input.content || input.content.trim().length === 0) {
+    return { success: false, message: "content is required" };
+  }
+
+  const workspaceDir = getWorkspaceDir();
+  const pkbDir = join(workspaceDir, "pkb");
+  const archiveDir = join(pkbDir, "archive");
+
+  // Ensure directories exist
+  mkdirSync(pkbDir, { recursive: true });
+  mkdirSync(archiveDir, { recursive: true });
+
+  // Build timestamped entry
+  const now = new Date();
+  const month = now.toLocaleString("en-US", { month: "short" });
+  const day = now.getDate();
+  const hours = now.getHours();
+  const minutes = String(now.getMinutes()).padStart(2, "0");
+  const ampm = hours >= 12 ? "PM" : "AM";
+  const displayHour = hours % 12 || 12;
+  const entry = `- [${month} ${day}, ${displayHour}:${minutes} ${ampm}] ${input.content.trim()}\n`;
+
+  // Append to buffer.md
+  const bufferPath = join(pkbDir, "buffer.md");
+  appendFileSync(bufferPath, entry, "utf-8");
+
+  // Append to daily archive
+  const yyyy = now.getFullYear();
+  const mm = String(now.getMonth() + 1).padStart(2, "0");
+  const dd = String(now.getDate()).padStart(2, "0");
+  const archivePath = join(archiveDir, `${yyyy}-${mm}-${dd}.md`);
+  if (!existsSync(archivePath)) {
+    appendFileSync(archivePath, `# ${month} ${day}, ${yyyy}\n\n`, "utf-8");
+  }
+  appendFileSync(archivePath, entry, "utf-8");
+
+  return { success: true, message: "Saved to knowledge base." };
+}

package/src/memory/graph/tools.ts

@@ -0,0 +1,97 @@
+// ---------------------------------------------------------------------------
+// Memory Graph — Tool definitions for recall and remember
+//
+// These replace memory_recall and memory_manage from the old system.
+// ---------------------------------------------------------------------------
+
+import type { ToolDefinition } from "../../providers/types.js";
+
+/**
+ * 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.
+ */
+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.",
+  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.",
+      },
+      num_results: {
+        type: "integer",
+        description:
+          "Maximum number of results to return (default 20, max 50).",
+      },
+      mode: {
+        type: "string",
+        enum: ["memory", "archive"],
+        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)",
+          },
+        },
+      },
+    },
+    required: ["query"],
+  },
+};
+
+/**
+ * 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.
+ */
+export const graphRememberDefinition: ToolDefinition = {
+  name: "remember",
+  description:
+    "Save a fact to your knowledge base. Call this AGGRESSIVELY — every preference, location, name, date, habit, opinion, health detail, plan, relationship fact, routine, or commitment. The bar is: if you wouldn't want to ask about it again, remember it. Examples: 'Prefers UberEats over DoorDash', 'Lives in NYC, from Texas', 'Takes 45mg nicotine daily, tapering', 'Girlfriend Yen is in Texas', 'Watches vampire show Saturday nights', 'NYU Summit April 10-11'. 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.",
+  input_schema: {
+    type: "object",
+    properties: {
+      content: {
+        type: "string",
+        description:
+          "The fact to remember. Write naturally — a preference, a detail, a commitment, a plan. No need to categorize.",
+      },
+    },
+    required: ["content"],
+  },
+};