Mem0 CLI 配置完全指南config.json 文件格式、环境变量、mem0 init向导与配置优先级规则【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchainMem0 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.jsonmem0 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.pyNode 侧对应 cli/node/src/config.ts。两份实现的数据结构、解析顺序与脱敏规则保持一致具体差异在文末第六节说明。二、配置文件位置与安全权限路径权限说明~/.mem0/0700仅属主可读写执行配置目录由mem0 init自动创建~/.mem0/config.json0600仅属主可读写配置文件存放 API Key、默认实体与平台设置收紧权限是刻意的安全设计0600/0700保证同一台机器上的其他系统用户无法读取你的 API Key。源码中这份逻辑在 config.py 中体现为ensure_config_dir()创建目录后用os.chmod(CONFIG_DIR, stat.S_IRWXU)强制0700cli/python/src/mem0_cli/config.py#L81-L85save_config()写入文件后用os.chmod(CONFIG_FILE, stat.S_IRUSR | stat.S_IWUSR)强制0600cli/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 字段参考表字段类型默认值说明versioninteger1配置 schema 版本defaults.user_idstring默认用户 ID用于给命令划定作用域defaults.agent_idstring默认 Agent ID用于给命令划定作用域defaults.app_idstring默认应用 ID用于给命令划定作用域defaults.run_idstring默认运行 ID用于给命令划定作用域platform.api_keystringMem0 Platform 的 API Keym0-开头platform.base_urlstringhttps://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_idplatform.agent_mode布尔值为true表示当前 Key 还是未认领的 Agent Mode 影子 Keyplatform.created_viaKey 的创建途径取值集合为agent_mode | email | api_key | existing_keyplatform.agent_callerAgent 的自报身份例如claude-code、cursor仅当created_via agent_mode时有意义platform.claimed_atAgent Key 被人类通过邮箱认领的 ISO 时间戳platform.default_user_idAgent bootstrap 返回的user_slug形式的自动默认作用域telemetry.anonymous_id匿名遥测 IDagent_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的调用链一一对应展示 mem0 banner检测已存在的配置若存在且含 API Key则请求确认是否覆盖覆盖不可撤销提示输入 API Key输入以*掩码回显支持退格与CtrlU清空整行——该能力由_prompt_secret()实现非 Windows 下通过termiostty.setraw()进入原始终端模式逐字符读取cli/python/src/mem0_cli/commands/init_cmd.py#L34-L93提示输入默认用户 ID默认值为mem0-cli实际为${USER}/${USERNAME}环境变量取不到时回退mem0-cli调用平台 status/ping 端点验证连通性返回失败会提示重新获取 Key以0600权限保存配置到~/.mem0/config.json打印成功消息与上手提示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-keyCLI 也会自动用${USER}/mem0-cli补齐 user_id让管道与流水线场景「部分标志也能工作」cli/python/src/mem0_cli/commands/init_cmd.py#L406-L425。4.2 邮箱登录流程# 交互式发送验证码后提示输入 mem0 init --email alicecompany.com # 完全非交互式 mem0 init --email alicecompany.com --code 482901执行步骤对应_email_login()cli/python/src/mem0_cli/commands/init_cmd.py#L125-L194若未提供--code先向POST /api/v1/auth/email_code/请求给邮箱发送6 位验证码收到429会提示「Too many attempts, try again in a few minutes」立即退出若带了--code则直接进入校验否则在 TTY 中提示输入验证码非 TTY 且无--code会报错并提示补上--code携带{email: ..., code: ...}调用POST /api/v1/auth/email_code/verify/完成校验成功时从服务端响应中取回API Key、org_id、project_id并写入配置若该邮箱尚未注册则自动创建账号邮箱格式会先经过^[^\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 的无头认证无邮箱、无 DashboardSKILL 文档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 Keymem0 init会警告并请求确认提示会以脱敏形式展示已有 Key例如(API key: m0-a...mnop)。想跳过该检查请加--forcemem0 init --api-key m0-new-key --user-id alice --force源码行为TTY 下给出Overwrite existing config? This cannot be undone.的 yes/no 确认非 TTY 下则直接报错并提示改用--forcecli/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.1mem0 config show以格式化表格text 模式或 JSON envelopejson 模式展示当前生效配置。API Key 永远以脱敏形式展示。mem0 config show mem0 config show -o jsonPython 实现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/--agentshow 会自动切到 json/agent 输出保证 stdout 可被 LLM 直接解析。5.2mem0 config get key读取单个配置值key 使用点号路径dotted notationmem0 config get platform.api_key # 输出: m0-a...mnop已脱敏 mem0 config get defaults.user_id # 输出: alice合法 key 集合platform.api_keyplatform.base_urldefaults.user_iddefaults.agent_iddefaults.app_iddefaults.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.3mem0 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-L244Node 对等实现在 cli/node/src/config.ts#L213-L231布尔字段接受true、1、yes不区分大小写视为真其余一律为假整数字段按int()/parseInt(value, 10)解析解析失败则拒绝写入字符串字段原样存储。转换依据当前值的运行时类型isinstance(current, bool)/typeof current boolean动态判定——这意味着转换规则对点号路径背后真实的字段类型是自适应的。便捷别名除了完整点号路径两个实现都支持短别名。Python 侧的映射SHORT_KEY_ALIASEScli/python/src/mem0_cli/config.py#L70-L78与 Node 侧KEY_MAPcli/node/src/config.ts#L188-L204提供api_key、base_url、user_email、user_id、agent_id、app_id、run_id——它们分别映射到platform.*或defaults.*的对应字段。5.4mem0 config clear彻底移除配置文件~/.mem0/config.json让 CLI 回到「未初始化」状态之后所有命令会提示先运行mem0 init或设置MEM0_API_KEYmem0 config clear补充说明该行为在 skills/mem0-cli/references/command-reference.md 与本文所属的 configuration.md 中均有定义。实际使用前建议执行mem0 config --help确认你安装版本的子命令清单——当前仓库快照中 Python 入口config_app注册的子命令为show/get/setcli/python/src/mem0_cli/app.py#L729-L775文档与代码的同步以具体发布版本为准。六、环境变量无文件化的配置注入环境变量覆盖配置文件的值但被 CLI 标志覆盖。这是 CI/CD 与容器场景最常用的配置通道——无需落盘任何密钥文件。环境变量对应配置路径类型默认值MEM0_API_KEYplatform.api_keystringMEM0_BASE_URLplatform.base_urlstringhttps://api.mem0.aiMEM0_USER_IDdefaults.user_idstringMEM0_AGENT_IDdefaults.agent_idstringMEM0_APP_IDdefaults.app_idstringMEM0_RUN_IDdefaults.run_idstring源码佐证Python 的load_config()分两个阶段组装最终配置——先读config.json落盘值再对每个MEM0_*环境变量做「非空即覆盖」处理cli/python/src/mem0_cli/config.py#L119-L142Node 的loadConfig()结构一致cli/node/src/config.ts#L120-L131。由于覆盖发生在「文件读取之后、默认值兜底之前」因此环境变量为空字符串/未设置时配置文件的同名字段原样生效环境变量只要非空就一定顶掉文件值。典型用法export MEM0_API_KEYm0-xxx export MEM0_USER_IDalice 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_IDcharlie命令行又传了--user-id alice则最终生效的 user_id 是alice。这一条规则在两条代码路径上落实连接级覆盖_get_backend_and_config()中若命令行传入api_key/base_url就直接写入内存中的 config 对象cli/python/src/mem0_cli/app.py#L100-L152作用域级解析_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 Keyconfig show、config get、status 输出等一律按如下规则脱敏条件输出空字符串(not set)长度 ≤ 8前 2 个字符 ***长度 8前 4 个字符 ... 后 4 个字符示例→(not set)m0-abc→m0***m0-abcdefghijklmnop→m0-a...mnop该函数的命名统一为 Python 的redact_keycli/python/src/mem0_cli/config.py#L196-L202与 Node 的redactKeycli/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_keyplatformapi_keyplatform.base_urlplatformbase_urldefaults.user_iddefaultsuser_iddefaults.agent_iddefaultsagent_iddefaults.app_iddefaultsapp_iddefaults.run_iddefaultsrun_id十、双实现一致性说明本仓库同时维护 Nodemem0/cli与 Pythonmem0-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.mdSkill 总览与安装方式见 skills/mem0-cli/SKILL.mdPython 实现配置读写与脱敏 cli/python/src/mem0_cli/config.pyconfig 子命令 cli/python/src/mem0_cli/commands/config_cmd.pyinit 向导 cli/python/src/mem0_cli/commands/init_cmd.py主入口与作用域解析 cli/python/src/mem0_cli/app.pyNode 实现配置读写与脱敏 cli/node/src/config.tsconfig 子命令 cli/node/src/commands/config.tsinit 向导 cli/node/src/commands/init.ts规范依据机器可读规范 cli/cli-spec.json人类可读规范 cli/CLI_SPECIFICATION.md【免费下载链接】embedchainThe Memory Layer for AI Agents - Drop-in memory infrastructure for AI agents and apps. Context that persists. Built for production.项目地址: https://gitcode.com/GitHub_Trending/em/embedchain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考