@mem0/cli 0.1.0

package/src/backend/base.ts

@@ -0,0 +1,115 @@
+/**
+ * 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[];
+  enableGraph?: boolean;
+}
+
+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[];
+  enableGraph?: boolean;
+}
+
+export interface ListOptions {
+  userId?: string;
+  agentId?: string;
+  appId?: string;
+  runId?: string;
+  page?: number;
+  pageSize?: number;
+  category?: string;
+  after?: string;
+  before?: string;
+  enableGraph?: boolean;
+}
+
+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>>;
+
+  status(opts?: { userId?: string; agentId?: string }): Promise<Record<string, unknown>>;
+
+  entities(entityType: 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);
+}
+

package/src/backend/index.ts

@@ -0,0 +1,7 @@
+/**
+ * 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";

package/src/backend/platform.ts

@@ -0,0 +1,303 @@
+/**
+ * Platform (SaaS) backend — communicates with api.mem0.ai.
+ */
+
+import type { PlatformConfig } from "../config.js";
+import {
+  type AddOptions,
+  APIError,
+  AuthError,
+  type Backend,
+  type DeleteOptions,
+  type EntityIds,
+  type ListOptions,
+  NotFoundError,
+  type SearchOptions,
+} from "./base.js";
+
+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",
+    };
+  }
+
+  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 fetchOpts: RequestInit = {
+      method,
+      headers: this.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();
+        detail = (body as Record<string, string>).detail ?? resp.statusText;
+      } catch {
+        detail = resp.statusText;
+      }
+      throw new APIError(path, detail);
+    }
+    if (!resp.ok) {
+      throw new Error(`HTTP ${resp.status}: ${resp.statusText}`);
+    }
+    if (resp.status === 204) {
+      return {};
+    }
+    return resp.json();
+  }
+
+  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;
+    if (opts.enableGraph) payload.enable_graph = true;
+
+    return (await this._request("POST", "/v1/memories/", { 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;
+    if (opts.enableGraph) payload.enable_graph = true;
+
+    const result = (await this._request("POST", "/v2/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/${memoryId}/`)) 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;
+    if (opts.enableGraph) payload.enable_graph = true;
+
+    const result = (await this._request("POST", "/v2/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;
+    return (await this._request("PUT", `/v1/memories/${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> = {};
+      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/${memoryId}/`)) as Record<
+        string,
+        unknown
+      >;
+    }
+    throw new Error("Either memoryId or --all is required");
+  }
+
+  async deleteEntities(opts: EntityIds): Promise<Record<string, unknown>> {
+    const params: Record<string, string> = {};
+    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;
+    if (Object.keys(params).length === 0) {
+      throw new Error("At least one entity ID is required for deleteEntities.");
+    }
+    return (await this._request("DELETE", "/v1/entities/", { params })) as Record<
+      string,
+      unknown
+    >;
+  }
+
+  async status(
+    opts: { userId?: string; agentId?: string } = {},
+  ): Promise<Record<string, unknown>> {
+    try {
+      if (opts.userId || opts.agentId) {
+        const payload: Record<string, unknown> = {};
+        const statusParams: Record<string, string> = { page: "1", page_size: "1" };
+        const apiFilters = this._buildFilters({
+          userId: opts.userId,
+          agentId: opts.agentId,
+        });
+        if (apiFilters) payload.filters = apiFilters;
+        await this._request("POST", "/v2/memories/", { json: payload, params: statusParams });
+      } else {
+        await this._request("GET", "/v1/entities/");
+      }
+      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;
+  }
+}

package/src/branding.ts

@@ -0,0 +1,145 @@
+/**
+ * Branding and ASCII art for mem0 CLI.
+ */
+
+import chalk from "chalk";
+import ora, { type Ora } from "ora";
+import { createRequire } from "node:module";
+
+const _require = createRequire(import.meta.url);
+const PKG_VERSION: string = _require("../package.json").version;
+
+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 {
+  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${PKG_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 {
+  console.log(`${success(sym("✓", "[ok]"))} ${message}`);
+}
+
+export function printError(message: string, hint?: string): void {
+  console.error(`${error(sym("✗", "[error]") + " Error:")} ${message}`);
+  if (hint) {
+    console.error(`  ${dim(hint)}`);
+  }
+}
+
+export function printWarning(message: string): void {
+  console.error(`${warning(sym("⚠", "[warn]"))} ${message}`);
+}
+
+export function printInfo(message: string): void {
+  console.log(`${brand(sym("◆", "*"))} ${message}`);
+}
+
+export function printScope(ids: Record<string, string | undefined>): void {
+  const parts: string[] = [];
+  for (const [key, val] of Object.entries(ids)) {
+    if (val) {
+      const label = key.replace(/_/g, " ").replace("id", "ID").trim();
+      parts.push(`${label}=${val}`);
+    }
+  }
+  if (parts.length > 0) {
+    console.log(`  ${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> {
+  const ctx: TimedStatusContext = { successMsg: "", errorMsg: "" };
+  const spinner = ora({ text: dim(message), color: "magenta", 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) {
+      console.error(`${error("✗ Error:")} ${ctx.errorMsg} (${elapsed}s)`);
+    }
+    throw err;
+  }
+}
+
+/** Format helpers using brand colors for external use. */
+export const colors = { brand, accent, success, error, warning, dim };

package/src/commands/config.ts

@@ -0,0 +1,90 @@
+/**
+ * Config management commands: show, set, get.
+ */
+
+import Table from "cli-table3";
+import { printError, printSuccess, colors } from "../branding.js";
+import {
+  getNestedValue,
+  loadConfig,
+  redactKey,
+  saveConfig,
+  setNestedValue,
+} from "../config.js";
+import { formatJsonEnvelope } from "../output.js";
+
+const { brand, accent, dim } = colors;
+
+export function cmdConfigShow(opts: { output?: string } = {}): void {
+  const config = loadConfig();
+
+  if (opts.output === "json") {
+    formatJsonEnvelope({
+      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,
+          enable_graph: config.defaults.enableGraph,
+        },
+        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(["defaults.enable_graph", String(config.defaults.enableGraph)]);
+  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 {
+  const config = loadConfig();
+  const value = getNestedValue(config, key);
+
+  if (value === undefined) {
+    printError(`Unknown config key: ${key}`);
+  } else {
+    // Redact secrets
+    if (key.includes("api_key") || key.split(".").pop() === "key") {
+      console.log(redactKey(String(value)));
+    } else {
+      console.log(String(value));
+    }
+  }
+}
+
+export function cmdConfigSet(key: string, value: string): void {
+  const config = loadConfig();
+  if (setNestedValue(config, key, value)) {
+    saveConfig(config);
+    const display = key.includes("key") ? redactKey(value) : value;
+    printSuccess(`${key} = ${display}`);
+  } else {
+    printError(`Unknown config key: ${key}`);
+  }
+}