Mem0 CLI 配置完全指南：config.json 文件格式、环境变量、`mem0 init` 向导与配置优先级规则

Mem0 CLI 是 mem0「AI Agent 记忆层」平台的官方命令行工具（Python 版 mem0-cli 与 Node 版 @mem0/cli 行为完全一致）。要让所有记忆读写命令（mem0 add、mem0 search、mem0 list 等）在终端、CI/CD 流水线以及 AI Agent 中稳定运行，前提是把 API Key、默认作用域和平台地址配置正确。本文以仓库内技能文档 skills/mem0-cli/references/configuration.md 为主线，逐层拆解配置文件 ~/.mem0/config.json 的格式与权限、mem0 init 的三种认证流程、mem0 config 子命令、环境变量以及四级优先级规则，并结合 CLI 源码给出实现级佐证。读完你即可独立完成 Mem0 CLI 的初始化、迁移、排障与安全加固。

---

一、配置体系总览：三层来源，四个层级

Mem0 CLI 的配置最终只服务于一件事：在执行命令时确定「用哪个 Key 调用哪个平台地址、默认作用在哪个实体上」。全部配置可以归为三组：

配置来源	载体	写入/设置方式
配置文件	~/.mem0/config.json	mem0 init 向导 或 mem0 config set
环境变量	MEM0_API_KEY、MEM0_USER_ID 等	shell 导出 / CI 变量注入
CLI 标志	--api-key、--base-url、--user-id 等	每条命令的参数

这三组来源不是并列的，而是严格按「CLI 标志 > 环境变量 > 配置文件 > 内置默认值」的顺序解析。理解这套优先级（见后文第五节）是排查「为什么我改了配置不生效」这类问题的基础。

从实现上看，Python 侧的全部逻辑集中在 cli/python/src/mem0_cli/config.py，Node 侧对应 cli/node/src/config.ts。两份实现的数据结构、解析顺序与脱敏规则保持一致（具体差异在文末第六节说明）。

---

二、配置文件位置与安全权限

路径	权限	说明
~/.mem0/	0700（仅属主可读写执行）	配置目录，由 mem0 init 自动创建
~/.mem0/config.json	0600（仅属主可读写）	配置文件，存放 API Key、默认实体与平台设置

收紧权限是刻意的安全设计：0600/0700 保证同一台机器上的其他系统用户无法读取你的 API Key。源码中这份逻辑在 config.py 中体现为：

• ensure_config_dir() 创建目录后用 os.chmod(CONFIG_DIR, stat.S_IRWXU) 强制 0700（cli/python/src/mem0_cli/config.py#L81-L85）；
• save_config() 写入文件后用 os.chmod(CONFIG_FILE, stat.S_IRUSR | stat.S_IWUSR) 强制 0600（cli/python/src/mem0_cli/config.py#L147-L180）。

Node 版在 cli/node/src/config.ts 中使用 fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 }) 与 fs.chmodSync(CONFIG_FILE, 0o600) 完成同样的加固。

⚠️ 安全红线：永远不要把 ~/.mem0/config.json、.env 或 API Key 提交进版本库（skills/mem0-cli/SKILL.md 中有同样强调）。若需在 CI 中使用，请优先走环境变量注入而非复制文件。

一个容易被忽略的联动：save_config() 在保存成功后，会把当前 API Key 同步到生态触点（如 Claude Code 插件的环境变量注入、shell rc 导出），该同步是幂等且 best-effort 的——只更新既有条目、绝不新建条目、失败也不阻塞配置文件本身的写入（cli/python/src/mem0_cli/config.py#L182-L193）。所以配置文件始终是权威数据源。

---

三、配置文件 Schema 与字段参考

3.1 基础 Schema（参考文档定义的最小形态）

~/.mem0/config.json 的标准形态如下：

{
  "version": 1,
  "defaults": {
    "user_id": "",
    "agent_id": "",
    "app_id": "",
    "run_id": ""
  },
  "platform": {
    "api_key": "",
    "base_url": "https://api.mem0.ai"
  }
}

3.2 字段参考表

字段	类型	默认值	说明
version	integer	1	配置 schema 版本
defaults.user_id	string	""	默认用户 ID，用于给命令划定作用域
defaults.agent_id	string	""	默认 Agent ID，用于给命令划定作用域
defaults.app_id	string	""	默认应用 ID，用于给命令划定作用域
defaults.run_id	string	""	默认运行 ID，用于给命令划定作用域
platform.api_key	string	""	Mem0 Platform 的 API Key（m0- 开头）
platform.base_url	string	"https://api.mem0.ai"	所有 API 请求的基地址

3.3 源码级扩充：当前实现里 Schema 不止这些字段

参考文档描述的是「核心字段」；对照当前仓库中 Python 的 dataclass 定义（cli/python/src/mem0_cli/config.py#L26-L67）与 Node 的 interface 定义（cli/node/src/config.ts#L20-L55），两者完全对等，且实际落地到磁盘时还包含以下扩展字段，其中大部分服务于 Agent Mode 的生命周期管理：

{
  "version": 1,
  "defaults": { "user_id": "", "agent_id": "", "app_id": "", "run_id": "" },
  "platform": {
    "api_key": "",
    "base_url": "https://api.mem0.ai",
    "user_email": "",
    "agent_mode": false,
    "created_via": "",
    "agent_caller": "",
    "claimed_at": "",
    "default_user_id": ""
  },
  "telemetry": { "anonymous_id": "" },
  "agent_rush": { "acknowledged_at": "" }
}

这些扩展字段的语义如下：

• platform.user_email：登录邮箱，由 email 登录流写入，之后会被 ping 响应里的真实邮箱刷新（用于遥测 distinct_id）；
• platform.agent_mode：布尔值，为 true 表示当前 Key 还是未认领的 Agent Mode 影子 Key；
• platform.created_via：Key 的创建途径，取值集合为 "agent_mode" | "email" | "api_key" | "existing_key"；
• platform.agent_caller：Agent 的自报身份，例如 claude-code、cursor，仅当 created_via == "agent_mode" 时有意义；
• platform.claimed_at：Agent Key 被人类通过邮箱认领的 ISO 时间戳；
• platform.default_user_id：Agent bootstrap 返回的 user_<slug> 形式的自动默认作用域；
• telemetry.anonymous_id：匿名遥测 ID；
• agent_rush.acknowledged_at：用户首次交互式执行 mem0 agent-rush add 时确认「记忆公开」警告的时间戳，为空表示尚未确认。

写入磁盘时 save_config() 会将上述对象完整序列化（cli/python/src/mem0_cli/config.py#L151-L175）。换句话说：即使某次 mem0 init 只写了几个核心字段，配置文件也会以整棵 schema 落盘，后续命令读取时缺省字段自动回退默认值。

---

四、mem0 init：三种认证流程与两种运行模式

init 命令是整个配置体系的入口，提供两类认证流程（API Key 与邮箱验证码），同时兼容完全交互与完全非交互两种终端场景。

4.1 API Key 流程（默认）

# 完全交互式：
mem0 init

# 完全非交互式（同时给出两个标志即跳过所有提问）：
mem0 init --api-key m0-xxx --user-id alice

交互式模式的执行步骤（与 cli/python/src/mem0_cli/commands/init_cmd.py 中 run_init → _setup_platform → _setup_defaults → _validate_platform 的调用链一一对应）：

1. 展示 mem0 banner；
2. 检测已存在的配置；若存在且含 API Key，则请求确认是否覆盖（覆盖不可撤销）；
3. 提示输入 API Key，输入以 * 掩码回显，支持退格与 Ctrl+U 清空整行——该能力由 _prompt_secret() 实现，非 Windows 下通过 termios + tty.setraw() 进入原始终端模式逐字符读取（cli/python/src/mem0_cli/commands/init_cmd.py#L34-L93）；
4. 提示输入默认用户 ID，默认值为 mem0-cli（实际为 ${USER}/${USERNAME} 环境变量，取不到时回退 mem0-cli）；
5. 调用平台 status/ping 端点验证连通性，返回失败会提示重新获取 Key；
6. 以 0600 权限保存配置到 ~/.mem0/config.json；
7. 打印成功消息与上手提示（mem0 add、mem0 search 示例）。

非交互模式：当同时提供了 --api-key 与 --user-id 时跳过全部提示直接保存；而当运行环境不是 TTY 且缺失必要标志时，会打印如下错误：

Non-interactive terminal detected and missing required flags.
Usage: mem0 init --api-key <key> --user-id <id>

这里源码还隐藏一个对 CI 友好的细节：非 TTY 下即使只给了 --api-key，CLI 也会自动用 ${USER}/mem0-cli 补齐 user_id，让管道与流水线场景「部分标志也能工作」（cli/python/src/mem0_cli/commands/init_cmd.py#L406-L425）。

4.2 邮箱登录流程

# 交互式（发送验证码后提示输入）：
mem0 init --email [e-mail]

# 完全非交互式：
mem0 init --email [e-mail] --code 482901

执行步骤（对应 _email_login()，cli/python/src/mem0_cli/commands/init_cmd.py#L125-L194）：

1. 若未提供 --code，先向 POST /api/v1/auth/email_code/ 请求给邮箱发送 6 位验证码；收到 429 会提示「Too many attempts, try again in a few minutes」，立即退出；
2. 若带了 --code 则直接进入校验；否则在 TTY 中提示输入验证码（非 TTY 且无 --code 会报错并提示补上 --code）；
3. 携带 {"email": ..., "code": ...} 调用 POST /api/v1/auth/email_code/verify/ 完成校验；
4. 成功时从服务端响应中取回 API Key、org_id、project_id 并写入配置；若该邮箱尚未注册，则自动创建账号；
5. 邮箱格式会先经过 ^[^@\s]+@[^@\s]+\.[^@\s]+$ 正则校验，不合法直接报错退出。

约束：邮箱流程与 --api-key 互斥，同时给出会报 Cannot use both --api-key and --email.。另外，若不传任何标志进入交互式向导，CLI 会先询问认证方式：1. Login with email (recommended) 或 2. Enter API key manually。

4.3 Agent Mode 的无头认证（无邮箱、无 Dashboard）

SKILL 文档（skills/mem0-cli/SKILL.md）给出了专为 AI Agent 设计的无头认证：

mem0 init --agent --agent-caller <your-name> --json

将 <your-name> 替换为 Agent 的自报身份（如 claude-code、cursor、codex、cline、aider）。其核心逻辑在 run_init 的 Agent Mode 分支中（cli/python/src/mem0_cli/commands/init_cmd.py#L262-L339），遵循三条规则：

• 规则 1：若环境变量 MEM0_API_KEY 已存在且通过 /v1/ping/ 校验有效 → 复用现有 Key，不新发；
• 规则 2：若配置文件中已有有效 Key → 复用，同样不覆盖；
• 规则 3：均无效时，调用 POST /api/v1/auth/agent_mode/ 铸一枚新的影子 Key（几秒内完成），并把 user_<slug> 写为默认作用域。

Key 在 <5 秒内可用。此后人类可通过 mem0 init --email <your-email> 认领该 Agent Key——认领走 OTP 设备流（claim flow），不产生新 Key，因此记忆得以保留、Agent 侧无感。若漏传 --agent-caller，事后补跑 mem0 identify <your-name> 即可幂等 PATCH 同一条 Key 的身份。若因任何原因从 Agent 环境重启初始化，只要旧 Key 仍有效，就会命中规则 1/2 的复用逻辑而不会重复铸号。

4.4 强制覆盖已有配置

如果 ~/.mem0/config.json 已存在且含 API Key，mem0 init 会警告并请求确认（提示会以脱敏形式展示已有 Key，例如 (API key: m0-a...mnop)）。想跳过该检查请加 --force：

mem0 init --api-key m0-new-key --user-id alice --force

源码行为：TTY 下给出 Overwrite existing config? This cannot be undone. 的 yes/no 确认；非 TTY 下则直接报错并提示改用 --force（cli/python/src/mem0_cli/commands/init_cmd.py#L342-L362）。

---

五、mem0 config 子命令：运行时的配置查看与修改

配置落地后，日常排查与调整主要靠 mem0 config 这组子命令（在 cli/python/src/mem0_cli/app.py 中以 config_app 子命令组注册，见 cli/python/src/mem0_cli/app.py#L726-L775）。

5.1 mem0 config show

以格式化表格（text 模式）或 JSON envelope（json 模式）展示当前生效配置。API Key 永远以脱敏形式展示。

mem0 config show
mem0 config show -o json

Python 实现（cli/python/src/mem0_cli/commands/config_cmd.py#L21-L81）中，text 模式用 rich Table 输出六个核心键（defaults.user_id/agent_id/app_id/run_id 与 platform.api_key/base_url），空字符串显示为灰色 (not set)，platform.api_key 一律经 redact_key() 脱敏。json/agent 模式则输出标准 envelope：{"status", "command", "scope", ...} 结构（SKILL.md 中给出的统一响应壳）。注意：若当前处于 Agent 模式（--json/--agent），show 会自动切到 json/agent 输出，保证 stdout 可被 LLM 直接解析。

5.2 mem0 config get <key>

读取单个配置值，key 使用点号路径（dotted notation）：

mem0 config get platform.api_key     # 输出: m0-a...mnop（已脱敏）
mem0 config get defaults.user_id     # 输出: alice

合法 key 集合：

• platform.api_key
• platform.base_url
• defaults.user_id
• defaults.agent_id
• defaults.app_id
• defaults.run_id

对未知 key，会向 stderr 打印 Unknown config key: <key>。源码实现上，Python 的 get_nested_value()（cli/python/src/mem0_cli/config.py#L205-L215）沿点号逐层 getattr 取值，取不到返回 None 触发错误分支；Node 版则通过 KEY_MAP 静态映射取值（cli/node/src/config.ts#L206-L211）。

5.3 mem0 config set <key> <value>

写入单个配置值并立刻保存配置文件（保存后自动恢复 0600 权限，并触发前文提到的 API Key 生态同步）：

mem0 config set defaults.user_id alice
mem0 config set platform.base_url https://api.mem0.ai

类型自动转换规则（set_nested_value()，cli/python/src/mem0_cli/config.py#L218-L244；Node 对等实现在 cli/node/src/config.ts#L213-L231）：

• 布尔字段：接受 true、1、yes（不区分大小写）视为真，其余一律为假；
• 整数字段：按 int()/parseInt(value, 10) 解析，解析失败则拒绝写入；
• 字符串字段：原样存储。

转换依据当前值的运行时类型（isinstance(current, bool) / typeof current === "boolean"）动态判定——这意味着转换规则对点号路径背后真实的字段类型是自适应的。

便捷别名：除了完整点号路径，两个实现都支持短别名。Python 侧的映射 SHORT_KEY_ALIASES（cli/python/src/mem0_cli/config.py#L70-L78）与 Node 侧 KEY_MAP（cli/node/src/config.ts#L188-L204）提供：api_key、base_url、user_email、user_id、agent_id、app_id、run_id——它们分别映射到 platform.* 或 defaults.* 的对应字段。

5.4 mem0 config clear

彻底移除配置文件 ~/.mem0/config.json，让 CLI 回到「未初始化」状态（之后所有命令会提示先运行 mem0 init 或设置 MEM0_API_KEY）：

mem0 config clear

补充说明：该行为在 skills/mem0-cli/references/command-reference.md 与本文所属的 configuration.md 中均有定义。实际使用前建议执行 mem0 config --help 确认你安装版本的子命令清单——当前仓库快照中 Python 入口 config_app 注册的子命令为 show/get/set（cli/python/src/mem0_cli/app.py#L729-L775），文档与代码的同步以具体发布版本为准。

---

六、环境变量：无文件化的配置注入

环境变量覆盖配置文件的值，但被 CLI 标志覆盖。这是 CI/CD 与容器场景最常用的配置通道——无需落盘任何密钥文件。

环境变量	对应配置路径	类型	默认值
MEM0_API_KEY	platform.api_key	string	""
MEM0_BASE_URL	platform.base_url	string	"https://api.mem0.ai"
MEM0_USER_ID	defaults.user_id	string	""
MEM0_AGENT_ID	defaults.agent_id	string	""
MEM0_APP_ID	defaults.app_id	string	""
MEM0_RUN_ID	defaults.run_id	string	""

源码佐证：Python 的 load_config() 分两个阶段组装最终配置——先读 config.json 落盘值，再对每个 MEM0_* 环境变量做「非空即覆盖」处理（cli/python/src/mem0_cli/config.py#L119-L142）；Node 的 loadConfig() 结构一致（cli/node/src/config.ts#L120-L131）。由于覆盖发生在「文件读取之后、默认值兜底之前」，因此：

• 环境变量为空字符串/未设置时，配置文件的同名字段原样生效；
• 环境变量只要非空，就一定顶掉文件值。

典型用法：

export MEM0_API_KEY="m0-xxx"
export MEM0_USER_ID="alice"
mem0 add "I prefer dark mode"   # 无需 init，直接使用

---

七、配置优先级：四级解析规则

所有配置值按下述顺序解析（最优先者在前）：

1. CLI 标志        --api-key, --user-id, --base-url 等
2. 环境变量        MEM0_API_KEY, MEM0_USER_ID 等
3. 配置文件        ~/.mem0/config.json
4. 内置默认值      空字符串、false、https://api.mem0.ai

示例：假设配置文件里 user_id: "bob"、环境变量设置了 MEM0_USER_ID=charlie，命令行又传了 --user-id alice，则最终生效的 user_id 是 alice。

这一条规则在两条代码路径上落实：

1. 连接级覆盖：_get_backend_and_config() 中，若命令行传入 api_key/base_url 就直接写入内存中的 config 对象（cli/python/src/mem0_cli/app.py#L100-L152）；

2. 作用域级解析：_resolve_ids() 专门处理 user_id/agent_id/app_id/run_id 的最终取值（cli/python/src/mem0_cli/app.py#L164-L191）。其语义值得单独强调：

   • 只要显式传了任意一个作用域标志（如 --user-id），就只用显式 ID，不再混入配置文件里的其他实体默认值（避免过度过滤）；
   • 一个作用域标志都没传时，四个默认实体 ID 全部取自配置。

所以「想临时用 --user-id carol 覆盖默认 bob」是安全的；而「想给默认 user 额外叠加 --agent-id」反而不生效——这属于 CLI 刻意的隔离语义，而不是 Bug。相关边界场景在 skills/mem0-cli/SKILL.md 的 Common Edge Cases 一节亦有说明。

完整的分级规则同时写在了两个 config 模块的 docstring 顶部（cli/python/src/mem0_cli/config.py#L1-L8、cli/node/src/config.ts#L1-L9），与官方 CLI 规范 cli/CLI_SPECIFICATION.md 的要求一致。

---

八、API Key 脱敏规则

无论何时展示 API Key（config show、config get、status 输出等），一律按如下规则脱敏：

条件	输出
空字符串	(not set)
长度 ≤ 8	前 2 个字符 + ***
长度 > 8	前 4 个字符 + ... + 后 4 个字符

示例：

• "" → (not set)
• "m0-abc" → m0***
• "m0-abcdefghijklmnop" → m0-a...mnop

该函数的命名统一为 Python 的 redact_key（cli/python/src/mem0_cli/config.py#L196-L202）与 Node 的 redactKey（cli/node/src/config.ts#L181-L185），实现完全一致。此外 mem0 config get 与 mem0 config set 还有一层保护：只要 key 名里含 "key"（如 platform.api_key）就脱敏，防止通过子命令把完整密钥回显到屏幕或日志（cli/python/src/mem0_cli/commands/config_cmd.py#L85-L127）。Node 侧测试 cli/node/tests/config.test.ts 对 redactKey 的三种分支（空值/短 Key/长 Key）均有断言覆盖。

---

九、点号路径映射总表

mem0 config get / mem0 config set 使用点号路径定位字段。完整映射如下：

点号路径	所属 Section	字段
platform.api_key	platform	api_key
platform.base_url	platform	base_url
defaults.user_id	defaults	user_id
defaults.agent_id	defaults	agent_id
defaults.app_id	defaults	app_id
defaults.run_id	defaults	run_id

---

十、双实现一致性说明

本仓库同时维护 Node（@mem0/cli）与 Python（mem0-cli）两套实现，二者都源自同一份机器可读规范 cli/cli-spec.json，配置相关的强制要求也记录在 cli/CLI_SPECIFICATION.md（例如第 1558 行要求实现 load_config/save_config/ensure_config_dir/redact_key/get_nested_value/set_nested_value）。本文涉及的所有行为——文件路径与权限、字段命名（磁盘上统一使用 snake_case）、优先级、脱敏、类型转换、Agent Mode 扩展字段——在两份实现中对等存在，差异仅体现在代码风格（如 Python 的 dataclass 与 Node 的 interface）。因此无论你 pip install mem0-cli 还是 npm install -g @mem0/cli，配置体验一致。

一图记忆整个配置体系：mem0 init（或手动 export 环境变量）→ 生成/注入配置 → 任意记忆命令执行时经「CLI 标志 > 环境变量 > config.json > 默认值」解析出最终 Key、Base URL 与实体作用域 → 敏感信息在任何输出路径上都被 redact_key/redactKey 拦下。排查配置问题时，按此链路从高到低逐层核对即可。

延伸阅读

• 同主题技能文档：完整命令与标志参考见 skills/mem0-cli/references/command-reference.md，流水线/脚本化/Agent 工作流配方见 skills/mem0-cli/references/workflows.md，Skill 总览与安装方式见 skills/mem0-cli/SKILL.md
• Python 实现：配置读写与脱敏 cli/python/src/mem0_cli/config.py，config 子命令 cli/python/src/mem0_cli/commands/config_cmd.py，init 向导 cli/python/src/mem0_cli/commands/init_cmd.py，主入口与作用域解析 cli/python/src/mem0_cli/app.py
• Node 实现：配置读写与脱敏 cli/node/src/config.ts，config 子命令 cli/node/src/commands/config.ts，init 向导 cli/node/src/commands/init.ts
• 规范依据：机器可读规范 cli/cli-spec.json，人类可读规范 cli/CLI_SPECIFICATION.md