@vellumai/assistant 0.6.4 → 0.6.6

package/src/memory/graph/retriever.ts

@@ -15,7 +15,11 @@ import {
 import type { ContentBlock, ImageContent } from "../../providers/types.js";
 import { getLogger } from "../../util/logger.js";
 import { embedWithRetry } from "../embed.js";
-import { selectedBackendSupportsMultimodal } from "../embedding-backend.js";
+import {
+  generateSparseEmbedding,
+  selectedBackendSupportsMultimodal,
+} from "../embedding-backend.js";
+import type { QdrantSparseVector } from "../qdrant-client.js";
 import { searchGraphNodes } from "./graph-search.js";
 import type { InContextTracker } from "./injection.js";
 import {
@@ -28,7 +32,12 @@ import {
   weightsForContextLoad,
 } from "./scoring.js";
 import { sampleSerendipity } from "./serendipity.js";
-import { getEdgesForNode, getNodesByIds, queryNodes } from "./store.js";
+import {
+  getEdgesForNode,
+  getNodesByIds,
+  queryCapabilityNodes,
+  queryNodes,
+} from "./store.js";
 import { getActiveTriggersByType } from "./store.js";
 import {
   evaluateEventTriggers,
@@ -46,6 +55,13 @@ import { isCapabilityNode } from "./types.js";
 
 const log = getLogger("graph-retriever");
 
+function extractCapabilityId(node: MemoryNode): string | null {
+  const match = node.content.match(
+    /^skill:(\S+)\n|^cli:(\S+)\n|^\s*The ".*?" skill \(([^)]+)\)|^\s*The "assistant (\S+)" CLI command/,
+  );
+  return match?.[1] ?? match?.[2] ?? match?.[3] ?? match?.[4] ?? null;
+}
+
 // ---------------------------------------------------------------------------
 // LLM re-ranking + deduplication
 // ---------------------------------------------------------------------------
@@ -81,7 +97,7 @@ async function rerankAndDedup(
   if (candidates.length <= maxNodes) return candidates;
 
   try {
-    const provider = await getConfiguredProvider();
+    const provider = await getConfiguredProvider("memoryRetrieval");
     if (!provider) return candidates.slice(0, maxNodes);
 
     // Numbered listing for the LLM: index + age + full content
@@ -111,7 +127,7 @@ Your job:
 3. Return the IDs in order of importance (most important first).`,
       {
         config: {
-          modelIntent: "quality-optimized" as const,
+          callSite: "memoryRetrieval" as const,
           tool_choice: { type: "tool" as const, name: "select_memories" },
           thinking: { type: "disabled" },
           temperature: 0,
@@ -180,7 +196,7 @@ async function dedupForTurn(
   query: string,
 ): Promise<{ nodes: ScoredNode[]; llmApplied: boolean }> {
   try {
-    const provider = await getConfiguredProvider();
+    const provider = await getConfiguredProvider("memoryRetrieval");
     if (!provider)
       return { nodes: candidates.slice(0, maxNodes), llmApplied: false };
 
@@ -202,7 +218,7 @@ async function dedupForTurn(
       `Dedupe + rerank the following numbered items. Pick the most relevant items to the query. Call the select_items tool.\n\nBe aggressive on dedup — when multiple items describe the same event, fact, or status, keep ONLY the richest version. But be generous on relevance — only cut items that are completely irrelevant to the query. If it's even tangentially related, keep it.`,
       {
         config: {
-          modelIntent: "latency-optimized" as const,
+          callSite: "memoryRetrieval" as const,
           tool_choice: { type: "tool" as const, name: "select_items" },
           thinking: { type: "disabled" },
           temperature: 0,
@@ -273,7 +289,7 @@ async function dedupCrossCategory(
   maxNodes: number,
 ): Promise<ScoredNode[]> {
   try {
-    const provider = await getConfiguredProvider();
+    const provider = await getConfiguredProvider("memoryRetrieval");
     if (!provider) return candidates.slice(0, maxNodes);
 
     const now = Date.now();
@@ -294,7 +310,7 @@ async function dedupCrossCategory(
       `Deduplicate the following numbered items. When multiple items describe the same event, fact, or status, keep ONLY the richest version. Keep ALL items that are not duplicates — do not filter by relevance or topic. Call the select_items tool with every item that survives dedup.`,
       {
         config: {
-          modelIntent: "latency-optimized" as const,
+          callSite: "memoryRetrieval" as const,
           tool_choice: { type: "tool" as const, name: "select_items" },
           thinking: { type: "disabled" },
           temperature: 0,
@@ -347,6 +363,13 @@ export interface ContextLoadOpts {
   serendipitySlots?: number;
   /** Maximum nodes to return (default 40). */
   maxNodes?: number;
+  /**
+   * Optional dedicated user-message query text. When present and non-empty,
+   * `loadContextMemory` embeds this text independently of
+   * `recentSummaries` and uses the resulting vector to rank capability
+   * reserve slots. Leave `undefined` to use summary-only retrieval.
+   */
+  userQuery?: string;
 }
 
 export interface ContextLoadResult {
@@ -355,6 +378,37 @@ export interface ContextLoadResult {
   triggeredNodes: TriggeredResult[];
   latencyMs: number;
   metrics: RetrievalMetrics;
+  /**
+   * Dense query vector computed from `recentSummaries`. Surfaced so downstream
+   * callers (e.g. the PKB hint retriever) can reuse the same embedding for a
+   * second Qdrant query without paying for another embedding call. `undefined`
+   * when no summaries were provided or embedding failed (circuit breaker).
+   */
+  queryVector?: number[];
+  /**
+   * Optional sparse vector passed into `searchGraphNodes` alongside the dense
+   * query vector. Currently always `undefined` — reserved for future hybrid
+   * retrieval that produces a sparse vector at the call site.
+   */
+  sparseVector?: QdrantSparseVector;
+  /**
+   * Dense query vector computed from `opts.userQuery`. Surfaced so
+   * downstream callers (PKB hint search) can prefer it over the
+   * summary-based `queryVector` for user-intent-aligned retrieval.
+   * `undefined` when `userQuery` was not provided, was effectively empty,
+   * or the dedicated embed call was skipped/failed.
+   */
+  userQueryVector?: number[];
+  /**
+   * Sparse (TF-IDF) vector of `opts.userQuery`. Surfaced so PKB hint search
+   * can pair it with `userQueryVector` to run a hybrid dense+sparse query —
+   * RRF fusion captures lexical matches (exact filenames, proper nouns,
+   * uncommon tokens) that pure dense embeddings wash out. Computed locally
+   * (no embedding-service call), so it's cheap to produce whenever the user
+   * query is non-empty. `undefined` on the same conditions as
+   * `userQueryVector`.
+   */
+  userQuerySparseVector?: QdrantSparseVector;
 }
 
 /**
@@ -380,6 +434,7 @@ export async function loadContextMemory(
 
   // 1. Embed recent conversation summaries as retrieval queries
   let queryVector: number[] | null = null;
+  const sparseVector: QdrantSparseVector | undefined = undefined;
   let embeddingProvider: string | null = null;
   let embeddingModel: string | null = null;
   let contextQueryText: string | null = null;
@@ -400,15 +455,51 @@ export async function loadContextMemory(
     }
   }
 
+  // 1b. Dedicated user-query embedding. Always embed the user query
+  //     independently when present. Summaries and the user query are
+  //     disjoint signals, so both vectors carry unique retrieval value —
+  //     especially in workloads with short summaries and a substantive
+  //     user question.
+  let userQueryVector: number[] | null = null;
+  let userQuerySparseVector: QdrantSparseVector | undefined = undefined;
+  const userQueryCandidateIds = new Map<string, number>(); // nodeId → score
+  const trimmedUserQuery = opts.userQuery?.trim() ?? "";
+  const shouldEmbedUserQuery = trimmedUserQuery.length > 0;
+  if (shouldEmbedUserQuery) {
+    try {
+      const result = await embedWithRetry(opts.config, [trimmedUserQuery], {
+        signal: opts.signal,
+      });
+      userQueryVector = result.vectors[0] ?? null;
+      if (!embeddingProvider) {
+        embeddingProvider = result.provider;
+        embeddingModel = result.model;
+      }
+    } catch (err) {
+      log.warn({ err }, "Failed to embed userQuery for context load");
+    }
+    // Sparse embedding is a local TF-IDF computation — no network call, so
+    // compute it independently of the dense embed. Even if the dense call
+    // failed, a sparse vector is still useful for downstream consumers that
+    // can operate on it alone.
+    const sparse = generateSparseEmbedding(trimmedUserQuery);
+    if (sparse.indices.length > 0) {
+      userQuerySparseVector = sparse;
+    }
+  }
+
   // 2. Hybrid retrieval from Qdrant (dense search on graph_node points)
   const semanticCandidateIds = new Map<string, number>(); // nodeId → score
   let hybridSearchLatencyMs = 0;
   if (queryVector) {
     const searchStart = Date.now();
     try {
-      const results = await searchGraphNodes(queryVector, maxNodes * 3, [
-        opts.scopeId,
-      ]);
+      const results = await searchGraphNodes(
+        queryVector,
+        maxNodes * 3,
+        [opts.scopeId],
+        sparseVector,
+      );
       for (const r of results) {
         semanticCandidateIds.set(r.nodeId, r.score);
       }
@@ -420,6 +511,30 @@ export async function loadContextMemory(
   }
   const pureSemanticHits = semanticCandidateIds.size;
 
+  // 2b. Run a parallel Qdrant search against the user-query vector and merge
+  //     the results into the organic scoring pool via max-score union: a node
+  //     hit by only the user-query vector still participates in downstream
+  //     scoring, and a node hit by both vectors retains the higher score.
+  if (userQueryVector) {
+    try {
+      const results = await searchGraphNodes(
+        userQueryVector,
+        maxNodes * 3,
+        [opts.scopeId],
+        undefined,
+      );
+      for (const r of results) {
+        userQueryCandidateIds.set(r.nodeId, r.score);
+        const existing = semanticCandidateIds.get(r.nodeId);
+        if (existing === undefined || r.score > existing) {
+          semanticCandidateIds.set(r.nodeId, r.score);
+        }
+      }
+    } catch (err) {
+      log.warn({ err }, "Qdrant search failed for userQuery vector");
+    }
+  }
+
   // Also include top-significance nodes as a fallback
   const topSignificance = queryNodes({
     scopeId: opts.scopeId,
@@ -428,7 +543,7 @@ export async function loadContextMemory(
   });
   for (const node of topSignificance) {
     if (!semanticCandidateIds.has(node.id)) {
-      semanticCandidateIds.set(node.id, 0); // no semantic score, ranked by significance
+      semanticCandidateIds.set(node.id, 0); // no score from either Qdrant query, ranked by significance only
     }
   }
 
@@ -550,47 +665,69 @@ export async function loadContextMemory(
   // Sort by score descending
   scored.sort((a, b) => b.score - a.score);
 
-  // 5b. Reserve slots for skill/CLI capabilities. Queried directly from
-  // SQLite — no Qdrant vectors needed — so capabilities surface even on
-  // fresh assistants whose embedding jobs haven't completed yet.
+  // 5b. Reserve slots for skill/CLI capabilities.
+  //
+  // Source candidates from the hydrated semantic-search set (the same
+  // strategy `retrieveForTurn` uses) so ranking reflects query relevance.
+  // For cold-start cases (capability nodes exist in SQLite but their
+  // embeddings haven't landed in Qdrant yet), fall back to a narrow
+  // SQL pull that matches only capability-shaped content so organic
+  // procedurals can't crowd the pool.
   const capabilityReserve = ctxLoadCfg.capabilityReserve;
-  const rawCapabilityNodes =
-    capabilityReserve > 0
-      ? queryNodes({
-          scopeId: opts.scopeId,
-          types: ["procedural"],
-          fidelityNot: ["gone"],
-          limit: capabilityReserve * 4,
-        })
-      : [];
+  const capabilityEntries: { node: MemoryNode; sim: number }[] = [];
+  if (capabilityReserve > 0) {
+    const uniqueCapabilityIds = new Set<string>();
+    let untaggedCount = 0;
+    for (const [nodeId, node] of nodeMap) {
+      if (node.fidelity === "gone") continue;
+      if (!isCapabilityNode(node)) continue;
+      const sim =
+        userQueryCandidateIds.get(nodeId) ??
+        semanticCandidateIds.get(nodeId) ??
+        0;
+      capabilityEntries.push({ node, sim });
+      const capId = extractCapabilityId(node);
+      if (capId) uniqueCapabilityIds.add(capId);
+      else untaggedCount++;
+    }
+
+    // Gate the fallback on distinct capability IDs (plus any entries
+    // whose content didn't match a known ID pattern), not raw entry
+    // count — duplicate capability-ID seeding formats can otherwise push
+    // `capabilityEntries.length` past the threshold and then collapse
+    // below it during the dedup pass below.
+    const distinctCount = uniqueCapabilityIds.size + untaggedCount;
+    if (distinctCount < capabilityReserve) {
+      const alreadySeen = new Set(capabilityEntries.map((e) => e.node.id));
+      const fallback = queryCapabilityNodes(
+        opts.scopeId,
+        capabilityReserve * 4,
+      );
+      for (const node of fallback) {
+        if (alreadySeen.has(node.id)) continue;
+        const sim =
+          userQueryCandidateIds.get(node.id) ??
+          semanticCandidateIds.get(node.id) ??
+          0;
+        capabilityEntries.push({ node, sim });
+      }
+    }
+  }
+
+  capabilityEntries.sort((a, b) => b.sim - a.sim);
 
   // Dedup: both seeding systems may create nodes for the same capability.
   // Extract capability ID from content and keep only the first node per ID.
   const seenCapabilityIds = new Set<string>();
-  const capabilityNodes = rawCapabilityNodes
-    .filter(isCapabilityNode)
-    .filter((node) => {
-      const match = node.content.match(
-        /^skill:(\S+)\n|^cli:(\S+)\n|^\s*The ".*?" skill \(([^)]+)\)|^\s*The "assistant (\S+)" CLI command/,
-      );
-      const capId = match?.[1] ?? match?.[2] ?? match?.[3] ?? match?.[4];
-      if (capId) {
-        if (seenCapabilityIds.has(capId)) return false;
-        seenCapabilityIds.add(capId);
-      }
-      return true;
-    });
-
-  // Rank by semantic similarity when a query vector exists
-  let selectedCapabilities: MemoryNode[];
-  if (queryVector && capabilityNodes.length > capabilityReserve) {
-    selectedCapabilities = capabilityNodes
-      .map((node) => ({ node, sim: semanticCandidateIds.get(node.id) ?? 0 }))
-      .sort((a, b) => b.sim - a.sim)
-      .slice(0, capabilityReserve)
-      .map((e) => e.node);
-  } else {
-    selectedCapabilities = capabilityNodes.slice(0, capabilityReserve);
+  const selectedCapabilities: MemoryNode[] = [];
+  for (const { node } of capabilityEntries) {
+    if (selectedCapabilities.length >= capabilityReserve) break;
+    const capId = extractCapabilityId(node);
+    if (capId) {
+      if (seenCapabilityIds.has(capId)) continue;
+      seenCapabilityIds.add(capId);
+    }
+    selectedCapabilities.push(node);
   }
 
   const reservedCapabilities: ScoredNode[] = selectedCapabilities.map(
@@ -697,6 +834,10 @@ export async function loadContextMemory(
       queryContext: contextQueryText,
       topCandidates,
     },
+    queryVector: queryVector ?? undefined,
+    sparseVector,
+    userQueryVector: userQueryVector ?? undefined,
+    userQuerySparseVector,
   };
 }
 
@@ -726,6 +867,28 @@ export interface TurnRetrievalResult {
   triggeredNodes: TriggeredResult[];
   latencyMs: number;
   metrics: RetrievalMetrics;
+  /**
+   * Dense query vector computed from the last-exchange text (assistant +
+   * user message). Surfaced so downstream callers (e.g. the PKB hint
+   * retriever in `applyRuntimeInjections`) can reuse the same embedding
+   * for a second Qdrant query without paying for another embedding call.
+   * `undefined` when no text was embedded (image-only turn) or embedding
+   * failed (circuit breaker).
+   */
+  queryVector?: number[];
+  /**
+   * Sparse (TF-IDF) vector of the user's last message, computed once per
+   * turn and reused across every return path of `retrieveForTurn`. Surfaced
+   * so downstream callers (e.g. the PKB hint retriever in
+   * `applyRuntimeInjections`) can pair it with `queryVector` to run a
+   * hybrid dense+sparse query — RRF fusion pulls in lexical matches
+   * (exact filenames, proper nouns, uncommon tokens) that pure dense
+   * embeddings wash out. Computed locally (no embedding-service call), so
+   * it survives even when the dense embed fails via the circuit breaker.
+   * `undefined` when the user's last message is empty/whitespace-only or
+   * yields no TF-IDF tokens.
+   */
+  sparseVector?: QdrantSparseVector;
 }
 
 /**
@@ -766,6 +929,24 @@ export async function retrieveForTurn(
     .filter((m) => m.length > 0)
     .join("\n\n");
 
+  // Sparse (TF-IDF) vector of the user's last message only. Surfaced so PKB
+  // hint search can pair it with the per-turn dense vector, pulling in
+  // lexical matches (exact filenames, proper nouns, uncommon tokens) that
+  // pure dense embeddings wash out. Computed locally with no network call.
+  // The dense `queryVector` for per-turn is the combined assistant+user
+  // embedding (it drives graph search), so this pairing is slightly
+  // asymmetric — the sparse signal is user-only while the dense is mixed.
+  // That's acceptable for PKB's purpose: lexical matches are overwhelmingly
+  // driven by the user's own wording.
+  const trimmedUserLast = opts.userLastMessage.trim();
+  let perTurnSparseVector: QdrantSparseVector | undefined = undefined;
+  if (trimmedUserLast.length > 0) {
+    const sparse = generateSparseEmbedding(trimmedUserLast);
+    if (sparse.indices.length > 0) {
+      perTurnSparseVector = sparse;
+    }
+  }
+
   // Image-to-image search: embed incoming user images as queries
   // Runs before the text-empty early return so image-only turns are handled
   const imageBlocks = (opts.userLastMessageBlocks ?? []).filter(
@@ -828,6 +1009,8 @@ export async function retrieveForTurn(
         embeddingModel,
         queryContext: queryText || null,
       },
+      queryVector: undefined,
+      sparseVector: perTurnSparseVector,
     };
   }
 
@@ -900,6 +1083,8 @@ export async function retrieveForTurn(
             embeddingModel,
             queryContext: queryText || null,
           },
+          queryVector: undefined,
+          sparseVector: perTurnSparseVector,
         };
       }
     }
@@ -952,6 +1137,8 @@ export async function retrieveForTurn(
         embeddingModel,
         queryContext: queryText || null,
       },
+      queryVector: queryEmbeddings[0],
+      sparseVector: perTurnSparseVector,
     };
   }
 
@@ -1134,5 +1321,7 @@ export async function retrieveForTurn(
       queryContext: queryText || null,
       topCandidates,
     },
+    queryVector: queryEmbeddings[0],
+    sparseVector: perTurnSparseVector,
   };
 }

package/src/memory/graph/store.ts

@@ -358,6 +358,47 @@ export function queryNodes(filters: NodeQueryFilters): MemoryNode[] {
   return query.all().map(rowToNode);
 }
 
+/**
+ * Pull capability (skill / CLI) nodes directly from SQLite, ordered by
+ * significance DESC. Matches the content shapes produced by both the
+ * legacy (`skill:{id}\n`, `cli:{name}\n`) and current
+ * (`The "..." skill (id) is available.`, `The "assistant ..." CLI command`)
+ * seeding systems — keeping the SQL filter in sync with `isCapabilityNode`.
+ *
+ * Used as a cold-start fallback for context-load capability injection when
+ * no semantic-search candidates are capability nodes (e.g. fresh assistants
+ * whose embedding jobs haven't completed yet). The content-pattern filter
+ * prevents organic procedural memories from crowding out real capabilities.
+ */
+export function queryCapabilityNodes(
+  scopeId: string,
+  limit: number,
+): MemoryNode[] {
+  const db = getDb();
+  const rows = db
+    .select()
+    .from(memoryGraphNodes)
+    .where(
+      and(
+        eq(memoryGraphNodes.scopeId, scopeId),
+        eq(memoryGraphNodes.type, "procedural"),
+        sql`${memoryGraphNodes.fidelity} != 'gone'`,
+        or(
+          sql`${memoryGraphNodes.content} LIKE 'skill:%'`,
+          sql`${memoryGraphNodes.content} LIKE 'cli:%'`,
+          and(
+            sql`${memoryGraphNodes.content} LIKE 'The "%'`,
+            sql`${memoryGraphNodes.content} LIKE '% is available.%'`,
+          ),
+        ),
+      ),
+    )
+    .orderBy(sql`${memoryGraphNodes.significance} DESC`)
+    .limit(limit)
+    .all();
+  return rows.map(rowToNode);
+}
+
 /** Count all non-gone nodes in a scope. */
 export function countNodes(scopeId: string): number {
   const db = getDb();

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

@@ -14,6 +14,8 @@ 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 { enqueuePkbIndexJob } from "../jobs/embed-pkb-file.js";
+import { PKB_WORKSPACE_SCOPE } from "../pkb/types.js";
 import { searchGraphNodes } from "./graph-search.js";
 import { getNodesByIds } from "./store.js";
 
@@ -249,6 +251,7 @@ async function handleArchiveRecall(
 
 export interface RememberInput {
   content: string;
+  finish_turn?: boolean;
 }
 
 export interface RememberResult {
@@ -286,6 +289,7 @@ export function handleRemember(
   // Append to buffer.md
   const bufferPath = join(pkbDir, "buffer.md");
   appendFileSync(bufferPath, entry, "utf-8");
+  enqueuePkbReindex(pkbDir, bufferPath);
 
   // Append to daily archive
   const yyyy = now.getFullYear();
@@ -296,6 +300,29 @@ export function handleRemember(
     appendFileSync(archivePath, `# ${month} ${day}, ${yyyy}\n\n`, "utf-8");
   }
   appendFileSync(archivePath, entry, "utf-8");
+  enqueuePkbReindex(pkbDir, archivePath);
 
   return { success: true, message: "Saved to knowledge base." };
 }
+
+/**
+ * Fire-and-forget enqueue of a PKB re-index job for a file we just wrote.
+ *
+ * Always indexes under {@link PKB_WORKSPACE_SCOPE}. See the comment on that
+ * constant for why PKB points are not per-conversation-scoped.
+ *
+ * Wrapped in try/catch so an enqueue failure (e.g. DB hiccup) cannot break
+ * the remember call — the write has already succeeded and the user's fact
+ * is safe on disk.
+ */
+function enqueuePkbReindex(pkbRoot: string, absPath: string): void {
+  try {
+    enqueuePkbIndexJob({
+      pkbRoot,
+      absPath,
+      memoryScopeId: PKB_WORKSPACE_SCOPE,
+    });
+  } catch (err) {
+    log.warn({ err, absPath }, "Failed to enqueue PKB re-index job");
+  }
+}

package/src/memory/graph/tools.ts

@@ -82,7 +82,7 @@ export const graphRecallDefinition: ToolDefinition = {
 export const graphRememberDefinition: ToolDefinition = {
   name: "remember",
   description:
-    "Save a fact to your knowledge base. Call this AGGRESSIVELY — capture anything concrete about their life: preferences, locations, names, dates, habits, opinions, health details, plans, relationship facts, routines, commitments. Default to remembering; only skip obvious noise (small talk, hypotheticals, things they're just musing about). Don't judge importance — filing decides that later. 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. CORRECTIONS are the highest priority — when the user corrects a fact you had wrong, `remember` the correction immediately. The wrong version is already propagated in your prior turns and memory graph; skipping a correction means future-you keeps operating on the old value. Never skip a correction even if you'd skip the equivalent fresh fact.",
+    "Save a fact to your knowledge base. Call this AGGRESSIVELY — capture anything concrete about their life: preferences, locations, names, dates, habits, opinions, health details, plans, relationship facts, routines, commitments. Default to remembering; only skip obvious noise (small talk, hypotheticals, things they're just musing about). Don't judge importance — filing decides that later. Examples: 'Prefers UberEats over DoorDash', 'Lives in NYC, from Texas', 'Takes daily medication, tapering dose', 'Partner Alex lives in Austin', 'Watches a weekly show on Saturday nights', 'Conference in May'. 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. CORRECTIONS are the highest priority — when the user corrects a fact you had wrong, `remember` the correction immediately. The wrong version is already propagated in your prior turns and memory graph; skipping a correction means future-you keeps operating on the old value. Never skip a correction even if you'd skip the equivalent fresh fact.",
   input_schema: {
     type: "object",
     properties: {
@@ -91,6 +91,11 @@ export const graphRememberDefinition: ToolDefinition = {
         description:
           "The fact to remember. Write naturally — a preference, a detail, a commitment, a plan. No need to categorize.",
       },
+      finish_turn: {
+        type: "boolean",
+        description:
+          "Set to true ONLY on the final `remember` call when you have nothing else to say and want to hand control back to the user. When true, the assistant turn ends after this tool call and no further LLM call is made. Do NOT set true on intermediate `remember` calls. Default: false.",
+      },
     },
     required: ["content"],
   },

package/src/memory/indexer.ts

@@ -203,11 +203,11 @@ export async function indexMessageNow(
       );
 
       // ── Auto-analysis triggers ─────────────────────────────────────
-      // Both triggers route through `upsertDebouncedJob` in the helper,
-      // so a single pending row is shared. Order matters: the idle
-      // upsert runs first (pushing `runAfter` into the future); the
-      // batch trigger runs last so a threshold crossing pulls
-      // `runAfter` back to "now" and overrides the idle debounce.
+      // Immediate triggers (batch, compaction) and debounced triggers
+      // (idle, lifecycle) write to separate rows keyed by triggerGroup
+      // via `upsertAutoAnalysisJob`. When an immediate trigger fires,
+      // it cancels any pending debounced row for the same conversation
+      // to avoid redundant analysis runs.
       enqueueAutoAnalysisIfEnabled({
         conversationId: input.conversationId,
         trigger: "idle",