Agent Account Provisioning

Overview

Agent account provisioning provides a zero-friction mechanism for autonomous AI agents to bootstrap platform credentials, establish ownership identities, and interact with remote memory services without manual browser-based authentication. By evaluating environment heuristics and state flags, the command-line interface automatically detects autonomous execution contexts and initiates backend provisioning to mint shadow API keys and slug-derived user identifiers. This workflow addresses the friction of programmatic onboarding, enabling unattended initialization while maintaining secure pathways for human operators to claim and upgrade provisioned accounts to permanent email-bound identities via one-time passwords. Once configured, agents can self-identify, manage metadata schemas, and execute specialized remote workloads such as [[AGENTRUSH]] operations under fully provisioned credentials.

Sources: cli/python/src/mem0_cli/commands/init_cmd.py:214-239, cli/node/src/commands/agent-mode.ts:38-55, cli/python/src/mem0_cli/commands/agent_mode_cmd.py:52-70, cli/python/src/mem0_cli/agent_detect.py:1-13

Agent Context Detection

Environment Heuristics and Curated Runtimes

The command-line interface determines whether it is running within an autonomous agent context by inspecting environment heuristics, state flags, and specific runtime indicators. During initialization via mem0 init, the detection logic checks if an explicit agent flag is active, evaluates global agent mode state flags, or queries runtime environment variables for recognized AI agent frameworks.

The detection module scans the environment for curated environment variables mapped to known agent runtimes. This check serves as a context trigger only; it enables zero-friction auto-bootstrap UX but does not automatically populate canonical agent identity fields on platform records.

Sources: cli/node/src/agent-detect.ts:14-31, cli/python/src/mem0_cli/agent_detect.py:19-36

Sources: cli/python/src/mem0_cli/agent_detect.py:9-12

State Flags and Resolution Rules

The composite agent context check (_agent_ctx) combines three distinct Boolean conditions evaluated sequentially during initialization:

Copy_agent_ctx = agent or _global_agent_mode() or (detect_agent_caller() is not None)

Sources: cli/python/src/mem0_cli/commands/init_cmd.py:266-266

State management utilities track whether the root option handler has enabled agent mode globally, while individual commands access or mutate this state.

Sources: cli/node/src/state.ts:44-46

Autonomous Backend Bootstrapping

Request Dispatch and Platform Envelopes

When autonomous agent context detection is triggered during initialization, the command-line interface executes a unattended HTTP POST request to the remote platform endpoint /api/v1/auth/agent_mode/. Both the Python and Node.js client implementations transmit custom client language and source headers alongside optional payload fields such as the analytics source tag and the self-declared agent_caller identity.

Copyconst 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;
}

Sources: cli/node/src/commands/agent-mode.ts:11-25, cli/python/src/mem0_cli/commands/agent_mode_cmd.py:26-29

The backend responds with a JSON bootstrap envelope containing the provisioned API credentials, organizational scopes, and default user identifiers. The client validation logic enforces strict type checks to ensure that required fields such as api_key and default_user_id are populated strings before persisting the configuration locally.

Sources: cli/node/src/commands/agent-mode.ts:16-25, cli/python/src/mem0_cli/commands/agent_mode_cmd.py:32-50

Sources: cli/node/src/commands/agent-mode.ts:116-124, cli/python/src/mem0_cli/commands/agent_mode_cmd.py:32-50

Error Handling and Rate Limiting

The bootstrap workflow intercepts specific HTTP status codes to handle network interruptions, service availability, and rate-limiting constraints without leaking raw backend tracebacks.

Sources: cli/node/src/commands/agent-mode.ts:82-113, cli/python/src/mem0_cli/commands/agent_mode_cmd.py:89-112

Sources: cli/node/src/commands/agent-mode.ts:101-110, cli/python/src/mem0_cli/commands/agent_mode_cmd.py:102-110

Interactive Claim and Upgrade Flow

OTP Verification and Upgrade Sequence

The claim workflow allows human operators to bind an agent-provisioned shadow account to a permanent email identity without requiring a browser session or polling loops. When an existing configuration contains an active agent mode API key and a user passes the --email flag to the initialization command, the CLI dispatches a device claim flow using a one-time passcode.

Copyif email and CONFIG_FILE.exists():
    existing = load_config()
    if existing.platform.agent_mode and existing.platform.api_key:
        email = email.strip().lower()
        _validate_email(email)
        print_info(console, f"Claiming Agent Mode account to {email}...")
        claim_via_otp(existing, email=email, code=code)
        _fire_init("email", claimed=True)
        return

Sources: cli/python/src/mem0_cli/commands/init_cmd.py:252-260

The upgrade process executes in two explicit phases across both the Python and Node.js implementations:

1. Passcode Generation Request: Unless a verification code is provided directly via the --code flag, the CLI transmits a POST request to /api/v1/auth/email_code/ containing the target email address. If the terminal is running in an interactive TTY session, it prompts the operator for the received code; non-interactive environments without a supplied code terminate immediately with a usage hint.
2. Atomic Verification and Claim: The client sends a POST request to /api/v1/auth/email_code/verify/ carrying the email, the trimmed verification code, and the raw agent mode API key under the parameter agent_mode_api_key. The backend processes this inline to execute an upgrade-in-place transaction.

Copy// 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,
	}),

Sources: cli/node/src/commands/agent-mode.ts:180-230, cli/python/src/mem0_cli/commands/agent_mode_cmd.py:165-208

Sources: cli/python/src/mem0_cli/commands/agent_mode_cmd.py:143-153

State Mutations and Error Handling

Upon receiving a successful verification response confirming claimed: true, the local configuration file is mutated to reflect the permanent identity state. The platform.agent_mode flag is disabled, platform.claimed_at is stamped with the verification timestamp (or current UTC time), platform.user_email is populated with the verified address, and platform.created_via switches from agent_mode to email.

Copyclaim_body = verify.json()
if not claim_body.get("claimed"):
    print_error(err_console, f"Unexpected verify response: {claim_body}")
    raise typer.Exit(1)
 
config.platform.agent_mode = False
config.platform.claimed_at = claim_body.get("claimed_at") or _utcnow_iso()
config.platform.user_email = email
config.platform.created_via = "email"
save_config(config)
print_success(console, f"Agent claimed to {email}. Your API key is unchanged.")

Sources: cli/python/src/mem0_cli/commands/agent_mode_cmd.py:225-235

Sources: cli/node/src/commands/agent-mode.ts:234-260, cli/python/src/mem0_cli/commands/agent_mode_cmd.py:210-224

Sources: cli/node/src/commands/agent-mode.ts:250-265, cli/python/src/mem0_cli/commands/agent_mode_cmd.py:219-223

Agent Ownership Identification

Identification Commands and Schema Mutations

When an agent-mode initialization occurs without supplying an explicit --agent-caller argument, the platform backend initializes the row with agent_caller=NULL. To resolve this, active agents execute mem0 identify <name> (run_identify in Python and TypeScript implementations) to issue a schema mutation against the platform backend.

CopyUsed 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 — running it again just
overwrites.
"""

Sources: cli/python/src/mem0_cli/commands/identify_cmd.py:3-7

The CLI validates that an active API key exists and that agent_mode is enabled in the local configuration before transmitting payloads. Requests target the endpoint /api/v1/auth/agent_mode/caller/ via HTTP PATCH with headers specifying X-Mem0-Source: cli, X-Mem0-Client-Language (python or node), and a bearer token authentication header.

Copy_SOURCE_HEADERS = {
    "X-Mem0-Source": "cli",
    "X-Mem0-Client-Language": "python",
}
 
 
def run_identify(name: str) -> None:
    """PATCH the active agent-mode key's agent_caller field."""
    config = load_config()
    if not config.platform.api_key:
        print_error(
            err_console,
            "No API key configured. Run `mem0 init --agent` first.",
        )
        raise typer.Exit(1)
    if not config.platform.agent_mode:
        print_error(
            err_console,
            "This command only works on unclaimed agent-mode keys.",
        )
        raise typer.Exit(1)
 
    name = (name or "").strip()
    if not name:
        print_error(err_console, "Agent name is required.")
        raise typer.Exit(1)
 
    base_url = (config.platform.base_url or "https://api.mem0.ai").rstrip("/")
    try:
        with httpx.Client(timeout=30.0) as client:
            resp = client.patch(
                f"{base_url}/api/v1/auth/agent_mode/caller/",
                headers={
                    **_SOURCE_HEADERS,
                    "Authorization": f"Token {config.platform.api_key}",
                    "Content-Type": "application/json",
                },
                json={"agent_caller": name},
            )

Sources: cli/python/src/mem0_cli/commands/identify_cmd.py:21-59, cli/node/src/commands/identify.ts:12-50

Sources: cli/python/src/mem0_cli/commands/identify_cmd.py:5-6, cli/python/src/mem0_cli/commands/identify_cmd.py:72-74

AGENTRUSH Identifier Resolution

To inspect the provisioned agent's default_user_id without network traversal, agents execute mem0 whoami (run_whoami / cmdWhoami). This command reads directly from local configuration storage to output the assigned AGENTRUSH session identifier and directs operators to view their row at https://mem0.ai/agentrush.

Copy"""mem0 whoami — print the active agent's default_user_id (AGENTRUSH identifier)."""
 
from __future__ import annotations
 
import typer
from rich.console import Console
 
from mem0_cli.branding import BRAND_COLOR, print_error, print_info
from mem0_cli.config import load_config
 
console = Console()
err_console = Console(stderr=True)
 
 
def run_whoami() -> None:
    config = load_config()
    session_id = config.platform.default_user_id if config.platform else None
    if not session_id:
        print_error(
            err_console,
            "No default_user_id found. Run `mem0 init --agent` first.",
        )
        raise typer.Exit(1)
    console.print(f"Your AGENTRUSH identifier:  [{BRAND_COLOR}]{session_id}[/{BRAND_COLOR}]")
    print_info(console, "Find your row at https://mem0.ai/agentrush")

Sources: cli/python/src/mem0_cli/commands/whoami_cmd.py:1-25, cli/node/src/commands/whoami.ts:1-18

Sources: cli/python/src/mem0_cli/commands/whoami_cmd.py:18-23, cli/node/src/commands/whoami.ts:11-15

Provisioned Agent Runtime Capabilities

AGENTRUSH Execution and API Routing

Provisioned agents interact with the platform using dedicated game commands wrapped by mem0 agent-rush add and mem0 agent-rush search. These commands issue POST requests to hardcoded endpoints /v1/agent-rush/memories/ and /v1/agent-rush/memories/search/ using base URLs resolved from local configuration files.

Copy"""mem0 agent-rush — AGENTRUSH game commands.
 
Wraps the platform's /v1/agent-rush/{memories/, memories/search/} endpoints.
Hardcoded routing; no flags needed.
"""

Sources: cli/python/src/mem0_cli/commands/agent_rush_cmd.py:1-5, cli/node/src/commands/agent-rush.ts:1-4

All runtime requests carry specialized source headers including X-Mem0-Source: cli, X-Mem0-Client-Language (python or node), X-Mem0-Mode: agent-rush, and an authorization header containing the agent's API token.

Copy_SOURCE_HEADERS = {
    "X-Mem0-Source": "cli",
    "X-Mem0-Client-Language": "python",
    "X-Mem0-Mode": "agent-rush",
}

Sources: cli/python/src/mem0_cli/commands/agent_rush_cmd.py:29-33, cli/node/src/commands/agent-rush.ts:50-57

Verification and Error Handling

When errors occur during runtime execution, the CLI parses response codes from platform payloads and maps them to descriptive user hints.

Copy_ERROR_HINTS = {
    "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.",
}

Sources: cli/python/src/mem0_cli/commands/agent_rush_cmd.py:35-45, cli/node/src/commands/agent-rush.ts:18-31

Sources: cli/python/src/mem0_cli/commands/agent_rush_cmd.py:86-115, cli/node/src/commands/agent-rush.ts:100-119

Related

• Python CLI Architecture
• Node.js CLI Architecture