Telemetry and Metrics

Copy_LIFECYCLE_EVENTS = frozenset(
    {"mem0.init", "mem0.reset", "mem0._create_procedural_memory", "mem0.notice_displayed", "$identify"}
)

Copy// __MEM0_SDK_VERSION__ is inlined by tsup/esbuild's `define` at build time from
// package.json. In unbundled environments (ts-jest, jest globalSetup) the
// identifier is not defined, so guard with typeof to fall back safely.
let version =
  typeof __MEM0_SDK_VERSION__ !== "undefined" ? __MEM0_SDK_VERSION__ : "dev";
 
// Safely check for process.env in different environments
let MEM0_TELEMETRY = true;
try {
  MEM0_TELEMETRY =
    process?.env?.MEM0_TELEMETRY?.toLowerCase() === "false" ? false : true;
} catch (error) {}
const POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX";
const POSTHOG_HOST = "https://us.i.posthog.com/i/v0/e/";
const NOTICE_EVENT_NAME = "mem0.notice_displayed";
 

Copyasync function captureClientEvent(
  eventName: string,
  instance: TelemetryInstance,
  additionalData: Record<string, any> = {},
) {
  if (!instance.telemetryId) {
    console.warn("No telemetry ID found for instance");
    return;
  }
 
  // >= so that rate=0 drops everything and rate=1 keeps everything (Math.random() ∈ [0, 1)).
  const alwaysSend = ALWAYS_SEND_EVENTS.has(eventName);
  if (!alwaysSend && Math.random() >= MEM0_TELEMETRY_SAMPLE_RATE) {
    return;
  }
 
  const eventData: TelemetryEventData = {
    function: `${instance.constructor.name}`,
    method: eventName,
    api_host: instance.host,
    timestamp: new Date().toISOString(),
    client_version: version,
    client_source: "nodejs",
    ...additionalData,
    // sample_rate set AFTER the spread so callers can never override it
    sample_rate: alwaysSend ? 1.0 : MEM0_TELEMETRY_SAMPLE_RATE,
  };
 
  await telemetry.captureEvent(
    instance.telemetryId,
    `mem0.${eventName}`,
    eventData,
  );
}

Copyfunction 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, "")}`;
	}
}

CopyPROJECT_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX"
HOST = "https://us.i.posthog.com"
 
ENABLED = os.environ.get("MEM0_TELEMETRY", "true").lower() not in {"0", "false", "no", "off"}
STATE_PATH = Path(os.environ.get("MEM0_TELEMETRY_STATE_PATH", "/app/history/telemetry.json"))
 
_lock = Lock()
_client: Any = None
_dashboard_nudge_logged = False
 
 
def _load_state() -> dict[str, Any]:
    if not STATE_PATH.exists():
        return {}
    try:
        return json.loads(STATE_PATH.read_text())
    except (OSError, json.JSONDecodeError):
        return {}
 
 
def _save_state(state: dict[str, Any]) -> None:
    try:
        STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
        STATE_PATH.write_text(json.dumps(state))
    except OSError:
        logging.exception("telemetry: failed to persist state")
 
 
def _install_id(state: dict[str, Any]) -> str:
    install_id = state.get("install_id")
    if not install_id:
        install_id = str(uuid.uuid4())
        state["install_id"] = install_id
        _save_state(state)
    return install_id
 
 
def _get_client():
    global _client
    if _client is not None:
        return _client
    try:
        from posthog import Posthog
    except ImportError:
        logging.warning("telemetry: posthog package not installed; disabling")
        return None
    _client = Posthog(project_api_key=PROJECT_API_KEY, host=HOST, disable_geoip=True)
    return _client

Copydef _capture_once(email: str, event: str, state_key: str, extra: dict[str, Any] | None = None) -> None:
    if not ENABLED:
        return
 
    with _lock:
        state = _load_state()
        if state.get(state_key):
            return
 
        client = _get_client()
        if client is None:
            return
 
        try:
            client.capture(
                distinct_id=_install_id(state),
                event=event,
                properties={
                    "email_domain": email.rsplit("@", 1)[-1].lower() if "@" in email else "unknown",
                    "server_version": mem0.__version__,
                    **(extra or {}),
                },
            )
            state[state_key] = datetime.now(timezone.utc).isoformat()
            _save_state(state)
        except Exception:
            logging.exception("telemetry: failed to send %s event", event)
 
 
def capture_admin_registered(email: str) -> None:
    _capture_once(email, "admin_registered", "admin_registered_sent_at")
 
 
def capture_onboarding_completed(email: str, use_case: str) -> None:
    _capture_once(email, "onboarding_completed", "onboarding_sent_at", {"use_case": use_case})
 

Copydef log_dashboard_nudge_once(dashboard_url: str) -> None:
    """Log a hint pointing the operator to the web dashboard the first time a memory
    is stored. Fires at most once per process (so a restart may re-log it on the next
    add — harmless for a discovery nudge). LOCAL console log only — sends nothing
    off-box, so it is intentionally NOT gated by MEM0_TELEMETRY.
    """
    global _dashboard_nudge_logged
    if _dashboard_nudge_logged:
        return
    _dashboard_nudge_logged = True
    logging.info(
        "First memory stored. Open the dashboard at %s to view and manage your memories.",
        dashboard_url,
    )

CopyPOSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX"
POSTHOG_CAPTURE_URL = "https://us.i.posthog.com/i/v0/e/"
POSTHOG_BATCH_URL = "https://us.i.posthog.com/batch/"
EVENT_PREFIX = "code"
SPOOL_LIMIT_BYTES = 256 * 1024
BATCH_SIZE = 100
SEND_TIMEOUT = 5
CLAIM_STALE_SECONDS = 120
CLAIM_EXPIRY_SECONDS = 7 * 24 * 60 * 60
# A batch is only discarded once it has genuinely been retried this many times.
MAX_CLAIM_ATTEMPTS = 3
# Parked claims drained per run, after the live spool. Bounded so a long backlog
# cannot turn one flush into an unbounded send loop.
MAX_PARKED_PER_RUN = 3
# Added to the wait before a released claim becomes reclaimable, per attempt
# already spent. Releasing straight to "reclaimable now" let two senders burn the
# whole budget within seconds of one another on a single momentary failure, and
# discard a batch a retry a minute later would have delivered.
RETRY_COOLDOWN_SECONDS = 60
 

CopySPOOL_LIMIT_BYTES = 256 * 1024
BATCH_SIZE = 100
SEND_TIMEOUT = 5
CLAIM_STALE_SECONDS = 120
CLAIM_EXPIRY_SECONDS = 7 * 24 * 60 * 60
# A batch is only discarded once it has genuinely been retried this many times.
MAX_CLAIM_ATTEMPTS = 3
# Parked claims drained per run, after the live spool. Bounded so a long backlog
# cannot turn one flush into an unbounded send loop.
MAX_PARKED_PER_RUN = 3
# Added to the wait before a released claim becomes reclaimable, per attempt
# already spent. Releasing straight to "reclaimable now" let two senders burn the
# whole budget within seconds of one another on a single momentary failure, and
# discard a batch a retry a minute later would have delivered.
RETRY_COOLDOWN_SECONDS = 60

Copydef _install_salt() -> str:
    """Random per-install salt, created once and memoized for the process.
 
    Deliberately its own file, claimed with O_CREAT|O_EXCL, rather than a key in
    the identity file. Three reasons, all of which produced wrong data when this
    lived in the identity dict:
 
    - Hooks are short-lived separate processes firing on every tool call, and
      people run more than one agent window. A read-modify-write would let each
      process mint its own salt, so one repository would hash several ways in the
      window before a writer won.
    - resolve_distinct_id holds a copy of the identity dict across a network call
      to /v1/ping/, so whichever write landed second erased the other's key —
      losing either the salt (repo_hash changes mid-stream) or the email (a
      second $identify, splitting the person).
    - Touching the identity file from record() would create it, and is_first_run
      keys off that file, so recording an event would silently suppress the
      install event.
 
    Published atomically, and there is deliberately no derived fallback. Creating
    the file with O_CREAT|O_EXCL and then writing into it leaves a window where
    the file exists and is empty, and a concurrent hook that reads it in that
    window gets nothing. Falling back to a digest of the path would hand that
    process a salt an attacker can compute, memoized for its whole run, which is
    the privacy control this function exists to provide silently turning itself
    off under load. The salt is written to a private temp file first and linked
    into place, so the name either does not exist or already has the full value.
 
    Returns "" when it genuinely cannot persist. Callers omit the hash entirely
    rather than emit an unsalted one.
    """

Copydef init(harness: str = "", source_tag: str = "") -> None:
    """Override the generated identity. Optional — core/_harness_id.py is the default.
 
    The fallback shape matches memory_core.configure_harness's (``<HOST>_PLUGIN``).
    It used to be ``MEM0_<HOST>_PLUGIN`` here and ``<host>_plugin`` there, which
    meant one plugin could emit three different source values depending on which
    process happened to send the batch.
    """
    global _harness, _source_tag
    _harness = harness or _DEFAULT_HARNESS
    _source_tag = source_tag or (
        f"{_harness.upper().replace('-', '_')}_PLUGIN" if harness else _DEFAULT_SOURCE_TAG
    )

Copyexport interface TelemetryConfig {
  host: string;
  source: string;
  version: string;
  distinctId: string | (() => string | undefined);
  delivery?: (batch: Record<string, unknown>[]) => void | Promise<void>;
  flushThreshold?: number;
  flushIntervalMs?: number;
  maxQueueSize?: number;
  commonProperties?: Record<string, unknown>;
  eventName?: (event: string) => string;
  enabled?: () => boolean;
}

Copyexport function createTelemetry(config: TelemetryConfig) {
  let queue: Record<string, unknown>[] = [];
  let timer: ReturnType<typeof setInterval> | undefined;
  let consecutiveFailures = 0;
  let retryNotBefore = 0;
  let exitFlushAttempted = false;
  let flushing = false;
  const flushThreshold = config.flushThreshold ?? 10;
  const maxQueueSize = config.maxQueueSize ?? 100;
 

Copyconst POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX";
const POSTHOG_BATCH_URL = "https://us.i.posthog.com/batch/";

Copyfunction safeValue(value: unknown): unknown {
  if (typeof value === "string") return redactSecrets(value);
  if (Array.isArray(value)) return value.map(safeValue);
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.entries(value)
        .filter(([key]) => !PRIVATE_KEYS.has(key.toLowerCase().replace(/[^a-z]/g, "")))
        .map(([key, nested]) => [key, safeValue(nested)]),
    );
  }
  return value;
}

Copyconst PRIVATE_KEYS = new Set([
  "apikey",
  "authorization",
  "password",
  "query",
  "secret",
  "prompt",
  "token",
  "text",
  "memory",
  "message",
  "error",
  "path",
  "cwd",
  "userid",
  "agentid",
  "runid",
  "repoid",
  "repositoryid",
  "projectid",
  "appid",
  "filters",
]);

Copyfunction keyFingerprint(apiKey?: string): string {
  return apiKey ? createHash("sha256").update(apiKey).digest("hex").slice(0, 16) : "";
}
 
function distinctId(apiKey?: string): string {
  try {
    const auth = readPluginAuth();
    if (auth.userEmail) {
      // Only when it belongs to the key in hand. Without this check a cached
      // email was used forever: switch to a different account and every event
      // kept reporting under the previous one, with nothing to notice it by.
      if (auth.keyFingerprint === keyFingerprint(apiKey)) {
        return createHash("sha256").update(auth.userEmail).digest("hex");
      }
      // Only a REAL key that disagrees means the account changed. Without the
      // apiKey guard the comparison is `undefined === ""` for any call that
      // simply omits the key, so a capture with no context wiped a perfectly
      // good account out of openclaw.json.
      //
      // A row with an email and NO fingerprint is the legacy shape, from an
      // install predating this field. Clearing it here deleted a real account
      // before anything had replaced it, and if the re-resolve then failed
      // because the user was offline the email was gone from disk for good. The
      // Python core refuses the same trade: verify, and keep what you have until
      // the verification succeeds. resolveEmail below overwrites both fields
      // when it does, so there is nothing to clear first.
      if (apiKey && auth.keyFingerprint) clearResolvedAccount();
    }
  } catch {
    // Fall through to the API key or anonymous identity.
  }
  return apiKey ? createHash("sha256").update(apiKey).digest("hex") : anonymousId();
}

Copyfunction distinctId(apiKey: string): string {
  return createHash("sha256").update(apiKey).digest("hex").slice(0, 32);
}
 
/**
 * Salted so the hash is not enumerable.
 *
 * An unsalted SHA-256 of a project id is reversible by anyone who can guess the
 * id, which for a project identifier is a small space. The API key is the salt:
 * it is already in play here (distinctId is a digest of it), it is high entropy,
 * and using it needs no per-install file and so no write race to get wrong. The
 * hash is therefore per account rather than per machine, which also keeps joins
 * working for one user across machines. It resets when the key rotates, which is
 * consistent, because distinctId resets with it.
 *
 * Both are omitted without a key. An event cannot be built without a distinctId
 * anyway, so this costs nothing.
 */
function projectHash(projectId?: string, apiKey?: string): Record<string, string> {
  if (!projectId || !apiKey) return {};
  return { project_hash: createHash("sha256").update(`${apiKey}:${projectId}`).digest("hex") };
}

Copyfunction anonymousId(): string {
  if (cachedAnonymousId) return cachedAnonymousId;
  try {
    const stored = JSON.parse(fs.readFileSync(TELEMETRY_ID_PATH, "utf-8")).anonymousId;
    if (typeof stored === "string" && stored) return (cachedAnonymousId = stored);
  } catch {
    // First run or unreadable identity file.
  }
  const created = `pi-mem0-anon-${randomUUID().replace(/-/g, "")}`;
  try {
    fs.mkdirSync(CONFIG_DIR, { recursive: true });
    fs.writeFileSync(TELEMETRY_ID_PATH, JSON.stringify({ anonymousId: created }), "utf-8");
  } catch {
    // An unwritable config directory must not break the plugin.
  }
  return (cachedAnonymousId = created);
}
 
function distinctId(apiKey?: string): string {
  return apiKey ? createHash("sha256").update(apiKey).digest("hex") : anonymousId();
}
 
function previousAnonymousId(id: string): string | undefined {
  if (identified || id.startsWith("pi-mem0-anon-")) return undefined;
  identified = true;
  try {
    const stored = JSON.parse(fs.readFileSync(TELEMETRY_ID_PATH, "utf-8")).anonymousId;
    fs.unlinkSync(TELEMETRY_ID_PATH);
    cachedAnonymousId = undefined;
    return typeof stored === "string" && stored ? stored : undefined;
  } catch {
    return undefined;
  }
}