feat(memory): add OSS-to-Platform notices (#5494)

mem0-ts/src/oss/src/memory/index.ts

@@ -36,10 +36,29 @@ import {
   SearchMemoryOptions,
   DeleteAllMemoryOptions,
   GetAllMemoryOptions,
+  UpdateProjectOptions,
 } from "./memory.types";
 import { parse_vision_messages } from "../utils/memory";
 import { HistoryManager } from "../storage/base";
 import { captureClientEvent } from "../utils/telemetry";
+import {
+  detectScaleThresholdFromAddResult,
+  detectScaleThresholdFromTopK,
+  detectPerformanceSlowQuery,
+  detectTemporalUsageFromMetadata,
+  detectTemporalUsageFromSearch,
+  displayDecayUsageNotice,
+  displayFirstRunNotice,
+  displayPerformanceSlowQueryNotice,
+  displayScaleThresholdNotice,
+  displayTemporalUsageNotice,
+  getDecayFeatureErrorMessage,
+  getDecayUsageDeleteCountAfterSuccess,
+  getTemporalFeatureErrorMessage,
+  isDecayUsageDeleteEligible,
+  PerformanceSlowQueryTrigger,
+  ScaleThresholdTrigger,
+} from "../utils/notices";
 import { lemmatizeForBm25 } from "../utils/lemmatization";
 import {
   extractEntities,
@@ -494,6 +513,73 @@ export class Memory {
     }
   }
 
+  private async _displayFirstRunNotice(triggerFunction: string) {
+    try {
+      await this._getTelemetryId();
+      await displayFirstRunNotice(this, triggerFunction);
+    } catch {}
+  }
+
+  private async _displayDecayUsageNotice(trigger: {
+    triggerFunction: "delete" | "delete_all";
+    triggerSource: "delete_count" | "delete_all";
+    triggerReason: "repeated_deletes" | "bulk_delete";
+    deleteCount?: number;
+    deletedCount?: number;
+  }) {
+    try {
+      await this._getTelemetryId();
+      await displayDecayUsageNotice(this, trigger);
+    } catch {}
+  }
+
+  private async _displayTemporalUsageNotice(trigger: {
+    triggerFunction: "add" | "search";
+    triggerSource: "metadata" | "query" | "filter";
+    triggerReason:
+      | "date_like_metadata"
+      | "relative_phrase"
+      | "date_like_query"
+      | "date_range_filter";
+  }) {
+    try {
+      await this._getTelemetryId();
+      await displayTemporalUsageNotice(this, trigger);
+    } catch {}
+  }
+
+  private async _displayScaleThresholdNotice(trigger: ScaleThresholdTrigger) {
+    try {
+      await this._getTelemetryId();
+      await displayScaleThresholdNotice(this, trigger);
+    } catch {}
+  }
+
+  private async _displayPerformanceSlowQueryNotice(
+    trigger: PerformanceSlowQueryTrigger,
+  ) {
+    try {
+      await this._getTelemetryId();
+      await displayPerformanceSlowQueryNotice(this, trigger);
+    } catch {}
+  }
+
+  private async _getNoticeTelemetryId() {
+    try {
+      if (
+        !this.telemetryId ||
+        this.telemetryId === "anonymous" ||
+        this.telemetryId === "anonymous-supabase"
+      ) {
+        this.telemetryId = (await getOrCreateMem0UserId()) || "anonymous";
+      }
+      return this.telemetryId;
+    } catch {
+      this.telemetryId = "anonymous";
+      return this.telemetryId;
+    }
+  }
+
   static fromConfig(configDict: Record<string, any>): Memory {
     try {
       const config = MemoryConfigSchema.parse(configDict);
@@ -504,10 +590,29 @@ export class Memory {
     }
   }
 
+  async updateProject(options: UpdateProjectOptions = {}): Promise<never> {
+    if (options?.decay === true) {
+      await this._getNoticeTelemetryId();
+      throw new Error(await getDecayFeatureErrorMessage(this));
+    }
+
+    throw new Error("Project updates are not supported by the OSS Memory SDK.");
+  }
+
   async add(
     messages: string | Message[],
     config: AddMemoryOptions,
   ): Promise<SearchResult> {
+    if (config?.timestamp !== undefined) {
+      await this._getNoticeTelemetryId();
+      throw new Error(
+        await getTemporalFeatureErrorMessage(this, {
+          triggerFunction: "add",
+          triggerParameter: "timestamp",
+        }),
+      );
+    }
+
     // Validate messages input
     if (messages === undefined || messages === null) {
       throw new Error(
@@ -515,6 +620,10 @@ export class Memory {
       );
     }
 
+    const temporalUsageNotice = detectTemporalUsageFromMetadata(
+      config?.metadata,
+    );
+
     await this._ensureInitialized();
     await this._captureEvent("add", {
       message_count: Array.isArray(messages) ? messages.length : 1,
@@ -554,6 +663,27 @@ export class Memory {
       infer,
     );
 
+    if (temporalUsageNotice) {
+      await this._displayTemporalUsageNotice({
+        triggerFunction: "add",
+        triggerSource: temporalUsageNotice.triggerSource,
+        triggerReason: temporalUsageNotice.triggerReason,
+      });
+    } else {
+      const scaleThresholdNotice = await detectScaleThresholdFromAddResult(
+        this,
+        vectorStoreResult,
+      );
+      if (scaleThresholdNotice) {
+        await this._displayScaleThresholdNotice({
+          triggerFunction: "add",
+          ...scaleThresholdNotice,
+        });
+      } else {
+        await this._displayFirstRunNotice("add");
+      }
+    }
+
     return {
       results: vectorStoreResult,
     };
@@ -996,7 +1126,10 @@ export class Memory {
   async get(memoryId: string): Promise<MemoryItem | null> {
     await this._ensureInitialized();
     const memory = await this.vectorStore.get(memoryId);
-    if (!memory) return null;
+    if (!memory) {
+      await this._displayFirstRunNotice("get");
+      return null;
+    }
 
     const filters = {
       ...(memory.payload.user_id && { user_id: memory.payload.user_id }),
@@ -1031,13 +1164,30 @@ export class Memory {
       }
     }
 
-    return { ...memoryItem, ...filters };
+    const result = { ...memoryItem, ...filters };
+    await this._displayFirstRunNotice("get");
+    return result;
   }
 
   async search(
     query: string,
     config: SearchMemoryOptions,
   ): Promise<SearchResult> {
+    if (config?.referenceDate !== undefined) {
+      await this._getNoticeTelemetryId();
+      throw new Error(
+        await getTemporalFeatureErrorMessage(this, {
+          triggerFunction: "search",
+          triggerParameter: "referenceDate",
+        }),
+      );
+    }
+
+    const temporalUsageNotice = detectTemporalUsageFromSearch(
+      query,
+      config?.filters,
+    );
+
     // Reject top-level entity params - must use filters instead
     rejectTopLevelEntityParams(config as Record<string, any>, "search");
 
@@ -1105,6 +1255,8 @@ export class Memory {
       );
     }
 
+    const searchStartMs = Date.now();
+
     // Step 1: Preprocess query
     const queryLemmatized = lemmatizeForBm25(query);
     const queryEntities = extractEntities(query);
@@ -1280,9 +1432,41 @@ export class Memory {
         };
       });
 
-    return {
+    const result = {
       results,
     };
+    const searchElapsedMs = Date.now() - searchStartMs;
+    if (temporalUsageNotice) {
+      await this._displayTemporalUsageNotice({
+        triggerFunction: "search",
+        triggerSource: temporalUsageNotice.triggerSource,
+        triggerReason: temporalUsageNotice.triggerReason,
+      });
+    } else {
+      const scaleThresholdNotice = detectScaleThresholdFromTopK(topK);
+      if (scaleThresholdNotice) {
+        await this._displayScaleThresholdNotice({
+          triggerFunction: "search",
+          ...scaleThresholdNotice,
+        });
+      } else {
+        const performanceSlowQueryNotice = detectPerformanceSlowQuery(
+          searchElapsedMs,
+          topK,
+          results.length,
+        );
+        if (performanceSlowQueryNotice) {
+          await this._displayPerformanceSlowQueryNotice({
+            triggerFunction: "search",
+            triggerReason: "slow_query",
+            ...performanceSlowQueryNotice,
+          });
+        } else {
+          await this._displayFirstRunNotice("search");
+        }
+      }
+    }
+    return result;
   }
 
   async update(memoryId: string, data: string): Promise<{ message: string }> {
@@ -1290,14 +1474,28 @@ export class Memory {
     await this._captureEvent("update", { memory_id: memoryId });
     const embedding = await this.embedder.embed(data);
     await this.updateMemory(memoryId, data, { [data]: embedding });
-    return { message: "Memory updated successfully!" };
+    const result = { message: "Memory updated successfully!" };
+    await this._displayFirstRunNotice("update");
+    return result;
   }
 
   async delete(memoryId: string): Promise<{ message: string }> {
     await this._ensureInitialized();
     await this._captureEvent("delete", { memory_id: memoryId });
     await this.deleteMemory(memoryId);
-    return { message: "Memory deleted successfully!" };
+    const result = { message: "Memory deleted successfully!" };
+    const deleteCount = getDecayUsageDeleteCountAfterSuccess();
+    if (isDecayUsageDeleteEligible(deleteCount)) {
+      await this._displayDecayUsageNotice({
+        triggerFunction: "delete",
+        triggerSource: "delete_count",
+        triggerReason: "repeated_deletes",
+        deleteCount,
+      });
+    } else {
+      await this._displayFirstRunNotice("delete");
+    }
+    return result;
   }
 
   async deleteAll(
@@ -1328,12 +1526,25 @@ export class Memory {
       await this.deleteMemory(memory.id);
     }
 
-    return { message: "Memories deleted successfully!" };
+    const result = { message: "Memories deleted successfully!" };
+    if (memories.length > 0) {
+      await this._displayDecayUsageNotice({
+        triggerFunction: "delete_all",
+        triggerSource: "delete_all",
+        triggerReason: "bulk_delete",
+        deletedCount: memories.length,
+      });
+    } else {
+      await this._displayFirstRunNotice("delete_all");
+    }
+    return result;
   }
 
   async history(memoryId: string): Promise<any[]> {
     await this._ensureInitialized();
-    return this.db.getHistory(memoryId);
+    const result = await this.db.getHistory(memoryId);
+    await this._displayFirstRunNotice("history");
+    return result;
   }
 
   async reset(): Promise<void> {
@@ -1385,6 +1596,7 @@ export class Memory {
       console.error(this._initError);
     });
     await this._initPromise;
+    await this._displayFirstRunNotice("reset");
   }
 
   async getAll(config: GetAllMemoryOptions): Promise<SearchResult> {
@@ -1452,7 +1664,17 @@ export class Memory {
       ...(mem.payload.run_id && { run_id: mem.payload.run_id }),
     }));
 
-    return { results };
+    const result = { results };
+    const scaleThresholdNotice = detectScaleThresholdFromTopK(topK);
+    if (scaleThresholdNotice) {
+      await this._displayScaleThresholdNotice({
+        triggerFunction: "get_all",
+        ...scaleThresholdNotice,
+      });
+    } else {
+      await this._displayFirstRunNotice("get_all");
+    }
+    return result;
   }
 
   private async createMemory(

mem0-ts/src/oss/src/memory/memory.types.ts

@@ -11,6 +11,7 @@ export interface AddMemoryOptions extends Entity {
   metadata?: Record<string, any>;
   filters?: SearchFilters;
   infer?: boolean;
+  timestamp?: number | string | Date | null;
 }
 
 export interface SearchMemoryOptions {
@@ -18,6 +19,7 @@ export interface SearchMemoryOptions {
   filters?: SearchFilters;
   threshold?: number;
   explain?: boolean;
+  referenceDate?: number | string | Date | null;
 }
 
 export interface GetAllMemoryOptions {
@@ -26,3 +28,8 @@ export interface GetAllMemoryOptions {
 }
 
 export interface DeleteAllMemoryOptions extends Entity {}
+
+export interface UpdateProjectOptions {
+  decay?: boolean;
+  [key: string]: any;
+}

mem0-ts/src/oss/src/utils/telemetry.ts

@@ -13,10 +13,12 @@ let version =
 // Safely check for process.env in different environments
 let MEM0_TELEMETRY = true;
 try {
-  MEM0_TELEMETRY = process?.env?.MEM0_TELEMETRY === "false" ? false : true;
+  MEM0_TELEMETRY =
+    process?.env?.MEM0_TELEMETRY?.toLowerCase() === "false" ? false : true;
 } catch (error) {}
 const POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX";
 const POSTHOG_HOST = "https://us.i.posthog.com/i/v0/e/";
+const NOTICE_EVENT_NAME = "mem0.notice_displayed";
 
 // Default sampling rate for hot-path OSS events. Lifecycle events always fire at 100%.
 // Override via MEM0_TELEMETRY_SAMPLE_RATE env var. Mirrors mem0/memory/telemetry.py.
@@ -35,7 +37,11 @@ const MEM0_TELEMETRY_SAMPLE_RATE: number = ((): number => {
 })();
 
 // Events that bypass sampling. Keep in sync with _captureEvent call sites in memory/index.ts.
-const LIFECYCLE_EVENTS: ReadonlySet<string> = new Set(["init", "reset"]);
+const ALWAYS_SEND_EVENTS: ReadonlySet<string> = new Set([
+  "init",
+  "reset",
+  "notice_displayed",
+]);
 
 class UnifiedTelemetry implements TelemetryClient {
   private apiKey: string;
@@ -91,6 +97,10 @@ class UnifiedTelemetry implements TelemetryClient {
 
 const telemetry = new UnifiedTelemetry(POSTHOG_API_KEY, POSTHOG_HOST);
 
+function isTelemetryEnabled(): boolean {
+  return MEM0_TELEMETRY;
+}
+
 async function captureClientEvent(
   eventName: string,
   instance: TelemetryInstance,
@@ -102,8 +112,8 @@ async function captureClientEvent(
   }
 
   // >= so that rate=0 drops everything and rate=1 keeps everything (Math.random() ∈ [0, 1)).
-  const isLifecycle = LIFECYCLE_EVENTS.has(eventName);
-  if (!isLifecycle && Math.random() >= MEM0_TELEMETRY_SAMPLE_RATE) {
+  const alwaysSend = ALWAYS_SEND_EVENTS.has(eventName);
+  if (!alwaysSend && Math.random() >= MEM0_TELEMETRY_SAMPLE_RATE) {
     return;
   }
 
@@ -116,7 +126,7 @@ async function captureClientEvent(
     client_source: "nodejs",
     ...additionalData,
     // sample_rate set AFTER the spread so callers can never override it
-    sample_rate: isLifecycle ? 1.0 : MEM0_TELEMETRY_SAMPLE_RATE,
+    sample_rate: alwaysSend ? 1.0 : MEM0_TELEMETRY_SAMPLE_RATE,
   };
 
   await telemetry.captureEvent(
@@ -126,4 +136,36 @@ async function captureClientEvent(
   );
 }
 
-export { telemetry, captureClientEvent };
+async function captureNoticeEvent(
+  instance: TelemetryInstance,
+  properties: Record<string, any> = {},
+) {
+  if (!instance.telemetryId) return;
+
+  const eventData: TelemetryEventData = {
+    function: `${instance.constructor.name}`,
+    method: "notice_displayed",
+    api_host: instance.host,
+    timestamp: new Date().toISOString(),
+    client_version: version,
+    client_source: "nodejs",
+    ...properties,
+    sample_rate: 1.0,
+  };
+
+  await telemetry.captureEvent(
+    instance.telemetryId,
+    NOTICE_EVENT_NAME,
+    eventData,
+  );
+}
+
+export {
+  POSTHOG_API_KEY,
+  POSTHOG_HOST,
+  NOTICE_EVENT_NAME,
+  telemetry,
+  captureClientEvent,
+  captureNoticeEvent,
+  isTelemetryEnabled,
+};

mem0-ts/src/oss/tests/config-manager.test.ts

@@ -418,6 +418,7 @@ describe("Memory – LM Studio end-to-end flow", () => {
     }));
     jest.doMock("../src/utils/telemetry", () => ({
       captureClientEvent: jest.fn().mockResolvedValue(undefined),
+      isTelemetryEnabled: jest.fn(() => false),
     }));
 
     MemoryClass = require("../src/memory").Memory;

mem0-ts/src/oss/tests/dimension-autodetect.test.ts

@@ -290,6 +290,7 @@ describe("Memory – auto-initialization", () => {
 
     jest.doMock("../src/utils/telemetry", () => ({
       captureClientEvent: jest.fn().mockResolvedValue(undefined),
+      isTelemetryEnabled: jest.fn(() => false),
     }));
 
     MemoryClass = require("../src/memory").Memory;

mem0-ts/src/oss/tests/notices.decay-feature.test.ts

@@ -0,0 +1,387 @@
+/// <reference types="jest" />
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+jest.setTimeout(15000);
+
+jest.mock("../src/embeddings/google", () => ({
+  GoogleEmbedder: jest.fn(),
+}));
+jest.mock("../src/llms/google", () => ({
+  GoogleLLM: jest.fn(),
+}));
+
+const mockEmbedding = new Array(1536).fill(0.1);
+jest.mock("../src/embeddings/openai", () => ({
+  OpenAIEmbedder: jest.fn().mockImplementation(() => ({
+    embed: jest.fn().mockResolvedValue(mockEmbedding),
+    embedBatch: jest
+      .fn()
+      .mockImplementation((texts: string[]) =>
+        Promise.resolve(texts.map(() => mockEmbedding)),
+      ),
+    embeddingDims: 1536,
+  })),
+}));
+
+jest.mock("../src/llms/openai", () => ({
+  OpenAILLM: jest.fn().mockImplementation(() => ({
+    generateResponse: jest.fn(),
+  })),
+}));
+
+const DECAY_COPY =
+  'Memory decay requires Mem0 Platform. Get a free API key at https://app.mem0.ai?utm_source=oss_sdk&utm_medium=in_product&utm_campaign=decay_stub&utm_content=node_error and use `import MemoryClient from "mem0ai"`.';
+const PLAIN_DECAY_ERROR =
+  "The decay parameter is not supported by the OSS Memory SDK.";
+const PROJECT_UPDATE_ERROR =
+  "Project updates are not supported by the OSS Memory SDK.";
+
+function makeTempMem0Dir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "mem0-node-decay-feature-"));
+}
+
+function decayPayload(overrides: Record<string, any> = {}) {
+  return {
+    notices: {
+      decay_stub: {
+        enabled: true,
+        notice_type: "error",
+        copy: DECAY_COPY,
+        ...overrides,
+      },
+    },
+  };
+}
+
+function createFetchMock(options: {
+  variant?: string;
+  payload?: unknown;
+  failFlags?: boolean;
+  flagEnabled?: boolean;
+}) {
+  const calls: any[] = [];
+  const fetchMock = jest.fn(async (url: string | URL, init?: RequestInit) => {
+    const target = String(url);
+
+    if (target.includes("/flags")) {
+      if (options.failFlags) {
+        throw new Error("flag evaluation failed");
+      }
+      return {
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          flags: {
+            "mem0-oss-notices": {
+              key: "mem0-oss-notices",
+              enabled: options.flagEnabled ?? true,
+              variant: options.variant ?? "displayed",
+              metadata: {
+                payload:
+                  options.payload === undefined
+                    ? JSON.stringify(decayPayload())
+                    : options.payload,
+              },
+            },
+          },
+        }),
+      };
+    }
+
+    if (target.includes("/i/v0/e/")) {
+      calls.push(JSON.parse(String(init?.body)));
+      return {
+        ok: true,
+        text: jest.fn().mockResolvedValue(""),
+      };
+    }
+
+    return {
+      ok: true,
+      json: jest.fn().mockResolvedValue({}),
+      text: jest.fn().mockResolvedValue(""),
+    };
+  });
+
+  return { fetchMock, calls };
+}
+
+function noticeEvents(calls: any[]) {
+  return calls.filter((call) => call.event === "mem0.notice_displayed");
+}
+
+async function createMemory() {
+  const { Memory } = await import("../src/memory");
+  return new Memory({
+    version: "v1.1",
+    embedder: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "text-embedding-3-small" },
+    },
+    vectorStore: {
+      provider: "memory",
+      config: {
+        collectionName: `test-decay-feature-${Date.now()}-${Math.random()}`,
+        dimension: 1536,
+        dbPath: ":memory:",
+      },
+    },
+    llm: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "gpt-5-mini" },
+    },
+    historyDbPath: ":memory:",
+  });
+}
+
+describe("Node OSS decay feature error notice", () => {
+  let originalMem0Dir: string | undefined;
+  let originalTelemetry: string | undefined;
+  let originalSampleRate: string | undefined;
+  let originalFetch: typeof global.fetch;
+
+  beforeEach(() => {
+    originalMem0Dir = process.env.MEM0_DIR;
+    originalTelemetry = process.env.MEM0_TELEMETRY;
+    originalSampleRate = process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    originalFetch = global.fetch;
+
+    process.env.MEM0_DIR = makeTempMem0Dir();
+    process.env.MEM0_TELEMETRY = "true";
+    process.env.MEM0_TELEMETRY_SAMPLE_RATE = "1";
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    if (originalMem0Dir === undefined) delete process.env.MEM0_DIR;
+    else process.env.MEM0_DIR = originalMem0Dir;
+
+    if (originalTelemetry === undefined) delete process.env.MEM0_TELEMETRY;
+    else process.env.MEM0_TELEMETRY = originalTelemetry;
+
+    if (originalSampleRate === undefined) {
+      delete process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    } else {
+      process.env.MEM0_TELEMETRY_SAMPLE_RATE = originalSampleRate;
+    }
+
+    global.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.resetModules();
+  });
+
+  it("raises CTA copy for displayed and emits displayed=true", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.updateProject({ decay: true })).rejects.toThrow(
+      DECAY_COPY,
+    );
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "decay_stub",
+        notice_type: "error",
+        flag_key: "mem0-oss-notices",
+        variant: "displayed",
+        displayed: true,
+        payload: DECAY_COPY,
+        notice_config_found: true,
+        sync_type: "async",
+        trigger_function: "update_project",
+        trigger_parameter: "decay",
+        sample_rate: 1,
+      }),
+    );
+  });
+
+  it("raises CTA copy for holdout and emits displayed=true", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "holdout" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.updateProject({ decay: true })).rejects.toThrow(
+      DECAY_COPY,
+    );
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "decay_stub",
+        variant: "holdout",
+        displayed: true,
+        trigger_function: "update_project",
+        trigger_parameter: "decay",
+      }),
+    );
+    expect(notices[0].properties.bypass_reason).toBeUndefined();
+  });
+
+  it("uses plain error for unknown future variants and emits not_displayed", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "silent" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.updateProject({ decay: true })).rejects.toThrow(
+      PLAIN_DECAY_ERROR,
+    );
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "decay_stub",
+        variant: "silent",
+        displayed: false,
+        bypass_reason: "not_displayed",
+        payload: DECAY_COPY,
+      }),
+    );
+  });
+
+  it("uses plain error for disabled payload and emits payload_disabled", async () => {
+    const { fetchMock, calls } = createFetchMock({
+      variant: "holdout",
+      payload: JSON.stringify(decayPayload({ enabled: false })),
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.updateProject({ decay: true })).rejects.toThrow(
+      PLAIN_DECAY_ERROR,
+    );
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "decay_stub",
+        displayed: false,
+        bypass_reason: "payload_disabled",
+        disabled_reason: "payload_disabled",
+        notice_config_found: true,
+      }),
+    );
+  });
+
+  it.each([
+    [
+      "missing config",
+      JSON.stringify({ notices: {} }),
+      "missing_notice_config",
+    ],
+    [
+      "missing copy",
+      JSON.stringify(decayPayload({ copy: "" })),
+      "missing_copy",
+    ],
+    ["malformed payload", "{not-json", "missing_notice_config"],
+  ])("uses plain error for %s", async (_label, payload, bypassReason) => {
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      payload,
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.updateProject({ decay: true })).rejects.toThrow(
+      PLAIN_DECAY_ERROR,
+    );
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "decay_stub",
+        displayed: false,
+        bypass_reason: bypassReason,
+      }),
+    );
+  });
+
+  it("uses plain error and emits no event when the blunt flag is disabled", async () => {
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      flagEnabled: false,
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.updateProject({ decay: true })).rejects.toThrow(
+      PLAIN_DECAY_ERROR,
+    );
+
+    expect(noticeEvents(calls)).toHaveLength(0);
+  });
+
+  it("uses plain error and emits no event when PostHog fails", async () => {
+    const { fetchMock, calls } = createFetchMock({ failFlags: true });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.updateProject({ decay: true })).rejects.toThrow(
+      PLAIN_DECAY_ERROR,
+    );
+
+    expect(noticeEvents(calls)).toHaveLength(0);
+  });
+
+  it("uses plain error and skips flag evaluation when telemetry is off", async () => {
+    process.env.MEM0_TELEMETRY = "False";
+    jest.resetModules();
+
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.updateProject({ decay: true })).rejects.toThrow(
+      PLAIN_DECAY_ERROR,
+    );
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(noticeEvents(calls)).toHaveLength(0);
+  });
+
+  it.each([
+    ["empty options", {}],
+    ["decay false", { decay: false }],
+    ["non-decay options", { customInstructions: "Updated" }],
+  ])("does not emit notice telemetry for %s", async (_label, options) => {
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.updateProject(options)).rejects.toThrow(
+      PROJECT_UPDATE_ERROR,
+    );
+
+    expect(
+      fetchMock.mock.calls.filter(([url]) => String(url).includes("/flags")),
+    ).toHaveLength(0);
+    expect(noticeEvents(calls)).toHaveLength(0);
+  });
+
+  it("does not trigger first-run notice or update_project telemetry", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.updateProject({ decay: true })).rejects.toThrow(
+      DECAY_COPY,
+    );
+
+    const eventNames = calls.map((call) => call.event);
+    expect(eventNames).toContain("mem0.notice_displayed");
+    expect(eventNames).not.toContain("mem0.update_project");
+    expect(
+      noticeEvents(calls).some(
+        (call) => call.properties.notice_id === "first_run",
+      ),
+    ).toBe(false);
+  });
+});

mem0-ts/src/oss/tests/notices.decay-usage.test.ts

@@ -0,0 +1,526 @@
+/// <reference types="jest" />
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+jest.setTimeout(15000);
+
+jest.mock("../src/embeddings/google", () => ({
+  GoogleEmbedder: jest.fn(),
+}));
+jest.mock("../src/llms/google", () => ({
+  GoogleLLM: jest.fn(),
+}));
+
+const mockEmbedding = new Array(1536).fill(0.1);
+jest.mock("../src/embeddings/openai", () => ({
+  OpenAIEmbedder: jest.fn().mockImplementation(() => ({
+    embed: jest.fn().mockResolvedValue(mockEmbedding),
+    embedBatch: jest
+      .fn()
+      .mockImplementation((texts: string[]) =>
+        Promise.resolve(texts.map(() => mockEmbedding)),
+      ),
+    embeddingDims: 1536,
+  })),
+}));
+
+jest.mock("../src/llms/openai", () => ({
+  OpenAILLM: jest.fn().mockImplementation(() => ({
+    generateResponse: jest.fn(),
+  })),
+}));
+
+const DECAY_USAGE_COPY =
+  "Tip: Python fallback copy with memory.project.update(decay=True).";
+
+function makeTempMem0Dir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "mem0-node-decay-usage-"));
+}
+
+function configPath(): string {
+  return path.join(process.env.MEM0_DIR as string, "config.json");
+}
+
+function readConfig(): Record<string, any> {
+  const file = configPath();
+  if (!fs.existsSync(file)) return {};
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function writeConfig(config: Record<string, any>) {
+  fs.mkdirSync(path.dirname(configPath()), { recursive: true });
+  fs.writeFileSync(configPath(), JSON.stringify(config, null, 4));
+}
+
+function consumeFirstRun() {
+  writeConfig({
+    user_id: "node-decay-usage-test-user",
+    notice_state: {
+      first_run: {
+        consumed: true,
+        trigger_function: "test_setup",
+        variant: "test",
+      },
+    },
+  });
+}
+
+function decayUsagePayload(overrides: Record<string, any> = {}) {
+  return {
+    notices: {
+      decay_usage: {
+        enabled: true,
+        notice_type: "log_line",
+        copy: DECAY_USAGE_COPY,
+        ...overrides,
+      },
+    },
+  };
+}
+
+function createFetchMock(options: {
+  variant?: string;
+  payload?: unknown;
+  failFlags?: boolean;
+  flagEnabled?: boolean;
+}) {
+  const calls: any[] = [];
+  const fetchMock = jest.fn(async (url: string | URL, init?: RequestInit) => {
+    const target = String(url);
+
+    if (target.includes("/flags")) {
+      if (options.failFlags) {
+        throw new Error("flag evaluation failed");
+      }
+      const payload =
+        options.payload === undefined
+          ? JSON.stringify(decayUsagePayload())
+          : options.payload;
+      return {
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          flags: {
+            "mem0-oss-notices": {
+              key: "mem0-oss-notices",
+              enabled: options.flagEnabled ?? true,
+              variant: options.variant ?? "displayed",
+              metadata: { payload },
+            },
+          },
+        }),
+      };
+    }
+
+    if (target.includes("/i/v0/e/")) {
+      calls.push(JSON.parse(String(init?.body)));
+      return {
+        ok: true,
+        text: jest.fn().mockResolvedValue(""),
+      };
+    }
+
+    return {
+      ok: true,
+      json: jest.fn().mockResolvedValue({}),
+      text: jest.fn().mockResolvedValue(""),
+    };
+  });
+
+  return { fetchMock, calls };
+}
+
+function noticeEvents(calls: any[]) {
+  return calls.filter((call) => call.event === "mem0.notice_displayed");
+}
+
+function flagRequestCount(fetchMock: jest.Mock) {
+  return fetchMock.mock.calls.filter(([url]) => String(url).includes("/flags"))
+    .length;
+}
+
+async function createMemory() {
+  const { Memory } = await import("../src/memory");
+  return new Memory({
+    version: "v1.1",
+    embedder: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "text-embedding-3-small" },
+    },
+    vectorStore: {
+      provider: "memory",
+      config: {
+        collectionName: `test-decay-usage-${Date.now()}-${Math.random()}`,
+        dimension: 1536,
+        dbPath: ":memory:",
+      },
+    },
+    llm: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "gpt-5-mini" },
+    },
+    historyDbPath: ":memory:",
+  });
+}
+
+async function addMemories(memory: any, userId: string, count: number) {
+  const ids: string[] = [];
+  for (let index = 0; index < count; index++) {
+    const result = await memory.add(`Decay usage memory ${index}`, {
+      userId,
+      infer: false,
+    });
+    ids.push(result.results[0].id);
+  }
+  return ids;
+}
+
+describe("Node OSS decay usage notice", () => {
+  let originalMem0Dir: string | undefined;
+  let originalTelemetry: string | undefined;
+  let originalSampleRate: string | undefined;
+  let originalFetch: typeof global.fetch;
+  let stderrSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    originalMem0Dir = process.env.MEM0_DIR;
+    originalTelemetry = process.env.MEM0_TELEMETRY;
+    originalSampleRate = process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    originalFetch = global.fetch;
+
+    process.env.MEM0_DIR = makeTempMem0Dir();
+    process.env.MEM0_TELEMETRY = "true";
+    process.env.MEM0_TELEMETRY_SAMPLE_RATE = "1";
+    stderrSpy = jest
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    if (originalMem0Dir === undefined) delete process.env.MEM0_DIR;
+    else process.env.MEM0_DIR = originalMem0Dir;
+
+    if (originalTelemetry === undefined) delete process.env.MEM0_TELEMETRY;
+    else process.env.MEM0_TELEMETRY = originalTelemetry;
+
+    if (originalSampleRate === undefined) {
+      delete process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    } else {
+      process.env.MEM0_TELEMETRY_SAMPLE_RATE = originalSampleRate;
+    }
+
+    global.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.resetModules();
+  });
+
+  it("does not evaluate or write decay state before the 5th successful delete", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    const ids = await addMemories(memory, "decay-delete-user", 4);
+
+    for (const id of ids) {
+      await memory.delete(id);
+    }
+
+    expect(flagRequestCount(fetchMock)).toBe(0);
+    expect(noticeEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.decay_usage).toBeUndefined();
+    expect(stderrSpy).not.toHaveBeenCalledWith(
+      expect.stringContaining(DECAY_USAGE_COPY),
+    );
+  });
+
+  it("evaluates on the 5th successful delete and records delete_count", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    const ids = await addMemories(memory, "decay-delete-user", 5);
+
+    for (const id of ids) {
+      await memory.delete(id);
+    }
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "decay_usage",
+        notice_type: "log_line",
+        flag_key: "mem0-oss-notices",
+        variant: "displayed",
+        displayed: true,
+        payload: DECAY_USAGE_COPY,
+        notice_config_found: true,
+        sync_type: "async",
+        trigger_function: "delete",
+        trigger_source: "delete_count",
+        trigger_reason: "repeated_deletes",
+        delete_count: 5,
+        sample_rate: 1,
+      }),
+    );
+    expect(stderrSpy.mock.calls.flat().join("")).toContain(DECAY_USAGE_COPY);
+    expect(readConfig().notice_state.decay_usage.events).toHaveLength(1);
+  });
+
+  it("does not count or emit when delete fails", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    jest
+      .spyOn(memory as any, "deleteMemory")
+      .mockRejectedValue(new Error("delete failed"));
+
+    await expect(memory.delete("memory-id")).rejects.toThrow("delete failed");
+
+    expect(flagRequestCount(fetchMock)).toBe(0);
+    expect(noticeEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.decay_usage).toBeUndefined();
+  });
+
+  it("evaluates deleteAll after deleting at least one memory", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addMemories(memory, "decay-delete-all-user", 3);
+
+    await memory.deleteAll({ userId: "decay-delete-all-user" });
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "decay_usage",
+        variant: "displayed",
+        displayed: true,
+        payload: DECAY_USAGE_COPY,
+        trigger_function: "delete_all",
+        trigger_source: "delete_all",
+        trigger_reason: "bulk_delete",
+        deleted_count: 3,
+      }),
+    );
+  });
+
+  it("does not evaluate deleteAll when no memories are deleted", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.deleteAll({ userId: "empty-delete-all-user" });
+
+    expect(flagRequestCount(fetchMock)).toBe(0);
+    expect(noticeEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.decay_usage).toBeUndefined();
+  });
+
+  it("does not evaluate when deleteAll fails", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.deleteAll({} as any)).rejects.toThrow(
+      "At least one filter is required",
+    );
+
+    expect(flagRequestCount(fetchMock)).toBe(0);
+    expect(noticeEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.decay_usage).toBeUndefined();
+  });
+
+  it("is silent for holdout and emits displayed=false", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "holdout" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addMemories(memory, "decay-holdout-user", 3);
+
+    await memory.deleteAll({ userId: "decay-holdout-user" });
+
+    expect(stderrSpy).not.toHaveBeenCalledWith(
+      expect.stringContaining(DECAY_USAGE_COPY),
+    );
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "decay_usage",
+        variant: "holdout",
+        displayed: false,
+        bypass_reason: "holdout",
+        trigger_function: "delete_all",
+      }),
+    );
+  });
+
+  it.each([
+    [
+      "disabled payload",
+      JSON.stringify(decayUsagePayload({ enabled: false })),
+      "payload_disabled",
+      "payload_disabled",
+    ],
+    [
+      "missing config",
+      JSON.stringify({ notices: {} }),
+      "missing_notice_config",
+      undefined,
+    ],
+    [
+      "missing copy",
+      JSON.stringify({
+        notices: {
+          decay_usage: { enabled: true, notice_type: "log_line" },
+        },
+      }),
+      "missing_copy",
+      undefined,
+    ],
+    ["malformed payload", "{not-json", "missing_notice_config", undefined],
+  ])(
+    "stays silent and emits safe bypass for %s",
+    async (_label, payload, bypassReason, disabledReason) => {
+      consumeFirstRun();
+      const { fetchMock, calls } = createFetchMock({
+        variant: "displayed",
+        payload,
+      });
+      global.fetch = fetchMock as any;
+      const memory = await createMemory();
+      await addMemories(memory, "decay-bypass-user", 3);
+
+      await memory.deleteAll({ userId: "decay-bypass-user" });
+
+      expect(stderrSpy).not.toHaveBeenCalledWith(
+        expect.stringContaining(DECAY_USAGE_COPY),
+      );
+      const notices = noticeEvents(calls);
+      expect(notices).toHaveLength(1);
+      expect(notices[0].properties).toEqual(
+        expect.objectContaining({
+          notice_id: "decay_usage",
+          displayed: false,
+          bypass_reason: bypassReason,
+          ...(disabledReason && { disabled_reason: disabledReason }),
+        }),
+      );
+    },
+  );
+
+  it("does not emit or consume cap when the blunt flag is disabled", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      flagEnabled: false,
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addMemories(memory, "decay-flag-disabled-user", 3);
+
+    await memory.deleteAll({ userId: "decay-flag-disabled-user" });
+
+    expect(noticeEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.decay_usage).toBeUndefined();
+  });
+
+  it("does not emit or consume cap when PostHog fails", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ failFlags: true });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addMemories(memory, "decay-posthog-failure-user", 3);
+
+    await memory.deleteAll({ userId: "decay-posthog-failure-user" });
+
+    expect(noticeEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.decay_usage).toBeUndefined();
+  });
+
+  it("skips flag evaluation, event emission, and state writes when telemetry is off", async () => {
+    process.env.MEM0_TELEMETRY = "False";
+    jest.resetModules();
+
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addMemories(memory, "decay-telemetry-off-user", 3);
+
+    await memory.deleteAll({ userId: "decay-telemetry-off-user" });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(noticeEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.decay_usage).toBeUndefined();
+  });
+
+  it("blocks the 11th evaluated opportunity before flag evaluation", async () => {
+    consumeFirstRun();
+    const now = new Date();
+    writeConfig({
+      ...readConfig(),
+      notice_state: {
+        ...readConfig().notice_state,
+        first_run: readConfig().notice_state.first_run,
+        decay_usage: {
+          events: Array.from({ length: 10 }, (_, index) => ({
+            evaluated_at: new Date(now.getTime() - index * 1000).toISOString(),
+            variant: "displayed",
+          })),
+        },
+      },
+    });
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addMemories(memory, "decay-cap-user", 1);
+
+    await memory.deleteAll({ userId: "decay-cap-user" });
+
+    expect(flagRequestCount(fetchMock)).toBe(0);
+    expect(noticeEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state.decay_usage.events).toHaveLength(10);
+  });
+
+  it("does not consume first-run on a qualifying decay usage call", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      payload: JSON.stringify({
+        notices: {
+          first_run: {
+            enabled: true,
+            notice_type: "log_line",
+            copy: "First-run should not appear",
+          },
+          decay_usage: {
+            enabled: true,
+            notice_type: "log_line",
+            copy: DECAY_USAGE_COPY,
+          },
+        },
+      }),
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addMemories(memory, "decay-priority-user", 3);
+    const config = readConfig();
+    delete config.notice_state.first_run;
+    writeConfig(config);
+
+    await memory.deleteAll({ userId: "decay-priority-user" });
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties.notice_id).toBe("decay_usage");
+    expect(readConfig().notice_state.first_run).toBeUndefined();
+    expect(readConfig().notice_state.decay_usage.events).toHaveLength(1);
+  });
+});

mem0-ts/src/oss/tests/notices.first-run.test.ts

@@ -0,0 +1,409 @@
+/// <reference types="jest" />
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+jest.setTimeout(15000);
+
+jest.mock("../src/embeddings/google", () => ({
+  GoogleEmbedder: jest.fn(),
+}));
+jest.mock("../src/llms/google", () => ({
+  GoogleLLM: jest.fn(),
+}));
+
+jest.mock("../src/llms/openai", () => ({
+  OpenAILLM: jest.fn().mockImplementation(() => ({
+    generateResponse: jest.fn().mockResolvedValue(
+      JSON.stringify({
+        memory: [{ id: "0", text: "stored fact", attributed_to: "user" }],
+      }),
+    ),
+  })),
+}));
+
+const mockEmbedding = new Array(1536).fill(0.1);
+jest.mock("../src/embeddings/openai", () => ({
+  OpenAIEmbedder: jest.fn().mockImplementation(() => ({
+    embed: jest.fn().mockResolvedValue(mockEmbedding),
+    embedBatch: jest
+      .fn()
+      .mockImplementation((texts: string[]) =>
+        Promise.resolve(texts.map(() => mockEmbedding)),
+      ),
+    embeddingDims: 1536,
+  })),
+}));
+
+const FIRST_RUN_COPY = "First-run CTA from PostHog";
+
+function makeTempMem0Dir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "mem0-node-first-run-"));
+}
+
+function firstRunPayload(overrides: Record<string, any> = {}) {
+  return {
+    notices: {
+      first_run: {
+        enabled: true,
+        notice_type: "log_line",
+        copy: FIRST_RUN_COPY,
+        ...overrides,
+      },
+    },
+  };
+}
+
+function createFetchMock(options: {
+  variant?: string;
+  payload?: Record<string, any>;
+  failFlags?: boolean;
+}) {
+  const calls: any[] = [];
+  const fetchMock = jest.fn(async (url: string | URL, init?: RequestInit) => {
+    const target = String(url);
+
+    if (target.includes("/flags")) {
+      if (options.failFlags) {
+        throw new Error("flag evaluation failed");
+      }
+      return {
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          flags: {
+            "mem0-oss-notices": {
+              key: "mem0-oss-notices",
+              enabled: true,
+              variant: options.variant ?? "displayed",
+              metadata: {
+                payload: JSON.stringify(options.payload ?? firstRunPayload()),
+              },
+            },
+          },
+        }),
+      };
+    }
+
+    if (target.includes("/i/v0/e/")) {
+      calls.push(JSON.parse(String(init?.body)));
+      return {
+        ok: true,
+        text: jest.fn().mockResolvedValue(""),
+      };
+    }
+
+    return {
+      ok: true,
+      json: jest.fn().mockResolvedValue({}),
+      text: jest.fn().mockResolvedValue(""),
+    };
+  });
+
+  return { fetchMock, calls };
+}
+
+function noticeEvents(calls: any[]) {
+  return calls.filter((call) => call.event === "mem0.notice_displayed");
+}
+
+async function createMemory() {
+  const { Memory } = await import("../src/memory");
+  return new Memory({
+    version: "v1.1",
+    embedder: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "text-embedding-3-small" },
+    },
+    vectorStore: {
+      provider: "memory",
+      config: {
+        collectionName: `test-first-run-${Date.now()}-${Math.random()}`,
+        dimension: 1536,
+        dbPath: ":memory:",
+      },
+    },
+    llm: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "gpt-5-mini" },
+    },
+    historyDbPath: ":memory:",
+  });
+}
+
+describe("Node OSS first-run notice", () => {
+  let originalMem0Dir: string | undefined;
+  let originalTelemetry: string | undefined;
+  let originalSampleRate: string | undefined;
+  let originalFetch: typeof global.fetch;
+  let stderrSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    originalMem0Dir = process.env.MEM0_DIR;
+    originalTelemetry = process.env.MEM0_TELEMETRY;
+    originalSampleRate = process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    originalFetch = global.fetch;
+
+    process.env.MEM0_DIR = makeTempMem0Dir();
+    process.env.MEM0_TELEMETRY = "true";
+    process.env.MEM0_TELEMETRY_SAMPLE_RATE = "1";
+    stderrSpy = jest
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    if (originalMem0Dir === undefined) delete process.env.MEM0_DIR;
+    else process.env.MEM0_DIR = originalMem0Dir;
+
+    if (originalTelemetry === undefined) delete process.env.MEM0_TELEMETRY;
+    else process.env.MEM0_TELEMETRY = originalTelemetry;
+
+    if (originalSampleRate === undefined) {
+      delete process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    } else {
+      process.env.MEM0_TELEMETRY_SAMPLE_RATE = originalSampleRate;
+    }
+
+    global.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.resetModules();
+  });
+
+  it("shows the displayed first-run copy once after a successful public call", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Direct storage content", {
+      userId: "first-run-user",
+      infer: false,
+    });
+    await memory.add("Second direct storage content", {
+      userId: "first-run-user",
+      infer: false,
+    });
+
+    const stderrOutput = stderrSpy.mock.calls.flat().join("");
+    expect(stderrOutput.match(new RegExp(FIRST_RUN_COPY, "g"))).toHaveLength(1);
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "first_run",
+        notice_type: "log_line",
+        flag_key: "mem0-oss-notices",
+        variant: "displayed",
+        displayed: true,
+        payload: FIRST_RUN_COPY,
+        notice_config_found: true,
+        sync_type: "async",
+        trigger_function: "add",
+        sample_rate: 1,
+      }),
+    );
+
+    const { __noticeTestHooks } = await import("../src/utils/notices");
+    const config = __noticeTestHooks.loadMem0Config();
+    expect(config.notice_state.first_run).toEqual(
+      expect.objectContaining({
+        consumed: true,
+        trigger_function: "add",
+        variant: "displayed",
+      }),
+    );
+  });
+
+  it("treats missing enabled as enabled, matching Python payload semantics", async () => {
+    const payload = firstRunPayload();
+    delete (payload.notices.first_run as Record<string, any>).enabled;
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      payload,
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Missing enabled payload content", {
+      userId: "first-run-missing-enabled",
+      infer: false,
+    });
+
+    const stderrOutput = stderrSpy.mock.calls.flat().join("");
+    expect(stderrOutput).toContain(FIRST_RUN_COPY);
+    expect(noticeEvents(calls)[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "first_run",
+        displayed: true,
+        payload: FIRST_RUN_COPY,
+      }),
+    );
+  });
+
+  it("is silent for holdout but still emits and consumes the opportunity", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "holdout" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Holdout content", {
+      userId: "first-run-holdout",
+      infer: false,
+    });
+
+    expect(stderrSpy).not.toHaveBeenCalledWith(
+      expect.stringContaining(FIRST_RUN_COPY),
+    );
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "first_run",
+        variant: "holdout",
+        displayed: false,
+        bypass_reason: "holdout",
+        notice_config_found: true,
+      }),
+    );
+  });
+
+  it("is silent for disabled payloads and records a safe bypass", async () => {
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      payload: firstRunPayload({ enabled: false }),
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Disabled payload content", {
+      userId: "first-run-disabled",
+      infer: false,
+    });
+
+    const stderrOutput = stderrSpy.mock.calls.flat().join("");
+    expect(stderrOutput).not.toContain(FIRST_RUN_COPY);
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "first_run",
+        displayed: false,
+        bypass_reason: "payload_disabled",
+        disabled_reason: "payload_disabled",
+        notice_config_found: true,
+      }),
+    );
+  });
+
+  it("lets the payload disabled kill switch take precedence over holdout", async () => {
+    const { fetchMock, calls } = createFetchMock({
+      variant: "holdout",
+      payload: firstRunPayload({ enabled: false }),
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Disabled holdout payload content", {
+      userId: "first-run-disabled-holdout",
+      infer: false,
+    });
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "first_run",
+        variant: "holdout",
+        displayed: false,
+        bypass_reason: "payload_disabled",
+        disabled_reason: "payload_disabled",
+        notice_config_found: true,
+      }),
+    );
+  });
+
+  it("does not evaluate flags, emit, or write state when telemetry is off", async () => {
+    process.env.MEM0_TELEMETRY = "false";
+    jest.resetModules();
+
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Telemetry off content", {
+      userId: "first-run-off",
+      infer: false,
+    });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(noticeEvents(calls)).toHaveLength(0);
+    const { __noticeTestHooks } = await import("../src/utils/notices");
+    expect(__noticeTestHooks.loadMem0Config().notice_state).toBeUndefined();
+  });
+
+  it("does not export internal notice test hooks from the public OSS entrypoint", async () => {
+    const publicOssEntry = await import("../src");
+
+    expect(publicOssEntry).not.toHaveProperty("__noticeTestHooks");
+  });
+
+  it("treats uppercase False as telemetry off", async () => {
+    process.env.MEM0_TELEMETRY = "False";
+    jest.resetModules();
+
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Uppercase telemetry off content", {
+      userId: "first-run-off-uppercase",
+      infer: false,
+    });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(noticeEvents(calls)).toHaveLength(0);
+    const { __noticeTestHooks } = await import("../src/utils/notices");
+    expect(__noticeTestHooks.loadMem0Config().notice_state).toBeUndefined();
+  });
+
+  it("does not run after a failed public call", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.add("Missing owner", {} as any)).rejects.toThrow(
+      "One of the filters: userId, agentId or runId is required!",
+    );
+
+    expect(
+      fetchMock.mock.calls.filter(([url]) => String(url).includes("/flags")),
+    ).toHaveLength(0);
+    expect(noticeEvents(calls)).toHaveLength(0);
+  });
+
+  it("does not break the successful operation when flag evaluation fails", async () => {
+    const { fetchMock, calls } = createFetchMock({ failFlags: true });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    const result = await memory.add("Flag failure content", {
+      userId: "first-run-failure",
+      infer: false,
+    });
+
+    expect(result.results).toHaveLength(1);
+    expect(noticeEvents(calls)).toHaveLength(0);
+  });
+
+  it("can trigger from get() when get is the first successful public call", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(memory.get("missing-memory-id")).resolves.toBeNull();
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties.trigger_function).toBe("get");
+  });
+});

mem0-ts/src/oss/tests/notices.foundation.test.ts

@@ -0,0 +1,227 @@
+/// <reference types="jest" />
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import type { TelemetryInstance } from "../src/utils/telemetry.types";
+
+function makeTempMem0Dir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "mem0-node-notices-"));
+}
+
+function makeInstance(
+  overrides: Partial<TelemetryInstance> = {},
+): TelemetryInstance {
+  return {
+    telemetryId: "notice-test-user",
+    constructor: { name: "Memory" },
+    host: "https://test.example.com",
+    ...overrides,
+  };
+}
+
+describe("Node OSS notice foundation", () => {
+  let originalMem0Dir: string | undefined;
+  let originalTelemetry: string | undefined;
+  let originalFetch: typeof global.fetch;
+
+  beforeEach(() => {
+    originalMem0Dir = process.env.MEM0_DIR;
+    originalTelemetry = process.env.MEM0_TELEMETRY;
+    originalFetch = global.fetch;
+    process.env.MEM0_DIR = makeTempMem0Dir();
+    process.env.MEM0_TELEMETRY = "true";
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    if (originalMem0Dir === undefined) delete process.env.MEM0_DIR;
+    else process.env.MEM0_DIR = originalMem0Dir;
+
+    if (originalTelemetry === undefined) delete process.env.MEM0_TELEMETRY;
+    else process.env.MEM0_TELEMETRY = originalTelemetry;
+
+    global.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.resetModules();
+  });
+
+  it("writes notice state into isolated MEM0_DIR config and preserves user_id", async () => {
+    const notices = await import("../src/utils/notices");
+    const configPath = notices.getMem0ConfigPath();
+
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify({ user_id: "existing-user" }));
+
+    expect(
+      notices.recordNoticeOpportunity("foundation_notice", {
+        variant: "displayed",
+      }),
+    ).toBe(true);
+
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    expect(config.user_id).toBe("existing-user");
+    expect(config.notice_state.foundation_notice.events).toHaveLength(1);
+  });
+
+  it("writes config through a temp-file path and leaves no temp file behind", async () => {
+    const notices = await import("../src/utils/notices");
+
+    expect(notices.writeMem0ConfigAtomic({ user_id: "atomic-user" })).toBe(
+      true,
+    );
+
+    const configDir = path.dirname(notices.getMem0ConfigPath());
+    const tempFiles = fs
+      .readdirSync(configDir)
+      .filter((name) => name.endsWith(".tmp"));
+    expect(tempFiles).toHaveLength(0);
+    expect(notices.loadMem0Config().user_id).toBe("atomic-user");
+  });
+
+  it("allows 10 evaluated opportunities in a rolling window and blocks the 11th", async () => {
+    const notices = await import("../src/utils/notices");
+    const now = new Date("2026-06-11T12:00:00.000Z");
+    let state: Record<string, any> = {};
+
+    for (let i = 0; i < 10; i++) {
+      const nextState = notices.appendNoticeCapEvent(
+        state,
+        { variant: "displayed", index: i },
+        { now: new Date(now.getTime() + i) },
+      );
+      expect(nextState).not.toBeNull();
+      state = nextState!;
+    }
+
+    expect(notices.hasNoticeCapRoom(state, { now })).toBe(false);
+    expect(
+      notices.appendNoticeCapEvent(state, { variant: "displayed" }, { now }),
+    ).toBeNull();
+  });
+
+  it("drops old cap events outside the rolling window", async () => {
+    const notices = await import("../src/utils/notices");
+    const oldEvent = {
+      evaluated_at: "2026-06-01T00:00:00.000Z",
+      variant: "displayed",
+    };
+    const now = new Date("2026-06-11T12:00:00.000Z");
+
+    expect(notices.hasNoticeCapRoom({ events: [oldEvent] }, { now })).toBe(
+      true,
+    );
+    const nextState = notices.appendNoticeCapEvent(
+      { events: [oldEvent] },
+      { variant: "displayed" },
+      { now },
+    );
+    expect(nextState?.events).toHaveLength(1);
+  });
+
+  it("does not evaluate flags or write notice state when telemetry is off", async () => {
+    process.env.MEM0_TELEMETRY = "false";
+    jest.resetModules();
+
+    const fetchMock = jest.fn();
+    global.fetch = fetchMock as any;
+    const notices = await import("../src/utils/notices");
+
+    await expect(
+      notices.evaluateNoticeFlag("notice-test-user", { fetchImpl: fetchMock }),
+    ).resolves.toBeNull();
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(
+      notices.recordNoticeOpportunity("foundation_notice", {
+        variant: "displayed",
+      }),
+    ).toBe(false);
+    expect(fs.existsSync(notices.getMem0ConfigPath())).toBe(false);
+  });
+
+  it("returns null when PostHog flag evaluation fails", async () => {
+    const notices = await import("../src/utils/notices");
+    const fetchMock = jest.fn().mockRejectedValue(new Error("network down"));
+
+    await expect(
+      notices.evaluateNoticeFlag("notice-test-user", { fetchImpl: fetchMock }),
+    ).resolves.toBeNull();
+  });
+
+  it("returns null when PostHog flag evaluation times out", async () => {
+    const notices = await import("../src/utils/notices");
+    const fetchMock = jest.fn(
+      (_url: string | URL | Request, init?: RequestInit) =>
+        new Promise((_resolve, reject) => {
+          init?.signal?.addEventListener("abort", () => {
+            reject(new Error("aborted"));
+          });
+        }),
+    );
+
+    await expect(
+      notices.evaluateNoticeFlag("notice-test-user", {
+        fetchImpl: fetchMock as any,
+        timeoutMs: 1,
+      }),
+    ).resolves.toBeNull();
+  });
+
+  it("parses displayed variant and JSON payload from PostHog flags response", async () => {
+    const notices = await import("../src/utils/notices");
+    const payload = {
+      notices: {
+        foundation_notice: {
+          enabled: true,
+          notice_type: "log_line",
+          copy: "Foundation notice",
+        },
+      },
+    };
+    const fetchMock = jest.fn().mockResolvedValue({
+      ok: true,
+      json: jest.fn().mockResolvedValue({
+        flags: {
+          "mem0-oss-notices": {
+            key: "mem0-oss-notices",
+            enabled: true,
+            variant: "displayed",
+            metadata: { payload: JSON.stringify(payload) },
+          },
+        },
+      }),
+    });
+
+    const result = await notices.evaluateNoticeFlag("notice-test-user", {
+      fetchImpl: fetchMock,
+    });
+    expect(result?.variant).toBe("displayed");
+    const parsed = notices.getNoticeConfigFromPayload(
+      result?.payload,
+      "foundation_notice",
+    );
+    expect(parsed.found).toBe(true);
+    expect(parsed.config?.copy).toBe("Foundation notice");
+  });
+
+  it("emits mem0.notice_displayed with sample_rate=1", async () => {
+    const fetchMock = jest.fn().mockResolvedValue({
+      ok: true,
+      text: jest.fn().mockResolvedValue(""),
+    });
+    global.fetch = fetchMock as any;
+    const notices = await import("../src/utils/notices");
+
+    await notices.emitNoticeDisplayed(makeInstance(), {
+      notice_id: "foundation_notice",
+      notice_type: "log_line",
+      flag_key: "mem0-oss-notices",
+      variant: "displayed",
+      displayed: true,
+    });
+
+    const body = JSON.parse(fetchMock.mock.calls[0][1].body);
+    expect(body.event).toBe("mem0.notice_displayed");
+    expect(body.properties.sample_rate).toBe(1);
+    expect(body.properties.notice_id).toBe("foundation_notice");
+  });
+});

mem0-ts/src/oss/tests/notices.performance-slow-query.test.ts

@@ -0,0 +1,492 @@
+/// <reference types="jest" />
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+jest.setTimeout(15000);
+
+jest.mock("../src/embeddings/google", () => ({
+  GoogleEmbedder: jest.fn(),
+}));
+jest.mock("../src/llms/google", () => ({
+  GoogleLLM: jest.fn(),
+}));
+
+const mockEmbedding = new Array(1536).fill(0.1);
+jest.mock("../src/embeddings/openai", () => ({
+  OpenAIEmbedder: jest.fn().mockImplementation(() => ({
+    embed: jest.fn().mockResolvedValue(mockEmbedding),
+    embedBatch: jest
+      .fn()
+      .mockImplementation((texts: string[]) =>
+        Promise.resolve(texts.map(() => mockEmbedding)),
+      ),
+    embeddingDims: 1536,
+  })),
+}));
+
+jest.mock("../src/llms/openai", () => ({
+  OpenAILLM: jest.fn().mockImplementation(() => ({
+    generateResponse: jest.fn(),
+  })),
+}));
+
+const PERFORMANCE_COPY =
+  "Mem0 Platform is optimized for this type of workload. Its retrieval benchmarked at ~0.8-1.09s p50 across LoCoMo, LongMemEval, and BEAM 1M/10M workloads; you can use it for free by getting an API key at: https://app.mem0.ai";
+
+function makeTempMem0Dir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "mem0-node-performance-"));
+}
+
+function configPath(): string {
+  return path.join(process.env.MEM0_DIR as string, "config.json");
+}
+
+function readConfig(): Record<string, any> {
+  const file = configPath();
+  if (!fs.existsSync(file)) return {};
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function writeConfig(config: Record<string, any>) {
+  fs.mkdirSync(path.dirname(configPath()), { recursive: true });
+  fs.writeFileSync(configPath(), JSON.stringify(config, null, 4));
+}
+
+function consumeFirstRun() {
+  writeConfig({
+    user_id: "node-performance-test-user",
+    notice_state: {
+      first_run: {
+        consumed: true,
+        trigger_function: "test_setup",
+        variant: "test",
+      },
+    },
+  });
+}
+
+function performancePayload(overrides: Record<string, any> = {}) {
+  return {
+    notices: {
+      performance_slow_query: {
+        enabled: true,
+        notice_type: "log_line",
+        copy: PERFORMANCE_COPY,
+        ...overrides,
+      },
+    },
+  };
+}
+
+function createFetchMock(options: {
+  variant?: string;
+  payload?: unknown;
+  failFlags?: boolean;
+  flagEnabled?: boolean;
+}) {
+  const calls: any[] = [];
+  const fetchMock = jest.fn(async (url: string | URL, init?: RequestInit) => {
+    const target = String(url);
+
+    if (target.includes("/flags")) {
+      if (options.failFlags) {
+        throw new Error("flag evaluation failed");
+      }
+      const payload =
+        options.payload === undefined
+          ? JSON.stringify(performancePayload())
+          : options.payload;
+      return {
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          flags: {
+            "mem0-oss-notices": {
+              key: "mem0-oss-notices",
+              enabled: options.flagEnabled ?? true,
+              variant: options.variant ?? "displayed",
+              metadata: { payload },
+            },
+          },
+        }),
+      };
+    }
+
+    if (target.includes("/i/v0/e/")) {
+      calls.push(JSON.parse(String(init?.body)));
+      return {
+        ok: true,
+        text: jest.fn().mockResolvedValue(""),
+      };
+    }
+
+    return {
+      ok: true,
+      json: jest.fn().mockResolvedValue({}),
+      text: jest.fn().mockResolvedValue(""),
+    };
+  });
+
+  return { fetchMock, calls };
+}
+
+function noticeEvents(calls: any[]) {
+  return calls.filter((call) => call.event === "mem0.notice_displayed");
+}
+
+function performanceEvents(calls: any[]) {
+  return noticeEvents(calls).filter(
+    (call) => call.properties.notice_id === "performance_slow_query",
+  );
+}
+
+function flagRequestCount(fetchMock: jest.Mock) {
+  return fetchMock.mock.calls.filter(([url]) => String(url).includes("/flags"))
+    .length;
+}
+
+function mockSearchElapsed(elapsedMs: number) {
+  let now = 1000;
+  jest.spyOn(Date, "now").mockImplementation(() => {
+    const current = now;
+    now += elapsedMs;
+    return current;
+  });
+}
+
+async function createMemory() {
+  const { Memory } = await import("../src/memory");
+  return new Memory({
+    version: "v1.1",
+    embedder: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "text-embedding-3-small" },
+    },
+    vectorStore: {
+      provider: "memory",
+      config: {
+        collectionName: `test-performance-${Date.now()}-${Math.random()}`,
+        dimension: 1536,
+        dbPath: ":memory:",
+      },
+    },
+    llm: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "gpt-5-mini" },
+    },
+    historyDbPath: ":memory:",
+  });
+}
+
+async function addSeed(memory: any, userId = "performance-user") {
+  await memory.add("The user's favorite drink is green tea.", {
+    userId,
+    infer: false,
+  });
+}
+
+describe("Node OSS performance slow query notice", () => {
+  let originalMem0Dir: string | undefined;
+  let originalTelemetry: string | undefined;
+  let originalSampleRate: string | undefined;
+  let originalFetch: typeof global.fetch;
+  let stderrSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    originalMem0Dir = process.env.MEM0_DIR;
+    originalTelemetry = process.env.MEM0_TELEMETRY;
+    originalSampleRate = process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    originalFetch = global.fetch;
+
+    process.env.MEM0_DIR = makeTempMem0Dir();
+    process.env.MEM0_TELEMETRY = "true";
+    process.env.MEM0_TELEMETRY_SAMPLE_RATE = "1";
+    stderrSpy = jest
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    if (originalMem0Dir === undefined) delete process.env.MEM0_DIR;
+    else process.env.MEM0_DIR = originalMem0Dir;
+
+    if (originalTelemetry === undefined) delete process.env.MEM0_TELEMETRY;
+    else process.env.MEM0_TELEMETRY = originalTelemetry;
+
+    if (originalSampleRate === undefined) {
+      delete process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    } else {
+      process.env.MEM0_TELEMETRY_SAMPLE_RATE = originalSampleRate;
+    }
+
+    global.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.resetModules();
+  });
+
+  it("displays and emits safe fields after a slow successful search", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSeed(memory);
+    stderrSpy.mockClear();
+    mockSearchElapsed(2345);
+
+    const result = await memory.search("favorite drink private text", {
+      filters: { user_id: "performance-user" },
+      topK: 3,
+    });
+
+    expect(result.results.length).toBeGreaterThan(0);
+    expect(stderrSpy).toHaveBeenCalledWith(`${PERFORMANCE_COPY}\n`);
+    const event = performanceEvents(calls)[0];
+    expect(event.properties).toEqual(
+      expect.objectContaining({
+        notice_id: "performance_slow_query",
+        notice_type: "log_line",
+        flag_key: "mem0-oss-notices",
+        variant: "displayed",
+        displayed: true,
+        payload: PERFORMANCE_COPY,
+        notice_config_found: true,
+        sync_type: "async",
+        trigger_function: "search",
+        trigger_reason: "slow_query",
+        elapsed_ms: 2345,
+        threshold_ms: 2000,
+        top_k: 3,
+        result_count: result.results.length,
+        sample_rate: 1,
+      }),
+    );
+    const serialized = JSON.stringify(event.properties);
+    expect(serialized).not.toContain("private text");
+    expect(serialized).not.toContain("performance-user");
+  });
+
+  it("is silent for holdout and emits displayed=false", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "holdout" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSeed(memory);
+    stderrSpy.mockClear();
+    mockSearchElapsed(2345);
+
+    await memory.search("favorite drink", {
+      filters: { user_id: "performance-user" },
+      topK: 3,
+    });
+
+    expect(stderrSpy).not.toHaveBeenCalled();
+    expect(performanceEvents(calls)[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "performance_slow_query",
+        variant: "holdout",
+        displayed: false,
+        bypass_reason: "holdout",
+      }),
+    );
+  });
+
+  it.each([
+    [
+      "disabled payload",
+      JSON.stringify(performancePayload({ enabled: false })),
+      "payload_disabled",
+    ],
+    [
+      "missing config",
+      JSON.stringify({ notices: {} }),
+      "missing_notice_config",
+    ],
+    [
+      "missing copy",
+      JSON.stringify(performancePayload({ copy: "" })),
+      "missing_copy",
+    ],
+    ["malformed payload", "{not-json", "missing_notice_config"],
+  ])("is silent and safe for %s", async (_label, payload, bypassReason) => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      payload,
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSeed(memory);
+    stderrSpy.mockClear();
+    mockSearchElapsed(2345);
+
+    await memory.search("favorite drink", {
+      filters: { user_id: "performance-user" },
+      topK: 3,
+    });
+
+    expect(stderrSpy).not.toHaveBeenCalled();
+    expect(performanceEvents(calls)[0].properties).toEqual(
+      expect.objectContaining({
+        displayed: false,
+        bypass_reason: bypassReason,
+      }),
+    );
+  });
+
+  it("does not evaluate fast searches", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSeed(memory);
+    mockSearchElapsed(100);
+
+    await memory.search("favorite drink", {
+      filters: { user_id: "performance-user" },
+      topK: 3,
+    });
+
+    expect(flagRequestCount(fetchMock)).toBe(0);
+    expect(performanceEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.performance_slow_query).toBeUndefined();
+  });
+
+  it("does not evaluate failed searches", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    mockSearchElapsed(2345);
+
+    await expect(
+      memory.search("private slow query", {
+        filters: {},
+        topK: 3,
+      }),
+    ).rejects.toThrow("filters must contain");
+
+    expect(flagRequestCount(fetchMock)).toBe(0);
+    expect(performanceEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.performance_slow_query).toBeUndefined();
+  });
+
+  it("does not consume cap or emit when the blunt flag is disabled", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      flagEnabled: false,
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSeed(memory);
+    mockSearchElapsed(2345);
+
+    await memory.search("favorite drink", {
+      filters: { user_id: "performance-user" },
+      topK: 3,
+    });
+
+    expect(performanceEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.performance_slow_query).toBeUndefined();
+  });
+
+  it("does not consume cap or emit when PostHog fails", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ failFlags: true });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSeed(memory);
+    mockSearchElapsed(2345);
+
+    await memory.search("favorite drink", {
+      filters: { user_id: "performance-user" },
+      topK: 3,
+    });
+
+    expect(performanceEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.performance_slow_query).toBeUndefined();
+  });
+
+  it("does nothing when telemetry is off", async () => {
+    process.env.MEM0_TELEMETRY = "false";
+    jest.resetModules();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSeed(memory);
+    mockSearchElapsed(2345);
+
+    await memory.search("favorite drink", {
+      filters: { user_id: "performance-user" },
+      topK: 3,
+    });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(performanceEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state).toBeUndefined();
+  });
+
+  it("caps evaluated opportunities at 10 per rolling week", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSeed(memory);
+    stderrSpy.mockClear();
+    mockSearchElapsed(2345);
+
+    for (let index = 1; index <= 11; index++) {
+      await memory.search(`favorite drink ${index}`, {
+        filters: { user_id: "performance-user" },
+        topK: 3,
+      });
+    }
+
+    expect(performanceEvents(calls)).toHaveLength(10);
+    expect(flagRequestCount(fetchMock)).toBe(10);
+    expect(stderrSpy).toHaveBeenCalledTimes(10);
+    expect(
+      readConfig().notice_state.performance_slow_query.events,
+    ).toHaveLength(10);
+  });
+
+  it("lets temporal usage and scale threshold take priority", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSeed(memory);
+    mockSearchElapsed(2345);
+
+    await memory.search("what happened last week?", {
+      filters: { user_id: "performance-user" },
+      topK: 3,
+    });
+    await memory.search("favorite drink", {
+      filters: { user_id: "performance-user" },
+      topK: 50,
+    });
+
+    expect(performanceEvents(calls)).toHaveLength(0);
+    const noticeIds = noticeEvents(calls).map(
+      (call) => call.properties.notice_id,
+    );
+    expect(noticeIds).toEqual(["temporal_usage", "scale_threshold"]);
+  });
+
+  it("does not consume first-run on the same qualifying performance call", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    mockSearchElapsed(2345);
+
+    await memory.search("favorite drink", {
+      filters: { user_id: "performance-user" },
+      topK: 3,
+    });
+
+    expect(performanceEvents(calls)).toHaveLength(1);
+    expect(readConfig().notice_state.first_run).toBeUndefined();
+  });
+});

mem0-ts/src/oss/tests/notices.scale-threshold.test.ts

@@ -0,0 +1,463 @@
+/// <reference types="jest" />
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+jest.setTimeout(15000);
+
+jest.mock("../src/embeddings/google", () => ({
+  GoogleEmbedder: jest.fn(),
+}));
+jest.mock("../src/llms/google", () => ({
+  GoogleLLM: jest.fn(),
+}));
+
+const mockEmbedding = new Array(1536).fill(0.1);
+jest.mock("../src/embeddings/openai", () => ({
+  OpenAIEmbedder: jest.fn().mockImplementation(() => ({
+    embed: jest.fn().mockResolvedValue(mockEmbedding),
+    embedBatch: jest
+      .fn()
+      .mockImplementation((texts: string[]) =>
+        Promise.resolve(texts.map(() => mockEmbedding)),
+      ),
+    embeddingDims: 1536,
+  })),
+}));
+
+jest.mock("../src/llms/openai", () => ({
+  OpenAILLM: jest.fn().mockImplementation(() => ({
+    generateResponse: jest.fn(),
+  })),
+}));
+
+const SCALE_TOP_K_COPY = "Scale top {top_k}";
+const SCALE_MEMORY_COUNT_COPY = "Scale count {memory_count}";
+
+function makeTempMem0Dir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "mem0-node-scale-"));
+}
+
+function configPath(): string {
+  return path.join(process.env.MEM0_DIR as string, "config.json");
+}
+
+function readConfig(): Record<string, any> {
+  const file = configPath();
+  if (!fs.existsSync(file)) return {};
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function writeConfig(config: Record<string, any>) {
+  fs.mkdirSync(path.dirname(configPath()), { recursive: true });
+  fs.writeFileSync(configPath(), JSON.stringify(config, null, 4));
+}
+
+function consumeFirstRun(scaleState: Record<string, any> = {}) {
+  writeConfig({
+    user_id: "node-scale-test-user",
+    notice_state: {
+      first_run: {
+        consumed: true,
+        trigger_function: "test_setup",
+        variant: "test",
+      },
+      ...(Object.keys(scaleState).length > 0 && {
+        scale_threshold: scaleState,
+      }),
+    },
+  });
+}
+
+function scalePayload(overrides: Record<string, any> = {}) {
+  return {
+    notices: {
+      scale_threshold: {
+        enabled: true,
+        notice_type: "log_line",
+        copies: {
+          top_k: SCALE_TOP_K_COPY,
+          memory_count: SCALE_MEMORY_COUNT_COPY,
+        },
+        ...overrides,
+      },
+    },
+  };
+}
+
+function createFetchMock(options: {
+  variant?: string;
+  payload?: unknown;
+  failFlags?: boolean;
+  flagEnabled?: boolean;
+}) {
+  const calls: any[] = [];
+  const fetchMock = jest.fn(async (url: string | URL, init?: RequestInit) => {
+    const target = String(url);
+
+    if (target.includes("/flags")) {
+      if (options.failFlags) {
+        throw new Error("flag evaluation failed");
+      }
+      const payload =
+        options.payload === undefined
+          ? JSON.stringify(scalePayload())
+          : options.payload;
+      return {
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          flags: {
+            "mem0-oss-notices": {
+              key: "mem0-oss-notices",
+              enabled: options.flagEnabled ?? true,
+              variant: options.variant ?? "displayed",
+              metadata: { payload },
+            },
+          },
+        }),
+      };
+    }
+
+    if (target.includes("/i/v0/e/")) {
+      calls.push(JSON.parse(String(init?.body)));
+      return {
+        ok: true,
+        text: jest.fn().mockResolvedValue(""),
+      };
+    }
+
+    return {
+      ok: true,
+      json: jest.fn().mockResolvedValue({}),
+      text: jest.fn().mockResolvedValue(""),
+    };
+  });
+
+  return { fetchMock, calls };
+}
+
+function noticeEvents(calls: any[]) {
+  return calls.filter((call) => call.event === "mem0.notice_displayed");
+}
+
+function scaleEvents(calls: any[]) {
+  return noticeEvents(calls).filter(
+    (call) => call.properties.notice_id === "scale_threshold",
+  );
+}
+
+function flagRequestCount(fetchMock: jest.Mock) {
+  return fetchMock.mock.calls.filter(([url]) => String(url).includes("/flags"))
+    .length;
+}
+
+async function createMemory() {
+  const { Memory } = await import("../src/memory");
+  return new Memory({
+    version: "v1.1",
+    embedder: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "text-embedding-3-small" },
+    },
+    vectorStore: {
+      provider: "memory",
+      config: {
+        collectionName: `test-scale-${Date.now()}-${Math.random()}`,
+        dimension: 1536,
+        dbPath: ":memory:",
+      },
+    },
+    llm: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "gpt-5-mini" },
+    },
+    historyDbPath: ":memory:",
+  });
+}
+
+async function addSeed(memory: any, userId = "scale-user") {
+  await memory.add("The user's favorite drink is green tea.", {
+    userId,
+    infer: false,
+  });
+}
+
+describe("Node OSS scale threshold notice", () => {
+  let originalMem0Dir: string | undefined;
+  let originalTelemetry: string | undefined;
+  let originalSampleRate: string | undefined;
+  let originalFetch: typeof global.fetch;
+  let stderrSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    originalMem0Dir = process.env.MEM0_DIR;
+    originalTelemetry = process.env.MEM0_TELEMETRY;
+    originalSampleRate = process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    originalFetch = global.fetch;
+
+    process.env.MEM0_DIR = makeTempMem0Dir();
+    process.env.MEM0_TELEMETRY = "true";
+    process.env.MEM0_TELEMETRY_SAMPLE_RATE = "1";
+    stderrSpy = jest
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    if (originalMem0Dir === undefined) delete process.env.MEM0_DIR;
+    else process.env.MEM0_DIR = originalMem0Dir;
+
+    if (originalTelemetry === undefined) delete process.env.MEM0_TELEMETRY;
+    else process.env.MEM0_TELEMETRY = originalTelemetry;
+
+    if (originalSampleRate === undefined) {
+      delete process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    } else {
+      process.env.MEM0_TELEMETRY_SAMPLE_RATE = originalSampleRate;
+    }
+
+    global.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.resetModules();
+  });
+
+  it("detects high topK after successful search", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await addSeed(memory);
+    stderrSpy.mockClear();
+    const result = await memory.search("favorite drink private text", {
+      filters: { user_id: "scale-user" },
+      topK: 50,
+    });
+
+    expect(result.results.length).toBeGreaterThan(0);
+    expect(stderrSpy).toHaveBeenCalledWith("Scale top 50\n");
+    const event = scaleEvents(calls)[0];
+    expect(event.properties).toMatchObject({
+      notice_id: "scale_threshold",
+      displayed: true,
+      trigger_function: "search",
+      trigger_source: "top_k",
+      trigger_reason: "high_top_k",
+      top_k: 50,
+      threshold: 50,
+      sample_rate: 1,
+    });
+    expect(JSON.stringify(event.properties)).not.toContain("private text");
+  });
+
+  it("detects high topK after successful getAll", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await addSeed(memory);
+    stderrSpy.mockClear();
+    const result = await memory.getAll({
+      filters: { user_id: "scale-user" },
+      topK: 50,
+    });
+
+    expect(result.results.length).toBeGreaterThan(0);
+    expect(stderrSpy).toHaveBeenCalledWith("Scale top 50\n");
+    const event = scaleEvents(calls)[0];
+    expect(event.properties).toMatchObject({
+      notice_id: "scale_threshold",
+      displayed: true,
+      trigger_function: "get_all",
+      trigger_source: "top_k",
+      trigger_reason: "high_top_k",
+      top_k: 50,
+      threshold: 50,
+    });
+  });
+
+  it("does not evaluate topK below the threshold", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await addSeed(memory);
+    await memory.search("favorite drink", {
+      filters: { user_id: "scale-user" },
+      topK: 49,
+    });
+
+    expect(flagRequestCount(fetchMock)).toBe(0);
+    expect(scaleEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.scale_threshold).toBeUndefined();
+  });
+
+  it("marks memory-count threshold evaluated before PostHog display", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ failFlags: true });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    (memory as any).vectorStore.count = jest
+      .fn()
+      .mockResolvedValue({ count: 2000 });
+
+    await memory.add("Scale count threshold fixture.", {
+      userId: "scale-user",
+      infer: false,
+    });
+
+    expect((memory as any).vectorStore.count).toHaveBeenCalledTimes(1);
+    expect(
+      readConfig().notice_state.scale_threshold
+        .memory_count_threshold_evaluated,
+    ).toBe(true);
+    expect(scaleEvents(calls)).toHaveLength(0);
+  });
+
+  it("does not count provider memories once threshold was evaluated", async () => {
+    consumeFirstRun({ memory_count_threshold_evaluated: true });
+    const { fetchMock } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    (memory as any).vectorStore.count = jest
+      .fn()
+      .mockResolvedValue({ count: 2000 });
+
+    await memory.add("Scale count already evaluated fixture.", {
+      userId: "scale-user",
+      infer: false,
+    });
+
+    expect((memory as any).vectorStore.count).not.toHaveBeenCalled();
+    expect(flagRequestCount(fetchMock)).toBe(0);
+  });
+
+  it("throttles under-threshold provider counts", async () => {
+    consumeFirstRun();
+    const { fetchMock } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    (memory as any).vectorStore.count = jest
+      .fn()
+      .mockResolvedValue({ count: 1999 });
+
+    await memory.add("Scale count under threshold one.", {
+      userId: "scale-user",
+      infer: false,
+    });
+    await memory.add("Scale count under threshold two.", {
+      userId: "scale-user",
+      infer: false,
+    });
+
+    expect((memory as any).vectorStore.count).toHaveBeenCalledTimes(1);
+    expect(flagRequestCount(fetchMock)).toBe(0);
+  });
+
+  it("records holdout and disabled variants silently", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({
+      variant: "holdout",
+      payload: JSON.stringify(scalePayload({ enabled: false })),
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await addSeed(memory);
+    stderrSpy.mockClear();
+    await memory.search("favorite drink", {
+      filters: { user_id: "scale-user" },
+      topK: 50,
+    });
+
+    expect(stderrSpy).not.toHaveBeenCalled();
+    const event = scaleEvents(calls)[0];
+    expect(event.properties).toMatchObject({
+      displayed: false,
+      bypass_reason: "payload_disabled",
+      disabled_reason: "payload_disabled",
+      variant: "holdout",
+    });
+  });
+
+  it("treats missing enabled as enabled for scale payloads", async () => {
+    consumeFirstRun();
+    const payload = scalePayload();
+    delete (payload.notices.scale_threshold as Record<string, any>).enabled;
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      payload: JSON.stringify(payload),
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await addSeed(memory);
+    stderrSpy.mockClear();
+    await memory.search("favorite drink", {
+      filters: { user_id: "scale-user" },
+      topK: 50,
+    });
+
+    expect(stderrSpy.mock.calls.flat().join("")).toContain("Scale top 50");
+    expect(scaleEvents(calls)[0].properties).toMatchObject({
+      notice_id: "scale_threshold",
+      displayed: true,
+      payload: "Scale top 50",
+    });
+  });
+
+  it("caps evaluated scale opportunities at 10 per week", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await addSeed(memory);
+    stderrSpy.mockClear();
+    for (let index = 0; index < 11; index++) {
+      await memory.search(`favorite drink ${index}`, {
+        filters: { user_id: "scale-user" },
+        topK: 50,
+      });
+    }
+
+    expect(scaleEvents(calls)).toHaveLength(10);
+    expect(flagRequestCount(fetchMock)).toBe(10);
+    expect(stderrSpy).toHaveBeenCalledTimes(10);
+    expect(readConfig().notice_state.scale_threshold.events).toHaveLength(10);
+  });
+
+  it("does not consume first-run on the same qualifying scale call", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.getAll({
+      filters: { user_id: "scale-user" },
+      topK: 50,
+    });
+
+    expect(scaleEvents(calls)).toHaveLength(1);
+    expect(readConfig().notice_state?.first_run).toBeUndefined();
+  });
+
+  it("telemetry off skips flag evaluation, event emission, and state writes", async () => {
+    process.env.MEM0_TELEMETRY = "false";
+    jest.resetModules();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.getAll({
+      filters: { user_id: "scale-user" },
+      topK: 50,
+    });
+
+    expect(flagRequestCount(fetchMock)).toBe(0);
+    expect(scaleEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state).toBeUndefined();
+  });
+});

mem0-ts/src/oss/tests/notices.temporal-feature.test.ts

@@ -0,0 +1,516 @@
+/// <reference types="jest" />
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+jest.setTimeout(15000);
+
+jest.mock("../src/embeddings/google", () => ({
+  GoogleEmbedder: jest.fn(),
+}));
+jest.mock("../src/llms/google", () => ({
+  GoogleLLM: jest.fn(),
+}));
+
+const mockEmbedding = new Array(1536).fill(0.1);
+const mockEmbed = jest.fn().mockResolvedValue(mockEmbedding);
+const mockEmbedBatch = jest
+  .fn()
+  .mockImplementation((texts: string[]) =>
+    Promise.resolve(texts.map(() => mockEmbedding)),
+  );
+
+jest.mock("../src/embeddings/openai", () => ({
+  OpenAIEmbedder: jest.fn().mockImplementation(() => ({
+    embed: mockEmbed,
+    embedBatch: mockEmbedBatch,
+    embeddingDims: 1536,
+  })),
+}));
+
+const mockGenerateResponse = jest.fn();
+jest.mock("../src/llms/openai", () => ({
+  OpenAILLM: jest.fn().mockImplementation(() => ({
+    generateResponse: mockGenerateResponse,
+  })),
+}));
+
+const TEMPORAL_COPY =
+  "Temporal reasoning requires a Mem0 API key. Get one for free at https://app.mem0.ai";
+const PLAIN_TIMESTAMP_ERROR =
+  "The timestamp parameter is not supported by the OSS Memory SDK.";
+const PLAIN_REFERENCE_DATE_ERROR =
+  "The referenceDate parameter is not supported by the OSS Memory SDK.";
+
+function makeTempMem0Dir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "mem0-node-temporal-feature-"));
+}
+
+function temporalPayload(overrides: Record<string, any> = {}) {
+  return {
+    notices: {
+      temporal_stub: {
+        enabled: true,
+        notice_type: "error",
+        copy: TEMPORAL_COPY,
+        ...overrides,
+      },
+    },
+  };
+}
+
+function createFetchMock(options: {
+  variant?: string;
+  payload?: unknown;
+  failFlags?: boolean;
+  flagEnabled?: boolean;
+}) {
+  const calls: any[] = [];
+  const fetchMock = jest.fn(async (url: string | URL, init?: RequestInit) => {
+    const target = String(url);
+
+    if (target.includes("/flags")) {
+      if (options.failFlags) {
+        throw new Error("flag evaluation failed");
+      }
+      return {
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          flags: {
+            "mem0-oss-notices": {
+              key: "mem0-oss-notices",
+              enabled: options.flagEnabled ?? true,
+              variant: options.variant ?? "displayed",
+              metadata: {
+                payload:
+                  options.payload === undefined
+                    ? JSON.stringify(temporalPayload())
+                    : options.payload,
+              },
+            },
+          },
+        }),
+      };
+    }
+
+    if (target.includes("/i/v0/e/")) {
+      calls.push(JSON.parse(String(init?.body)));
+      return {
+        ok: true,
+        text: jest.fn().mockResolvedValue(""),
+      };
+    }
+
+    return {
+      ok: true,
+      json: jest.fn().mockResolvedValue({}),
+      text: jest.fn().mockResolvedValue(""),
+    };
+  });
+
+  return { fetchMock, calls };
+}
+
+function noticeEvents(calls: any[]) {
+  return calls.filter((call) => call.event === "mem0.notice_displayed");
+}
+
+async function createMemory() {
+  const { Memory } = await import("../src/memory");
+  return new Memory({
+    version: "v1.1",
+    embedder: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "text-embedding-3-small" },
+    },
+    vectorStore: {
+      provider: "memory",
+      config: {
+        collectionName: `test-temporal-feature-${Date.now()}-${Math.random()}`,
+        dimension: 1536,
+        dbPath: ":memory:",
+      },
+    },
+    llm: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "gpt-5-mini" },
+    },
+    historyDbPath: ":memory:",
+  });
+}
+
+describe("Node OSS temporal feature error notice", () => {
+  let originalMem0Dir: string | undefined;
+  let originalTelemetry: string | undefined;
+  let originalSampleRate: string | undefined;
+  let originalFetch: typeof global.fetch;
+
+  beforeEach(() => {
+    originalMem0Dir = process.env.MEM0_DIR;
+    originalTelemetry = process.env.MEM0_TELEMETRY;
+    originalSampleRate = process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    originalFetch = global.fetch;
+
+    process.env.MEM0_DIR = makeTempMem0Dir();
+    process.env.MEM0_TELEMETRY = "true";
+    process.env.MEM0_TELEMETRY_SAMPLE_RATE = "1";
+    mockEmbed.mockClear();
+    mockEmbedBatch.mockClear();
+    mockGenerateResponse.mockClear();
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    if (originalMem0Dir === undefined) delete process.env.MEM0_DIR;
+    else process.env.MEM0_DIR = originalMem0Dir;
+
+    if (originalTelemetry === undefined) delete process.env.MEM0_TELEMETRY;
+    else process.env.MEM0_TELEMETRY = originalTelemetry;
+
+    if (originalSampleRate === undefined) {
+      delete process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    } else {
+      process.env.MEM0_TELEMETRY_SAMPLE_RATE = originalSampleRate;
+    }
+
+    global.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.resetModules();
+  });
+
+  it.each([
+    ["add", "timestamp"],
+    ["search", "referenceDate"],
+  ])(
+    "raises CTA copy for displayed %s(%s) and emits displayed=true",
+    async (triggerFunction, triggerParameter) => {
+      const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+      global.fetch = fetchMock as any;
+      const memory = await createMemory();
+
+      if (triggerFunction === "add") {
+        await expect(
+          memory.add("Temporal add", {
+            userId: "temporal-user",
+            timestamp: 1778112000,
+          }),
+        ).rejects.toThrow(TEMPORAL_COPY);
+      } else {
+        await expect(
+          memory.search("Temporal search", {
+            filters: { user_id: "temporal-user" },
+            referenceDate: "2026-05-06",
+          }),
+        ).rejects.toThrow(TEMPORAL_COPY);
+      }
+
+      const notices = noticeEvents(calls);
+      expect(notices).toHaveLength(1);
+      expect(notices[0].properties).toEqual(
+        expect.objectContaining({
+          notice_id: "temporal_stub",
+          notice_type: "error",
+          flag_key: "mem0-oss-notices",
+          variant: "displayed",
+          displayed: true,
+          payload: TEMPORAL_COPY,
+          notice_config_found: true,
+          sync_type: "async",
+          trigger_function: triggerFunction,
+          trigger_parameter: triggerParameter,
+          sample_rate: 1,
+        }),
+      );
+    },
+  );
+
+  it.each([
+    ["add", "timestamp"],
+    ["search", "referenceDate"],
+  ])(
+    "raises CTA copy for holdout %s(%s) and emits displayed=true",
+    async (triggerFunction, triggerParameter) => {
+      const { fetchMock, calls } = createFetchMock({ variant: "holdout" });
+      global.fetch = fetchMock as any;
+      const memory = await createMemory();
+
+      if (triggerFunction === "add") {
+        await expect(
+          memory.add("Temporal add", {
+            userId: "temporal-user",
+            timestamp: null,
+          }),
+        ).rejects.toThrow(TEMPORAL_COPY);
+      } else {
+        await expect(
+          memory.search("Temporal search", {
+            filters: { user_id: "temporal-user" },
+            referenceDate: null,
+          }),
+        ).rejects.toThrow(TEMPORAL_COPY);
+      }
+
+      const notices = noticeEvents(calls);
+      expect(notices).toHaveLength(1);
+      expect(notices[0].properties).toEqual(
+        expect.objectContaining({
+          notice_id: "temporal_stub",
+          variant: "holdout",
+          displayed: true,
+          trigger_function: triggerFunction,
+          trigger_parameter: triggerParameter,
+        }),
+      );
+      expect(notices[0].properties.bypass_reason).toBeUndefined();
+    },
+  );
+
+  it("uses plain error for unknown future variants and emits not_displayed", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "silent" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(
+      memory.add("Temporal add", {
+        userId: "temporal-user",
+        timestamp: 1778112000,
+      }),
+    ).rejects.toThrow(PLAIN_TIMESTAMP_ERROR);
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "temporal_stub",
+        variant: "silent",
+        displayed: false,
+        bypass_reason: "not_displayed",
+        payload: TEMPORAL_COPY,
+      }),
+    );
+  });
+
+  it("treats missing enabled as enabled for feature-error payloads", async () => {
+    const payload = temporalPayload();
+    delete (payload.notices.temporal_stub as Record<string, any>).enabled;
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      payload: JSON.stringify(payload),
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(
+      memory.add("Temporal add", {
+        userId: "temporal-user",
+        timestamp: 1778112000,
+      }),
+    ).rejects.toThrow(TEMPORAL_COPY);
+
+    expect(noticeEvents(calls)[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "temporal_stub",
+        displayed: true,
+        payload: TEMPORAL_COPY,
+      }),
+    );
+  });
+
+  it("uses timestamp plain error for disabled payload and emits payload_disabled", async () => {
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      payload: JSON.stringify(temporalPayload({ enabled: false })),
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(
+      memory.add("Temporal add", {
+        userId: "temporal-user",
+        timestamp: 1778112000,
+      }),
+    ).rejects.toThrow(PLAIN_TIMESTAMP_ERROR);
+
+    const notices = noticeEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "temporal_stub",
+        displayed: false,
+        bypass_reason: "payload_disabled",
+        disabled_reason: "payload_disabled",
+        notice_config_found: true,
+        trigger_function: "add",
+        trigger_parameter: "timestamp",
+      }),
+    );
+  });
+
+  it.each([
+    [
+      "missing config",
+      JSON.stringify({ notices: {} }),
+      "missing_notice_config",
+    ],
+    [
+      "missing copy",
+      JSON.stringify(temporalPayload({ copy: "" })),
+      "missing_copy",
+    ],
+    ["malformed payload", "{not-json", "missing_notice_config"],
+  ])(
+    "uses referenceDate plain error for %s",
+    async (_label, payload, bypassReason) => {
+      const { fetchMock, calls } = createFetchMock({
+        variant: "displayed",
+        payload,
+      });
+      global.fetch = fetchMock as any;
+      const memory = await createMemory();
+
+      await expect(
+        memory.search("Temporal search", {
+          filters: { user_id: "temporal-user" },
+          referenceDate: "2026-05-06",
+        }),
+      ).rejects.toThrow(PLAIN_REFERENCE_DATE_ERROR);
+
+      const notices = noticeEvents(calls);
+      expect(notices).toHaveLength(1);
+      expect(notices[0].properties).toEqual(
+        expect.objectContaining({
+          notice_id: "temporal_stub",
+          displayed: false,
+          bypass_reason: bypassReason,
+          trigger_function: "search",
+          trigger_parameter: "referenceDate",
+        }),
+      );
+    },
+  );
+
+  it("uses plain error and emits no event when the blunt flag is disabled", async () => {
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      flagEnabled: false,
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(
+      memory.add("Temporal add", {
+        userId: "temporal-user",
+        timestamp: 1778112000,
+      }),
+    ).rejects.toThrow(PLAIN_TIMESTAMP_ERROR);
+
+    expect(noticeEvents(calls)).toHaveLength(0);
+  });
+
+  it("uses plain error and emits no event when PostHog fails", async () => {
+    const { fetchMock, calls } = createFetchMock({ failFlags: true });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(
+      memory.search("Temporal search", {
+        filters: { user_id: "temporal-user" },
+        referenceDate: "2026-05-06",
+      }),
+    ).rejects.toThrow(PLAIN_REFERENCE_DATE_ERROR);
+
+    expect(noticeEvents(calls)).toHaveLength(0);
+  });
+
+  it("uses plain error and skips flag evaluation when telemetry is off", async () => {
+    process.env.MEM0_TELEMETRY = "False";
+    jest.resetModules();
+
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(
+      memory.add("Temporal add", {
+        userId: "temporal-user",
+        timestamp: 1778112000,
+      }),
+    ).rejects.toThrow(PLAIN_TIMESTAMP_ERROR);
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(noticeEvents(calls)).toHaveLength(0);
+  });
+
+  it("throws before add validation, normal telemetry, embeddings, and first-run", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    const addToVectorStoreSpy = jest.spyOn(memory as any, "addToVectorStore");
+
+    await expect(
+      memory.add(
+        undefined as any,
+        {
+          timestamp: 1778112000,
+        } as any,
+      ),
+    ).rejects.toThrow(TEMPORAL_COPY);
+
+    expect(mockEmbed).not.toHaveBeenCalled();
+    expect(addToVectorStoreSpy).not.toHaveBeenCalled();
+    expect(calls.map((call) => call.event)).not.toContain("mem0.add");
+    expect(
+      noticeEvents(calls).some(
+        (call) => call.properties.notice_id === "first_run",
+      ),
+    ).toBe(false);
+  });
+
+  it("throws before search validation, normal telemetry, embeddings, and first-run", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(
+      memory.search("Temporal search", {
+        userId: "invalid-top-level-user",
+        referenceDate: "2026-05-06",
+      } as any),
+    ).rejects.toThrow(TEMPORAL_COPY);
+
+    expect(mockEmbed).not.toHaveBeenCalled();
+    expect(calls.map((call) => call.event)).not.toContain("mem0.search");
+    expect(
+      noticeEvents(calls).some(
+        (call) => call.properties.notice_id === "first_run",
+      ),
+    ).toBe(false);
+  });
+
+  it("leaves normal add/search calls unchanged when temporal options are omitted", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "holdout" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    const addResult = await memory.add("Normal add", {
+      userId: "normal-user",
+      infer: false,
+    });
+    expect(addResult.results).toHaveLength(1);
+
+    const searchResult = await memory.search("Normal add", {
+      filters: { user_id: "normal-user" },
+      topK: 3,
+    });
+    expect(searchResult.results.length).toBeGreaterThanOrEqual(0);
+
+    const eventNames = calls.map((call) => call.event);
+    expect(eventNames).toContain("mem0.add");
+    expect(eventNames).toContain("mem0.search");
+    expect(
+      noticeEvents(calls).some(
+        (call) => call.properties.notice_id === "temporal_stub",
+      ),
+    ).toBe(false);
+  });
+});

mem0-ts/src/oss/tests/notices.temporal-usage.test.ts

@@ -0,0 +1,594 @@
+/// <reference types="jest" />
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+jest.setTimeout(15000);
+
+jest.mock("../src/embeddings/google", () => ({
+  GoogleEmbedder: jest.fn(),
+}));
+jest.mock("../src/llms/google", () => ({
+  GoogleLLM: jest.fn(),
+}));
+
+const mockEmbedding = new Array(1536).fill(0.1);
+jest.mock("../src/embeddings/openai", () => ({
+  OpenAIEmbedder: jest.fn().mockImplementation(() => ({
+    embed: jest.fn().mockResolvedValue(mockEmbedding),
+    embedBatch: jest
+      .fn()
+      .mockImplementation((texts: string[]) =>
+        Promise.resolve(texts.map(() => mockEmbedding)),
+      ),
+    embeddingDims: 1536,
+  })),
+}));
+
+jest.mock("../src/llms/openai", () => ({
+  OpenAILLM: jest.fn().mockImplementation(() => ({
+    generateResponse: jest.fn(),
+  })),
+}));
+
+const TEMPORAL_USAGE_COPY =
+  "This looks like a time-aware memory workflow. Mem0 Platform has temporal reasoning built in. Use `timestamp` when adding memories and `reference_date` when searching.";
+
+function makeTempMem0Dir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "mem0-node-temporal-usage-"));
+}
+
+function configPath(): string {
+  return path.join(process.env.MEM0_DIR as string, "config.json");
+}
+
+function readConfig(): Record<string, any> {
+  const file = configPath();
+  if (!fs.existsSync(file)) return {};
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function writeConfig(config: Record<string, any>) {
+  fs.mkdirSync(path.dirname(configPath()), { recursive: true });
+  fs.writeFileSync(configPath(), JSON.stringify(config, null, 4));
+}
+
+function consumeFirstRun() {
+  writeConfig({
+    user_id: "node-temporal-usage-test-user",
+    notice_state: {
+      first_run: {
+        consumed: true,
+        trigger_function: "test_setup",
+        variant: "test",
+      },
+    },
+  });
+}
+
+function temporalUsagePayload(overrides: Record<string, any> = {}) {
+  return {
+    notices: {
+      temporal_usage: {
+        enabled: true,
+        notice_type: "log_line",
+        copy: TEMPORAL_USAGE_COPY,
+        ...overrides,
+      },
+    },
+  };
+}
+
+function createFetchMock(options: {
+  variant?: string;
+  payload?: unknown;
+  failFlags?: boolean;
+  flagEnabled?: boolean;
+}) {
+  const calls: any[] = [];
+  const fetchMock = jest.fn(async (url: string | URL, init?: RequestInit) => {
+    const target = String(url);
+
+    if (target.includes("/flags")) {
+      if (options.failFlags) {
+        throw new Error("flag evaluation failed");
+      }
+      const payload =
+        options.payload === undefined
+          ? JSON.stringify(temporalUsagePayload())
+          : options.payload;
+      return {
+        ok: true,
+        json: jest.fn().mockResolvedValue({
+          flags: {
+            "mem0-oss-notices": {
+              key: "mem0-oss-notices",
+              enabled: options.flagEnabled ?? true,
+              variant: options.variant ?? "displayed",
+              metadata: { payload },
+            },
+          },
+        }),
+      };
+    }
+
+    if (target.includes("/i/v0/e/")) {
+      calls.push(JSON.parse(String(init?.body)));
+      return {
+        ok: true,
+        text: jest.fn().mockResolvedValue(""),
+      };
+    }
+
+    return {
+      ok: true,
+      json: jest.fn().mockResolvedValue({}),
+      text: jest.fn().mockResolvedValue(""),
+    };
+  });
+
+  return { fetchMock, calls };
+}
+
+function noticeEvents(calls: any[]) {
+  return calls.filter((call) => call.event === "mem0.notice_displayed");
+}
+
+function temporalUsageEvents(calls: any[]) {
+  return noticeEvents(calls).filter(
+    (call) => call.properties.notice_id === "temporal_usage",
+  );
+}
+
+function flagRequestCount(fetchMock: jest.Mock) {
+  return fetchMock.mock.calls.filter(([url]) => String(url).includes("/flags"))
+    .length;
+}
+
+async function createMemory() {
+  const { Memory } = await import("../src/memory");
+  return new Memory({
+    version: "v1.1",
+    embedder: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "text-embedding-3-small" },
+    },
+    vectorStore: {
+      provider: "memory",
+      config: {
+        collectionName: `test-temporal-usage-${Date.now()}-${Math.random()}`,
+        dimension: 1536,
+        dbPath: ":memory:",
+      },
+    },
+    llm: {
+      provider: "openai",
+      config: { apiKey: "test-key", model: "gpt-5-mini" },
+    },
+    historyDbPath: ":memory:",
+  });
+}
+
+async function addSearchSeed(memory: any, userId = "temporal-user") {
+  await memory.add("The user's favorite drink is green tea.", {
+    userId,
+    infer: false,
+  });
+}
+
+describe("Node OSS temporal usage notice", () => {
+  let originalMem0Dir: string | undefined;
+  let originalTelemetry: string | undefined;
+  let originalSampleRate: string | undefined;
+  let originalFetch: typeof global.fetch;
+  let stderrSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    originalMem0Dir = process.env.MEM0_DIR;
+    originalTelemetry = process.env.MEM0_TELEMETRY;
+    originalSampleRate = process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    originalFetch = global.fetch;
+
+    process.env.MEM0_DIR = makeTempMem0Dir();
+    process.env.MEM0_TELEMETRY = "true";
+    process.env.MEM0_TELEMETRY_SAMPLE_RATE = "1";
+    stderrSpy = jest
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    jest.resetModules();
+  });
+
+  afterEach(() => {
+    if (originalMem0Dir === undefined) delete process.env.MEM0_DIR;
+    else process.env.MEM0_DIR = originalMem0Dir;
+
+    if (originalTelemetry === undefined) delete process.env.MEM0_TELEMETRY;
+    else process.env.MEM0_TELEMETRY = originalTelemetry;
+
+    if (originalSampleRate === undefined) {
+      delete process.env.MEM0_TELEMETRY_SAMPLE_RATE;
+    } else {
+      process.env.MEM0_TELEMETRY_SAMPLE_RATE = originalSampleRate;
+    }
+
+    global.fetch = originalFetch;
+    jest.restoreAllMocks();
+    jest.resetModules();
+  });
+
+  it("detects timestamp-like metadata after successful add", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    const result = await memory.add("Temporal metadata memory", {
+      userId: "temporal-user",
+      infer: false,
+      metadata: { event_date: "2025-04-09" },
+    });
+
+    expect(result.results).toHaveLength(1);
+    expect(stderrSpy).toHaveBeenCalledWith(`${TEMPORAL_USAGE_COPY}\n`);
+    const notices = temporalUsageEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "temporal_usage",
+        notice_type: "log_line",
+        flag_key: "mem0-oss-notices",
+        variant: "displayed",
+        displayed: true,
+        payload: TEMPORAL_USAGE_COPY,
+        notice_config_found: true,
+        sync_type: "async",
+        trigger_function: "add",
+        trigger_source: "metadata",
+        trigger_reason: "date_like_metadata",
+        sample_rate: 1,
+      }),
+    );
+    expect(readConfig().notice_state.temporal_usage.events).toHaveLength(1);
+  });
+
+  it("emits query trigger fields after successful search", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSearchSeed(memory);
+
+    await memory.search("what happened last week?", {
+      filters: { user_id: "temporal-user" },
+      topK: 3,
+    });
+
+    const notices = temporalUsageEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "temporal_usage",
+        displayed: true,
+        trigger_function: "search",
+        trigger_source: "query",
+        trigger_reason: "relative_phrase",
+      }),
+    );
+  });
+
+  it("detects temporal range filters after successful search", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSearchSeed(memory);
+
+    await memory.search("favorite drink", {
+      filters: {
+        user_id: "temporal-user",
+        AND: [{ created_at: { gte: "2025-04-01" } }],
+      },
+      topK: 3,
+    });
+
+    const notices = temporalUsageEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "temporal_usage",
+        displayed: true,
+        trigger_function: "search",
+        trigger_source: "filter",
+        trigger_reason: "date_range_filter",
+      }),
+    );
+  });
+
+  it("does not evaluate for normal non-temporal add/search calls", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Normal memory", {
+      userId: "normal-user",
+      infer: false,
+      metadata: { category: "planning" },
+    });
+    await memory.search("favorite drink", {
+      filters: { user_id: "normal-user" },
+      topK: 3,
+    });
+
+    expect(flagRequestCount(fetchMock)).toBe(0);
+    expect(temporalUsageEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.temporal_usage).toBeUndefined();
+  });
+
+  it("does not evaluate when add/search fail", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await expect(
+      memory.add("Invalid temporal metadata add", {
+        infer: false,
+        metadata: { event_date: "2025-04-09" },
+      } as any),
+    ).rejects.toThrow("One of the filters");
+    await expect(
+      memory.search("what happened last week?", {
+        filters: {},
+      }),
+    ).rejects.toThrow("filters must contain");
+
+    expect(temporalUsageEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.temporal_usage).toBeUndefined();
+  });
+
+  it("is silent for holdout and emits displayed=false", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "holdout" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Temporal metadata memory", {
+      userId: "temporal-user",
+      infer: false,
+      metadata: { event_date: "2025-04-09" },
+    });
+
+    expect(stderrSpy).not.toHaveBeenCalled();
+    const notices = temporalUsageEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "temporal_usage",
+        variant: "holdout",
+        displayed: false,
+        bypass_reason: "holdout",
+        trigger_source: "metadata",
+        trigger_reason: "date_like_metadata",
+      }),
+    );
+  });
+
+  it.each([
+    [
+      "disabled payload",
+      JSON.stringify(temporalUsagePayload({ enabled: false })),
+      "payload_disabled",
+    ],
+    [
+      "missing config",
+      JSON.stringify({ notices: {} }),
+      "missing_notice_config",
+    ],
+    [
+      "missing copy",
+      JSON.stringify(temporalUsagePayload({ copy: "" })),
+      "missing_copy",
+    ],
+    ["malformed payload", "{not-json", "missing_notice_config"],
+  ])("is silent and safe for %s", async (_label, payload, bypassReason) => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      payload,
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Temporal metadata memory", {
+      userId: "temporal-user",
+      infer: false,
+      metadata: { event_date: "2025-04-09" },
+    });
+
+    expect(stderrSpy).not.toHaveBeenCalled();
+    const notices = temporalUsageEvents(calls);
+    expect(notices).toHaveLength(1);
+    expect(notices[0].properties).toEqual(
+      expect.objectContaining({
+        notice_id: "temporal_usage",
+        displayed: false,
+        bypass_reason: bypassReason,
+      }),
+    );
+  });
+
+  it("does not consume cap or emit when the blunt flag is disabled", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({
+      variant: "displayed",
+      flagEnabled: false,
+    });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Temporal metadata memory", {
+      userId: "temporal-user",
+      infer: false,
+      metadata: { event_date: "2025-04-09" },
+    });
+
+    expect(temporalUsageEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.temporal_usage).toBeUndefined();
+  });
+
+  it("does not consume cap or emit when PostHog fails", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ failFlags: true });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Temporal metadata memory", {
+      userId: "temporal-user",
+      infer: false,
+      metadata: { event_date: "2025-04-09" },
+    });
+
+    expect(temporalUsageEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state?.temporal_usage).toBeUndefined();
+  });
+
+  it("does nothing when telemetry is off", async () => {
+    process.env.MEM0_TELEMETRY = "False";
+    jest.resetModules();
+
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Temporal metadata memory", {
+      userId: "temporal-user",
+      infer: false,
+      metadata: { event_date: "2025-04-09" },
+    });
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(temporalUsageEvents(calls)).toHaveLength(0);
+    expect(readConfig().notice_state).toBeUndefined();
+  });
+
+  it("caps evaluated opportunities at 10 per rolling week", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSearchSeed(memory);
+
+    for (let index = 1; index <= 11; index++) {
+      await memory.search(`what happened last week ${index}?`, {
+        filters: { user_id: "temporal-user" },
+        topK: 3,
+      });
+    }
+
+    expect(temporalUsageEvents(calls)).toHaveLength(10);
+    expect(flagRequestCount(fetchMock)).toBe(10);
+    expect(readConfig().notice_state.temporal_usage.events).toHaveLength(10);
+    expect(stderrSpy).toHaveBeenCalledTimes(10);
+  });
+
+  it("does not consume first-run on the same qualifying temporal usage call", async () => {
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+
+    await memory.add("Temporal metadata memory", {
+      userId: "temporal-user",
+      infer: false,
+      metadata: { event_date: "2025-04-09" },
+    });
+
+    expect(readConfig().notice_state.first_run).toBeUndefined();
+    await memory.add("Normal follow-up memory", {
+      userId: "temporal-user",
+      infer: false,
+    });
+
+    const notices = noticeEvents(calls);
+    expect(notices.map((call) => call.properties.notice_id)).toEqual([
+      "temporal_usage",
+      "first_run",
+    ]);
+    expect(readConfig().notice_state.first_run.consumed).toBe(true);
+  });
+
+  it("does not include raw query, metadata, or filter values in telemetry props", async () => {
+    consumeFirstRun();
+    const { fetchMock, calls } = createFetchMock({ variant: "displayed" });
+    global.fetch = fetchMock as any;
+    const memory = await createMemory();
+    await addSearchSeed(memory);
+
+    await memory.search("private trip since 2025-04-09", {
+      filters: {
+        user_id: "temporal-user",
+        created_at: { gte: "2025-04-09" },
+      },
+      topK: 3,
+    });
+
+    const props = temporalUsageEvents(calls)[0].properties;
+    const serialized = JSON.stringify(props);
+    expect(serialized).not.toContain("private trip");
+    expect(serialized).not.toContain("2025-04-09");
+    expect(serialized).not.toContain("temporal-user");
+  });
+
+  it("detects expected query, metadata, and filter cases conservatively", async () => {
+    const { __noticeTestHooks } = await import("../src/utils/notices");
+
+    expect(
+      __noticeTestHooks.detectTemporalUsageFromSearch("notes from today", null),
+    ).toEqual({ triggerSource: "query", triggerReason: "relative_phrase" });
+    expect(
+      __noticeTestHooks.detectTemporalUsageFromSearch(
+        "notes from 2025-04-09",
+        null,
+      ),
+    ).toEqual({ triggerSource: "query", triggerReason: "date_like_query" });
+    expect(
+      __noticeTestHooks.detectTemporalUsageFromMetadata({
+        event_date: "2025-04-09",
+      }),
+    ).toEqual({
+      triggerSource: "metadata",
+      triggerReason: "date_like_metadata",
+    });
+    expect(
+      __noticeTestHooks.detectTemporalUsageFromSearch("favorite drink", {
+        AND: [{ created_at: { gte: "2025-04-01" } }],
+      }),
+    ).toEqual({ triggerSource: "filter", triggerReason: "date_range_filter" });
+    expect(
+      __noticeTestHooks.detectTemporalUsageFromSearch("favorite drink", null),
+    ).toBeNull();
+    expect(
+      __noticeTestHooks.detectTemporalUsageFromMetadata({
+        category: "planning",
+      }),
+    ).toBeNull();
+  });
+
+  it("detectors never raise for cyclic metadata or filters", async () => {
+    const { __noticeTestHooks } = await import("../src/utils/notices");
+    const metadata: Record<string, any> = {};
+    metadata.self = metadata;
+    const filters: Record<string, any> = {};
+    filters.AND = [filters];
+
+    expect(
+      __noticeTestHooks.detectTemporalUsageFromMetadata(metadata),
+    ).toBeNull();
+    expect(
+      __noticeTestHooks.detectTemporalUsageFromSearch(
+        "favorite drink",
+        filters,
+      ),
+    ).toBeNull();
+  });
+});

mem0-ts/src/oss/tests/telemetry-sampling.test.ts

@@ -61,6 +61,13 @@ describe("telemetry sampling", () => {
       expect(fetchMock).toHaveBeenCalledTimes(1);
     });
 
+    it("notice_displayed event fires even at the highest random value", async () => {
+      randomSpy.mockReturnValue(0.999);
+      const { captureClientEvent } = await import("../src/utils/telemetry");
+      await captureClientEvent("notice_displayed", makeInstance());
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
     it("init event payload has sample_rate: 1.0", async () => {
       randomSpy.mockReturnValue(0.999);
       const { captureClientEvent } = await import("../src/utils/telemetry");

mem0-ts/src/oss/tests/vector-stores-compat.test.ts

@@ -923,6 +923,7 @@ describe("Memory class – backward compat with all providers", () => {
 
     jest.doMock("../src/utils/telemetry", () => ({
       captureClientEvent: jest.fn().mockResolvedValue(undefined),
+      isTelemetryEnabled: jest.fn(() => false),
     }));
 
     MemoryClass = require("../src/memory").Memory;