@vellumai/assistant 0.8.0 → 0.8.2

package/src/memory/external-conversation-store.ts

@@ -7,7 +7,7 @@
  * list APIs.
  */
 
-import { and, eq, inArray } from "drizzle-orm";
+import { and, eq, inArray, isNull } from "drizzle-orm";
 
 import { getDb } from "./db-connection.js";
 import { externalConversationBindings } from "./schema.js";
@@ -16,6 +16,7 @@ export interface ExternalConversationBinding {
   conversationId: string;
   sourceChannel: string;
   externalChatId: string;
+  externalThreadId?: string | null;
   externalUserId?: string | null;
   displayName?: string | null;
   username?: string | null;
@@ -29,11 +30,19 @@ export interface UpsertBindingInput {
   conversationId: string;
   sourceChannel: string;
   externalChatId: string;
+  externalThreadId?: string | null;
   externalUserId?: string | null;
   displayName?: string | null;
   username?: string | null;
 }
 
+function normalizeExternalThreadId(
+  externalThreadId?: string | null,
+): string | null {
+  const trimmed = externalThreadId?.trim();
+  return trimmed ? trimmed : null;
+}
+
 /**
  * Insert or update an external conversation binding on conflict (conversationId).
  * On conflict, updates channel metadata and timestamps.
@@ -41,12 +50,14 @@ export interface UpsertBindingInput {
 export function upsertBinding(input: UpsertBindingInput): void {
   const db = getDb();
   const now = Date.now();
+  const externalThreadId = normalizeExternalThreadId(input.externalThreadId);
 
-  // If a stale binding exists for this (sourceChannel, externalChatId) under a
+  // If a stale binding exists for this channel/chat/thread tuple under a
   // different conversationId, remove it first so the unique index is not violated.
-  const existing = getBindingByChannelChat(
+  const existing = getBindingByChannelChatThread(
     input.sourceChannel,
     input.externalChatId,
+    externalThreadId,
   );
   if (existing && existing.conversationId !== input.conversationId) {
     db.delete(externalConversationBindings)
@@ -64,6 +75,7 @@ export function upsertBinding(input: UpsertBindingInput): void {
       conversationId: input.conversationId,
       sourceChannel: input.sourceChannel,
       externalChatId: input.externalChatId,
+      externalThreadId,
       externalUserId: input.externalUserId ?? null,
       displayName: input.displayName ?? null,
       username: input.username ?? null,
@@ -76,6 +88,7 @@ export function upsertBinding(input: UpsertBindingInput): void {
       set: {
         sourceChannel: input.sourceChannel,
         externalChatId: input.externalChatId,
+        externalThreadId,
         externalUserId: input.externalUserId ?? null,
         displayName: input.displayName ?? null,
         username: input.username ?? null,
@@ -95,15 +108,18 @@ export function upsertOutboundBinding(input: {
   conversationId: string;
   sourceChannel: string;
   externalChatId: string;
+  externalThreadId?: string | null;
 }): void {
   const db = getDb();
   const now = Date.now();
+  const externalThreadId = normalizeExternalThreadId(input.externalThreadId);
 
-  // If a stale binding exists for this (sourceChannel, externalChatId) under a
+  // If a stale binding exists for this channel/chat/thread tuple under a
   // different conversationId, remove it first so the unique index is not violated.
-  const existing = getBindingByChannelChat(
+  const existing = getBindingByChannelChatThread(
     input.sourceChannel,
     input.externalChatId,
+    externalThreadId,
   );
   if (existing && existing.conversationId !== input.conversationId) {
     db.delete(externalConversationBindings)
@@ -121,6 +137,7 @@ export function upsertOutboundBinding(input: {
       conversationId: input.conversationId,
       sourceChannel: input.sourceChannel,
       externalChatId: input.externalChatId,
+      externalThreadId,
       externalUserId: null,
       displayName: null,
       username: null,
@@ -133,6 +150,7 @@ export function upsertOutboundBinding(input: {
       set: {
         sourceChannel: input.sourceChannel,
         externalChatId: input.externalChatId,
+        externalThreadId,
         updatedAt: now,
         lastOutboundAt: now,
       },
@@ -161,8 +179,20 @@ export function getBindingByConversation(
 export function getBindingByChannelChat(
   sourceChannel: string,
   externalChatId: string,
+): ExternalConversationBinding | null {
+  return getBindingByChannelChatThread(sourceChannel, externalChatId, null);
+}
+
+/**
+ * Look up an external binding by channel + external chat ID + optional thread ID.
+ */
+export function getBindingByChannelChatThread(
+  sourceChannel: string,
+  externalChatId: string,
+  externalThreadId?: string | null,
 ): ExternalConversationBinding | null {
   const db = getDb();
+  const normalizedThreadId = normalizeExternalThreadId(externalThreadId);
   const row = db
     .select()
     .from(externalConversationBindings)
@@ -170,6 +200,12 @@ export function getBindingByChannelChat(
       and(
         eq(externalConversationBindings.sourceChannel, sourceChannel),
         eq(externalConversationBindings.externalChatId, externalChatId),
+        normalizedThreadId
+          ? eq(
+              externalConversationBindings.externalThreadId,
+              normalizedThreadId,
+            )
+          : isNull(externalConversationBindings.externalThreadId),
       ),
     )
     .get();
@@ -195,6 +231,31 @@ export function deleteBindingByChannelChat(
     .run();
 }
 
+/**
+ * Remove an external binding by channel + external chat ID + thread ID.
+ */
+export function deleteBindingByChannelChatThread(
+  sourceChannel: string,
+  externalChatId: string,
+  externalThreadId: string,
+): void {
+  const db = getDb();
+  const normalizedThreadId = normalizeExternalThreadId(externalThreadId);
+  if (!normalizedThreadId) {
+    deleteBindingByChannelChat(sourceChannel, externalChatId);
+    return;
+  }
+  db.delete(externalConversationBindings)
+    .where(
+      and(
+        eq(externalConversationBindings.sourceChannel, sourceChannel),
+        eq(externalConversationBindings.externalChatId, externalChatId),
+        eq(externalConversationBindings.externalThreadId, normalizedThreadId),
+      ),
+    )
+    .run();
+}
+
 /**
  * Get bindings for multiple conversation IDs at once.
  * Returns a map of conversationId -> binding for efficient lookup.

package/src/memory/graph/__tests__/conversation-graph-memory-v2-routing.test.ts

@@ -107,18 +107,20 @@ mock.module("@qdrant/js-client-rest", () => ({
   QdrantClient: MockQdrantClient,
 }));
 
+const embedWithBackendMock = mock(async (_config, texts: string[]) => ({
+  provider: "local",
+  model: "test-model",
+  vectors: texts.map(() => [0.1, 0.2, 0.3]) as number[][],
+}));
+const generateSparseEmbeddingMock = mock((_text: string) => ({
+  indices: [1, 2, 3],
+  values: [0.5, 0.5, 0.5] as number[],
+}));
 const realEmbeddingBackend = await import("../../embedding-backend.js");
 mock.module("../../embedding-backend.js", () => ({
   ...realEmbeddingBackend,
-  embedWithBackend: async () => ({
-    provider: "local",
-    model: "test-model",
-    vectors: [[0.1, 0.2, 0.3]] as number[][],
-  }),
-  generateSparseEmbedding: () => ({
-    indices: [1, 2, 3],
-    values: [0.5, 0.5, 0.5] as number[],
-  }),
+  embedWithBackend: embedWithBackendMock,
+  generateSparseEmbedding: generateSparseEmbeddingMock,
 }));
 
 const realQdrantClient = await import("../../qdrant-client.js");
@@ -293,6 +295,8 @@ beforeEach(() => {
   qdrantState.queryResponses.sparse.length = 0;
   loadContextMemoryMock.mockClear();
   retrieveForTurnMock.mockClear();
+  embedWithBackendMock.mockClear();
+  generateSparseEmbeddingMock.mockClear();
   _resetMemoryV2QdrantForTests();
 });
 
@@ -390,6 +394,59 @@ describe("ConversationGraphMemory.prepareMemory — v2 routing (per-turn path)",
     expect(firstBlock.text).toContain("# memory/concepts/alice-vscode.md");
   });
 
+  test("per-turn dense embedding is computed from combined assistant+user text", async () => {
+    // Short referential follow-ups ("do that one") carry no semantic signal
+    // on their own — the dense PKB query embedding must mirror v1's
+    // `retrieveForTurn` and combine the prior assistant turn so hint search
+    // still resolves what "that one" refers to. The sparse vector matches
+    // v1 by using the user message alone so lexical signal isn't diluted.
+    stageTurn([{ slug: "alice-vscode", denseScore: 0.9 }]);
+
+    const memory = makeMemory();
+    const config = makeConfig(true);
+    const assistantText =
+      "Alice prefers VS Code as her editor — she finds the extension ecosystem unmatched.";
+    const userText = "do that one";
+    const messages: Message[] = [
+      {
+        role: "user",
+        content: [
+          { type: "text" as const, text: "what editors did we cover?" },
+        ],
+      },
+      {
+        role: "assistant",
+        content: [{ type: "text" as const, text: assistantText }],
+      },
+      { role: "user", content: [{ type: "text" as const, text: userText }] },
+    ];
+
+    await memory.prepareMemory(
+      messages,
+      config,
+      new AbortController().signal,
+      noopEvent,
+    );
+
+    // v1's `retrieveForTurn` joins assistantLast + userLast with "\n\n" and
+    // embeds the combined string as the dense query vector. Assert the v2
+    // path makes the exact same embed call somewhere during this turn.
+    const expectedCombined = `${assistantText}\n\n${userText}`;
+    const matchingCall = embedWithBackendMock.mock.calls.find((call) => {
+      const texts = call[1] as string[];
+      return texts.length === 1 && texts[0] === expectedCombined;
+    });
+    expect(matchingCall).toBeDefined();
+
+    // Sparse embedding for the per-turn query uses userLast only.
+    expect(generateSparseEmbeddingMock.mock.calls).toContainEqual([userText]);
+    expect(
+      generateSparseEmbeddingMock.mock.calls.some((call) =>
+        (call[0] as string).includes(assistantText),
+      ),
+    ).toBe(false);
+  });
+
   test("config on with empty Qdrant hits → no v2 block, v1 fallback skipped", async () => {
     // No `stageTurn` call — every channel returns `{ points: [] }` so the
     // candidate set is empty and `injectMemoryV2Block` returns block=null.

package/src/memory/graph/__tests__/remember-description.test.ts

@@ -0,0 +1,55 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+let flagEnabled = false;
+
+mock.module("../../../config/assistant-feature-flags.js", () => ({
+  isAssistantFeatureFlagEnabled: (_key: string, _config: unknown) =>
+    flagEnabled,
+}));
+
+import { getRememberDescription } from "../tools.js";
+
+const stubConfig = {} as unknown as Parameters<
+  typeof getRememberDescription
+>[0];
+
+describe("getRememberDescription", () => {
+  beforeEach(() => {
+    flagEnabled = false;
+  });
+
+  test("flag off — returns the default high-pressure description", () => {
+    const desc = getRememberDescription(stubConfig);
+    expect(desc).toContain("**CRITICAL:**");
+    expect(desc).toContain("most frequently used tool");
+    expect(desc).toContain("almost every turn");
+  });
+
+  test("flag on — returns the relaxed judgment-framing description", () => {
+    flagEnabled = true;
+    const desc = getRememberDescription(stubConfig);
+    expect(desc).not.toContain("**CRITICAL:**");
+    expect(desc).not.toContain("almost every turn");
+    expect(desc).toContain("a retrospective pass");
+    expect(desc).toContain("Use judgment");
+  });
+
+  test("the two variants differ", () => {
+    flagEnabled = false;
+    const off = getRememberDescription(stubConfig);
+    flagEnabled = true;
+    const on = getRememberDescription(stubConfig);
+    expect(off).not.toBe(on);
+  });
+
+  test("corrections-are-priority language is preserved in BOTH variants", () => {
+    flagEnabled = false;
+    expect(getRememberDescription(stubConfig)).toMatch(
+      /Corrections are.*highest priority/i,
+    );
+    flagEnabled = true;
+    expect(getRememberDescription(stubConfig)).toMatch(
+      /Corrections are.*highest priority/i,
+    );
+  });
+});

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

@@ -7,6 +7,7 @@
 // ---------------------------------------------------------------------------
 
 import { and, desc, eq, inArray, ne, notInArray } from "drizzle-orm";
+import { z } from "zod";
 
 import type { AssistantConfig } from "../../config/types.js";
 import { estimateTextTokens } from "../../context/token-estimator.js";
@@ -19,6 +20,8 @@ import type {
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir } from "../../util/platform.js";
 import { getDb } from "../db-connection.js";
+import { embedWithRetry } from "../embed.js";
+import { generateSparseEmbedding } from "../embedding-backend.js";
 import type { QdrantSparseVector } from "../qdrant-client.js";
 import { memorySummaries } from "../schema.js";
 import { conversations } from "../schema/conversations.js";
@@ -388,8 +391,15 @@ export class ConversationGraphMemory {
 
       return await this.runPerTurn(messages, config, abortSignal);
     } catch (err) {
+      const errCode =
+        err instanceof z.ZodError ? err.issues[0]?.code : undefined;
       log.warn(
-        { err: err instanceof Error ? err.message : String(err) },
+        {
+          err: err instanceof Error ? err.message : String(err),
+          conversationId: this.conversationId,
+          turn: this.tracker.getTurn(),
+          errCode,
+        },
         "Memory retrieval failed (non-fatal)",
       );
       return noopResult;
@@ -422,10 +432,21 @@ export class ConversationGraphMemory {
       "",
       signal,
     );
-    this.initialized = true;
-    this.needsReload = false;
 
     if (v2.routed) {
+      // Surface a user-query embedding so PKB hint search still runs on v2
+      // turns. v1's `loadContextMemory` produced these as a side effect of
+      // hybrid retrieval; the v2 path skips that retrieval, so embed
+      // explicitly here.
+      const userQueryText = rawUserText ?? userQuery ?? "";
+      const userQueryEmbed = await this.computeQueryVectors(
+        userQueryText,
+        userQueryText,
+        config,
+        signal,
+      );
+      this.initialized = true;
+      this.needsReload = false;
       this.lastInjectedBlock = v2.injectedBlockText;
       this.lastInjectedNodeIds = [];
       this.lastInjectedImages = new Map();
@@ -438,6 +459,8 @@ export class ConversationGraphMemory {
         mode: "context-load" as const,
         injectedBlockText: v2.injectedBlockText,
         metrics: null,
+        userQueryVector: userQueryEmbed.dense,
+        userQuerySparseVector: userQueryEmbed.sparse,
       };
     }
 
@@ -449,6 +472,12 @@ export class ConversationGraphMemory {
       config,
       signal,
     });
+    // Set initialized only after v1 retrieval succeeds. If `loadContextMemory`
+    // throws (transient DB/Qdrant failure), `prepareMemory` catches and
+    // returns noop, but we want the next turn to retry the bootstrap path
+    // rather than be stuck in per-turn mode.
+    this.initialized = true;
+    this.needsReload = false;
 
     if (result.nodes.length === 0) {
       this.lastInjectedBlock = null;
@@ -569,6 +598,22 @@ export class ConversationGraphMemory {
       signal,
     );
     if (v2.routed) {
+      // Surface a per-turn query embedding so PKB hint search still runs
+      // on v2 turns. v1's `retrieveForTurn` produced these as a side effect;
+      // the v2 path skips that retrieval, so embed explicitly here. Match
+      // v1's split: dense embeds the combined assistant+user text (short
+      // referential follow-ups like "do that one" need the assistant turn
+      // for semantic grounding), while sparse uses the user message alone
+      // to keep lexical signal focused on what the user actually said.
+      const denseQueryText = [assistantLast, userLast]
+        .filter((m) => m.length > 0)
+        .join("\n\n");
+      const perTurnEmbed = await this.computeQueryVectors(
+        denseQueryText,
+        userLast,
+        config,
+        signal,
+      );
       this.lastInjectedBlock = v2.injectedBlockText;
       this.lastInjectedNodeIds = [];
       this.lastInjectedImages = new Map();
@@ -581,6 +626,8 @@ export class ConversationGraphMemory {
         mode: "per-turn" as const,
         injectedBlockText: v2.injectedBlockText,
         metrics: null,
+        queryVector: perTurnEmbed.dense,
+        sparseVector: perTurnEmbed.sparse,
       };
     }
 
@@ -652,6 +699,41 @@ export class ConversationGraphMemory {
     };
   }
 
+  /**
+   * Embed a query string for PKB hint search on v2 turns. v1 retrieval
+   * produced these vectors as a side effect; on v2 we skip retrieval, so
+   * the agent loop loses the dense/sparse pair it needs to drive
+   * `buildPkbReminderWithHints`. Failures here degrade PKB hints to the
+   * static fallback rather than blocking the turn.
+   */
+  private async computeQueryVectors(
+    denseText: string,
+    sparseText: string,
+    config: AssistantConfig,
+    signal: AbortSignal,
+  ): Promise<{ dense?: number[]; sparse?: QdrantSparseVector }> {
+    const trimmedDense = denseText.trim();
+    const trimmedSparse = sparseText.trim();
+    let dense: number[] | undefined;
+    if (trimmedDense.length > 0) {
+      try {
+        const result = await embedWithRetry(config, [trimmedDense], { signal });
+        dense = result.vectors[0];
+      } catch (err) {
+        log.warn(
+          { err: err instanceof Error ? err.message : String(err) },
+          "Failed to embed query for PKB hints on v2 path",
+        );
+      }
+    }
+    let sparse: QdrantSparseVector | undefined;
+    if (trimmedSparse.length > 0) {
+      const sparseRaw = generateSparseEmbedding(trimmedSparse);
+      sparse = sparseRaw.indices.length > 0 ? sparseRaw : undefined;
+    }
+    return { dense, sparse };
+  }
+
   /**
    * Run the v2 activation pipeline when the workspace config
    * (`memory.v2.enabled`) is on.
@@ -716,7 +798,11 @@ export class ConversationGraphMemory {
  * Count the leading content blocks on a user message that were added by
  * `injectMemoryBlock`. Memory-injected images use a 3-block pattern
  * (opening `<memory_image>` text + image + closing `</memory_image>` text),
- * followed by a `<memory>…</memory>` text block (legacy `<memory __injected>` is also accepted). A legacy
+ * followed by a `<memory>…</memory>` text block (legacy `<memory __injected>` is also accepted).
+ * The bare `<memory>` form is matched only when the block also ends with
+ * `\n</memory>`, so user-authored content that happens to begin with
+ * `<memory>` (for example, a message discussing the XML-like markup) is not
+ * mistaken for an injected prefix and stripped on re-injection. A legacy
  * 2-block image pattern (no closing tag) is also accepted for backward
  * compatibility. The injection prefix is always contiguous at the start,
  * so we stop at the first non-memory block.
@@ -729,7 +815,8 @@ export function countMemoryPrefixBlocks(content: ContentBlock[]): number {
     const block = content[firstNonMemory];
     if (
       block.type === "text" &&
-      (block.text.startsWith("<memory>\n") ||
+      ((block.text.startsWith("<memory>\n") &&
+        block.text.endsWith("\n</memory>")) ||
         block.text.startsWith("<memory __injected>\n"))
     ) {
       firstNonMemory++;

package/src/memory/graph/extraction.ts

@@ -723,8 +723,12 @@ export function parseExtractionResponse(
 
     // Auto-create event trigger when event_date is set but LLM didn't include one,
     // or replace a malformed event trigger (event_date unset) with a valid one.
+    // Only auto-create for future events — past-dated memories (historical
+    // milestones, dated events that already happened) shouldn't generate
+    // ramp/follow-up reminders.
     if (
       node.eventDate != null &&
+      node.eventDate > now &&
       (!Array.isArray(raw.triggers) ||
         !raw.triggers.some((t) => t.type === "event" && t.event_date != null))
     ) {

package/src/memory/graph/graph-memory-state-store.ts

@@ -24,9 +24,7 @@ export function saveGraphMemoryState(
 /**
  * Load graph memory state for a conversation, or null if none exists.
  */
-export function loadGraphMemoryState(
-  conversationId: string,
-): string | null {
+export function loadGraphMemoryState(conversationId: string): string | null {
   const db = getDb();
   const row = db
     .select({ stateJson: conversationGraphMemoryState.stateJson })
@@ -35,3 +33,18 @@ export function loadGraphMemoryState(
     .get();
   return row?.stateJson ?? null;
 }
+
+/**
+ * Copy the parent conversation's graph memory state row to a new conversation
+ * id so the forked conversation resumes with the parent's InContextTracker
+ * snapshot (in-context node IDs, per-node turn log, current turn). No-op if
+ * the parent has no row yet.
+ */
+export function forkGraphMemoryState(
+  parentConversationId: string,
+  newConversationId: string,
+): void {
+  const stateJson = loadGraphMemoryState(parentConversationId);
+  if (stateJson == null) return;
+  saveGraphMemoryState(newConversationId, stateJson);
+}

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

@@ -69,6 +69,22 @@ export function handleRemember(
   return { success: true, message: "Saved to knowledge base." };
 }
 
+/**
+ * Format `now` as a buffer-entry timestamp (`Mon D, h:mm AM/PM`). Exported so
+ * the memory v2 consolidation job can present its cutoff in the same shape
+ * the buffer entries use, making the agent's "timestamp ≥ cutoff" comparison
+ * unambiguous at minute precision.
+ */
+export function formatBufferTimestamp(now: Date): string {
+  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;
+  return `${month} ${day}, ${displayHour}:${minutes} ${ampm}`;
+}
+
 /**
  * Build a timestamped bullet entry for `buffer.md` / `archive/<date>.md`.
  *
@@ -80,13 +96,7 @@ export function handleRemember(
  * entries identically to user-facing `remember()` calls.
  */
 export function formatRememberEntry(content: string, now: Date): string {
-  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;
-  return `- [${month} ${day}, ${displayHour}:${minutes} ${ampm}] ${content}\n`;
+  return `- [${formatBufferTimestamp(now)}] ${content}\n`;
 }
 
 /**

package/src/memory/graph/tools.ts

@@ -2,6 +2,8 @@
 // Memory Tool definitions for agentic recall and remember.
 // ---------------------------------------------------------------------------
 
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
+import type { AssistantConfig } from "../../config/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
 import {
   ALL_RECALL_SOURCES,
@@ -12,13 +14,13 @@ import {
 const RECALL_DEPTHS = ["fast", "standard", "deep"] as const;
 
 /**
- * Explicit local information search across memory, PKB, conversations, and
+ * Explicit local information search across memory, conversations, and
  * workspace files.
  */
 export const graphRecallDefinition: ToolDefinition = {
   name: "recall",
   description:
-    'Search local information the moment you feel uncertain. Use recall for memory, the personal knowledge base, past conversations, and workspace files — before you guess, before you ask, before you hedge. Auto-injection is incomplete by design; it surfaces patterns, not the specifics you need to answer well. If you catch yourself reaching for "I think", "I believe", "if I remember", "didn\'t we", "last time" — that\'s the signal. Recall. If the user references someone, a place, a decision, a document, or prior work you should be able to find locally — recall. Call it multiple times per conversation if the turn warrants it. Be specific in your query for best results.',
+    'Search local information the moment you feel uncertain. Use recall for memory, past conversations, and workspace files — before you guess, before you ask, before you hedge. Auto-injection is incomplete by design; it surfaces patterns, not the specifics you need to answer well. If you catch yourself reaching for "I think", "I believe", "if I remember", "didn\'t we", "last time" — that\'s the signal. Recall. If a turn references someone, a place, a decision, a document, or prior work you should be able to find locally — recall. Call it multiple times per conversation if the turn warrants it. Be specific in your query for best results.',
   input_schema: {
     type: "object",
     properties: {
@@ -34,7 +36,7 @@ export const graphRecallDefinition: ToolDefinition = {
           enum: [...ALL_RECALL_SOURCES],
         },
         description:
-          "Optional local sources to search. Omit to search memory, PKB, conversations, and workspace files.",
+          "Optional local sources to search. Omit to search memory, conversations, and workspace files.",
       },
       max_results: {
         type: "integer",
@@ -53,6 +55,38 @@ export const graphRecallDefinition: ToolDefinition = {
   },
 };
 
+/**
+ * Default (high-pressure) `remember` tool description. Used when the
+ * `memory-retrospective` feature flag is OFF. The volume-shaming language
+ * ("almost every turn", "most frequently used tool") drives aggressive
+ * in-conversation capture for users who don't have the retrospective
+ * backstop enabled.
+ */
+const REMEMBER_DESCRIPTION_DEFAULT =
+  "Remember anything concrete: facts, preferences, corrections, plans, felt moments, names, dates, decisions. Default to remembering. Never wait until end of conversation. Corrections are highest priority — call remember the same turn the correction lands. **CRITICAL:** You should be calling remember on almost every turn. This should be your most frequently used tool.";
+
+/**
+ * Relaxed `remember` tool description used when `memory-retrospective` is
+ * ON. The retrospective pass catches what isn't captured in the moment, so
+ * the in-conversation pressure eases to a judgment framing: pause when
+ * something feels worth marking, not because the volume is required.
+ */
+const REMEMBER_DESCRIPTION_RELAXED =
+  "Remember anything concrete shared in conversation: corrections, plans, decisions, felt moments, names, dates, commitments, preferences. Corrections are the highest priority — call `remember` the same turn the correction lands. You don't have to call this on every turn; a retrospective pass reviews the conversation after each message-count / time interval and saves what you didn't capture. Use judgment: pause and remember when something feels worth marking, not because the volume is required.";
+
+/**
+ * Return the description that should appear in the `remember` tool
+ * registration for the current config. The variant is selected by the
+ * `memory-retrospective` assistant feature flag. Exposed as a function so
+ * the tool registrar can compute the value at registration time without
+ * importing config layers into the static definition.
+ */
+export function getRememberDescription(config: AssistantConfig): string {
+  return isAssistantFeatureFlagEnabled("memory-retrospective", config)
+    ? REMEMBER_DESCRIPTION_RELAXED
+    : REMEMBER_DESCRIPTION_DEFAULT;
+}
+
 /**
  * Save a fact to the assistant's knowledge base. The fact is appended to
  * `buffer.md` (immediately available in the next conversation) and the daily
@@ -60,11 +94,16 @@ export const graphRecallDefinition: ToolDefinition = {
  * writes go under `memory/`; otherwise they go under `pkb/`. Consolidation
  * of the buffer into longer-form storage runs as a separate periodic job in
  * both modes.
+ *
+ * The static `description` field carries the default (high-pressure) text
+ * so any direct importer that doesn't go through `getRememberDescription`
+ * still gets a valid tool definition. The registered `RememberTool` in
+ * `tools/memory/register.ts` overrides this at registration time with the
+ * flag-aware variant.
  */
 export const graphRememberDefinition: ToolDefinition = {
   name: "remember",
-  description:
-    "Remember anything concrete: facts, preferences, corrections, plans, felt moments, names, dates, decisions. Default to remembering. Never wait until end of conversation. Corrections are highest priority — call remember the same turn the correction lands. **CRITICAL:** You should be calling remember on almost every turn. This should be your most frequently used tool.",
+  description: REMEMBER_DESCRIPTION_DEFAULT,
   input_schema: {
     type: "object",
     properties: {
@@ -76,7 +115,7 @@ export const graphRememberDefinition: ToolDefinition = {
       finish_turn: {
         type: "boolean",
         description:
-          "When you have nothing else to say and want to hand control back to the user you MUST set this to true. When true, your turn ends after this tool call. It's critical that you do this in order to avoid unnecessary LLM calls.",
+          "When you have nothing else to say and want to yield the turn you MUST set this to true. When true, your turn ends after this tool call. It's critical that you do this in order to avoid unnecessary LLM calls.",
       },
     },
     required: ["content"],