Node.js CLI Architecture

Copyprogram.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 */
	}
});

Copy * 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,
	};
}

Copyexport 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}`);
	}
}

Copylet _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;
}

Copyexport 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";
	}
}

Copythis.headers = {
	Authorization: `Token ${config.apiKey}`,
	"Content-Type": "application/json",
	"X-Mem0-Source": "CLI",
	"X-Mem0-Client": `mem0-cli-node/${CLI_VERSION}`,
	"X-Mem0-Client-Language": "node",
	"X-Mem0-Client-Version": CLI_VERSION,
};

CopysetCurrentCommand("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);
}

Copyexport 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>,
		opts?: UpdateOptions,
	): Promise<Record<string, unknown>>;
 
	delete(
		memoryId?: string,
		opts?: DeleteOptions,
	): Promise<Record<string, unknown>>;
}

Copyexport 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: [] },
	});

Copyswitch (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",
				"expiration_date",
			]),
		);
	case "list":
		return (data as Record<string, unknown>[]).map((r) =>
			pick(r, [
				"id",
				"memory",
				"created_at",
				"categories",
				"expiration_date",
			]),
		);
	case "get": {
		const r = data as Record<string, unknown>;
		return pick(r, [
			"id",
			"memory",
			"created_at",
			"updated_at",
			"categories",
			"metadata",
			"expiration_date",
		]);
	}
	case "update": {
		const r = data as Record<string, unknown>;
		return pick(r, ["id", "memory", "expiration_date"]);
	}
	case "delete":
	case "delete-all":
	case "entity delete":
		return data;