chore: import upstream snapshot with attribution

cli/node/src/agent-detect.ts

@@ -0,0 +1,32 @@
+/**
+ * Detect whether the CLI is being invoked from inside an AI-agent context.
+ *
+ * Used by `mem0 init` to auto-enter Agent Mode (Rule 3 bootstrap) when an
+ * agent runtime env var is present. The return value is a context **trigger
+ * only** — the canonical agent identity is self-declared by the agent via
+ * `--agent-caller <name>` (Proof Editor-style) and never sniffed from env
+ * vars to fill the `agent_caller` field on the APIKey row.
+ *
+ * Returns a short name or null. Honest reporting depends on `--agent-caller`;
+ * this list is just enough to enable the zero-friction auto-bootstrap UX.
+ */
+
+const AGENT_CALLER_ENV: ReadonlyArray<readonly [string, readonly string[]]> = [
+	["claude-code", ["CLAUDECODE", "CLAUDE_CODE"]],
+	["cursor", ["CURSOR_AGENT", "CURSOR_SESSION_ID"]],
+	["codex", ["CODEX_CLI", "OPENAI_CODEX"]],
+	["cline", ["CLINE_AGENT", "CLINE"]],
+	["continue", ["CONTINUE_AGENT", "CONTINUE_SESSION"]],
+	["aider", ["AIDER_SESSION"]],
+	["goose", ["GOOSE_AGENT"]],
+	["windsurf", ["WINDSURF_AGENT"]],
+] as const;
+
+export function detectAgentCaller(): string | null {
+	for (const [name, envVars] of AGENT_CALLER_ENV) {
+		if (envVars.some((v) => process.env[v])) {
+			return name;
+		}
+	}
+	return null;
+}

cli/node/src/backend/base.ts

@@ -0,0 +1,127 @@
+/**
+ * Abstract backend interface and factory.
+ */
+
+import type { Mem0Config } from "../config.js";
+import { PlatformBackend } from "./platform.js";
+
+export interface AddOptions {
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+	metadata?: Record<string, unknown>;
+	immutable?: boolean;
+	infer?: boolean;
+	expires?: string;
+	categories?: string[];
+}
+
+export interface SearchOptions {
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+	topK?: number;
+	threshold?: number;
+	rerank?: boolean;
+	keyword?: boolean;
+	filters?: Record<string, unknown>;
+	fields?: string[];
+}
+
+export interface ListOptions {
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+	page?: number;
+	pageSize?: number;
+	category?: string;
+	after?: string;
+	before?: string;
+}
+
+export interface DeleteOptions {
+	all?: boolean;
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+}
+
+export interface EntityIds {
+	userId?: string;
+	agentId?: string;
+	appId?: string;
+	runId?: string;
+}
+
+export interface Backend {
+	add(
+		content?: string,
+		messages?: Record<string, unknown>[],
+		opts?: AddOptions,
+	): Promise<Record<string, unknown>>;
+
+	search(
+		query: string,
+		opts?: SearchOptions,
+	): Promise<Record<string, unknown>[]>;
+
+	get(memoryId: string): Promise<Record<string, unknown>>;
+
+	listMemories(opts?: ListOptions): Promise<Record<string, unknown>[]>;
+
+	update(
+		memoryId: string,
+		content?: string,
+		metadata?: Record<string, unknown>,
+	): Promise<Record<string, unknown>>;
+
+	delete(
+		memoryId?: string,
+		opts?: DeleteOptions,
+	): Promise<Record<string, unknown>>;
+
+	deleteEntities(opts: EntityIds): Promise<Record<string, unknown>>;
+
+	ping(): Promise<Record<string, unknown>>;
+
+	status(opts?: { userId?: string; agentId?: string }): Promise<
+		Record<string, unknown>
+	>;
+
+	entities(entityType: string): Promise<Record<string, unknown>[]>;
+
+	listEvents(): Promise<Record<string, unknown>[]>;
+
+	getEvent(eventId: string): Promise<Record<string, unknown>>;
+}
+
+export class AuthError extends Error {
+	constructor(
+		message = "Authentication failed. Your API key may be invalid or expired.",
+	) {
+		super(message);
+		this.name = "AuthError";
+	}
+}
+
+export class NotFoundError extends Error {
+	constructor(path: string) {
+		super(`Resource not found: ${path}`);
+		this.name = "NotFoundError";
+	}
+}
+
+export class APIError extends Error {
+	constructor(path: string, detail: string) {
+		super(`Bad request to ${path}: ${detail}`);
+		this.name = "APIError";
+	}
+}
+
+export function getBackend(config: Mem0Config): Backend {
+	return new PlatformBackend(config.platform);
+}

cli/node/src/backend/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Backend factory re-export.
+ */
+
+export { getBackend } from "./base.js";
+export type {
+	Backend,
+	AddOptions,
+	SearchOptions,
+	ListOptions,
+	DeleteOptions,
+	EntityIds,
+} from "./base.js";
+export { AuthError, NotFoundError, APIError } from "./base.js";

cli/node/src/backend/platform.ts

@@ -0,0 +1,410 @@
+/**
+ * Platform (SaaS) backend — communicates with api.mem0.ai.
+ */
+
+import type { PlatformConfig } from "../config.js";
+import { captureNotice, isAgentMode } from "../state.js";
+import { CLI_VERSION } from "../version.js";
+import {
+	APIError,
+	type AddOptions,
+	AuthError,
+	type Backend,
+	type DeleteOptions,
+	type EntityIds,
+	type ListOptions,
+	NotFoundError,
+	type SearchOptions,
+} from "./base.js";
+
+function encodePathSegment(value: unknown): string {
+	return encodeURIComponent(String(value));
+}
+
+export class PlatformBackend implements Backend {
+	private baseUrl: string;
+	private headers: Record<string, string>;
+
+	constructor(config: PlatformConfig) {
+		this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+		this.headers = {
+			Authorization: `Token ${config.apiKey}`,
+			"Content-Type": "application/json",
+			"X-Mem0-Source": "cli",
+			"X-Mem0-Client-Language": "node",
+			"X-Mem0-Client-Version": CLI_VERSION,
+		};
+	}
+
+	private async _request(
+		method: string,
+		path: string,
+		opts?: { json?: unknown; params?: Record<string, string> },
+	): Promise<unknown> {
+		let url = `${this.baseUrl}${path}`;
+		if (opts?.params) {
+			const qs = new URLSearchParams(opts.params).toString();
+			url += `?${qs}`;
+		}
+
+		const headers = {
+			...this.headers,
+			"X-Mem0-Caller-Type": isAgentMode() ? "agent" : "user",
+		};
+
+		const fetchOpts: RequestInit = {
+			method,
+			headers,
+			signal: AbortSignal.timeout(30_000),
+		};
+		if (opts?.json) {
+			fetchOpts.body = JSON.stringify(opts.json);
+		}
+
+		const resp = await fetch(url, fetchOpts);
+
+		if (resp.status === 401) {
+			throw new AuthError();
+		}
+		if (resp.status === 404) {
+			throw new NotFoundError(path);
+		}
+		if (resp.status === 400) {
+			let detail: string;
+			try {
+				const body = (await resp.json()) as Record<string, unknown>;
+				detail =
+					((body.detail ?? body.message ?? JSON.stringify(body)) as string) ??
+					resp.statusText;
+			} catch {
+				detail = resp.statusText;
+			}
+			throw new APIError(path, detail);
+		}
+		if (!resp.ok) {
+			let detail: string = resp.statusText;
+			try {
+				const body = (await resp.json()) as Record<string, unknown>;
+				detail = (body.detail ?? body.message ?? resp.statusText) as string;
+			} catch {
+				/* ignore */
+			}
+			throw new Error(`HTTP ${resp.status}: ${detail}`);
+		}
+		if (resp.status === 204) {
+			return {};
+		}
+
+		const data = await resp.json();
+
+		// Pull the unclaimed-Agent-Mode notice out of the body (or the header
+		// fallback for endpoints returning non-dict / non-dict-leading payloads)
+		// and stash for end-of-command surfacing.
+		let notice: string | null = null;
+		if (
+			data &&
+			typeof data === "object" &&
+			!Array.isArray(data) &&
+			"mem0_notice" in data
+		) {
+			notice = (data as Record<string, unknown>).mem0_notice as string;
+			// biome-ignore lint/performance/noDelete: intentional strip so downstream consumers don't see duplicate notice
+			delete (data as Record<string, unknown>).mem0_notice;
+		} else if (
+			Array.isArray(data) &&
+			data.length > 0 &&
+			typeof data[0] === "object" &&
+			data[0] !== null &&
+			"mem0_notice" in data[0]
+		) {
+			notice = (data[0] as Record<string, unknown>).mem0_notice as string;
+			// biome-ignore lint/performance/noDelete: see above.
+			delete (data[0] as Record<string, unknown>).mem0_notice;
+		}
+		if (!notice) {
+			notice = resp.headers.get("X-Mem0-Notice-Message") ?? null;
+		}
+		captureNotice(notice);
+
+		return data;
+	}
+
+	async add(
+		content?: string,
+		messages?: Record<string, unknown>[],
+		opts: AddOptions = {},
+	): Promise<Record<string, unknown>> {
+		const payload: Record<string, unknown> = {};
+
+		if (messages) {
+			payload.messages = messages;
+		} else if (content) {
+			payload.messages = [{ role: "user", content }];
+		}
+
+		if (opts.userId) payload.user_id = opts.userId;
+		if (opts.agentId) payload.agent_id = opts.agentId;
+		if (opts.appId) payload.app_id = opts.appId;
+		if (opts.runId) payload.run_id = opts.runId;
+		if (opts.metadata) payload.metadata = opts.metadata;
+		if (opts.immutable) payload.immutable = true;
+		if (opts.infer === false) payload.infer = false;
+		if (opts.expires) payload.expiration_date = opts.expires;
+		if (opts.categories) payload.categories = opts.categories;
+		payload.source = "CLI";
+
+		return (await this._request("POST", "/v3/memories/add/", {
+			json: payload,
+		})) as Record<string, unknown>;
+	}
+
+	private _buildFilters(opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		extraFilters?: Record<string, unknown>;
+	}): Record<string, unknown> | undefined {
+		// If caller passed a pre-built filter structure, use it directly
+		if (
+			opts.extraFilters &&
+			("AND" in opts.extraFilters || "OR" in opts.extraFilters)
+		) {
+			return opts.extraFilters;
+		}
+
+		const andConditions: Record<string, unknown>[] = [];
+		if (opts.userId) andConditions.push({ user_id: opts.userId });
+		if (opts.agentId) andConditions.push({ agent_id: opts.agentId });
+		if (opts.appId) andConditions.push({ app_id: opts.appId });
+		if (opts.runId) andConditions.push({ run_id: opts.runId });
+
+		if (opts.extraFilters) {
+			for (const [k, v] of Object.entries(opts.extraFilters)) {
+				andConditions.push({ [k]: v });
+			}
+		}
+
+		if (andConditions.length === 1) return andConditions[0];
+		if (andConditions.length > 1) return { AND: andConditions };
+		return undefined;
+	}
+
+	async search(
+		query: string,
+		opts: SearchOptions = {},
+	): Promise<Record<string, unknown>[]> {
+		const payload: Record<string, unknown> = {
+			query,
+			top_k: opts.topK ?? 10,
+			threshold: opts.threshold ?? 0.3,
+		};
+
+		const apiFilters = this._buildFilters({
+			userId: opts.userId,
+			agentId: opts.agentId,
+			appId: opts.appId,
+			runId: opts.runId,
+			extraFilters: opts.filters,
+		});
+		if (apiFilters) payload.filters = apiFilters;
+		if (opts.rerank) payload.rerank = true;
+		if (opts.keyword) payload.keyword_search = true;
+		if (opts.fields) payload.fields = opts.fields;
+		payload.source = "CLI";
+
+		const result = (await this._request("POST", "/v3/memories/search/", {
+			json: payload,
+		})) as unknown;
+		if (Array.isArray(result)) return result;
+		const obj = result as Record<string, unknown>;
+		return (obj.results ?? obj.memories ?? []) as Record<string, unknown>[];
+	}
+
+	async get(memoryId: string): Promise<Record<string, unknown>> {
+		return (await this._request(
+			"GET",
+			`/v1/memories/${encodePathSegment(memoryId)}/`,
+			{
+				params: { source: "CLI" },
+			},
+		)) as Record<string, unknown>;
+	}
+
+	async listMemories(
+		opts: ListOptions = {},
+	): Promise<Record<string, unknown>[]> {
+		const payload: Record<string, unknown> = {};
+		const params: Record<string, string> = {
+			page: String(opts.page ?? 1),
+			page_size: String(opts.pageSize ?? 100),
+		};
+
+		const extra: Record<string, unknown> = {};
+		if (opts.category) {
+			extra.categories = { contains: opts.category };
+		}
+		if (opts.after) {
+			extra.created_at = {
+				...(extra.created_at as Record<string, unknown> | undefined),
+				gte: opts.after,
+			};
+		}
+		if (opts.before) {
+			extra.created_at = {
+				...(extra.created_at as Record<string, unknown> | undefined),
+				lte: opts.before,
+			};
+		}
+
+		const apiFilters = this._buildFilters({
+			userId: opts.userId,
+			agentId: opts.agentId,
+			appId: opts.appId,
+			runId: opts.runId,
+			extraFilters: Object.keys(extra).length > 0 ? extra : undefined,
+		});
+		if (apiFilters) payload.filters = apiFilters;
+		payload.source = "CLI";
+
+		const result = (await this._request("POST", "/v3/memories/", {
+			json: payload,
+			params,
+		})) as unknown;
+		if (Array.isArray(result)) return result;
+		const obj = result as Record<string, unknown>;
+		return (obj.results ?? obj.memories ?? []) as Record<string, unknown>[];
+	}
+
+	async update(
+		memoryId: string,
+		content?: string,
+		metadata?: Record<string, unknown>,
+	): Promise<Record<string, unknown>> {
+		const payload: Record<string, unknown> = {};
+		if (content) payload.text = content;
+		if (metadata) payload.metadata = metadata;
+		payload.source = "CLI";
+		return (await this._request(
+			"PUT",
+			`/v1/memories/${encodePathSegment(memoryId)}/`,
+			{
+				json: payload,
+			},
+		)) as Record<string, unknown>;
+	}
+
+	async delete(
+		memoryId?: string,
+		opts: DeleteOptions = {},
+	): Promise<Record<string, unknown>> {
+		if (opts.all) {
+			const params: Record<string, string> = { source: "CLI" };
+			if (opts.userId) params.user_id = opts.userId;
+			if (opts.agentId) params.agent_id = opts.agentId;
+			if (opts.appId) params.app_id = opts.appId;
+			if (opts.runId) params.run_id = opts.runId;
+			return (await this._request("DELETE", "/v1/memories/", {
+				params,
+			})) as Record<string, unknown>;
+		}
+		if (memoryId) {
+			return (await this._request(
+				"DELETE",
+				`/v1/memories/${encodePathSegment(memoryId)}/`,
+				{
+					params: { source: "CLI" },
+				},
+			)) as Record<string, unknown>;
+		}
+		throw new Error("Either memoryId or --all is required");
+	}
+
+	async deleteEntities(opts: EntityIds): Promise<Record<string, unknown>> {
+		// v2 endpoint: DELETE /v2/entities/{entity_type}/{entity_id}/
+		const typeMap: [string, string | undefined][] = [
+			["user", opts.userId],
+			["agent", opts.agentId],
+			["app", opts.appId],
+			["run", opts.runId],
+		];
+		const entities = typeMap.filter(([, v]) => v) as [string, string][];
+		if (entities.length === 0) {
+			throw new Error("At least one entity ID is required for deleteEntities.");
+		}
+		// Delete each provided entity via the v2 path-based endpoint. Key each
+		// response by entity type so a multi-entity delete (e.g. --user-id and
+		// --agent-id together) doesn't discard everything but the last result.
+		const results: Record<string, unknown> = {};
+		for (const [entityType, entityId] of entities) {
+			results[entityType] = (await this._request(
+				"DELETE",
+				`/v2/entities/${encodePathSegment(entityType)}/${encodePathSegment(entityId)}/`,
+				{ params: { source: "CLI" } },
+			)) as Record<string, unknown>;
+		}
+		return results;
+	}
+
+	async ping(): Promise<Record<string, unknown>> {
+		return (await this._request("GET", "/v1/ping/")) as Record<string, unknown>;
+	}
+
+	async status(
+		opts: { userId?: string; agentId?: string } = {},
+	): Promise<Record<string, unknown>> {
+		try {
+			await this.ping();
+			return { connected: true, backend: "platform", base_url: this.baseUrl };
+		} catch (e) {
+			return {
+				connected: false,
+				backend: "platform",
+				error: e instanceof Error ? e.message : String(e),
+			};
+		}
+	}
+
+	async entities(entityType: string): Promise<Record<string, unknown>[]> {
+		const result = (await this._request("GET", "/v1/entities/")) as unknown;
+		let items: Record<string, unknown>[];
+		if (Array.isArray(result)) {
+			items = result;
+		} else {
+			items = ((result as Record<string, unknown>).results ?? []) as Record<
+				string,
+				unknown
+			>[];
+		}
+
+		const typeMap: Record<string, string> = {
+			users: "user",
+			agents: "agent",
+			apps: "app",
+			runs: "run",
+		};
+		const targetType = typeMap[entityType];
+		if (targetType) {
+			items = items.filter(
+				(e) => (e.type as string | undefined)?.toLowerCase() === targetType,
+			);
+		}
+		return items;
+	}
+
+	async listEvents(): Promise<Record<string, unknown>[]> {
+		const result = (await this._request("GET", "/v1/events/")) as unknown;
+		if (Array.isArray(result)) return result;
+		return ((result as Record<string, unknown>).results ?? []) as Record<
+			string,
+			unknown
+		>[];
+	}
+
+	async getEvent(eventId: string): Promise<Record<string, unknown>> {
+		return (await this._request(
+			"GET",
+			`/v1/event/${encodePathSegment(eventId)}/`,
+		)) as Record<string, unknown>;
+	}
+}

cli/node/src/branding.ts

@@ -0,0 +1,172 @@
+/**
+ * Branding and ASCII art for mem0 CLI.
+ */
+
+import chalk from "chalk";
+import ora, { type Ora } from "ora";
+import { getCurrentCommand, isAgentMode } from "./state.js";
+import { CLI_VERSION } from "./version.js";
+
+export const LOGO = `
+███╗   ███╗███████╗███╗   ███╗ ██████╗      ██████╗██╗     ██╗
+████╗ ████║██╔════╝████╗ ████║██╔═████╗    ██╔════╝██║     ██║
+██╔████╔██║█████╗  ██╔████╔██║██║██╔██║    ██║     ██║     ██║
+██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║████╔╝██║    ██║     ██║     ██║
+██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║╚██████╔╝    ╚██████╗███████╗██║
+╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝ ╚═════╝      ╚═════╝╚══════╝╚═╝
+`;
+
+export const LOGO_MINI = "◆ mem0";
+export const TAGLINE = "The Memory Layer for AI Agents";
+
+export const BRAND_COLOR = "#8b5cf6";
+export const ACCENT_COLOR = "#a78bfa";
+export const SUCCESS_COLOR = "#22c55e";
+export const ERROR_COLOR = "#ef4444";
+export const WARNING_COLOR = "#f59e0b";
+export const DIM_COLOR = "#6b7280";
+
+const brand = chalk.hex(BRAND_COLOR);
+const accent = chalk.hex(ACCENT_COLOR);
+const success = chalk.hex(SUCCESS_COLOR);
+const error = chalk.hex(ERROR_COLOR);
+const warning = chalk.hex(WARNING_COLOR);
+const dim = chalk.hex(DIM_COLOR);
+
+/**
+ * Choose a symbol based on TTY/NO_COLOR. Fancy for interactive terminals,
+ * plain-text for piped/non-TTY or NO_COLOR environments.
+ */
+export function sym(fancy: string, plain: string): string {
+	if (!process.stdout.isTTY || process.env.NO_COLOR) return plain;
+	return fancy;
+}
+
+export function printBanner(): void {
+	if (isAgentMode()) return;
+	const pad = 3; // horizontal padding each side (matches Rich's padding=(0, 2))
+	const logoLines = LOGO.trimEnd().split("\n");
+	const tagline = `  ${TAGLINE}`;
+	const subtitle = `Node.js SDK · v${CLI_VERSION}`;
+	const contentLines = ["", ...logoLines, "", tagline, ""];
+
+	// Compute inner width from longest content line + padding both sides
+	const maxContent = Math.max(...contentLines.map((l) => l.length));
+	const innerWidth = maxContent + pad * 2;
+	const totalWidth = innerWidth + 2; // + 2 for │ borders
+
+	const topBorder = brand(`╭${"─".repeat(totalWidth - 2)}╮`);
+	const subtitleFill = totalWidth - 2 - subtitle.length - 3; // 3 = "─ " before subtitle + "─" after
+	const bottomBorder = brand(
+		`╰${"─".repeat(subtitleFill)} ${dim(subtitle)} ${"─"}╯`,
+	);
+
+	const body = contentLines.map((line) => {
+		const rightPad = innerWidth - pad - line.length;
+		return `${brand("│")}${" ".repeat(pad)}${brand.bold(line)}${" ".repeat(Math.max(rightPad, 0))}${brand("│")}`;
+	});
+	// Re-color tagline line with accent instead of brand.bold
+	const taglineIdx = body.length - 2; // second-to-last (before trailing empty line)
+	const taglineRightPad = innerWidth - pad - tagline.length;
+	body[taglineIdx] =
+		`${brand("│")}${" ".repeat(pad)}${accent(tagline)}${" ".repeat(Math.max(taglineRightPad, 0))}${brand("│")}`;
+
+	console.log(topBorder);
+	for (const line of body) console.log(line);
+	console.log(bottomBorder);
+}
+
+export function printSuccess(message: string): void {
+	if (isAgentMode()) return;
+	console.log(`${success(sym("✓", "[ok]"))} ${message}`);
+}
+
+export function printError(message: string, hint?: string): void {
+	if (isAgentMode()) {
+		const envelope = {
+			status: "error",
+			command: getCurrentCommand(),
+			error: message,
+			data: null,
+		};
+		console.log(JSON.stringify(envelope));
+		return;
+	}
+	console.error(`${error(`${sym("✗", "[error]")} Error:`)} ${message}`);
+	const resolvedHint =
+		hint ??
+		(message.includes("Authentication failed")
+			? `Run ${brand("mem0 init")} to reconfigure your API key · https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node`
+			: undefined);
+	if (resolvedHint) {
+		console.error(`  ${dim(resolvedHint)}`);
+	}
+}
+
+export function printWarning(message: string): void {
+	console.error(`${warning(sym("⚠", "[warn]"))} ${message}`);
+}
+
+export function printInfo(message: string): void {
+	if (isAgentMode()) return;
+	console.error(`${brand(sym("◆", "*"))} ${message}`);
+}
+
+export function printScope(ids: Record<string, string | undefined>): void {
+	if (isAgentMode()) return;
+	const parts: string[] = [];
+	for (const [key, val] of Object.entries(ids)) {
+		if (val) {
+			parts.push(`${key}=${val}`);
+		}
+	}
+	if (parts.length > 0) {
+		console.error(`  ${dim(`Scope: ${parts.join(", ")}`)}`);
+	}
+}
+
+export interface TimedStatusContext {
+	successMsg: string;
+	errorMsg: string;
+}
+
+/**
+ * Run an async function with a spinner, timing the operation.
+ * Equivalent to Python's timed_status context manager.
+ */
+export async function timedStatus<T>(
+	message: string,
+	fn: (ctx: TimedStatusContext) => Promise<T>,
+): Promise<T> {
+	if (isAgentMode()) {
+		const ctx: TimedStatusContext = { successMsg: "", errorMsg: "" };
+		return fn(ctx);
+	}
+	const ctx: TimedStatusContext = { successMsg: "", errorMsg: "" };
+	const spinner = ora({
+		text: dim(message),
+		color: "yellow",
+		stream: process.stderr,
+	}).start();
+	const start = performance.now();
+
+	try {
+		const result = await fn(ctx);
+		const elapsed = ((performance.now() - start) / 1000).toFixed(2);
+		spinner.stop();
+		if (ctx.successMsg) {
+			console.error(`${success("✓")} ${ctx.successMsg} (${elapsed}s)`);
+		}
+		return result;
+	} catch (err) {
+		const elapsed = ((performance.now() - start) / 1000).toFixed(2);
+		spinner.stop();
+		if (ctx.errorMsg) {
+			printError(`${ctx.errorMsg} (${elapsed}s)`);
+		}
+		throw err;
+	}
+}
+
+/** Format helpers using brand colors for external use. */
+export const colors = { brand, accent, success, error, warning, dim };

cli/node/src/commands/agent-mode.ts

@@ -0,0 +1,285 @@
+/**
+ * Agent Mode commands — bootstrap (unattended signup) and OTP-based claim.
+ */
+
+import readline from "node:readline";
+import { colors, printError, printInfo, printSuccess } from "../branding.js";
+import { type Mem0Config, saveConfig } from "../config.js";
+
+const { brand, dim } = colors;
+
+const SOURCE_HEADERS = {
+	"X-Mem0-Source": "cli",
+	"X-Mem0-Client-Language": "node",
+} as const;
+
+export interface BootstrapEnvelope {
+	api_key: string;
+	default_user_id: string;
+	org_id: string;
+	project_id: string;
+	mcp_url?: string;
+	smoke_test_url?: string;
+	claim_command?: string;
+	mem0_notice?: string;
+}
+
+function isValidEnvelope(v: unknown): v is BootstrapEnvelope {
+	return (
+		!!v &&
+		typeof v === "object" &&
+		typeof (v as BootstrapEnvelope).api_key === "string" &&
+		(v as BootstrapEnvelope).api_key.length > 0 &&
+		typeof (v as BootstrapEnvelope).default_user_id === "string" &&
+		(v as BootstrapEnvelope).default_user_id.length > 0
+	);
+}
+
+/**
+ * POST /api/v1/auth/agent_mode/ and mutate config in place.
+ *
+ * @param config - Mem0Config mutated in place with the new platform values.
+ * @param source - `--source` flag passthrough (analytics tag, free-form).
+ * @param agentCaller - Self-declared agent identity passed via `--agent-caller`
+ *   (e.g. `claude-code`, `cursor`). May be null when the caller omitted the
+ *   flag; the agent can backfill later via `mem0 identify <name>`. Sent to the
+ *   backend in the request body and saved into `platform.agentCaller` for
+ *   local introspection.
+ */
+export async function bootstrapViaBackend(
+	config: Mem0Config,
+	{
+		source,
+		agentCaller,
+	}: { source?: string | null; agentCaller?: string | null } = {},
+): Promise<void> {
+	const baseUrl = (config.platform.baseUrl || "https://api.mem0.ai").replace(
+		/\/+$/,
+		"",
+	);
+	const body: Record<string, unknown> = {};
+	if (source) body.source = source;
+	if (agentCaller) body.agent_caller = agentCaller;
+
+	let resp: Response;
+	try {
+		resp = await fetch(`${baseUrl}/api/v1/auth/agent_mode/`, {
+			method: "POST",
+			headers: {
+				...SOURCE_HEADERS,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify(body),
+			signal: AbortSignal.timeout(30_000),
+		});
+	} catch (err) {
+		printError(
+			`Network error contacting Mem0: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		process.exit(1);
+	}
+
+	if (resp.status === 429) {
+		printError("Rate-limited. Try again in a few minutes.");
+		process.exit(1);
+	}
+	if (resp.status === 503) {
+		printError("Agent Mode is temporarily disabled. Try again later.");
+		process.exit(1);
+	}
+	if (!resp.ok) {
+		let detail: string = resp.statusText;
+		try {
+			const errBody = (await resp.json()) as {
+				error?: string;
+				detail?: string;
+			};
+			detail = errBody.error ?? errBody.detail ?? resp.statusText;
+		} catch {
+			/* leave detail as statusText */
+		}
+		// Backend's @ratelimit decorator raises PermissionDenied, which DRF
+		// translates to a generic 403 "You do not have permission to perform
+		// this action." That's opaque — surface it as the rate-limit message
+		// it actually is.
+		if (resp.status === 403 && /permission/i.test(detail)) {
+			printError(
+				"Daily Agent Mode signup limit reached for this network (5/day). Try again from a different IP or after midnight UTC.",
+			);
+			process.exit(1);
+		}
+		printError(`Bootstrap failed: ${detail}`);
+		process.exit(1);
+	}
+
+	const envelope = (await resp.json()) as BootstrapEnvelope;
+	if (!isValidEnvelope(envelope)) {
+		// Defend against partial/malformed backend responses (e.g. {api_key: null}).
+		// Without this guard, the typed `string` field is silently set to
+		// undefined/null and persisted, producing confusing downstream errors.
+		printError(
+			"Bootstrap response missing required fields — please update the CLI.",
+		);
+		process.exit(1);
+	}
+
+	config.platform.apiKey = envelope.api_key;
+	config.platform.baseUrl = baseUrl;
+	config.platform.agentMode = true;
+	config.platform.createdVia = "agent_mode";
+	config.platform.agentCaller = agentCaller ?? "";
+	config.platform.claimedAt = "";
+	config.platform.defaultUserId = envelope.default_user_id;
+	// Adopt the slug-derived user_id as the default scope for memory ops.
+	config.defaults.userId = envelope.default_user_id;
+	saveConfig(config);
+
+	printSuccess(
+		`Agent Mode active. Default user_id: ${envelope.default_user_id}`,
+	);
+	if (envelope.mem0_notice) {
+		console.log(`\n\x1b[33m🔔 ${envelope.mem0_notice}\x1b[0m\n`);
+	} else {
+		// Fallback for older backends without the unified notice field.
+		const claimCmd = envelope.claim_command ?? "mem0 init --email <your-email>";
+		console.log(`  ${dim(`To claim this account later: ${claimCmd}`)}`);
+	}
+
+	if (!agentCaller) {
+		console.log(
+			`  ${dim("If you are an AI agent, identify yourself: `mem0 identify <your-name>` (e.g. claude-code, cursor).")}`,
+		);
+	}
+}
+
+/**
+ * Claim an existing Agent Mode account via OTP — no browser, no polling.
+ *
+ * Hits /api/v1/auth/email_code/ to send a verification code, prompts for it
+ * interactively (or accepts via `code`), then sends it to /verify/ alongside
+ * `agent_mode_api_key`. Backend's verify_email_code runs upgrade-in-place
+ * inline and returns the claim result.
+ */
+export async function claimViaOtp(
+	config: Mem0Config,
+	{ email, code }: { email: string; code?: string },
+): Promise<void> {
+	const baseUrl = (config.platform.baseUrl || "https://api.mem0.ai").replace(
+		/\/+$/,
+		"",
+	);
+	if (!config.platform.apiKey || !config.platform.agentMode) {
+		printError(
+			"This command requires an active Agent Mode config. Run `mem0 init` first.",
+		);
+		process.exit(1);
+	}
+
+	const rawKey = config.platform.apiKey;
+
+	// Step 1: request OTP (unless --code was supplied)
+	if (!code) {
+		const sendResp = await fetch(`${baseUrl}/api/v1/auth/email_code/`, {
+			method: "POST",
+			headers: { ...SOURCE_HEADERS, "Content-Type": "application/json" },
+			body: JSON.stringify({ email }),
+			signal: AbortSignal.timeout(30_000),
+		});
+		if (sendResp.status === 429) {
+			printError("Too many attempts. Try again in a few minutes.");
+			process.exit(1);
+		}
+		if (!sendResp.ok) {
+			let detail: string = sendResp.statusText;
+			try {
+				const errBody = (await sendResp.json()) as { error?: string };
+				if (errBody.error) detail = errBody.error;
+			} catch {
+				/* leave as statusText */
+			}
+			printError(`Failed to send code: ${detail}`);
+			process.exit(1);
+		}
+
+		printSuccess(`Verification code sent to ${email}. Check your inbox.`);
+
+		if (!process.stdin.isTTY) {
+			printError(
+				"No --code provided and terminal is non-interactive.",
+				`Re-run: mem0 init --email ${email} --code <code>`,
+			);
+			process.exit(1);
+		}
+
+		console.log();
+		code = await promptLine(`  ${brand("Verification Code")}`);
+		if (!code) {
+			printError("Code is required.");
+			process.exit(1);
+		}
+	}
+
+	// Step 2: verify + claim atomically
+	const verifyResp = await fetch(`${baseUrl}/api/v1/auth/email_code/verify/`, {
+		method: "POST",
+		headers: { ...SOURCE_HEADERS, "Content-Type": "application/json" },
+		body: JSON.stringify({
+			email,
+			code: code.trim(),
+			agent_mode_api_key: rawKey,
+		}),
+		signal: AbortSignal.timeout(30_000),
+	});
+
+	if (!verifyResp.ok) {
+		let detail: string = verifyResp.statusText;
+		let errCode = "";
+		try {
+			const errBody = (await verifyResp.json()) as {
+				error?: string;
+				code?: string;
+			};
+			if (errBody.error) detail = errBody.error;
+			if (errBody.code) errCode = errBody.code;
+		} catch {
+			/* leave as statusText */
+		}
+		printError(`Claim failed: ${detail}`);
+		if (errCode === "email_already_claimed") {
+			console.log(
+				`  ${dim("Tip: this email already has a Mem0 account. Sign in at app.mem0.ai with your existing credentials.")}`,
+			);
+		}
+		process.exit(1);
+	}
+
+	const claimBody = (await verifyResp.json()) as {
+		claimed?: boolean;
+		claimed_at?: string;
+	};
+	if (!claimBody.claimed) {
+		printError(`Unexpected verify response: ${JSON.stringify(claimBody)}`);
+		process.exit(1);
+	}
+
+	config.platform.agentMode = false;
+	config.platform.claimedAt = claimBody.claimed_at ?? new Date().toISOString();
+	config.platform.userEmail = email;
+	config.platform.createdVia = "email";
+	saveConfig(config);
+
+	printSuccess(`Agent claimed to ${email}. Your API key is unchanged.`);
+}
+
+function promptLine(label: string): Promise<string> {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	return new Promise((resolve) => {
+		rl.question(`${label}: `, (answer) => {
+			rl.close();
+			resolve(answer.trim());
+		});
+	});
+}

cli/node/src/commands/agent-rush.ts

@@ -0,0 +1,147 @@
+/**
+ * `mem0 agent-rush <add|search> "..."` — wraps the AGENTRUSH platform endpoints.
+ * Project routing is implicit (server-side); zero flags needed.
+ */
+
+import readline from "node:readline";
+import { colors, printError, printSuccess } from "../branding.js";
+import { loadConfig, saveConfig } from "../config.js";
+import { CLI_VERSION } from "../version.js";
+
+const PII_WARNING = [
+	"",
+	"⚠️  AGENTRUSH memories are PUBLIC — visible to any other player.",
+	"   Do not include real names, emails, secrets, work content, or PII.",
+	"",
+].join("\n");
+
+const ERROR_HINTS: Record<string, string> = {
+	agentrush_search_first:
+		"Run 3 'mem0 agent-rush search' commands before adding.",
+	agentrush_search_quota: "You've used your 3 lifetime searches.",
+	agentrush_add_quota: "You've used your 3 lifetime adds.",
+	agentrush_not_agent_mode:
+		"Re-run 'mem0 init --agent' to bootstrap an agent-mode key.",
+	agentrush_length: "Memory text must be 50-1000 characters.",
+	agentrush_no_urls: "URLs are not allowed.",
+	agentrush_blocklist: "Content contains a blocked term.",
+	agentrush_global_quota: "Event-wide cap reached. Try again later.",
+	agentrush_not_provisioned:
+		"AGENTRUSH is not provisioned in this environment.",
+};
+
+async function callEndpoint(
+	path: string,
+	body: Record<string, unknown>,
+): Promise<unknown> {
+	const config = loadConfig();
+	const baseUrl = (config.platform?.baseUrl ?? "https://api.mem0.ai").replace(
+		/\/+$/,
+		"",
+	);
+
+	if (!config.platform?.apiKey) {
+		printError("Not initialized. Run `mem0 init --agent` first.");
+		process.exit(1);
+	}
+
+	const resp = await fetch(`${baseUrl}${path}`, {
+		method: "POST",
+		headers: {
+			Authorization: `Token ${config.platform.apiKey}`,
+			"Content-Type": "application/json",
+			"X-Mem0-Source": "cli",
+			"X-Mem0-Client-Language": "node",
+			"X-Mem0-Client-Version": CLI_VERSION,
+			"X-Mem0-Mode": "agent-rush",
+		},
+		body: JSON.stringify(body),
+		signal: AbortSignal.timeout(30_000),
+	});
+
+	const json = await resp.json().catch(() => ({}));
+
+	if (!resp.ok) {
+		const code =
+			(json as { error?: { code?: string } }).error?.code ?? "unknown";
+		printError(`AGENTRUSH error: ${code}`);
+		if (ERROR_HINTS[code]) {
+			console.log(`  ${colors.dim(ERROR_HINTS[code])}`);
+		}
+		process.exit(1);
+	}
+
+	return json;
+}
+
+function promptLine(question: string): Promise<string> {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	return new Promise((resolve) => {
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer.trim());
+		});
+	});
+}
+
+/**
+ * Ensure the human has acknowledged that AGENTRUSH memories are PUBLIC.
+ *
+ * Interactive (TTY): show the prompt; on "y" persist `agentRush.acknowledgedAt`
+ * so we never ask the same machine twice. On anything else, abort.
+ *
+ * Non-interactive (agent invocation, no TTY): print the warning to stderr
+ * for the human reading the agent's transcript and proceed — agents can't
+ * answer y/N prompts.
+ */
+async function ensureWarningAcknowledged(): Promise<void> {
+	const config = loadConfig();
+	if (config.agentRush?.acknowledgedAt) return;
+
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		// Agent context: surface the warning to stderr, don't block.
+		console.error(PII_WARNING);
+		return;
+	}
+
+	console.log(PII_WARNING);
+	const answer = (await promptLine("   Continue? [y/N]: ")).toLowerCase();
+	if (answer !== "y" && answer !== "yes") {
+		printError("Aborted.");
+		process.exit(1);
+	}
+
+	config.agentRush.acknowledgedAt = new Date().toISOString();
+	saveConfig(config);
+}
+
+export async function cmdAgentRushAdd(content: string): Promise<void> {
+	await ensureWarningAcknowledged();
+	const result = await callEndpoint("/v1/agent-rush/memories/", { content });
+	printSuccess(
+		`Memory submitted (event_id: ${(result as { event_id?: string }).event_id ?? "?"})`,
+	);
+}
+
+export async function cmdAgentRushSearch(query: string): Promise<void> {
+	const result = (await callEndpoint("/v1/agent-rush/memories/search/", {
+		query,
+	})) as {
+		results?: Array<{ memory?: string }>;
+		memories?: Array<{ memory?: string }>;
+	};
+
+	const memories = result.results ?? result.memories ?? [];
+
+	if (memories.length === 0) {
+		console.log(colors.dim("(no results)"));
+		return;
+	}
+
+	memories.slice(0, 5).forEach((m, i) => {
+		console.log(`  ${i + 1}. ${m.memory ?? JSON.stringify(m)}`);
+	});
+}

cli/node/src/commands/config.ts

@@ -0,0 +1,109 @@
+/**
+ * Config management commands: show, set, get.
+ */
+
+import Table from "cli-table3";
+import { colors, printError, printSuccess } from "../branding.js";
+import {
+	getNestedValue,
+	loadConfig,
+	redactKey,
+	saveConfig,
+	setNestedValue,
+} from "../config.js";
+import { formatAgentEnvelope, formatJsonEnvelope } from "../output.js";
+import { isAgentMode, setCurrentCommand } from "../state.js";
+
+const { brand, accent, dim } = colors;
+
+export function cmdConfigShow(opts: { output?: string } = {}): void {
+	setCurrentCommand("config show");
+	const config = loadConfig();
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "config show",
+			data: {
+				defaults: {
+					user_id: config.defaults.userId || null,
+					agent_id: config.defaults.agentId || null,
+					app_id: config.defaults.appId || null,
+					run_id: config.defaults.runId || null,
+				},
+				platform: {
+					api_key: redactKey(config.platform.apiKey),
+					base_url: config.platform.baseUrl,
+				},
+			},
+		});
+		return;
+	}
+
+	console.log();
+	console.log(`  ${brand("◆ mem0 Configuration")}\n`);
+
+	const table = new Table({
+		head: [accent("Key"), accent("Value")],
+		style: { head: [], border: [] },
+	});
+
+	// Defaults
+	table.push(["defaults.user_id", config.defaults.userId || dim("(not set)")]);
+	table.push([
+		"defaults.agent_id",
+		config.defaults.agentId || dim("(not set)"),
+	]);
+	table.push(["defaults.app_id", config.defaults.appId || dim("(not set)")]);
+	table.push(["defaults.run_id", config.defaults.runId || dim("(not set)")]);
+	table.push(["", ""]);
+
+	// Platform
+	table.push(["platform.api_key", redactKey(config.platform.apiKey)]);
+	table.push(["platform.base_url", config.platform.baseUrl]);
+
+	console.log(table.toString());
+	console.log();
+}
+
+export function cmdConfigGet(key: string): void {
+	setCurrentCommand("config get");
+	const config = loadConfig();
+	const value = getNestedValue(config, key);
+
+	if (value === undefined) {
+		printError(`Unknown config key: ${key}`);
+	} else {
+		// Redact secrets
+		const displayValue =
+			key.includes("api_key") || key.split(".").pop() === "key"
+				? redactKey(String(value))
+				: String(value);
+		if (isAgentMode()) {
+			formatAgentEnvelope({
+				command: "config get",
+				data: { key, value: displayValue },
+			});
+		} else {
+			console.log(displayValue);
+		}
+	}
+}
+
+export function cmdConfigSet(key: string, value: string): void {
+	setCurrentCommand("config set");
+	const config = loadConfig();
+	if (setNestedValue(config, key, value)) {
+		saveConfig(config);
+		const display = key.includes("key") ? redactKey(value) : value;
+		if (isAgentMode()) {
+			formatAgentEnvelope({
+				command: "config set",
+				data: { key, value: display },
+			});
+		} else {
+			printSuccess(`${key} = ${display}`);
+		}
+	} else {
+		printError(`Unknown config key: ${key}`);
+	}
+}

cli/node/src/commands/entities.ts

@@ -0,0 +1,168 @@
+/**
+ * Entity management commands.
+ */
+
+import readline from "node:readline";
+import Table from "cli-table3";
+import type { Backend } from "../backend/base.js";
+import {
+	colors,
+	printError,
+	printInfo,
+	printSuccess,
+	timedStatus,
+} from "../branding.js";
+import { formatAgentEnvelope, formatJson } from "../output.js";
+import { setCurrentCommand } from "../state.js";
+
+const { brand, accent, dim } = colors;
+
+const VALID_TYPES = new Set(["users", "agents", "apps", "runs"]);
+
+export async function cmdEntitiesList(
+	backend: Backend,
+	entityType: string,
+	opts: { output: string },
+): Promise<void> {
+	setCurrentCommand("entity list");
+	if (!VALID_TYPES.has(entityType)) {
+		printError(
+			`Invalid entity type: ${entityType}. Use: ${[...VALID_TYPES].join(", ")}`,
+		);
+		process.exit(1);
+	}
+
+	const start = performance.now();
+	let results: Record<string, unknown>[];
+	try {
+		results = await timedStatus(`Fetching ${entityType}...`, async () => {
+			return backend.entities(entityType);
+		});
+	} catch (e) {
+		printError(
+			e instanceof Error ? e.message : String(e),
+			"This feature may require the mem0 Platform.",
+		);
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "entity list",
+			data: results,
+			count: results.length,
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	if (!results.length) {
+		printInfo(`No ${entityType} found.`);
+		return;
+	}
+
+	const table = new Table({
+		head: [accent("Name / ID"), accent("Created")],
+		style: { head: [], border: [] },
+	});
+
+	for (const entity of results) {
+		const name = String(entity.name ?? entity.id ?? "—");
+		const created = String(entity.created_at ?? "—").slice(0, 10);
+		table.push([name, created]);
+	}
+
+	console.log();
+	console.log(table.toString());
+	console.log(
+		`  ${dim(`${results.length} ${entityType} (${elapsed.toFixed(2)}s)`)}`,
+	);
+	console.log();
+}
+
+export async function cmdEntitiesDelete(
+	backend: Backend,
+	opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		dryRun?: boolean;
+		force: boolean;
+		output: string;
+	},
+): Promise<void> {
+	setCurrentCommand("entity delete");
+	const { isAgentMode } = await import("../state.js");
+	if (isAgentMode() && !opts.force) {
+		printError("Destructive operation requires --force in agent mode.");
+		process.exit(1);
+	}
+	if (!opts.userId && !opts.agentId && !opts.appId && !opts.runId) {
+		printError(
+			"Provide at least one of --user-id, --agent-id, --app-id, --run-id.",
+		);
+		process.exit(1);
+	}
+
+	const scopeParts: string[] = [];
+	if (opts.userId) scopeParts.push(`user=${opts.userId}`);
+	if (opts.agentId) scopeParts.push(`agent=${opts.agentId}`);
+	if (opts.appId) scopeParts.push(`app=${opts.appId}`);
+	if (opts.runId) scopeParts.push(`run=${opts.runId}`);
+	const scope = scopeParts.join(", ");
+
+	if (opts.dryRun) {
+		printInfo(`Would delete entity ${scope} and all its memories.`);
+		printInfo("No changes made.");
+		return;
+	}
+
+	if (!opts.force) {
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+		const answer = await new Promise<string>((resolve) => {
+			rl.question(
+				`\n  \u26a0  Delete entity ${scope} AND all its memories? This cannot be undone. [y/N] `,
+				resolve,
+			);
+		});
+		rl.close();
+		if (answer.toLowerCase() !== "y") {
+			printInfo("Cancelled.");
+			process.exit(0);
+		}
+	}
+
+	const start = performance.now();
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Deleting entity...", async () => {
+			return backend.deleteEntities({
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+			});
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent") {
+		formatAgentEnvelope({
+			command: "entity delete",
+			data: { deleted: true },
+			durationMs: Math.round(elapsed * 1000),
+		});
+	} else if (opts.output === "json") {
+		formatJson(result);
+	} else if (opts.output !== "quiet") {
+		printSuccess(`Entity deleted with all memories (${elapsed.toFixed(2)}s)`);
+	}
+}

cli/node/src/commands/events.ts

@@ -0,0 +1,169 @@
+/**
+ * Event commands: list and status.
+ */
+
+import boxen from "boxen";
+import Table from "cli-table3";
+import type { Backend } from "../backend/base.js";
+import { colors, printError, printInfo, timedStatus } from "../branding.js";
+import { formatAgentEnvelope, formatJson } from "../output.js";
+import { setCurrentCommand } from "../state.js";
+
+const { brand, accent, success, error: errorColor, warning, dim } = colors;
+
+function statusStyled(status: string): string {
+	switch (status.toUpperCase()) {
+		case "SUCCEEDED":
+			return success("SUCCEEDED");
+		case "PENDING":
+			return accent("PENDING");
+		case "FAILED":
+			return errorColor("FAILED");
+		case "PROCESSING":
+			return warning("PROCESSING");
+		default:
+			return status;
+	}
+}
+
+export async function cmdEventList(
+	backend: Backend,
+	opts: { output: string },
+): Promise<void> {
+	setCurrentCommand("event list");
+	const start = performance.now();
+	let results: Record<string, unknown>[];
+	try {
+		results = await timedStatus("Fetching events...", async () => {
+			return backend.listEvents();
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "event list",
+			data: results,
+			count: results.length,
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	if (results.length === 0) {
+		console.log();
+		printInfo("No events found.");
+		console.log();
+		return;
+	}
+
+	const table = new Table({
+		head: [
+			accent("Event ID"),
+			accent("Type"),
+			accent("Status"),
+			accent("Latency"),
+			accent("Created"),
+		],
+		colWidths: [12, 14, 14, 10, 22],
+		wordWrap: true,
+		style: { head: [], border: [] },
+	});
+
+	for (const ev of results) {
+		const evId = String(ev.id ?? "").slice(0, 8);
+		const evType = String(ev.event_type ?? "—");
+		const status = String(ev.status ?? "—");
+		const latency = ev.latency as number | undefined;
+		const latencyStr = latency !== undefined ? `${Math.round(latency)}ms` : "—";
+		const created = String(ev.created_at ?? "—")
+			.slice(0, 19)
+			.replace("T", " ");
+		table.push([dim(evId), evType, statusStyled(status), latencyStr, created]);
+	}
+
+	console.log();
+	console.log(table.toString());
+	console.log(
+		`  ${dim(`${results.length} event${results.length !== 1 ? "s" : ""}`)}`,
+	);
+	console.log();
+}
+
+export async function cmdEventStatus(
+	backend: Backend,
+	eventId: string,
+	opts: { output: string },
+): Promise<void> {
+	setCurrentCommand("event status");
+	const start = performance.now();
+	let ev: Record<string, unknown>;
+	try {
+		ev = await timedStatus("Fetching event...", async () => {
+			return backend.getEvent(eventId);
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "event status",
+			data: ev,
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	const status = String(ev.status ?? "—");
+	const evType = String(ev.event_type ?? "—");
+	const latency = ev.latency as number | undefined;
+	const latencyStr = latency !== undefined ? `${Math.round(latency)}ms` : "—";
+	const created = String(ev.created_at ?? "—")
+		.slice(0, 19)
+		.replace("T", " ");
+	const updated = String(ev.updated_at ?? "—")
+		.slice(0, 19)
+		.replace("T", " ");
+	const results = ev.results as Record<string, unknown>[] | undefined;
+
+	const lines: string[] = [];
+	lines.push(`  ${dim("Event ID:")}     ${eventId}`);
+	lines.push(`  ${dim("Type:")}         ${evType}`);
+	lines.push(`  ${dim("Status:")}       ${statusStyled(status)}`);
+	lines.push(`  ${dim("Latency:")}      ${latencyStr}`);
+	lines.push(`  ${dim("Created:")}      ${created}`);
+	lines.push(`  ${dim("Updated:")}      ${updated}`);
+
+	if (results && results.length > 0) {
+		lines.push("");
+		lines.push(`  ${dim(`Results (${results.length}):`)}`);
+		for (const r of results) {
+			const memId = String(r.id ?? "").slice(0, 8);
+			const data = r.data as Record<string, unknown> | undefined;
+			const memory = data?.memory ? String(data.memory) : "";
+			const evName = String(r.event ?? "");
+			const user = String(r.user_id ?? "");
+			let detail = `${evName}  ${memory}`;
+			if (user) detail += `  ${dim(`(user_id=${user})`)}`;
+			lines.push(`    ${success("·")} ${detail}  ${dim(`(${memId})`)}`);
+		}
+	}
+
+	const content = lines.join("\n");
+	console.log();
+	console.log(
+		boxen(content, {
+			title: brand("Event Status"),
+			titleAlignment: "left",
+			borderColor: "magenta",
+			padding: 1,
+		}),
+	);
+	console.log();
+}

cli/node/src/commands/identify.ts

@@ -0,0 +1,75 @@
+/**
+ * mem0 identify — declare which agent owns the current agent-mode key.
+ *
+ * Used when `mem0 init --agent` ran without --agent-caller, so the backend
+ * saved agent_caller=NULL. The agent re-runs `mem0 identify <name>` to PATCH
+ * its own row with its real identity. Idempotent.
+ */
+
+import { printError, printSuccess } from "../branding.js";
+import { loadConfig, saveConfig } from "../config.js";
+
+const SOURCE_HEADERS = {
+	"X-Mem0-Source": "cli",
+	"X-Mem0-Client-Language": "node",
+} as const;
+
+export async function runIdentify(name: string): Promise<void> {
+	const config = loadConfig();
+	if (!config.platform.apiKey) {
+		printError("No API key configured. Run `mem0 init --agent` first.");
+		process.exit(1);
+	}
+	if (!config.platform.agentMode) {
+		printError("This command only works on unclaimed agent-mode keys.");
+		process.exit(1);
+	}
+
+	const clean = (name ?? "").trim();
+	if (!clean) {
+		printError("Agent name is required.");
+		process.exit(1);
+	}
+
+	const baseUrl = (config.platform.baseUrl || "https://api.mem0.ai").replace(
+		/\/+$/,
+		"",
+	);
+
+	let resp: Response;
+	try {
+		resp = await fetch(`${baseUrl}/api/v1/auth/agent_mode/caller/`, {
+			method: "PATCH",
+			headers: {
+				...SOURCE_HEADERS,
+				Authorization: `Token ${config.platform.apiKey}`,
+				"Content-Type": "application/json",
+			},
+			body: JSON.stringify({ agent_caller: clean }),
+			signal: AbortSignal.timeout(30_000),
+		});
+	} catch (err) {
+		printError(
+			`Network error: ${err instanceof Error ? err.message : String(err)}`,
+		);
+		process.exit(1);
+	}
+
+	if (!resp.ok) {
+		let detail: string = resp.statusText;
+		try {
+			const body = (await resp.json()) as { error?: string };
+			if (body.error) detail = body.error;
+		} catch {
+			/* leave as statusText */
+		}
+		printError(`Identify failed: ${detail}`);
+		process.exit(1);
+	}
+
+	const body = (await resp.json()) as { agent_caller?: string };
+	const canonical = body.agent_caller ?? clean;
+	config.platform.agentCaller = canonical;
+	saveConfig(config);
+	printSuccess(`Identified as ${canonical}.`);
+}

cli/node/src/commands/init.ts

@@ -0,0 +1,612 @@
+/**
+ * mem0 init — interactive setup wizard.
+ */
+
+import fs from "node:fs";
+import readline from "node:readline";
+import { PlatformBackend } from "../backend/platform.js";
+import {
+	colors,
+	printBanner,
+	printError,
+	printInfo,
+	printSuccess,
+} from "../branding.js";
+import {
+	CONFIG_FILE,
+	DEFAULT_BASE_URL,
+	type Mem0Config,
+	createDefaultConfig,
+	loadConfig,
+	redactKey,
+	saveConfig,
+} from "../config.js";
+import { formatJsonEnvelope } from "../output.js";
+import { isAgentMode } from "../state.js";
+
+const { brand, dim } = colors;
+
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+
+function validateEmail(email: string): void {
+	if (!EMAIL_RE.test(email)) {
+		printError(`Invalid email address: ${JSON.stringify(email)}`);
+		process.exit(1);
+	}
+}
+
+/** @internal — exported for unit tests. */
+export async function pingKey(
+	apiKey: string,
+	baseUrl: string,
+	timeoutMs = 5000,
+): Promise<boolean> {
+	// Returns false ONLY on a definitive "invalid key" signal (HTTP 401/403).
+	// Network errors, timeouts, and 5xx responses return true so we prefer
+	// reusing an existing key over silently minting a new shadow on a transient
+	// blip (which would also clobber config + plugin-sync targets).
+	try {
+		const resp = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1/ping/`, {
+			headers: { Authorization: `Token ${apiKey}` },
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+		return resp.status !== 401 && resp.status !== 403;
+	} catch {
+		return true; // unknown — prefer reuse
+	}
+}
+
+async function maybeIdentify(
+	key: string,
+	baseUrl: string,
+	agentCaller: string | undefined,
+): Promise<void> {
+	// Best-effort PATCH agent_caller when --agent-caller is supplied on a
+	// reused key. Silent no-op on any failure — reuse must not break.
+	if (!agentCaller) return;
+	try {
+		const resp = await fetch(
+			`${baseUrl.replace(/\/+$/, "")}/api/v1/auth/agent_mode/caller/`,
+			{
+				method: "PATCH",
+				headers: {
+					Authorization: `Token ${key}`,
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify({ agent_caller: agentCaller }),
+				signal: AbortSignal.timeout(10_000),
+			},
+		);
+		if (resp.ok) {
+			try {
+				const body = (await resp.json()) as { agent_caller?: string };
+				if (fs.existsSync(CONFIG_FILE)) {
+					const cfg = loadConfig();
+					cfg.platform.agentCaller = body.agent_caller ?? agentCaller;
+					saveConfig(cfg);
+				}
+			} catch {
+				/* swallow — best effort */
+			}
+		}
+	} catch {
+		/* swallow — best effort */
+	}
+}
+
+async function emailLogin(
+	email: string,
+	code: string | undefined,
+	baseUrl: string,
+): Promise<Record<string, unknown>> {
+	const url = baseUrl.replace(/\/+$/, "");
+	let codeValue = code;
+
+	const sourceHeaders = {
+		"Content-Type": "application/json",
+		"X-Mem0-Source": "cli",
+		"X-Mem0-Client-Language": "node",
+	};
+
+	if (!codeValue) {
+		const resp = await fetch(`${url}/api/v1/auth/email_code/`, {
+			method: "POST",
+			headers: sourceHeaders,
+			body: JSON.stringify({ email }),
+			signal: AbortSignal.timeout(30_000),
+		});
+		if (resp.status === 429) {
+			printError("Too many attempts. Try again in a few minutes.");
+			process.exit(1);
+		}
+		if (!resp.ok) {
+			let detail: string;
+			try {
+				const body = (await resp.json()) as Record<string, unknown>;
+				detail = (body.error ?? body.detail ?? resp.statusText) as string;
+			} catch {
+				detail = resp.statusText;
+			}
+			printError(`Failed to send code: ${detail}`);
+			process.exit(1);
+		}
+
+		printSuccess("Verification code sent! Check your email.");
+
+		if (!process.stdin.isTTY) {
+			printError(
+				"No --code provided and terminal is non-interactive.",
+				"Run: mem0 init --email <email> --code <code>",
+			);
+			process.exit(1);
+		}
+
+		console.log();
+		const entered = await promptLine(`  ${brand("Verification Code")}`);
+		if (!entered) {
+			printError("Code is required.");
+			process.exit(1);
+		}
+		codeValue = entered;
+	}
+
+	const verifyResp = await fetch(`${url}/api/v1/auth/email_code/verify/`, {
+		method: "POST",
+		headers: sourceHeaders,
+		body: JSON.stringify({ email, code: codeValue.trim() }),
+		signal: AbortSignal.timeout(30_000),
+	});
+	if (verifyResp.status === 429) {
+		printError("Too many attempts. Try again in a few minutes.");
+		process.exit(1);
+	}
+	if (!verifyResp.ok) {
+		let detail: string;
+		try {
+			const body = (await verifyResp.json()) as Record<string, unknown>;
+			detail = (body.error ?? body.detail ?? verifyResp.statusText) as string;
+		} catch {
+			detail = verifyResp.statusText;
+		}
+		printError(`Verification failed: ${detail}`);
+		process.exit(1);
+	}
+
+	return verifyResp.json() as Promise<Record<string, unknown>>;
+}
+
+function promptSecret(label: string): Promise<string> {
+	return new Promise((resolve, reject) => {
+		process.stdout.write(label);
+
+		if (process.stdin.isTTY) {
+			process.stdin.setRawMode(true);
+		}
+		process.stdin.resume();
+		process.stdin.setEncoding("utf-8");
+
+		const chars: string[] = [];
+
+		const onData = (key: string) => {
+			for (const ch of key) {
+				if (ch === "\r" || ch === "\n") {
+					cleanup();
+					process.stdout.write("\n");
+					resolve(chars.join(""));
+					return;
+				}
+				if (ch === "\x03") {
+					cleanup();
+					reject(new Error("Interrupted"));
+					return;
+				}
+				if (ch === "\x7f" || ch === "\x08") {
+					// backspace
+					if (chars.length > 0) {
+						chars.pop();
+						process.stdout.write("\b \b");
+					}
+				} else if (ch === "\x15") {
+					// Ctrl+U — clear line
+					process.stdout.write("\b \b".repeat(chars.length));
+					chars.length = 0;
+				} else if (ch >= " ") {
+					chars.push(ch);
+					process.stdout.write("*");
+				}
+			}
+		};
+
+		const cleanup = () => {
+			process.stdin.removeListener("data", onData);
+			if (process.stdin.isTTY) {
+				process.stdin.setRawMode(false);
+			}
+			process.stdin.pause();
+		};
+
+		process.stdin.on("data", onData);
+	});
+}
+
+function promptLine(label: string, defaultValue?: string): Promise<string> {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+	const prompt = defaultValue ? `${label} [${defaultValue}]: ` : `${label}: `;
+	return new Promise((resolve) => {
+		rl.question(prompt, (answer) => {
+			rl.close();
+			resolve(answer.trim() || defaultValue || "");
+		});
+	});
+}
+
+async function setupPlatform(config: Mem0Config): Promise<void> {
+	console.log();
+	console.log(
+		`  ${dim("Get your API key at https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node")}`,
+	);
+	console.log();
+
+	process.stdout.write(`  ${brand("API Key")}: `);
+	const apiKey = await promptSecret("");
+	if (!apiKey) {
+		printError("API key is required.");
+		process.exit(1);
+	}
+	config.platform.apiKey = apiKey;
+	config.platform.createdVia = "api_key";
+}
+
+async function setupDefaults(config: Mem0Config): Promise<void> {
+	console.log();
+	printInfo("Set default entity IDs (press Enter to skip).\n");
+
+	const _systemUser = process.env.USER || process.env.USERNAME || "mem0-cli";
+	const userId = await promptLine(
+		`  ${brand("Default User ID")} ${dim("(recommended)")}`,
+		_systemUser,
+	);
+	if (userId) config.defaults.userId = userId;
+}
+
+async function validatePlatform(config: Mem0Config): Promise<void> {
+	console.log();
+	printInfo("Validating connection...");
+	try {
+		const backend = new PlatformBackend(config.platform);
+		const status = await backend.status({
+			userId: config.defaults.userId || undefined,
+			agentId: config.defaults.agentId || undefined,
+		});
+		if (status.connected) {
+			printSuccess("Connected to mem0 Platform!");
+			// Cache user_email from ping response for telemetry distinct_id
+			try {
+				const pingData = (await backend.ping()) as Record<string, unknown>;
+				const userEmail = pingData?.user_email as string | undefined;
+				if (userEmail) {
+					config.platform.userEmail = userEmail;
+				}
+			} catch {
+				/* ignore — telemetry ID will fall back to API key hash */
+			}
+		} else {
+			printError(
+				`Could not connect: ${status.error ?? "Unknown error"}`,
+				"Visit https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node to get a new key, or run mem0 init again.",
+			);
+		}
+	} catch (e) {
+		printError(`Connection test failed: ${e instanceof Error ? e.message : e}`);
+	}
+}
+
+export async function runInit(
+	opts: {
+		apiKey?: string;
+		userId?: string;
+		email?: string;
+		code?: string;
+		force?: boolean;
+		agent?: boolean;
+		source?: string;
+		agentCaller?: string;
+	} = {},
+): Promise<void> {
+	const { detectAgentCaller } = await import("../agent-detect.js");
+	const { bootstrapViaBackend, claimViaOtp } = await import("./agent-mode.js");
+	const { isAgentMode } = await import("../state.js");
+	const { captureEvent } = await import("../telemetry.js");
+
+	const fireInit = (
+		mode: "agent" | "email" | "api_key" | "existing_key",
+		claimed = false,
+	) => {
+		const props: Record<string, unknown> = { command: "init", mode };
+		// Self-declared via --agent-caller; not sniffed from env vars.
+		if (opts.agentCaller) props.agent_caller = opts.agentCaller;
+		if (opts.source) props.signup_source = opts.source;
+		if (claimed) props.claimed_agent_mode = true;
+		captureEvent("cli.init", props);
+	};
+
+	const config = createDefaultConfig();
+	const savedConfig = loadConfig();
+	const baseUrl =
+		process.env.MEM0_BASE_URL ||
+		savedConfig.platform.baseUrl ||
+		DEFAULT_BASE_URL;
+	config.platform.baseUrl = baseUrl;
+
+	// Guards
+	if (opts.code && !opts.email) {
+		printError("--code requires --email.");
+		process.exit(1);
+	}
+	if (opts.email && opts.apiKey) {
+		printError("Cannot use both --api-key and --email.");
+		process.exit(1);
+	}
+
+	// ── Claim flow: --email against an existing agent-mode config ───────────
+	if (
+		opts.email &&
+		fs.existsSync(CONFIG_FILE) &&
+		savedConfig.platform.agentMode &&
+		savedConfig.platform.apiKey
+	) {
+		const email = opts.email.trim().toLowerCase();
+		validateEmail(email);
+		printInfo(`Claiming Agent Mode account to ${email}...`);
+		await claimViaOtp(savedConfig, { email, code: opts.code });
+		fireInit("email", true);
+		return;
+	}
+
+	// ── Agent Mode path runs BEFORE the existing-config guard ──────────────
+	// Rule 1/2 will REUSE a valid existing key (not overwrite), so we must
+	// short-circuit before the guard prompts the user about overwriting.
+	// Rule 3 only mints when there's no valid key to reuse — in that case
+	// overwriting is what the user wants.
+	const agentCtx =
+		opts.agent === true || isAgentMode() || detectAgentCaller() !== null;
+	if (!opts.apiKey && !opts.email && agentCtx) {
+		const emitReuseEnvelope = (source: "env" | "config") => {
+			if (isAgentMode()) {
+				formatJsonEnvelope({
+					command: "init",
+					data: {
+						api_key_saved: false,
+						api_key_source: source,
+						agent_mode: false,
+						message:
+							"Existing Mem0 API key found and reused. No Agent Mode key was created.",
+					},
+				});
+			} else {
+				printSuccess(
+					source === "env"
+						? "Existing MEM0_API_KEY is valid; reusing it. No new Agent Mode key was minted."
+						: "Existing API key in config is valid; reusing it. No new Agent Mode key was minted.",
+				);
+			}
+		};
+		// Rule 1: env MEM0_API_KEY valid → reuse, no new key.
+		const envKey = (process.env.MEM0_API_KEY || "").trim();
+		if (envKey && (await pingKey(envKey, baseUrl))) {
+			await maybeIdentify(envKey, baseUrl, opts.agentCaller);
+			emitReuseEnvelope("env");
+			fireInit("existing_key");
+			return;
+		}
+		// Rule 2: existing config api_key valid → reuse.
+		if (
+			savedConfig.platform.apiKey &&
+			(await pingKey(savedConfig.platform.apiKey, baseUrl))
+		) {
+			await maybeIdentify(
+				savedConfig.platform.apiKey,
+				baseUrl,
+				opts.agentCaller,
+			);
+			emitReuseEnvelope("config");
+			fireInit("existing_key");
+			return;
+		}
+		// Rule 3: mint a fresh shadow (no valid key to reuse).
+		// agent_caller is self-declared via --agent-caller (Proof Editor-style),
+		// not derived from env-var sniffing. detectAgentCaller() above is still
+		// used as a context trigger (does this look like an agent?) but never
+		// to fill identity.
+		await bootstrapViaBackend(config, {
+			source: opts.source ?? null,
+			agentCaller: opts.agentCaller ?? null,
+		});
+		fireInit("agent");
+		return;
+	}
+
+	// Warn if an existing config with an API key would be overwritten
+	if (
+		!opts.force &&
+		fs.existsSync(CONFIG_FILE) &&
+		savedConfig.platform.apiKey
+	) {
+		console.log(
+			`\n  ${brand("Existing configuration found")} ${dim(`(API key: ${redactKey(savedConfig.platform.apiKey)})`)}`,
+		);
+		if (process.stdin.isTTY) {
+			const rl = readline.createInterface({
+				input: process.stdin,
+				output: process.stdout,
+			});
+			const answer = await new Promise<string>((resolve) => {
+				rl.question(
+					"  Overwrite existing config? This cannot be undone. [y/N] ",
+					resolve,
+				);
+			});
+			rl.close();
+			if (answer.toLowerCase() !== "y") {
+				printInfo("Cancelled. Use --force to skip this check.");
+				process.exit(0);
+			}
+		} else {
+			printError(
+				"Existing config would be overwritten.",
+				"Use --force to overwrite.",
+			);
+			process.exit(1);
+		}
+	}
+
+	// ── Email login flow ──────────────────────────────────────────────────────
+	if (opts.email) {
+		const email = opts.email.trim().toLowerCase();
+		validateEmail(email);
+
+		printBanner();
+		console.log();
+		printInfo(`Logging in as ${email}...\n`);
+
+		const result = await emailLogin(email, opts.code, baseUrl);
+
+		const apiKeyVal = result.api_key as string | undefined;
+		if (!apiKeyVal) {
+			printError(
+				"Auth succeeded but no API key was returned. Contact support.",
+			);
+			process.exit(1);
+		}
+
+		config.platform.apiKey = apiKeyVal;
+		config.platform.baseUrl = baseUrl;
+		config.platform.userEmail = email;
+		config.platform.createdVia = "email";
+		config.defaults.userId =
+			opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
+
+		saveConfig(config);
+		console.log();
+		printSuccess("Authenticated! Configuration saved to ~/.mem0/config.json");
+		console.log();
+		console.log(`  ${dim("Get started:")}`);
+		console.log(`  ${dim('  mem0 add "I prefer dark mode"')}`);
+		console.log(`  ${dim('  mem0 search "preferences"')}`);
+		console.log();
+		return;
+	}
+
+	// ── API key flow ──────────────────────────────────────────────────────────
+	// (Agent Mode branch runs earlier — see above, before the existing-config
+	// guard, so Rules 1/2 can REUSE a valid key without prompting overwrite.)
+
+	// Non-TTY: resolve defaults so partial flags work in pipelines / CI
+	if (!process.stdin.isTTY) {
+		if (!opts.apiKey) {
+			printError(
+				"Non-interactive terminal detected and --api-key is required.",
+				"Usage: mem0 init --api-key <key>, --email <addr>, or --agent for unattended Agent Mode bootstrap.",
+			);
+			process.exit(1);
+		}
+		opts.userId =
+			opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
+	}
+
+	// Non-interactive: both flags provided
+	if (opts.apiKey && opts.userId) {
+		config.platform.apiKey = opts.apiKey;
+		config.platform.createdVia = "api_key";
+		config.defaults.userId = opts.userId;
+		await validatePlatform(config);
+		saveConfig(config);
+		printSuccess("Configuration saved to ~/.mem0/config.json");
+		return;
+	}
+
+	printBanner();
+	console.log();
+	printInfo("Welcome! Let's set up your mem0 CLI.\n");
+
+	// Use provided API key or prompt
+	if (opts.apiKey) {
+		config.platform.apiKey = opts.apiKey;
+	} else {
+		console.log(`  ${brand("How would you like to authenticate?")}`);
+		console.log(`  ${dim("1.")} Login with email ${dim("(recommended)")}`);
+		console.log(`  ${dim("2.")} Enter API key manually`);
+		console.log();
+
+		const choice = await promptLine(`  ${brand("Choose")} [1/2]`, "1");
+
+		if (choice === "1") {
+			console.log();
+			const emailAddr = await promptLine(`  ${brand("Email")}`);
+			if (!emailAddr) {
+				printError("Email is required.");
+				process.exit(1);
+			}
+
+			const email = emailAddr.trim().toLowerCase();
+			validateEmail(email);
+			printInfo(`Logging in as ${email}...\n`);
+
+			const result = await emailLogin(email, undefined, baseUrl);
+
+			const apiKeyVal = result.api_key as string | undefined;
+			if (!apiKeyVal) {
+				printError(
+					"Auth succeeded but no API key was returned. Contact support.",
+				);
+				process.exit(1);
+			}
+
+			config.platform.apiKey = apiKeyVal;
+			config.platform.baseUrl = baseUrl;
+			config.platform.userEmail = email;
+			config.platform.createdVia = "email";
+			config.defaults.userId =
+				opts.userId || process.env.USER || process.env.USERNAME || "mem0-cli";
+
+			saveConfig(config);
+			console.log();
+			printSuccess("Authenticated! Configuration saved to ~/.mem0/config.json");
+			console.log();
+			console.log(`  ${dim("Get started:")}`);
+			console.log(`  ${dim('  mem0 add "I prefer dark mode"')}`);
+			console.log(`  ${dim('  mem0 search "preferences"')}`);
+			console.log();
+			return;
+		}
+
+		// choice === "2": fall through to API key prompt
+		await setupPlatform(config);
+	}
+
+	// Use provided user ID or prompt
+	if (opts.userId) {
+		config.defaults.userId = opts.userId;
+	} else {
+		await setupDefaults(config);
+	}
+
+	await validatePlatform(config);
+
+	saveConfig(config);
+	console.log();
+	printSuccess("Configuration saved to ~/.mem0/config.json");
+	console.log();
+	console.log(`  ${dim("Get started:")}`);
+	if (config.defaults.userId) {
+		console.log(`  ${dim('  mem0 add "I prefer dark mode"')}`);
+		console.log(`  ${dim('  mem0 search "preferences"')}`);
+	} else {
+		console.log(`  ${dim('  mem0 add "I prefer dark mode" --user-id alice')}`);
+		console.log(`  ${dim('  mem0 search "preferences" --user-id alice')}`);
+	}
+	console.log();
+}

cli/node/src/commands/memory.ts

@@ -0,0 +1,703 @@
+/**
+ * Memory CRUD commands: add, search, get, list, update, delete.
+ */
+
+import fs from "node:fs";
+import type { Backend } from "../backend/base.js";
+import {
+	printError,
+	printInfo,
+	printScope,
+	printSuccess,
+	timedStatus,
+} from "../branding.js";
+import {
+	formatAddResult,
+	formatAgentEnvelope,
+	formatJson,
+	formatJsonEnvelope,
+	formatMemoriesTable,
+	formatMemoriesText,
+	formatSingleMemory,
+	printResultSummary,
+} from "../output.js";
+import { isAgentMode, setCurrentCommand } from "../state.js";
+
+/** True only when stdin is an actual pipe or file redirect — never in agent mode. */
+function _stdinIsPiped(): boolean {
+	if (isAgentMode()) return false;
+	try {
+		const stat = fs.fstatSync(0);
+		return stat.isFIFO() || stat.isFile();
+	} catch {
+		return false;
+	}
+}
+
+export async function cmdAdd(
+	backend: Backend,
+	text: string | undefined,
+	opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		messages?: string;
+		file?: string;
+		metadata?: string;
+		immutable: boolean;
+		infer?: boolean;
+		expires?: string;
+		categories?: string;
+		output: string;
+	},
+): Promise<void> {
+	setCurrentCommand("add");
+	let msgs: Record<string, unknown>[] | undefined;
+	let content = text;
+
+	// Read from file
+	if (opts.file) {
+		try {
+			const raw = fs.readFileSync(opts.file, "utf-8");
+			msgs = JSON.parse(raw);
+		} catch (e) {
+			printError(`Failed to read file: ${e instanceof Error ? e.message : e}`);
+			process.exit(1);
+		}
+	}
+	// Parse messages JSON
+	else if (opts.messages) {
+		try {
+			msgs = JSON.parse(opts.messages);
+		} catch (e) {
+			printError(
+				`Invalid JSON in --messages: ${e instanceof Error ? e.message : e}`,
+			);
+			process.exit(1);
+		}
+	}
+	// Read from stdin only if stdin is an actual pipe or file redirect
+	else if (!content && _stdinIsPiped()) {
+		content = fs.readFileSync(0, "utf-8").trim();
+	}
+
+	if (content !== undefined && content.trim() === "") {
+		printError("Content cannot be empty.");
+		process.exit(1);
+	}
+	if (!content && !msgs) {
+		printError(
+			"No content provided. Pass text, --messages, --file, or pipe via stdin.",
+		);
+		process.exit(1);
+	}
+
+	// Validate --expires
+	if (opts.expires) {
+		if (!/^\d{4}-\d{2}-\d{2}$/.test(opts.expires)) {
+			printError(
+				"Invalid date format for --expires. Use YYYY-MM-DD (e.g. 2025-12-31).",
+			);
+			process.exit(1);
+		}
+		if (new Date(opts.expires) <= new Date()) {
+			printError("--expires date must be in the future.");
+			process.exit(1);
+		}
+	}
+
+	let meta: Record<string, unknown> | undefined;
+	if (opts.metadata) {
+		try {
+			meta = JSON.parse(opts.metadata);
+		} catch {
+			printError("Invalid JSON in --metadata.");
+			process.exit(1);
+		}
+	}
+
+	let cats: string[] | undefined;
+	if (opts.categories) {
+		try {
+			cats = JSON.parse(opts.categories);
+		} catch {
+			cats = opts.categories.split(",").map((c) => c.trim());
+		}
+	}
+
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Adding memory...", async () => {
+			return backend.add(content ?? undefined, msgs, {
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+				metadata: meta,
+				immutable: opts.immutable,
+				infer: opts.infer !== false,
+				expires: opts.expires,
+				categories: cats,
+			});
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+
+	if (opts.output === "quiet") return;
+
+	// Deduplicate PENDING entries sharing the same event_id across all output modes
+	const rawResults: Record<string, unknown>[] = Array.isArray(result)
+		? result
+		: ((result.results as Record<string, unknown>[]) ?? [result]);
+	const seenEvents = new Set<string>();
+	const deduped: Record<string, unknown>[] = [];
+	for (const r of rawResults) {
+		if (r.status === "PENDING") {
+			const eid = (r.event_id as string) ?? "";
+			if (eid && seenEvents.has(eid)) continue;
+			if (eid) seenEvents.add(eid);
+		}
+		deduped.push(r);
+	}
+	// Write back so downstream formatters see deduplicated data
+	const dedupedResult: Record<string, unknown> = Array.isArray(result)
+		? (deduped as unknown as Record<string, unknown>)
+		: { ...result, results: deduped };
+
+	if (opts.output === "agent") {
+		const scope: Record<string, string | undefined> = {
+			user_id: opts.userId,
+			agent_id: opts.agentId,
+			app_id: opts.appId,
+			run_id: opts.runId,
+		};
+		formatAgentEnvelope({
+			command: "add",
+			data: deduped,
+			scope,
+			count: deduped.length,
+		});
+		return;
+	}
+
+	if (opts.output === "json") {
+		formatAddResult(dedupedResult, opts.output);
+		return;
+	}
+
+	console.log();
+	printScope({
+		user_id: opts.userId,
+		agent_id: opts.agentId,
+		app_id: opts.appId,
+		run_id: opts.runId,
+	});
+	const count = deduped.length;
+	const allPending = count > 0 && deduped.every((r) => r.status === "PENDING");
+	if (allPending) {
+		printSuccess(
+			`Memory queued — ${count} event${count !== 1 ? "s" : ""} pending`,
+		);
+	} else {
+		printSuccess(
+			`Memory processed — ${count} memor${count === 1 ? "y" : "ies"} extracted`,
+		);
+	}
+	formatAddResult(dedupedResult, opts.output);
+}
+
+export async function cmdSearch(
+	backend: Backend,
+	query: string | undefined,
+	opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		topK: number;
+		threshold: number;
+		rerank: boolean;
+		keyword: boolean;
+		filterJson?: string;
+		fields?: string;
+		output: string;
+	},
+): Promise<void> {
+	setCurrentCommand("search");
+	if (!query) {
+		printError("No query provided. Pass a query argument or pipe via stdin.");
+		process.exit(1);
+	}
+
+	let filters: Record<string, unknown> | undefined;
+	if (opts.filterJson) {
+		try {
+			filters = JSON.parse(opts.filterJson);
+		} catch {
+			printError("Invalid JSON in --filter.");
+			process.exit(1);
+		}
+	}
+
+	const fieldList = opts.fields
+		? opts.fields.split(",").map((f) => f.trim())
+		: undefined;
+
+	if (opts.topK < 1) {
+		printError("--top-k must be >= 1.");
+		process.exit(1);
+	}
+	if (opts.threshold < 0 || opts.threshold > 1) {
+		printError("--threshold must be between 0.0 and 1.0.");
+		process.exit(1);
+	}
+
+	const start = performance.now();
+	let results: Record<string, unknown>[];
+	try {
+		results = await timedStatus("Searching memories...", async () => {
+			// biome-ignore lint/style/noNonNullAssertion: guarded by process.exit above
+			return backend.search(query!, {
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+				topK: opts.topK,
+				threshold: opts.threshold,
+				rerank: opts.rerank,
+				keyword: opts.keyword,
+				filters,
+				fields: fieldList,
+			});
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "quiet") return;
+
+	if (opts.output === "agent") {
+		const scope: Record<string, string | undefined> = {
+			user_id: opts.userId,
+			agent_id: opts.agentId,
+			app_id: opts.appId,
+			run_id: opts.runId,
+		};
+		formatAgentEnvelope({
+			command: "search",
+			data: results,
+			scope,
+			count: results.length,
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	if (opts.output === "json") {
+		formatJson(results);
+	} else if (opts.output === "table") {
+		if (results.length > 0) {
+			formatMemoriesTable(results, { showScore: true });
+			printResultSummary({
+				count: results.length,
+				durationSecs: elapsed,
+				scopeIds: { user_id: opts.userId, agent_id: opts.agentId },
+			});
+		} else {
+			console.log();
+			printInfo("No memories found matching your query.");
+			console.log();
+		}
+	} else {
+		if (results.length > 0) {
+			formatMemoriesText(results);
+			printResultSummary({
+				count: results.length,
+				durationSecs: elapsed,
+				scopeIds: { user_id: opts.userId, agent_id: opts.agentId },
+			});
+		} else {
+			console.log();
+			printInfo("No memories found matching your query.");
+			console.log();
+		}
+	}
+}
+
+export async function cmdGet(
+	backend: Backend,
+	memoryId: string,
+	opts: { output: string },
+): Promise<void> {
+	setCurrentCommand("get");
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Fetching memory...", async () => {
+			return backend.get(memoryId);
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+
+	if (opts.output === "agent") {
+		formatAgentEnvelope({ command: "get", data: result });
+	} else {
+		formatSingleMemory(result, opts.output);
+	}
+}
+
+export async function cmdList(
+	backend: Backend,
+	opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		page: number;
+		pageSize: number;
+		category?: string;
+		after?: string;
+		before?: string;
+		output: string;
+	},
+): Promise<void> {
+	setCurrentCommand("list");
+	if (opts.pageSize < 1) {
+		printError("--page-size must be >= 1.");
+		process.exit(1);
+	}
+	if (opts.page < 1) {
+		printError("--page must be >= 1.");
+		process.exit(1);
+	}
+
+	const start = performance.now();
+	let results: Record<string, unknown>[];
+	try {
+		results = await timedStatus("Listing memories...", async () => {
+			return backend.listMemories({
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+				page: opts.page,
+				pageSize: opts.pageSize,
+				category: opts.category,
+				after: opts.after,
+				before: opts.before,
+			});
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "quiet") return;
+
+	if (opts.output === "agent" || opts.output === "json") {
+		const scope: Record<string, string | undefined> = {
+			user_id: opts.userId,
+			agent_id: opts.agentId,
+			app_id: opts.appId,
+			run_id: opts.runId,
+		};
+		formatAgentEnvelope({
+			command: "list",
+			data: results,
+			scope,
+			count: results.length,
+			durationMs: Math.round(elapsed * 1000),
+		});
+	} else if (opts.output === "table") {
+		if (results.length > 0) {
+			formatMemoriesTable(results);
+			printResultSummary({
+				count: results.length,
+				durationSecs: elapsed,
+				page: opts.page,
+				scopeIds: { user_id: opts.userId, agent_id: opts.agentId },
+			});
+		} else {
+			console.log();
+			printInfo("No memories found.");
+			console.log();
+		}
+	} else {
+		if (results.length > 0) {
+			formatMemoriesText(results, "memories");
+			printResultSummary({
+				count: results.length,
+				durationSecs: elapsed,
+				page: opts.page,
+				scopeIds: { user_id: opts.userId, agent_id: opts.agentId },
+			});
+		} else {
+			console.log();
+			printInfo("No memories found.");
+			console.log();
+		}
+	}
+}
+
+export async function cmdUpdate(
+	backend: Backend,
+	memoryId: string,
+	text: string | undefined,
+	opts: { metadata?: string; output: string },
+): Promise<void> {
+	setCurrentCommand("update");
+	let meta: Record<string, unknown> | undefined;
+	if (opts.metadata) {
+		try {
+			meta = JSON.parse(opts.metadata);
+		} catch {
+			printError("Invalid JSON in --metadata.");
+			process.exit(1);
+		}
+	}
+
+	const start = performance.now();
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Updating memory...", async () => {
+			return backend.update(memoryId, text, meta);
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent") {
+		formatAgentEnvelope({
+			command: "update",
+			data: result,
+			durationMs: Math.round(elapsed * 1000),
+		});
+	} else if (opts.output === "json") {
+		formatJson(result);
+	} else if (opts.output !== "quiet") {
+		printSuccess(
+			`Memory ${memoryId.slice(0, 8)} updated (${elapsed.toFixed(2)}s)`,
+		);
+	}
+}
+
+export async function cmdDelete(
+	backend: Backend,
+	memoryId: string,
+	opts: { output: string; dryRun?: boolean; force?: boolean },
+): Promise<void> {
+	setCurrentCommand("delete");
+	if (opts.dryRun) {
+		let mem: Record<string, unknown>;
+		try {
+			mem = await backend.get(memoryId);
+		} catch (e) {
+			printError(e instanceof Error ? e.message : String(e));
+			process.exit(1);
+		}
+		const text = (mem.memory ?? mem.text ?? "") as string;
+		printInfo(`Would delete memory ${memoryId.slice(0, 8)}: ${text}`);
+		printInfo("No changes made.");
+		return;
+	}
+
+	const start = performance.now();
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Deleting...", async () => {
+			return backend.delete(memoryId);
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent") {
+		formatAgentEnvelope({
+			command: "delete",
+			data: { id: memoryId, deleted: true },
+			durationMs: Math.round(elapsed * 1000),
+		});
+	} else if (opts.output === "json") {
+		formatJson(result);
+	} else if (opts.output !== "quiet") {
+		printSuccess(
+			`Memory ${memoryId.slice(0, 8)} deleted (${elapsed.toFixed(2)}s)`,
+		);
+	}
+}
+
+export async function cmdDeleteAll(
+	backend: Backend,
+	opts: {
+		force: boolean;
+		dryRun?: boolean;
+		all?: boolean;
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+		output: string;
+	},
+): Promise<void> {
+	setCurrentCommand("delete-all");
+	const { isAgentMode } = await import("../state.js");
+	if (isAgentMode() && !opts.force) {
+		printError("Destructive operation requires --force in agent mode.");
+		process.exit(1);
+	}
+	if (opts.all) {
+		// Project-wide wipe using wildcard entity IDs
+		// Note: --dry-run is ignored here because the API has no count-before-delete endpoint.
+
+		if (!opts.force) {
+			const readline = await import("node:readline");
+			const rl = readline.createInterface({
+				input: process.stdin,
+				output: process.stdout,
+			});
+			const answer = await new Promise<string>((resolve) => {
+				rl.question(
+					"\n  \u26a0  Delete ALL memories across the ENTIRE project? This cannot be undone. [y/N] ",
+					resolve,
+				);
+			});
+			rl.close();
+			if (answer.toLowerCase() !== "y") {
+				printInfo("Cancelled.");
+				process.exit(0);
+			}
+		}
+
+		const start = performance.now();
+		let result: Record<string, unknown>;
+		try {
+			result = await timedStatus(
+				"Deleting all memories project-wide...",
+				async () => {
+					return backend.delete(undefined, {
+						all: true,
+						userId: "*",
+						agentId: "*",
+						appId: "*",
+						runId: "*",
+					});
+				},
+			);
+		} catch (e) {
+			printError(e instanceof Error ? e.message : String(e));
+			process.exit(1);
+		}
+		const elapsed = (performance.now() - start) / 1000;
+
+		if (opts.output === "agent") {
+			formatAgentEnvelope({
+				command: "delete-all",
+				data: result,
+				durationMs: Math.round(elapsed * 1000),
+			});
+		} else if (opts.output === "json") {
+			formatJson(result);
+		} else if (opts.output !== "quiet") {
+			if (result.message) {
+				printInfo(
+					"Deletion started. Memories will be removed in the background.",
+				);
+			} else {
+				printSuccess(`All project memories deleted (${elapsed.toFixed(2)}s)`);
+			}
+		}
+		return;
+	}
+
+	if (opts.dryRun) {
+		let memories: Record<string, unknown>[];
+		try {
+			memories = await backend.listMemories({
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+			});
+		} catch (e) {
+			printError(e instanceof Error ? e.message : String(e));
+			process.exit(1);
+		}
+		printInfo(`Would delete ${memories.length} memories.`);
+		printInfo("No changes made.");
+		return;
+	}
+
+	if (!opts.force) {
+		const scopeParts: string[] = [];
+		if (opts.userId) scopeParts.push(`user=${opts.userId}`);
+		if (opts.agentId) scopeParts.push(`agent=${opts.agentId}`);
+		if (opts.appId) scopeParts.push(`app=${opts.appId}`);
+		if (opts.runId) scopeParts.push(`run=${opts.runId}`);
+		const scope =
+			scopeParts.length > 0 ? scopeParts.join(", ") : "ALL entities";
+
+		const readline = await import("node:readline");
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+		const answer = await new Promise<string>((resolve) => {
+			rl.question(
+				`\n  \u26a0  Delete ALL memories for ${scope}? This cannot be undone. [y/N] `,
+				resolve,
+			);
+		});
+		rl.close();
+		if (answer.toLowerCase() !== "y") {
+			printInfo("Cancelled.");
+			process.exit(0);
+		}
+	}
+
+	const start = performance.now();
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Deleting all memories...", async () => {
+			return backend.delete(undefined, {
+				all: true,
+				userId: opts.userId,
+				agentId: opts.agentId,
+				appId: opts.appId,
+				runId: opts.runId,
+			});
+		});
+	} catch (e) {
+		printError(e instanceof Error ? e.message : String(e));
+		process.exit(1);
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent") {
+		formatAgentEnvelope({
+			command: "delete-all",
+			data: result,
+			durationMs: Math.round(elapsed * 1000),
+		});
+	} else if (opts.output === "json") {
+		formatJson(result);
+	} else if (opts.output !== "quiet") {
+		if (result.message) {
+			printInfo(
+				"Deletion started. Memories will be removed in the background.",
+			);
+		} else {
+			printSuccess(`All matching memories deleted (${elapsed.toFixed(2)}s)`);
+		}
+	}
+}

cli/node/src/commands/utils.ts

@@ -0,0 +1,155 @@
+/**
+ * Utility commands: status, version, import.
+ */
+
+import fs from "node:fs";
+import boxen from "boxen";
+import type { Backend } from "../backend/base.js";
+import { colors, printError, printSuccess, timedStatus } from "../branding.js";
+import { formatAgentEnvelope, formatJsonEnvelope } from "../output.js";
+import { setCurrentCommand } from "../state.js";
+import { CLI_VERSION } from "../version.js";
+
+const { brand, dim, success, error: errorColor } = colors;
+
+export async function cmdStatus(
+	backend: Backend,
+	opts: { userId?: string; agentId?: string; output?: string } = {},
+): Promise<void> {
+	setCurrentCommand("status");
+	const start = performance.now();
+	let result: Record<string, unknown>;
+	try {
+		result = await timedStatus("Checking connection...", async () => {
+			return backend.status({ userId: opts.userId, agentId: opts.agentId });
+		});
+	} catch (e) {
+		result = {
+			connected: false,
+			error: e instanceof Error ? e.message : String(e),
+		};
+	}
+	const elapsed = (performance.now() - start) / 1000;
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "status",
+			data: {
+				connected: result.connected,
+				backend: result.backend ?? null,
+				base_url: result.base_url ?? null,
+			},
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	const lines: string[] = [];
+	if (result.connected) {
+		lines.push(`  ${success("\u25cf")} Connected`);
+	} else {
+		lines.push(`  ${errorColor("\u25cf")} Disconnected`);
+	}
+
+	lines.push(`  ${dim("Backend:")}  ${result.backend ?? "?"}`);
+	if (result.base_url) {
+		lines.push(`  ${dim("API URL:")}  ${result.base_url}`);
+	}
+	if (result.error) {
+		lines.push(`  ${errorColor("Error:")}    ${result.error}`);
+		if (String(result.error).includes("Authentication failed")) {
+			lines.push("");
+			lines.push(
+				`  ${dim("Run")} ${brand("mem0 init")} ${dim("to reconfigure your API key")}`,
+			);
+			lines.push(
+				`  ${dim("Get a key at")} ${brand("https://app.mem0.ai/dashboard/api-keys?utm_source=oss&utm_medium=cli-node")}`,
+			);
+		}
+	}
+	lines.push(`  ${dim("Latency:")}  ${elapsed.toFixed(2)}s`);
+
+	const content = lines.join("\n");
+	console.log();
+	console.log(
+		boxen(content, {
+			title: brand("Connection Status"),
+			titleAlignment: "left",
+			borderColor: "magenta",
+			padding: 1,
+		}),
+	);
+	console.log();
+}
+
+export function cmdVersion(): void {
+	console.log(`  ${brand("◆ Mem0")} CLI v${CLI_VERSION}`);
+}
+
+export async function cmdImport(
+	backend: Backend,
+	filePath: string,
+	opts: { userId?: string; agentId?: string; output?: string },
+): Promise<void> {
+	setCurrentCommand("import");
+	let data: Record<string, unknown>[];
+	try {
+		const raw = fs.readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw);
+		data = Array.isArray(parsed) ? parsed : [parsed];
+	} catch (e) {
+		printError(`Failed to read file: ${e instanceof Error ? e.message : e}`);
+		process.exit(1);
+	}
+
+	let added = 0;
+	let failed = 0;
+	const start = performance.now();
+
+	for (let i = 0; i < data.length; i++) {
+		const item = data[i];
+		const content = (item.memory ?? item.text ?? item.content ?? "") as string;
+		if (!content) {
+			failed++;
+			continue;
+		}
+
+		try {
+			await backend.add(content, undefined, {
+				userId: opts.userId ?? (item.user_id as string | undefined),
+				agentId: opts.agentId ?? (item.agent_id as string | undefined),
+				metadata: item.metadata as Record<string, unknown> | undefined,
+			});
+			added++;
+		} catch {
+			failed++;
+		}
+
+		// Simple progress indicator
+		if ((i + 1) % 10 === 0 || i === data.length - 1) {
+			process.stdout.write(
+				`\r  ${dim(`Importing memories... ${i + 1}/${data.length}`)}`,
+			);
+		}
+	}
+
+	const elapsed = (performance.now() - start) / 1000;
+	console.log(); // Clear progress line
+
+	if (opts.output === "agent" || opts.output === "json") {
+		formatAgentEnvelope({
+			command: "import",
+			data: {
+				added,
+				failed,
+			},
+			durationMs: Math.round(elapsed * 1000),
+		});
+		return;
+	}
+
+	printSuccess(`Imported ${added} memories (${elapsed.toFixed(2)}s)`);
+	if (failed > 0) {
+		printError(`${failed} memories failed to import.`);
+	}
+}

cli/node/src/commands/whoami.ts

@@ -0,0 +1,18 @@
+/**
+ * `mem0 whoami` — print the active agent's default_user_id (AGENTRUSH identifier).
+ * Reads from local config; no network call.
+ */
+
+import { colors, printError, printInfo } from "../branding.js";
+import { loadConfig } from "../config.js";
+
+export async function cmdWhoami(): Promise<void> {
+	const config = loadConfig();
+	const sessionId = config.platform?.defaultUserId;
+	if (!sessionId) {
+		printError("No default_user_id found. Run `mem0 init --agent` first.");
+		process.exit(1);
+	}
+	console.log(`Your AGENTRUSH identifier:  ${colors.brand(sessionId)}`);
+	printInfo("Find your row at https://mem0.ai/agentrush");
+}

cli/node/src/config.ts

@@ -0,0 +1,232 @@
+/**
+ * Configuration management for mem0 CLI.
+ *
+ * Config precedence (highest to lowest):
+ * 1. CLI flags (--api-key, --base-url, etc.)
+ * 2. Environment variables (MEM0_API_KEY, etc.)
+ * 3. Config file (~/.mem0/config.json)
+ * 4. Defaults
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const CONFIG_DIR = path.join(os.homedir(), ".mem0");
+export const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+export const DEFAULT_BASE_URL = "https://api.mem0.ai";
+export const CONFIG_VERSION = 1;
+
+export interface PlatformConfig {
+	apiKey: string;
+	baseUrl: string;
+	userEmail: string;
+	// Agent Mode (unclaimed-shadow signup)
+	agentMode: boolean; // true while the key is an unclaimed agent-mode key
+	createdVia: string; // "agent_mode" | "email" | "api_key" | "existing_key"
+	agentCaller: string; // canonical agent name when createdVia === "agent_mode" (e.g. "claude-code")
+	claimedAt: string; // ISO timestamp once the agent has been claimed
+	defaultUserId: string; // `user_<slug>` returned by bootstrap; auto-default scope
+}
+
+export interface DefaultsConfig {
+	userId: string;
+	agentId: string;
+	appId: string;
+	runId: string;
+}
+
+export interface TelemetryConfig {
+	anonymousId: string;
+}
+
+export interface AgentRushConfig {
+	// ISO timestamp the human acknowledged the "memories are public" warning.
+	// Empty until first interactive `mem0 agent-rush add`.
+	acknowledgedAt: string;
+}
+
+export interface Mem0Config {
+	version: number;
+	defaults: DefaultsConfig;
+	platform: PlatformConfig;
+	telemetry: TelemetryConfig;
+	agentRush: AgentRushConfig;
+}
+
+export function createDefaultConfig(): Mem0Config {
+	return {
+		version: CONFIG_VERSION,
+		defaults: {
+			userId: "",
+			agentId: "",
+			appId: "",
+			runId: "",
+		},
+		platform: {
+			apiKey: "",
+			baseUrl: DEFAULT_BASE_URL,
+			userEmail: "",
+			agentMode: false,
+			createdVia: "",
+			agentCaller: "",
+			claimedAt: "",
+			defaultUserId: "",
+		},
+		telemetry: {
+			anonymousId: "",
+		},
+		agentRush: {
+			acknowledgedAt: "",
+		},
+	};
+}
+
+export function ensureConfigDir(): string {
+	fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+	return CONFIG_DIR;
+}
+
+export function loadConfig(): Mem0Config {
+	const config = createDefaultConfig();
+
+	if (fs.existsSync(CONFIG_FILE)) {
+		const raw = fs.readFileSync(CONFIG_FILE, "utf-8");
+		const data = JSON.parse(raw);
+
+		config.version = data.version ?? CONFIG_VERSION;
+
+		const plat = data.platform ?? {};
+		config.platform.apiKey = plat.api_key ?? "";
+		config.platform.baseUrl = plat.base_url ?? DEFAULT_BASE_URL;
+		config.platform.userEmail = plat.user_email ?? "";
+		config.platform.agentMode = Boolean(plat.agent_mode ?? false);
+		config.platform.createdVia = plat.created_via ?? "";
+		config.platform.agentCaller = plat.agent_caller ?? "";
+		config.platform.claimedAt = plat.claimed_at ?? "";
+		config.platform.defaultUserId = plat.default_user_id ?? "";
+
+		const defaults = data.defaults ?? {};
+		config.defaults.userId = defaults.user_id ?? "";
+		config.defaults.agentId = defaults.agent_id ?? "";
+		config.defaults.appId = defaults.app_id ?? "";
+		config.defaults.runId = defaults.run_id ?? "";
+		const telemetry = data.telemetry ?? {};
+		config.telemetry.anonymousId = telemetry.anonymous_id ?? "";
+		const agentRush = data.agent_rush ?? {};
+		config.agentRush.acknowledgedAt = agentRush.acknowledged_at ?? "";
+	}
+
+	// Environment variable overrides
+	if (process.env.MEM0_API_KEY)
+		config.platform.apiKey = process.env.MEM0_API_KEY;
+	if (process.env.MEM0_BASE_URL)
+		config.platform.baseUrl = process.env.MEM0_BASE_URL;
+	if (process.env.MEM0_USER_ID)
+		config.defaults.userId = process.env.MEM0_USER_ID;
+	if (process.env.MEM0_AGENT_ID)
+		config.defaults.agentId = process.env.MEM0_AGENT_ID;
+	if (process.env.MEM0_APP_ID) config.defaults.appId = process.env.MEM0_APP_ID;
+	if (process.env.MEM0_RUN_ID) config.defaults.runId = process.env.MEM0_RUN_ID;
+	return config;
+}
+
+export function saveConfig(config: Mem0Config): void {
+	ensureConfigDir();
+
+	const data = {
+		version: config.version,
+		defaults: {
+			user_id: config.defaults.userId,
+			agent_id: config.defaults.agentId,
+			app_id: config.defaults.appId,
+			run_id: config.defaults.runId,
+		},
+		platform: {
+			api_key: config.platform.apiKey,
+			base_url: config.platform.baseUrl,
+			user_email: config.platform.userEmail,
+			agent_mode: config.platform.agentMode,
+			created_via: config.platform.createdVia,
+			agent_caller: config.platform.agentCaller,
+			claimed_at: config.platform.claimedAt,
+			default_user_id: config.platform.defaultUserId,
+		},
+		telemetry: {
+			anonymous_id: config.telemetry.anonymousId,
+		},
+		agent_rush: {
+			acknowledged_at: config.agentRush.acknowledgedAt,
+		},
+	};
+
+	fs.writeFileSync(CONFIG_FILE, JSON.stringify(data, null, 2));
+	fs.chmodSync(CONFIG_FILE, 0o600);
+
+	// Propagate api_key to ecosystem touchpoints (Claude plugin env injection,
+	// shell rc exports). Idempotent — updates only EXISTING entries; never
+	// creates new ones. Best-effort: errors swallowed so config.json is
+	// always authoritative, never blocked by plugin-state issues.
+	if (config.platform.apiKey) {
+		try {
+			// eslint-disable-next-line @typescript-eslint/no-require-imports
+			const { syncApiKey } = require("./plugin-sync.js");
+			syncApiKey(config.platform.apiKey);
+		} catch {
+			/* swallow */
+		}
+	}
+}
+
+export function redactKey(key: string): string {
+	if (!key) return "(not set)";
+	if (key.length <= 8) return `${key.slice(0, 2)}***`;
+	return `${key.slice(0, 4)}...${key.slice(-4)}`;
+}
+
+/** Key map from dotted config path to the config object fields. */
+const KEY_MAP: Record<string, [keyof Mem0Config, string]> = {
+	"platform.api_key": ["platform", "apiKey"],
+	"platform.base_url": ["platform", "baseUrl"],
+	"platform.user_email": ["platform", "userEmail"],
+	"defaults.user_id": ["defaults", "userId"],
+	"defaults.agent_id": ["defaults", "agentId"],
+	"defaults.app_id": ["defaults", "appId"],
+	"defaults.run_id": ["defaults", "runId"],
+	// Short-form aliases
+	api_key: ["platform", "apiKey"],
+	base_url: ["platform", "baseUrl"],
+	user_email: ["platform", "userEmail"],
+	user_id: ["defaults", "userId"],
+	agent_id: ["defaults", "agentId"],
+	app_id: ["defaults", "appId"],
+	run_id: ["defaults", "runId"],
+};
+
+export function getNestedValue(config: Mem0Config, dottedKey: string): unknown {
+	const mapping = KEY_MAP[dottedKey];
+	if (!mapping) return undefined;
+	const [section, field] = mapping;
+	return (config[section] as unknown as Record<string, unknown>)[field];
+}
+
+export function setNestedValue(
+	config: Mem0Config,
+	dottedKey: string,
+	value: string,
+): boolean {
+	const mapping = KEY_MAP[dottedKey];
+	if (!mapping) return false;
+	const [section, field] = mapping;
+	const obj = config[section] as unknown as Record<string, unknown>;
+
+	const current = obj[field];
+	if (typeof current === "boolean") {
+		obj[field] = ["true", "1", "yes"].includes(value.toLowerCase());
+	} else if (typeof current === "number") {
+		obj[field] = Number.parseInt(value, 10);
+	} else {
+		obj[field] = value;
+	}
+	return true;
+}

cli/node/src/globals.d.ts

@@ -0,0 +1,2 @@
+/** Injected by tsup at build time from package.json version field. Undefined in dev/test. */
+declare const __CLI_VERSION__: string | undefined;

cli/node/src/help.ts

@@ -0,0 +1,378 @@
+/**
+ * Rich-style help formatter for Commander.js that matches the Python CLI's
+ * Typer + Rich output (rounded box panels, brand purple, grouped options).
+ */
+
+import chalk from "chalk";
+import type { Argument, Command, Help, Option } from "commander";
+// Colors imported from chalk directly to match Typer/Rich defaults
+
+// ── Colors (matching Typer/Rich defaults) ────────────────────────────────
+
+const cyanBold = chalk.cyan.bold; // option flags, command names
+const greenBold = chalk.green.bold; // switch flags (boolean --force etc)
+const yellowBold = chalk.yellow.bold; // metavar <value>
+const yellow = chalk.yellow; // "Usage:" label
+const bold = chalk.bold; // command name in usage
+const dim = chalk.dim; // defaults, descriptions
+const dimBorder = chalk.dim; // panel borders
+
+// ── Strip ANSI ───────────────────────────────────────────────────────────
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape sequence is intentional
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+function stripAnsi(str: string): number {
+	return str.replace(ANSI_RE, "").length;
+}
+
+// ── Command display order (matches Python CLI) ──────────────────────────
+
+/** Commands grouped into panels, matching Python CLI's rich_help_panel. */
+const COMMAND_GROUPS: { panel: string; commands: string[] }[] = [
+	{
+		panel: "Memory",
+		commands: ["add", "search", "get", "list", "update", "delete"],
+	},
+	{
+		panel: "Management",
+		commands: ["init", "status", "import", "help", "entity", "event", "config"],
+	},
+];
+
+/** Flat order derived from COMMAND_GROUPS. */
+const COMMAND_ORDER: string[] = COMMAND_GROUPS.flatMap((g) => g.commands);
+
+// ── Option-to-panel mapping (derived from Python's rich_help_panel) ─────
+
+const OPTION_PANELS: Record<string, Record<string, string>> = {
+	add: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--app-id": "Scope",
+		"--run-id": "Scope",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	search: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--app-id": "Scope",
+		"--run-id": "Scope",
+		"--top-k": "Search",
+		"--threshold": "Search",
+		"--rerank": "Search",
+		"--keyword": "Search",
+		"--filter": "Search",
+		"--fields": "Search",
+		"--graph": "Search",
+		"--no-graph": "Search",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	get: {
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	list: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--app-id": "Scope",
+		"--run-id": "Scope",
+		"--page": "Pagination",
+		"--page-size": "Pagination",
+		"--category": "Filters",
+		"--after": "Filters",
+		"--before": "Filters",
+		"--graph": "Filters",
+		"--no-graph": "Filters",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	update: {
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	delete: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--app-id": "Scope",
+		"--run-id": "Scope",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	status: {
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+	import: {
+		"--user-id": "Scope",
+		"--agent-id": "Scope",
+		"--output": "Output",
+		"--api-key": "Connection",
+		"--base-url": "Connection",
+	},
+};
+
+const PANEL_ORDER: string[] = [
+	"Scope",
+	"Search",
+	"Pagination",
+	"Filters",
+	"Output",
+	"Connection",
+];
+
+// ── Panel rendering ─────────────────────────────────────────────────────
+
+/**
+ * Render a Rich-style ROUNDED box panel.
+ *
+ * ```
+ * ╭─ Title ────────────────────────╮
+ * │ row content padded             │
+ * ╰────────────────────────────────╯
+ * ```
+ */
+function renderPanel(title: string, rows: string[], width: number): string {
+	if (rows.length === 0) return "";
+
+	// Inner width is total width minus the two border chars
+	const inner = width - 2;
+
+	// Top border: ╭─ Title ─...─╮
+	const titleStr = ` ${title} `;
+	const fillLen = Math.max(0, inner - 1 - titleStr.length);
+	const topLine =
+		dimBorder("╭─") +
+		dimBorder(titleStr) +
+		dimBorder("─".repeat(fillLen)) +
+		dimBorder("╮");
+
+	// Bottom border: ╰─...─╯
+	const bottomLine =
+		dimBorder("╰") + dimBorder("─".repeat(inner)) + dimBorder("╯");
+
+	// Content rows
+	const contentLines = rows.map((row) => {
+		const visLen = stripAnsi(row);
+		const pad = Math.max(0, inner - 1 - visLen);
+		return `${dimBorder("│")} ${row}${" ".repeat(pad)}${dimBorder("│")}`;
+	});
+
+	return [topLine, ...contentLines, bottomLine].join("\n");
+}
+
+// ── Format an option term (short + long) ────────────────────────────────
+
+function formatOptionTerm(opt: Option): string {
+	const parts: string[] = [];
+	if (opt.short) parts.push(opt.short);
+	if (opt.long) parts.push(opt.long);
+	let term = parts.join(", ");
+
+	// Append value placeholder for non-boolean options
+	if (opt.flags) {
+		const match = opt.flags.match(/<[^>]+>|\[[^\]]+\]/);
+		if (match) {
+			term += ` ${match[0]}`;
+		}
+	}
+	return term;
+}
+
+// ── Get the long flag name for panel lookup ─────────────────────────────
+
+function getLongFlag(opt: Option): string {
+	if (opt.long) return opt.long;
+	return opt.short || "";
+}
+
+// ── Format a default value ──────────────────────────────────────────────
+
+function formatDefault(opt: Option): string {
+	if (opt.defaultValue !== undefined && opt.defaultValue !== false) {
+		return dim(` [default: ${opt.defaultValue}]`);
+	}
+	return "";
+}
+
+// ── The main help formatter ─────────────────────────────────────────────
+
+export function richFormatHelp(cmd: Command, helper: Help): string {
+	const width = process.stdout.columns || 80;
+	const lines: string[] = [];
+
+	const isRoot = !cmd.parent;
+
+	// ── Usage line ──
+	const usage = helper.commandUsage(cmd);
+	lines.push("");
+	if (isRoot) {
+		// Root: "Usage: mem0 <command> [options]" — <command> yellow, [options] bold
+		lines.push(
+			` ${yellow("Usage:")} ${bold(cmd.name())} ${yellow("<command>")} ${bold("[options]")}`,
+		);
+	} else {
+		// Subcommands: split into command path (bold) and args (yellow)
+		const usageParts = usage.split(" ");
+		const cmdPath: string[] = [];
+		const argParts: string[] = [];
+		let pastCmd = false;
+		for (const part of usageParts) {
+			if (!pastCmd && !part.startsWith("[") && !part.startsWith("<")) {
+				cmdPath.push(part);
+			} else {
+				pastCmd = true;
+				argParts.push(part);
+			}
+		}
+		lines.push(
+			` ${yellow("Usage:")} ${bold(cmdPath.join(" "))} ${yellow(argParts.join(" "))}`,
+		);
+	}
+	lines.push("");
+
+	// ── Description ──
+	const desc = helper.commandDescription(cmd);
+	if (desc) {
+		// Split multi-line descriptions (e.g., title + tagline)
+		const descLines = desc.split("\n");
+		for (let i = 0; i < descLines.length; i++) {
+			const dLine = descLines[i];
+			// First line is the title, subsequent non-empty lines are tagline (dimmed)
+			if (i === 0 || dLine.trim() === "") {
+				lines.push(` ${dLine}`);
+			} else {
+				lines.push(` ${dim(dLine)}`);
+			}
+		}
+		lines.push("");
+	}
+
+	// ── Arguments panel (subcommands only) ──
+	if (!isRoot) {
+		const visibleArgs = helper.visibleArguments(cmd);
+		if (visibleArgs.length > 0) {
+			const maxLen = Math.max(
+				...visibleArgs.map((a: Argument) => a.name().length),
+			);
+			const argRows = visibleArgs.map((a: Argument) => {
+				const name = cyanBold(a.name().padEnd(maxLen));
+				const description = helper.argumentDescription(a);
+				return ` ${name}  ${description}`;
+			});
+			const panel = renderPanel("Arguments", argRows, width);
+			if (panel) lines.push(panel);
+		}
+	}
+
+	// ── Collect options (grouped into panels for subcommands) ──
+	const visibleOpts = helper.visibleOptions(cmd);
+	const cmdName = cmd.name();
+	const panelMap =
+		!isRoot && OPTION_PANELS[cmdName] ? OPTION_PANELS[cmdName] : {};
+
+	const grouped: Record<string, Option[]> = { Options: [] };
+	for (const panelName of PANEL_ORDER) {
+		grouped[panelName] = [];
+	}
+
+	for (const opt of visibleOpts) {
+		const flag = getLongFlag(opt);
+		const panel = panelMap[flag];
+		if (panel && PANEL_ORDER.includes(panel)) {
+			grouped[panel].push(opt);
+		} else {
+			grouped.Options.push(opt);
+		}
+	}
+
+	// ── Collect commands ──
+	const visibleCmds = helper.visibleCommands(cmd);
+
+	if (isRoot) {
+		// ROOT: Options first, then command groups (matches Python/Typer ordering)
+		if (grouped.Options.length > 0) {
+			const optRows = formatOptionRows(grouped.Options);
+			const panel = renderPanel("Options", optRows, width);
+			if (panel) lines.push(panel);
+		}
+		if (visibleCmds.length > 0) {
+			const cmdMap = new Map(visibleCmds.map((c) => [c.name(), c]));
+			for (const group of COMMAND_GROUPS) {
+				const groupCmds = group.commands
+					.map((name) => cmdMap.get(name))
+					.filter((c): c is Command => c !== undefined);
+				if (groupCmds.length === 0) continue;
+				const maxLen = Math.max(...groupCmds.map((c) => c.name().length));
+				const cmdRows = groupCmds.map((c) => {
+					const name = cyanBold(c.name().padEnd(maxLen));
+					const description = helper.subcommandDescription(c);
+					return ` ${name}  ${description}`;
+				});
+				const panel = renderPanel(group.panel, cmdRows, width);
+				if (panel) lines.push(panel);
+			}
+		}
+	} else {
+		// SUBCOMMANDS: Options/panels first, then sub-subcommands
+		const panelSequence = ["Options", ...PANEL_ORDER];
+		for (const panelName of panelSequence) {
+			const opts = grouped[panelName];
+			if (opts && opts.length > 0) {
+				const optRows = formatOptionRows(opts);
+				const panel = renderPanel(panelName, optRows, width);
+				if (panel) lines.push(panel);
+			}
+		}
+		// Sub-subcommands (e.g., config show/get/set, entity list/delete)
+		if (visibleCmds.length > 0) {
+			const maxLen = Math.max(...visibleCmds.map((c) => c.name().length));
+			const cmdRows = visibleCmds.map((c) => {
+				const name = cyanBold(c.name().padEnd(maxLen));
+				const description = helper.subcommandDescription(c);
+				return ` ${name}  ${description}`;
+			});
+			const panel = renderPanel("Commands", cmdRows, width);
+			if (panel) lines.push(panel);
+		}
+	}
+
+	lines.push("");
+	return lines.join("\n");
+}
+
+// ── Format option rows with aligned columns ─────────────────────────────
+
+function formatOptionRows(opts: Option[]): string[] {
+	const terms = opts.map((o) => formatOptionTerm(o));
+	const maxTermLen = Math.max(...terms.map((t) => t.length));
+
+	return opts.map((opt, i) => {
+		const term = cyanBold(terms[i].padEnd(maxTermLen));
+		const desc = opt.description || "";
+		const def = formatDefault(opt);
+		return ` ${term}  ${desc}${def}`;
+	});
+}
+
+// ── Sort commands by COMMAND_ORDER ──────────────────────────────────────
+
+function sortCommands(cmds: Command[]): Command[] {
+	return [...cmds].sort((a, b) => {
+		const ai = COMMAND_ORDER.indexOf(a.name());
+		const bi = COMMAND_ORDER.indexOf(b.name());
+		// Unknown commands go to end, preserving original order
+		const aIdx = ai === -1 ? COMMAND_ORDER.length : ai;
+		const bIdx = bi === -1 ? COMMAND_ORDER.length : bi;
+		return aIdx - bIdx;
+	});
+}

cli/node/src/index.ts

@@ -0,0 +1,880 @@
+#!/usr/bin/env node
+
+/**
+ * Main CLI application — the entrypoint for `mem0`.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { AuthError, type Backend, getBackend } from "./backend/index.js";
+import { colors, printError, printWarning } from "./branding.js";
+import type { Mem0Config } from "./config.js";
+import { loadConfig, saveConfig } from "./config.js";
+import { richFormatHelp } from "./help.js";
+import {
+	isAgentMode,
+	setAgentMode,
+	setCurrentCommand,
+	takeNotice,
+} from "./state.js";
+import { captureEvent } from "./telemetry.js";
+import { CLI_VERSION } from "./version.js";
+
+const program = new Command();
+
+// ── Validated user identity (set by getBackendAndConfig) ─────────────────
+
+let _validatedUserEmail: string | undefined;
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+async function getBackendAndConfig(
+	apiKey?: string,
+	baseUrl?: string,
+): Promise<{ backend: Backend; config: Mem0Config }> {
+	const config = loadConfig();
+
+	if (apiKey) config.platform.apiKey = apiKey;
+	if (baseUrl) config.platform.baseUrl = baseUrl;
+
+	if (!config.platform.apiKey) {
+		printError(
+			"No API key configured.",
+			"Run 'mem0 init' or set MEM0_API_KEY environment variable.",
+		);
+		process.exit(1);
+	}
+
+	const backend = getBackend(config);
+
+	// Validate the API key upfront with a fast timeout
+	try {
+		const pingData = (await Promise.race([
+			backend.ping(),
+			new Promise<never>((_, reject) =>
+				setTimeout(() => reject(new Error("timeout")), 5000),
+			),
+		])) as Record<string, unknown>;
+
+		const email = pingData?.user_email as string | undefined;
+		if (email) {
+			_validatedUserEmail = email;
+			if (config.platform.userEmail !== email) {
+				config.platform.userEmail = email;
+				try {
+					saveConfig(config);
+				} catch {
+					/* ignore */
+				}
+			}
+		}
+	} catch (e) {
+		if (e instanceof AuthError) {
+			printError(
+				"Invalid or expired API key.",
+				"Run 'mem0 init' or set MEM0_API_KEY environment variable.",
+			);
+			process.exit(1);
+		}
+		// Network error / timeout — warn but proceed
+		printWarning(
+			"Could not validate API key (network issue). Proceeding anyway.",
+		);
+	}
+
+	return { backend, config };
+}
+
+async function getBackendOnly(
+	apiKey?: string,
+	baseUrl?: string,
+): Promise<Backend> {
+	return (await getBackendAndConfig(apiKey, baseUrl)).backend;
+}
+
+function checkAgentMode(): boolean {
+	const rootOpts = program.opts();
+	const isAgent = !!(rootOpts.json || rootOpts.agent);
+	if (isAgent) setAgentMode(true);
+	return isAgent;
+}
+
+/**
+ * Resolve entity IDs: CLI flag > config default > undefined.
+ *
+ * If any explicit ID is provided, only use explicit IDs (don't mix
+ * in defaults for other entity types which would over-filter).
+ * If no explicit IDs, fall back to all configured defaults.
+ */
+function resolveIds(
+	config: Mem0Config,
+	opts: {
+		userId?: string;
+		agentId?: string;
+		appId?: string;
+		runId?: string;
+	},
+): { userId?: string; agentId?: string; appId?: string; runId?: string } {
+	const hasExplicit = !!(
+		opts.userId ||
+		opts.agentId ||
+		opts.appId ||
+		opts.runId
+	);
+	if (hasExplicit) {
+		return {
+			userId: opts.userId || undefined,
+			agentId: opts.agentId || undefined,
+			appId: opts.appId || undefined,
+			runId: opts.runId || undefined,
+		};
+	}
+	return {
+		userId: config.defaults.userId || undefined,
+		agentId: config.defaults.agentId || undefined,
+		appId: config.defaults.appId || undefined,
+		runId: config.defaults.runId || undefined,
+	};
+}
+
+// ── Main program ──────────────────────────────────────────────────────────
+
+program
+	.name("mem0")
+	.description(
+		`◆ Mem0 CLI v${CLI_VERSION} · Node.js SDK\n\nThe Memory Layer for AI Agents`,
+	)
+	// Positional options: flags AFTER a subcommand name belong to that
+	// subcommand, not the global program. Without this, `mem0 init --agent`
+	// routes `--agent` to the program-level alias (for --json) and init's own
+	// `--agent` (Agent Mode bootstrap) silently never fires.
+	.enablePositionalOptions()
+	.option("--version", "Show version and exit.")
+	.on("option:version", () => {
+		console.log(`  ${colors.brand("◆ Mem0")} CLI v${CLI_VERSION}`);
+		process.exit(0);
+	})
+	.option("--json", "Output as JSON for agent/programmatic use.")
+	.option(
+		"--agent",
+		"Output as JSON for agent/programmatic use. (alias: --json) Place BEFORE the subcommand: `mem0 --agent <cmd>`. On `init`, `mem0 init --agent` is the Agent Mode bootstrap flag instead.",
+	)
+	.usage("<command> [options]")
+	.helpOption("--help", "Show this message and exit.")
+	.addHelpCommand(false)
+	.configureHelp({ formatHelp: richFormatHelp });
+
+// ── Telemetry hook ───────────────────────────────────────────────────────
+
+program.hook("preAction", (_thisCommand, actionCommand) => {
+	try {
+		const commandName = actionCommand.name();
+		const parentName = actionCommand.parent?.name();
+		const fullCommand =
+			parentName && parentName !== "mem0"
+				? `${parentName}.${commandName}`
+				: commandName;
+		// Stash the active command name in shared state so the JSON
+		// error envelope (printError) can report which command failed
+		// instead of an empty `"command": ""` field.
+		setCurrentCommand(fullCommand);
+		// init fires its own telemetry from runInit with full M1-M6 props
+		// (mode/agent_caller/signup_source/claimed_agent_mode); skip the
+		// auto-fire here so we don't double-count.
+		if (fullCommand === "init") return;
+		const isAgent = !!(program.opts().json || program.opts().agent);
+		captureEvent(
+			`cli.${fullCommand}`,
+			{
+				command: fullCommand,
+				is_agent: isAgent,
+			},
+			_validatedUserEmail,
+		);
+	} catch {
+		/* silently swallow */
+	}
+});
+
+// ── Init ──────────────────────────────────────────────────────────────────
+
+program
+	.command("init")
+	.description("Interactive setup wizard for mem0 CLI.")
+	.option("--api-key <key>", "API key (skip prompt).")
+	.option("-u, --user-id <id>", "Default user ID (skip prompt).")
+	.option("--email <email>", "Login via email verification code.")
+	.option(
+		"--code <code>",
+		"Verification code (use with --email for non-interactive login).",
+	)
+	.option("--force", "Overwrite existing config without confirmation.", false)
+	.option(
+		"--agent",
+		"Bootstrap an unattended Agent Mode account (no email required).",
+		false,
+	)
+	.option(
+		"--source <channel>",
+		"Channel attribution for signup (e.g. github, hn, ph).",
+	)
+	.option(
+		"--agent-caller <name>",
+		"Self-declared agent identity (e.g. claude-code, cursor). Used with --agent to attribute Agent Mode signups.",
+	)
+	// Accept `--json` at the init level too so the PRD-documented form
+	// `mem0 init --agent --json` works without requiring users to move it
+	// before the subcommand. Effect is identical to the global `--json`:
+	// flip agent-mode output state.
+	.option("--json", "Output as JSON (alias for global `--json`).", false)
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 init\n  $ mem0 init --api-key m0-xxx --user-id alice\n  $ mem0 init --email you@example.com\n  $ mem0 init --email you@example.com --code 123456\n  $ mem0 init --agent             # Bootstrap an Agent Mode account (unattended)\n  $ mem0 init --email you@example.com  # Claims an existing Agent Mode key when one is present",
+	)
+	.action(async (opts) => {
+		// `--json` at init level mirrors the global flag — flip agent_mode
+		// state so downstream formatters use JSON envelopes.
+		if (opts.json) setAgentMode(true);
+		const { runInit } = await import("./commands/init.js");
+		await runInit({
+			apiKey: opts.apiKey,
+			userId: opts.userId,
+			email: opts.email,
+			code: opts.code,
+			force: opts.force,
+			agent: opts.agent,
+			source: opts.source,
+			agentCaller: opts.agentCaller,
+		});
+	});
+
+// ── Setup: identify (post-bootstrap agent self-tag) ──────────────────────
+
+program
+	.command("identify <name>")
+	.description(
+		"Tag your active Agent Mode key with the AI agent that's using it (e.g. claude-code, cursor).",
+	)
+	.action(async (name: string) => {
+		const { runIdentify } = await import("./commands/identify.js");
+		await runIdentify(name);
+	});
+
+// ── Setup: whoami (print active agent identifier) ────────────────────────
+
+program
+	.command("whoami")
+	.description("Print the active agent's AGENTRUSH identifier.")
+	.action(async () => {
+		const { cmdWhoami } = await import("./commands/whoami.js");
+		await cmdWhoami();
+	});
+
+// ── AGENTRUSH subcommand group ────────────────────────────────────────────
+
+const agentRush = program
+	.command("agent-rush")
+	.description("AGENTRUSH game commands.")
+	.addHelpCommand(false)
+	.configureHelp({ formatHelp: richFormatHelp });
+
+agentRush
+	.command("add <content...>")
+	.description("Submit a memory to AGENTRUSH.")
+	.addHelpText(
+		"after",
+		'\nExamples:\n  $ mem0 agent-rush add "I used mem0 to build a coding agent"\n  $ mem0 agent-rush add "Agents that remember are better agents"',
+	)
+	.action(async (parts: string[]) => {
+		const { cmdAgentRushAdd } = await import("./commands/agent-rush.js");
+		await cmdAgentRushAdd(parts.join(" "));
+	});
+
+agentRush
+	.command("search <query...>")
+	.description("Search AGENTRUSH memories.")
+	.addHelpText(
+		"after",
+		'\nExamples:\n  $ mem0 agent-rush search "agents and memory and tools"\n  $ mem0 agent-rush search "coding assistant"',
+	)
+	.action(async (parts: string[]) => {
+		const { cmdAgentRushSearch } = await import("./commands/agent-rush.js");
+		await cmdAgentRushSearch(parts.join(" "));
+	});
+
+// ── Memory: add ───────────────────────────────────────────────────────────
+
+program
+	.command("add [text]")
+	.description("Add a memory from text, messages, file, or stdin.")
+	.option("-u, --user-id <id>", "Scope to user.")
+	.option("--agent-id <id>", "Scope to agent.")
+	.option("--app-id <id>", "Scope to app.")
+	.option("--run-id <id>", "Scope to run.")
+	.option("--messages <json>", "Conversation messages as JSON.")
+	.option("-f, --file <path>", "Read messages from JSON file.")
+	.option("-m, --metadata <json>", "Custom metadata as JSON.")
+	.option("--immutable", "Prevent future updates.", false)
+	.option("--no-infer", "Skip inference, store raw.")
+	.option("--expires <date>", "Expiration date (YYYY-MM-DD).")
+	.option("--categories <value>", "Categories (JSON array or comma-separated).")
+	.option("-o, --output <format>", "Output format: text, json, quiet.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		'\nExamples:\n  $ mem0 add "I prefer dark mode" --user-id alice\n  $ echo "text" | mem0 add -u alice\n  $ mem0 add --file msgs.json -u alice -o json',
+	)
+	.action(async (text, opts) => {
+		const { cmdAdd } = await import("./commands/memory.js");
+		const isAgent = checkAgentMode();
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
+		const ids = resolveIds(config, opts);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdAdd(backend, text, { ...ids, ...opts, output });
+	});
+
+// ── Memory: search ────────────────────────────────────────────────────────
+
+program
+	.command("search [query]")
+	.description(
+		"Query your memory store — semantic, keyword, or hybrid retrieval.",
+	)
+	.option("-u, --user-id <id>", "Filter by user.")
+	.option("--agent-id <id>", "Filter by agent.")
+	.option("--app-id <id>", "Filter by app.")
+	.option("--run-id <id>", "Filter by run.")
+	.option(
+		"-k, --top-k <n>",
+		"Number of results.",
+		(v) => Number.parseInt(v),
+		10,
+	)
+	.option(
+		"--threshold <n>",
+		"Minimum similarity score.",
+		(v) => Number.parseFloat(v),
+		0.3,
+	)
+	.option("--rerank", "Enable reranking (Platform only).", false)
+	.option("--keyword", "Use keyword search.", false)
+	.option("--filter <json>", "Advanced filter expression (JSON).")
+	.option("--fields <list>", "Specific fields to return (comma-separated).")
+	.option("-o, --output <format>", "Output: text, json, table.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		'\nExamples:\n  $ mem0 search "preferences" --user-id alice\n  $ mem0 search "tools" -u alice -o json -k 5\n  $ echo "preferences" | mem0 search -u alice',
+	)
+	.action(async (query, opts) => {
+		let resolvedQuery = query;
+		if (!resolvedQuery && !process.stdin.isTTY) {
+			resolvedQuery = fs.readFileSync(0, "utf-8").trim();
+		}
+		if (!resolvedQuery) {
+			printError("No query provided. Pass a query argument or pipe via stdin.");
+			process.exit(1);
+		}
+		const { cmdSearch } = await import("./commands/memory.js");
+		const isAgent = checkAgentMode();
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
+		const ids = resolveIds(config, opts);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdSearch(backend, resolvedQuery, {
+			...ids,
+			topK: opts.topK,
+			threshold: opts.threshold,
+			rerank: opts.rerank,
+			keyword: opts.keyword,
+			filterJson: opts.filter,
+			fields: opts.fields,
+			output,
+		});
+	});
+
+// ── Memory: get ───────────────────────────────────────────────────────────
+
+program
+	.command("get <memoryId>")
+	.description("Get a specific memory by ID.")
+	.option("-o, --output <format>", "Output: text, json.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 get abc-123-def-456\n  $ mem0 get abc-123-def-456 -o json",
+	)
+	.action(async (memoryId, opts) => {
+		const { cmdGet } = await import("./commands/memory.js");
+		const isAgent = checkAgentMode();
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdGet(backend, memoryId, { output });
+	});
+
+// ── Memory: list ──────────────────────────────────────────────────────────
+
+program
+	.command("list")
+	.description("List memories with optional filters.")
+	.option("-u, --user-id <id>", "Filter by user.")
+	.option("--agent-id <id>", "Filter by agent.")
+	.option("--app-id <id>", "Filter by app.")
+	.option("--run-id <id>", "Filter by run.")
+	.option("--page <n>", "Page number.", (v) => Number.parseInt(v), 1)
+	.option(
+		"--page-size <n>",
+		"Results per page.",
+		(v) => Number.parseInt(v),
+		100,
+	)
+	.option("--category <name>", "Filter by category.")
+	.option("--after <date>", "Created after (YYYY-MM-DD).")
+	.option("--before <date>", "Created before (YYYY-MM-DD).")
+	.option("-o, --output <format>", "Output: text, json, table.", "table")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 list -u alice\n  $ mem0 list --category prefs --after 2024-01-01 -o json",
+	)
+	.action(async (opts) => {
+		const { cmdList } = await import("./commands/memory.js");
+		const isAgent = checkAgentMode();
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
+		const ids = resolveIds(config, opts);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdList(backend, {
+			...ids,
+			page: opts.page,
+			pageSize: opts.pageSize,
+			category: opts.category,
+			after: opts.after,
+			before: opts.before,
+			output,
+		});
+	});
+
+// ── Memory: update ────────────────────────────────────────────────────────
+
+program
+	.command("update <memoryId> [text]")
+	.description("Update a memory's text or metadata.")
+	.option("-m, --metadata <json>", "Update metadata (JSON).")
+	.option("-o, --output <format>", "Output: text, json, quiet.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		`\nExamples:\n  $ mem0 update abc-123 "new text"\n  $ mem0 update abc-123 --metadata '{"key":"val"}'\n  $ echo "new text" | mem0 update abc-123`,
+	)
+	.action(async (memoryId, text, opts) => {
+		let resolvedText = text;
+		if (!resolvedText && !opts.metadata && !process.stdin.isTTY) {
+			resolvedText = fs.readFileSync(0, "utf-8").trim();
+		}
+		const { cmdUpdate } = await import("./commands/memory.js");
+		const isAgent = checkAgentMode();
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdUpdate(backend, memoryId, resolvedText, {
+			metadata: opts.metadata,
+			output,
+		});
+	});
+
+// ── Memory: delete (consolidated) ─────────────────────────────────────────
+
+program
+	.command("delete [memoryId]")
+	.description("Delete a memory, all memories matching a scope, or an entity.")
+	.option("--all", "Delete all memories matching scope filters.", false)
+	.option(
+		"--entity",
+		"Delete the entity itself and all its memories (cascade).",
+		false,
+	)
+	.option("--project", "With --all: delete ALL memories project-wide.", false)
+	.option("--dry-run", "Show what would be deleted without deleting.", false)
+	.option("--force", "Skip confirmation.", false)
+	.option("-u, --user-id <id>", "Scope to user.")
+	.option("--agent-id <id>", "Scope to agent.")
+	.option("--app-id <id>", "Scope to app.")
+	.option("--run-id <id>", "Scope to run.")
+	.option("-o, --output <format>", "Output: text, json, quiet.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		[
+			"\nExamples:",
+			"  $ mem0 delete abc-123-def-456              # single memory",
+			"  $ mem0 delete --all -u alice --force        # all memories for user",
+			"  $ mem0 delete --all --project --force       # project-wide wipe",
+			"  $ mem0 delete --entity -u alice --force     # entity + all its memories",
+		].join("\n"),
+	)
+	.action(async (memoryId, opts) => {
+		const isAgent = checkAgentMode();
+		const output = isAgent ? "agent" : opts.output;
+		// ── Mutual-exclusion checks ──
+		if (memoryId && opts.all) {
+			printError("Cannot combine <memoryId> with --all. Use one or the other.");
+			process.exit(1);
+		}
+		if (memoryId && opts.entity) {
+			printError(
+				"Cannot combine <memoryId> with --entity. Use one or the other.",
+			);
+			process.exit(1);
+		}
+		if (opts.all && opts.entity) {
+			printError("Cannot combine --all with --entity. Use one or the other.");
+			process.exit(1);
+		}
+		if (!memoryId && !opts.all && !opts.entity) {
+			printError(
+				"Specify a memory ID, --all, or --entity.\n" +
+					"  mem0 delete <id>              Delete a single memory\n" +
+					"  mem0 delete --all [scope]     Delete all memories matching scope\n" +
+					"  mem0 delete --entity [scope]  Delete an entity and all its memories",
+			);
+			process.exit(1);
+		}
+
+		// ── Dispatch: single memory ──
+		if (memoryId) {
+			const { cmdDelete } = await import("./commands/memory.js");
+			const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+			await cmdDelete(backend, memoryId, {
+				output,
+				dryRun: opts.dryRun,
+				force: opts.force,
+			});
+			return;
+		}
+
+		// ── Dispatch: --all ──
+		if (opts.all) {
+			const { cmdDeleteAll } = await import("./commands/memory.js");
+			const { backend, config } = await getBackendAndConfig(
+				opts.apiKey,
+				opts.baseUrl,
+			);
+			const ids = opts.project
+				? {
+						userId: undefined,
+						agentId: undefined,
+						appId: undefined,
+						runId: undefined,
+					}
+				: resolveIds(config, opts);
+			await cmdDeleteAll(backend, {
+				force: opts.force,
+				dryRun: opts.dryRun,
+				all: opts.project,
+				...ids,
+				output,
+			});
+			return;
+		}
+
+		// ── Dispatch: --entity ──
+		if (opts.entity) {
+			const { cmdEntitiesDelete } = await import("./commands/entities.js");
+			const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+			await cmdEntitiesDelete(backend, { ...opts, output });
+			return;
+		}
+	});
+
+// ── Config subcommands ────────────────────────────────────────────────────
+
+const configCmd = program
+	.command("config")
+	.description("Manage mem0 configuration.")
+	.addHelpCommand(false);
+
+configCmd
+	.command("show")
+	.description("Display current configuration (secrets redacted).")
+	.option("-o, --output <format>", "Output: text, json.", "text")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 config show\n  $ mem0 config show -o json",
+	)
+	.action(async (opts) => {
+		const { cmdConfigShow } = await import("./commands/config.js");
+		const isAgent = checkAgentMode();
+		const output = isAgent ? "agent" : opts.output;
+		cmdConfigShow({ output });
+	});
+
+configCmd
+	.command("get <key>")
+	.description("Get a configuration value.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 config get platform.api_key\n  $ mem0 config get defaults.user_id",
+	)
+	.action(async (key) => {
+		const { cmdConfigGet } = await import("./commands/config.js");
+		checkAgentMode();
+		cmdConfigGet(key);
+	});
+
+configCmd
+	.command("set <key> <value>")
+	.description("Set a configuration value.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 config set defaults.user_id alice\n  $ mem0 config set platform.base_url https://api.mem0.ai",
+	)
+	.action(async (key, value) => {
+		const { cmdConfigSet } = await import("./commands/config.js");
+		checkAgentMode();
+		cmdConfigSet(key, value);
+	});
+
+// ── Entity subcommand group ───────────────────────────────────────────────
+
+const entityCmd = program
+	.command("entity")
+	.description("Manage entities.")
+	.addHelpCommand(false)
+	.configureHelp({ formatHelp: richFormatHelp });
+
+entityCmd
+	.command("list <entityType>")
+	.description("List all entities of a given type.")
+	.option("-o, --output <format>", "Output: table, json.", "table")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 entity list users\n  $ mem0 entity list agents -o json",
+	)
+	.action(async (entityType, opts) => {
+		const { cmdEntitiesList } = await import("./commands/entities.js");
+		const isAgent = checkAgentMode();
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdEntitiesList(backend, entityType, { output });
+	});
+
+entityCmd
+	.command("delete")
+	.description("Delete an entity and ALL its memories (cascade).")
+	.option("--dry-run", "Show what would be deleted without deleting.", false)
+	.option("-u, --user-id <id>", "Scope to user.")
+	.option("--agent-id <id>", "Scope to agent.")
+	.option("--app-id <id>", "Scope to app.")
+	.option("--run-id <id>", "Scope to run.")
+	.option("--force", "Skip confirmation.", false)
+	.option("-o, --output <format>", "Output: text, json, quiet.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 entity delete --user-id alice --force\n  $ mem0 entity delete --user-id alice --dry-run",
+	)
+	.action(async (opts) => {
+		const { cmdEntitiesDelete } = await import("./commands/entities.js");
+		const isAgent = checkAgentMode();
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdEntitiesDelete(backend, { ...opts, output });
+	});
+
+// ── Event subcommands ─────────────────────────────────────────────────────
+
+const eventCmd = program
+	.command("event")
+	.description("Inspect background processing events.")
+	.addHelpCommand(false)
+	.configureHelp({ formatHelp: richFormatHelp });
+
+eventCmd
+	.command("list")
+	.description("List recent background processing events.")
+	.option("-o, --output <format>", "Output: table, json.", "table")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 event list\n  $ mem0 event list -o json",
+	)
+	.action(async (opts) => {
+		const { cmdEventList } = await import("./commands/events.js");
+		const isAgent = checkAgentMode();
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdEventList(backend, { output });
+	});
+
+eventCmd
+	.command("status <eventId>")
+	.description("Check the status of a specific background event.")
+	.option("-o, --output <format>", "Output: text, json.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 event status <event-id>\n  $ mem0 event status <event-id> -o json",
+	)
+	.action(async (eventId, opts) => {
+		const { cmdEventStatus } = await import("./commands/events.js");
+		const isAgent = checkAgentMode();
+		const backend = await getBackendOnly(opts.apiKey, opts.baseUrl);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdEventStatus(backend, eventId, { output });
+	});
+
+// ── Utility commands ──────────────────────────────────────────────────────
+
+program
+	.command("status")
+	.description("Check connectivity and authentication.")
+	.option("-o, --output <format>", "Output: text, json.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText("after", "\nExamples:\n  $ mem0 status\n  $ mem0 status -o json")
+	.action(async (opts) => {
+		const { cmdStatus } = await import("./commands/utils.js");
+		const isAgent = checkAgentMode();
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdStatus(backend, {
+			userId: config.defaults.userId || undefined,
+			agentId: config.defaults.agentId || undefined,
+			output,
+		});
+	});
+
+program
+	.command("import <filePath>")
+	.description("Import memories from a JSON file.")
+	.option("-u, --user-id <id>", "Override user ID.")
+	.option("--agent-id <id>", "Override agent ID.")
+	.option("-o, --output <format>", "Output: text, json.", "text")
+	.option("--api-key <key>", "Override API key.")
+	.option("--base-url <url>", "Override API base URL.")
+	.addHelpText(
+		"after",
+		"\nExamples:\n  $ mem0 import data.json --user-id alice\n  $ mem0 import data.json -u alice -o json",
+	)
+	.action(async (filePath, opts) => {
+		const { cmdImport } = await import("./commands/utils.js");
+		const isAgent = checkAgentMode();
+		const { backend, config } = await getBackendAndConfig(
+			opts.apiKey,
+			opts.baseUrl,
+		);
+		const ids = resolveIds(config, opts);
+		const output = isAgent ? "agent" : opts.output;
+		await cmdImport(backend, filePath, {
+			userId: ids.userId,
+			agentId: ids.agentId,
+			output,
+		});
+	});
+
+// ── Help (machine-readable) ──────────────────────────────────────────────
+
+program
+	.command("help")
+	.description(
+		"Show help. Use --json for machine-readable output (for LLM agents).",
+	)
+	.option("--json", "Output machine-readable JSON for LLM agents.", false)
+	.addHelpText("after", "\nExamples:\n  $ mem0 help\n  $ mem0 help --json")
+	.action((opts) => {
+		// opts.json is set when `mem0 help --json` is used (subcommand flag).
+		// program.opts().json is set when the root --json global flag was used first.
+		if (opts.json || program.opts().json) {
+			// Load spec from parent directory
+			const __dirname = path.dirname(fileURLToPath(import.meta.url));
+			const specPath = path.join(__dirname, "..", "..", "cli-spec.json");
+			if (fs.existsSync(specPath)) {
+				const spec = JSON.parse(fs.readFileSync(specPath, "utf-8"));
+				console.log(JSON.stringify(spec, null, 2));
+			} else {
+				console.log(
+					JSON.stringify(
+						{
+							name: "mem0",
+							version: CLI_VERSION,
+							description: "The Memory Layer for AI Agents",
+						},
+						null,
+						2,
+					),
+				);
+			}
+		} else {
+			const { brand: b } = colors;
+			console.log(
+				`${b("◆ Mem0 CLI")} v${CLI_VERSION} · Node.js SDK\n  The Memory Layer for AI Agents\n`,
+			);
+			console.log("Usage: mem0 <command> [OPTIONS]\n");
+			console.log("Commands:");
+			console.log(
+				"  add              Add a memory from text, messages, file, or stdin",
+			);
+			console.log(
+				"  search           Query your memory store (semantic, keyword, hybrid)",
+			);
+			console.log("  get              Get a specific memory by ID");
+			console.log("  list             List memories with optional filters");
+			console.log("  update           Update a memory's text or metadata");
+			console.log(
+				"  delete           Delete a memory, all memories, or an entity",
+			);
+			console.log("  import           Import memories from a JSON file");
+			console.log("  config           Manage configuration (show, get, set)");
+			console.log("  entity           Manage entities (list, delete)");
+			console.log(
+				"  event            Inspect background events (list, status)",
+			);
+			console.log("  init             Interactive setup wizard");
+			console.log("  status           Check connectivity and authentication");
+			console.log();
+			console.log("  mem0 <command> --help    Get help for a command");
+			console.log(
+				"  mem0 help --json         Machine-readable help (for LLM agents)",
+			);
+			console.log();
+		}
+	});
+
+// ── Entrypoint ────────────────────────────────────────────────────────────
+
+// Surface any unclaimed Agent Mode notice once per command, after the primary
+// output. In JSON/agent mode the notice is folded into the envelope by
+// formatJsonEnvelope, so skip the stderr banner there to avoid duplication.
+function surfaceNotice(): void {
+	const notice = takeNotice();
+	if (notice && !isAgentMode()) {
+		process.stderr.write(`\n\x1b[33m🔔 ${notice}\x1b[0m\n\n`);
+	}
+}
+
+program.parseAsync().finally(() => {
+	surfaceNotice();
+});

cli/node/src/output.ts

@@ -0,0 +1,397 @@
+/**
+ * Output formatting for mem0 CLI — text, JSON, table, quiet modes.
+ */
+
+import boxen from "boxen";
+import Table from "cli-table3";
+import { colors, sym } from "./branding.js";
+import { takeNotice } from "./state.js";
+
+const { brand, accent, success, error: errorColor, dim } = colors;
+
+function formatDate(dtStr?: string): string | undefined {
+	if (!dtStr) return undefined;
+	try {
+		const dt = new Date(dtStr.replace("Z", "+00:00"));
+		return dt.toISOString().slice(0, 10);
+	} catch {
+		return dtStr?.slice(0, 10);
+	}
+}
+
+export function formatMemoriesText(
+	memories: Record<string, unknown>[],
+	title = "memories",
+): void {
+	const count = memories.length;
+	console.log(`\n${brand(`Found ${count} ${title}:`)}\n`);
+
+	for (let i = 0; i < memories.length; i++) {
+		const mem = memories[i];
+		const memoryText = (mem.memory ?? mem.text ?? "") as string;
+		const memId = ((mem.id as string) ?? "").slice(0, 8);
+		const score = mem.score as number | undefined;
+		const created = formatDate(mem.created_at as string | undefined);
+		let category: string | undefined;
+		const cats = mem.categories;
+		if (Array.isArray(cats)) {
+			category = cats[0] as string | undefined;
+		}
+
+		console.log(`  ${i + 1}. ${memoryText}`);
+
+		const details: string[] = [];
+		if (score !== undefined) details.push(`Score: ${score.toFixed(2)}`);
+		if (memId) details.push(`ID: ${memId}`);
+		if (created) details.push(`Created: ${created}`);
+		if (category) details.push(`Category: ${category}`);
+
+		if (details.length > 0) {
+			console.log(`     ${dim(details.join(" · "))}`);
+		}
+		console.log();
+	}
+}
+
+export function formatMemoriesTable(
+	memories: Record<string, unknown>[],
+	opts: { showScore?: boolean } = {},
+): void {
+	const head = opts.showScore
+		? [
+				accent("ID"),
+				accent("Score"),
+				accent("Memory"),
+				accent("Category"),
+				accent("Created"),
+			]
+		: [accent("ID"), accent("Memory"), accent("Category"), accent("Created")];
+	const colWidths = opts.showScore ? [38, 8, 40, 16, 14] : [38, 40, 16, 14];
+	const table = new Table({
+		head,
+		colWidths,
+		wordWrap: true,
+		style: { head: [], border: [] },
+	});
+
+	for (const mem of memories) {
+		const memId = (mem.id as string) ?? "";
+		let memoryText = (mem.memory ?? mem.text ?? "") as string;
+		if (memoryText.length > 60) {
+			memoryText = `${memoryText.slice(0, 57)}...`;
+		}
+		const categories = mem.categories;
+		const cat =
+			Array.isArray(categories) && categories.length > 0
+				? categories.length > 1
+					? `${categories[0]} (+${categories.length - 1})`
+					: (categories[0] as string)
+				: "—";
+		const created = formatDate(mem.created_at as string | undefined) ?? "—";
+		if (opts.showScore) {
+			const score = mem.score as number | undefined;
+			const scoreStr = score !== undefined ? score.toFixed(2) : "—";
+			table.push([dim(memId), scoreStr, memoryText, cat, created]);
+		} else {
+			table.push([dim(memId), memoryText, cat, created]);
+		}
+	}
+
+	console.log();
+	console.log(table.toString());
+	console.log();
+}
+
+export function formatJson(data: unknown): void {
+	console.log(JSON.stringify(data, null, 2));
+}
+
+export function formatSingleMemory(
+	mem: Record<string, unknown>,
+	output = "text",
+): void {
+	if (output === "json") {
+		formatJson(mem);
+		return;
+	}
+
+	const memoryText = (mem.memory ?? mem.text ?? "") as string;
+	const memId = (mem.id ?? "") as string;
+
+	const lines: string[] = [];
+	lines.push(`  ${memoryText}`);
+	lines.push("");
+
+	if (memId) lines.push(`  ${dim("ID:")}         ${memId}`);
+	const created = formatDate(mem.created_at as string | undefined);
+	if (created) lines.push(`  ${dim("Created:")}    ${created}`);
+	const updated = formatDate(mem.updated_at as string | undefined);
+	if (updated) lines.push(`  ${dim("Updated:")}    ${updated}`);
+	const meta = mem.metadata;
+	if (meta) lines.push(`  ${dim("Metadata:")}   ${JSON.stringify(meta)}`);
+	const categories = mem.categories;
+	if (categories) {
+		const catStr = Array.isArray(categories)
+			? categories.join(", ")
+			: String(categories);
+		lines.push(`  ${dim("Categories:")} ${catStr}`);
+	}
+
+	const content = lines.join("\n");
+	console.log();
+	console.log(
+		boxen(content, {
+			title: brand("Memory"),
+			titleAlignment: "left",
+			borderColor: "magenta",
+			padding: 1,
+		}),
+	);
+	console.log();
+}
+
+export function formatAddResult(
+	result: Record<string, unknown> | Record<string, unknown>[],
+	output = "text",
+): void {
+	if (output === "json") {
+		formatJson(result);
+		return;
+	}
+	if (output === "quiet") return;
+
+	const results: Record<string, unknown>[] = Array.isArray(result)
+		? result
+		: ((result.results as Record<string, unknown>[]) ?? [result]);
+
+	if (!results.length) {
+		console.log(`  ${dim("No memories extracted.")}`);
+		return;
+	}
+
+	console.log();
+	const seenPendingEvents = new Set<string>();
+	for (const r of results) {
+		// Detect async PENDING response
+		if (r.status === "PENDING") {
+			const eventId = (r.event_id as string) ?? "";
+			// Deduplicate PENDING entries with the same event_id
+			if (eventId && seenPendingEvents.has(eventId)) continue;
+			if (eventId) seenPendingEvents.add(eventId);
+			const icon = accent(sym("⧗", "..."));
+			const parts = [
+				`  ${icon} ${dim("Queued".padEnd(10))}`,
+				"Processing in background",
+			];
+			console.log(parts.join("  "));
+			if (eventId) {
+				console.log(`  ${dim(`  event_id: ${eventId}`)}`);
+				console.log(
+					`  ${dim(`  → Check status: mem0 event status ${eventId}`)}`,
+				);
+			}
+			continue;
+		}
+
+		const event = (r.event ?? "ADD") as string;
+		const memory = (r.memory ?? r.text ?? r.content ?? r.data ?? "") as string;
+		const memId = ((r.id as string) ?? (r.memory_id as string) ?? "").slice(
+			0,
+			8,
+		);
+
+		let icon: string;
+		let label: string;
+		if (event === "ADD") {
+			icon = success("+");
+			label = "Added";
+		} else if (event === "UPDATE") {
+			icon = accent("~");
+			label = "Updated";
+		} else if (event === "DELETE") {
+			icon = errorColor("-");
+			label = "Deleted";
+		} else if (event === "NOOP") {
+			icon = dim("·");
+			label = "No change";
+		} else {
+			icon = dim("?");
+			label = event;
+		}
+
+		const parts = [`  ${icon} ${dim(label.padEnd(10))}`];
+		if (memory) parts.push(memory);
+		if (memId) parts.push(dim(`(${memId})`));
+		console.log(parts.join("  "));
+	}
+	console.log();
+}
+
+export function formatJsonEnvelope(opts: {
+	command: string;
+	data: unknown;
+	durationMs?: number;
+	scope?: Record<string, string | undefined>;
+	count?: number;
+	status?: string;
+	error?: string;
+}): void {
+	const envelope: Record<string, unknown> = {
+		status: opts.status ?? "success",
+		command: opts.command,
+	};
+	if (opts.durationMs !== undefined) envelope.duration_ms = opts.durationMs;
+	if (opts.scope !== undefined) envelope.scope = opts.scope;
+	if (opts.count !== undefined) envelope.count = opts.count;
+	if (opts.error) envelope.error = opts.error;
+	envelope.data = opts.data;
+
+	// If the platform flagged this as an unclaimed Agent Mode account, surface
+	// the notice inside the JSON envelope so an agent consuming the output
+	// sees it without needing to inspect HTTP headers.
+	// eslint-disable-next-line @typescript-eslint/no-require-imports
+	const { takeNotice } = require("./state.js");
+	const notice = takeNotice();
+	if (notice) envelope.mem0_notice = notice;
+
+	console.log(JSON.stringify(envelope, null, 2));
+}
+
+function pick(
+	obj: Record<string, unknown>,
+	keys: string[],
+): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+	for (const key of keys) {
+		if (key in obj) result[key] = obj[key];
+	}
+	return result;
+}
+
+export function sanitizeAgentData(command: string, data: unknown): unknown {
+	if (data === null || data === undefined) return data;
+
+	switch (command) {
+		case "add": {
+			const items = Array.isArray(data) ? data : [data];
+			return items.map((item) => {
+				const r = item as Record<string, unknown>;
+				if (r.status === "PENDING") return pick(r, ["status", "event_id"]);
+				return pick(r, ["id", "memory", "event"]);
+			});
+		}
+		case "search":
+			return (data as Record<string, unknown>[]).map((r) =>
+				pick(r, ["id", "memory", "score", "created_at", "categories"]),
+			);
+		case "list":
+			return (data as Record<string, unknown>[]).map((r) =>
+				pick(r, ["id", "memory", "created_at", "categories"]),
+			);
+		case "get": {
+			const r = data as Record<string, unknown>;
+			return pick(r, [
+				"id",
+				"memory",
+				"created_at",
+				"updated_at",
+				"categories",
+				"metadata",
+			]);
+		}
+		case "update": {
+			const r = data as Record<string, unknown>;
+			return pick(r, ["id", "memory"]);
+		}
+		case "delete":
+		case "delete-all":
+		case "entity delete":
+			return data;
+		case "entity list":
+			return (data as Record<string, unknown>[]).map((r) => ({
+				name: (r.name ?? r.id) as string,
+				...pick(r, ["type", "count"]),
+			}));
+		case "event list":
+			return (data as Record<string, unknown>[]).map((r) =>
+				pick(r, ["id", "event_type", "status", "latency", "created_at"]),
+			);
+		case "event status": {
+			const ev = data as Record<string, unknown>;
+			const rawResults =
+				(ev.results as Record<string, unknown>[] | undefined) ?? [];
+			const sanitizedResults = rawResults.map((r) => {
+				const nested = r.data as Record<string, unknown> | undefined;
+				return {
+					id: r.id,
+					event: r.event,
+					user_id: r.user_id,
+					memory: nested?.memory ?? null,
+				};
+			});
+			return {
+				...pick(ev, [
+					"id",
+					"event_type",
+					"status",
+					"latency",
+					"created_at",
+					"updated_at",
+				]),
+				results: sanitizedResults,
+			};
+		}
+		default:
+			return data;
+	}
+}
+
+export function formatAgentEnvelope(opts: {
+	command: string;
+	data: unknown;
+	durationMs?: number;
+	scope?: Record<string, string | undefined>;
+	count?: number;
+}): void {
+	const envelope: Record<string, unknown> = {
+		status: "success",
+		command: opts.command,
+	};
+	if (opts.durationMs !== undefined) envelope.duration_ms = opts.durationMs;
+	if (opts.scope) {
+		const filtered = Object.fromEntries(
+			Object.entries(opts.scope).filter(([, v]) => v),
+		);
+		if (Object.keys(filtered).length > 0) envelope.scope = filtered;
+	}
+	if (opts.count !== undefined) envelope.count = opts.count;
+	envelope.data = sanitizeAgentData(opts.command, opts.data);
+
+	// Surface the unclaimed-Agent-Mode notice (if any) in the envelope so an
+	// agent reading the JSON output sees it without inspecting HTTP headers.
+	const notice = takeNotice();
+	if (notice) envelope.mem0_notice = notice;
+
+	console.log(JSON.stringify(envelope, null, 2));
+}
+
+export function printResultSummary(opts: {
+	count: number;
+	durationSecs?: number;
+	page?: number;
+	scopeIds?: Record<string, string | undefined>;
+}): void {
+	const parts = [`${opts.count} result${opts.count !== 1 ? "s" : ""}`];
+	if (opts.page !== undefined) parts.push(`page ${opts.page}`);
+	if (opts.scopeIds) {
+		const scopeParts = Object.entries(opts.scopeIds)
+			.filter(([, v]) => v)
+			.map(([k, v]) => `${k}=${v}`);
+		if (scopeParts.length > 0) parts.push(scopeParts.join(", "));
+	}
+	if (opts.durationSecs !== undefined)
+		parts.push(`${opts.durationSecs.toFixed(2)}s`);
+
+	console.log(`  ${dim(parts.join(" · "))}`);
+	console.log();
+}

cli/node/src/plugin-sync.ts

@@ -0,0 +1,120 @@
+/**
+ * Sync the active Mem0 API key into other ecosystem touchpoints.
+ *
+ * Why: the CLI canonical state is ~/.mem0/config.json. MCP servers
+ * (Claude Code plugin, Codex plugin) read MEM0_API_KEY from env or
+ * their own config files. Without a sync, agent-mode bootstrap mints a
+ * new key into config.json but the plugin's MCP keeps using the old
+ * key from env — silent surprise.
+ *
+ * Design:
+ *  - Update ONLY entries that already exist; never create new ones
+ *  - Preserve surrounding content, formatting, other keys
+ *  - Atomic writes (tmp + rename) so a crash mid-write doesn't corrupt
+ *  - Idempotent — re-running with the same key is a no-op
+ *
+ * Targets:
+ *  - ~/.claude/settings.json::env::MEM0_API_KEY (Claude Code env injection)
+ *  - ~/.zshrc / ~/.bashrc `export MEM0_API_KEY="..."` lines
+ *
+ * Out of scope: Codex / Cursor MCP configs and the plugin's own
+ * <plugin-dir>/.api_key file (plugin-managed, different schema).
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const CLAUDE_SETTINGS = path.join(os.homedir(), ".claude", "settings.json");
+const SHELL_RCS = [
+	path.join(os.homedir(), ".zshrc"),
+	path.join(os.homedir(), ".bashrc"),
+	path.join(os.homedir(), ".bash_profile"),
+];
+
+// Use [ \t]* (not \s*) so a trailing newline at end-of-file is preserved
+// when the MEM0_API_KEY export is the last line of the rc file.
+const RC_LINE_RE =
+	/^([ \t]*export[ \t]+MEM0_API_KEY[ \t]*=[ \t]*)(["']?)([^"'\n]*)(["']?)[ \t]*$/m;
+
+export function syncApiKey(apiKey: string): string[] {
+	if (!apiKey) return [];
+	const updated: string[] = [];
+	if (updateClaudeSettings(CLAUDE_SETTINGS, apiKey)) {
+		updated.push(CLAUDE_SETTINGS);
+	}
+	for (const rc of SHELL_RCS) {
+		if (updateShellRc(rc, apiKey)) updated.push(rc);
+	}
+	return updated;
+}
+
+/** @internal — exported for unit tests; consumers should use {@link syncApiKey}. */
+export function updateClaudeSettings(
+	filePath: string,
+	apiKey: string,
+): boolean {
+	if (!fs.existsSync(filePath)) return false;
+	let raw: string;
+	let data: Record<string, unknown>;
+	try {
+		raw = fs.readFileSync(filePath, "utf-8");
+		data = JSON.parse(raw);
+	} catch {
+		return false;
+	}
+	const env = data.env;
+	if (!env || typeof env !== "object" || !("MEM0_API_KEY" in env)) {
+		return false; // no existing entry — don't create one
+	}
+	const envObj = env as Record<string, string>;
+	if (envObj.MEM0_API_KEY === apiKey) return false; // already in sync
+	envObj.MEM0_API_KEY = apiKey;
+	atomicWriteText(filePath, `${JSON.stringify(data, null, 2)}\n`);
+	return true;
+}
+
+/** @internal — exported for unit tests; consumers should use {@link syncApiKey}. */
+export function updateShellRc(filePath: string, apiKey: string): boolean {
+	if (!fs.existsSync(filePath)) return false;
+	let text: string;
+	try {
+		text = fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return false;
+	}
+	const match = text.match(RC_LINE_RE);
+	if (!match) return false; // no existing line
+	if (match[3] === apiKey) return false;
+	const newText = text.replace(
+		RC_LINE_RE,
+		(_full, prefix) => `${prefix}"${apiKey}"`,
+	);
+	atomicWriteText(filePath, newText);
+	return true;
+}
+
+function atomicWriteText(filePath: string, content: string): void {
+	const dir = path.dirname(filePath);
+	const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.tmp`);
+	try {
+		fs.writeFileSync(tmp, content, "utf-8");
+		// Preserve permissions if original existed.
+		if (fs.existsSync(filePath)) {
+			try {
+				const mode = fs.statSync(filePath).mode & 0o777;
+				fs.chmodSync(tmp, mode);
+			} catch {
+				/* best-effort */
+			}
+		}
+		fs.renameSync(tmp, filePath);
+	} catch (err) {
+		try {
+			fs.unlinkSync(tmp);
+		} catch {
+			/* ignore */
+		}
+		throw err;
+	}
+}

cli/node/src/state.ts

@@ -0,0 +1,40 @@
+/**
+ * Agent mode state — set by the root program option handler,
+ * read by commands and branding functions.
+ */
+
+let _agentMode = false;
+let _currentCommand = "";
+let _pendingNotice = "";
+
+export function isAgentMode(): boolean {
+	return _agentMode;
+}
+
+export function setAgentMode(val: boolean): void {
+	_agentMode = val;
+}
+
+export function getCurrentCommand(): string {
+	return _currentCommand;
+}
+
+export function setCurrentCommand(name: string): void {
+	_currentCommand = name;
+}
+
+/**
+ * Stash a Mem0 backend notice (Agent Mode unclaimed reminder) for end-of-
+ * command surfacing. Called from the platform backend after each response so
+ * the notice prints once per command regardless of how many sub-requests
+ * fired. Last-write-wins is fine — the message text is identical.
+ */
+export function captureNotice(notice: string | null | undefined): void {
+	if (notice) _pendingNotice = notice;
+}
+
+export function takeNotice(): string {
+	const msg = _pendingNotice;
+	_pendingNotice = "";
+	return msg;
+}

cli/node/src/telemetry.ts

@@ -0,0 +1,157 @@
+/**
+ * CLI telemetry — anonymous usage tracking via PostHog.
+ *
+ * Sends fire-and-forget events by spawning a detached child process
+ * (telemetry-sender.cjs). The parent CLI process exits immediately;
+ * the child handles email resolution, caching, and the HTTP POST.
+ *
+ * Disable with: MEM0_TELEMETRY=false
+ */
+
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONFIG_FILE, loadConfig, saveConfig } from "./config.js";
+import { CLI_VERSION } from "./version.js";
+
+const POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX";
+const POSTHOG_HOST = "https://us.i.posthog.com/i/v0/e/";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SENDER_SCRIPT = path.join(__dirname, "..", "telemetry-sender.cjs");
+
+function isTelemetryEnabled(): boolean {
+	try {
+		return process.env.MEM0_TELEMETRY !== "false";
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * Return a persistent per-machine anonymous ID, generating one if needed.
+ *
+ * Stored in ~/.mem0/config.json under `telemetry.anonymous_id` so that
+ * repeat runs on the same machine share one PostHog identity instead of
+ * collapsing into a single shared fallback string.
+ */
+function getOrCreateAnonymousId(): string {
+	const config = loadConfig();
+	if (config.telemetry.anonymousId) {
+		return config.telemetry.anonymousId;
+	}
+
+	const newId = `cli-anon-${randomUUID().replace(/-/g, "")}`;
+	config.telemetry.anonymousId = newId;
+	try {
+		saveConfig(config);
+	} catch {
+		/* ignore persistence failure — still return the generated ID */
+	}
+	return newId;
+}
+
+/**
+ * Return a stable anonymous identifier for the current user.
+ *
+ * Priority: cached user_email (from /v1/ping/) > MD5(api_key) >
+ * persistent per-machine anonymous ID.
+ */
+function getDistinctId(): string {
+	try {
+		const config = loadConfig();
+		if (config.platform.userEmail) {
+			return config.platform.userEmail;
+		}
+		if (config.platform.apiKey) {
+			return createHash("md5").update(config.platform.apiKey).digest("hex");
+		}
+	} catch {
+		/* ignore */
+	}
+	try {
+		return getOrCreateAnonymousId();
+	} catch {
+		return `cli-anon-${randomUUID().replace(/-/g, "")}`;
+	}
+}
+
+/**
+ * Fire a PostHog event (non-blocking, returns void, never throws).
+ * Spawns telemetry-sender.cjs as a detached subprocess.
+ *
+ * When `preResolvedEmail` is provided (e.g. from an upfront ping
+ * validation), it is used directly as the PostHog distinct ID and the
+ * subprocess skips its own `/v1/ping/` call.
+ */
+export function captureEvent(
+	eventName: string,
+	properties: Record<string, unknown> = {},
+	preResolvedEmail?: string,
+): void {
+	if (!isTelemetryEnabled()) return;
+
+	try {
+		const config = loadConfig();
+		const distinctId = preResolvedEmail || getDistinctId();
+
+		// Detect anonymous → identified transition. If a stored anonymous_id
+		// exists and we just resolved to a real identity, fire a one-shot
+		// $identify event so PostHog stitches the pre-signup history onto
+		// the authenticated profile. Clear the stored id so we don't re-alias.
+		let anonIdToAlias: string | null = null;
+		if (
+			distinctId &&
+			!distinctId.startsWith("cli-anon-") &&
+			config.telemetry.anonymousId
+		) {
+			anonIdToAlias = config.telemetry.anonymousId;
+			config.telemetry.anonymousId = "";
+			try {
+				saveConfig(config);
+			} catch {
+				/* ignore — alias may double-fire next run, harmless */
+			}
+		}
+
+		// M4: every cli.* event carries agent_mode based on the config flag
+		// (unclaimed Agent Mode key). This is the growth-doc property used to
+		// join init → add → search funnels in PostHog.
+		const payload = {
+			api_key: POSTHOG_API_KEY,
+			distinct_id: distinctId,
+			event: eventName,
+			properties: {
+				source: "CLI",
+				language: "node",
+				cli_version: CLI_VERSION,
+				agent_mode: Boolean(config.platform.agentMode),
+				node_version: process.version,
+				os: process.platform,
+				...properties,
+				$process_person_profile: false,
+				$lib: "posthog-node",
+			},
+		};
+
+		const context = {
+			payload,
+			posthogHost: POSTHOG_HOST,
+			needsEmail: !distinctId || !distinctId.includes("@"),
+			mem0ApiKey: config.platform.apiKey || "",
+			mem0BaseUrl: config.platform.baseUrl || "https://api.mem0.ai",
+			configPath: CONFIG_FILE,
+			anonDistinctIdToAlias: anonIdToAlias,
+		};
+
+		const child = spawn(process.execPath, [SENDER_SCRIPT], {
+			detached: true,
+			stdio: ["pipe", "ignore", "ignore"],
+		});
+		child.stdin?.end(JSON.stringify(context));
+		child.unref();
+	} catch {
+		/* silently swallow */
+	}
+}

cli/node/src/version.ts

@@ -0,0 +1,10 @@
+import { createRequire } from "node:module";
+
+// __CLI_VERSION__ is replaced at build time by tsup (see tsup.config.ts).
+// When running via tsx in dev/test mode, fall back to reading package.json.
+// typeof is safe to use on undeclared identifiers — it returns 'undefined' without throwing.
+export const CLI_VERSION: string =
+	typeof __CLI_VERSION__ !== "undefined"
+		? (__CLI_VERSION__ as string)
+		: (createRequire(import.meta.url)("../package.json") as { version: string })
+				.version;