mem0 CLI 完全指南：为 AI Agent 设计的命令行记忆接口（Python 与 Node.js 双实现）

本文围绕仓库中 cli/README.md 展开，完整覆盖 mem0 CLI 的安装方式、快速上手流程、全部 11 个子命令、Agent 模式（--agent）的 JSON 信封协议、五种输出格式与环境变量配置，并结合 cli/node/src 中的真实源码解析配置优先级与 Agent 数据清洗机制。读完本文，你可以独立完成 CLI 的安装初始化、日常记忆增删改查操作，并掌握将 CLI 以机器可读方式接入 AI Agent 工具循环的方法。

安装与定位

mem0 CLI 是 mem0 官方命令行接口，对接 Mem0 Platform API。它对 AI Agent 的核心定位是：任意命令加上 --agent（或 --json）全局标志即可获得专为工具循环设计的结构化 JSON 输出——字段经过清洗、无颜色与 spinner、错误也以 JSON 形式返回。

两种语言实现分别通过包管理器全局安装，均提供行为一致的 mem0 可执行文件：

# Node.js（TypeScript 实现，Node.js 18+）
npm install -g @mem0/cli

# Python（3.10+）
pip install mem0-cli

Python 侧在 macOS Homebrew 环境下若因 externally-managed-environment（PEP 668）报错，建议改用 pipx install mem0-cli 或在虚拟环境中安装，详见 cli/python/README.md。

两个实现包的入口文档分别为 cli/node/README.md 和 cli/python/README.md，二者共享同一套命令规格，规格定义同时沉淀在 cli/CLI_SPECIFICATION.md 与 cli/cli-spec.json 中，并有 cli/node/tests/option-parity.test.ts 等测试保证双端选项对齐。

快速上手

初始化支持三种方式：交互式向导、邮箱验证码登录（获取新 API key）、或直接用已有 API key：

# 交互式设置向导
mem0 init

# 或邮箱登录（获取新 API key）
mem0 init --email [e-mail]

# 或用已有 API key 认证
mem0 init --api-key m0-xxx

初始化完成后即可进行完整的记忆生命周期操作：

# 添加记忆
mem0 add "I prefer dark mode and use vim keybindings" --user-id alice

# 搜索记忆
mem0 search "What are Alice's preferences?" --user-id alice

# 列出某用户的全部记忆
mem0 list --user-id alice

# 获取单条记忆
mem0 get <memory-id>

# 更新记忆
mem0 update <memory-id> "I switched to light mode"

# 删除记忆
mem0 delete <memory-id>

mem0 init 的完整标志如下：

标志	说明
--api-key	直接传入 API key（跳过提示）
-u, --user-id	设置默认用户 ID（跳过提示）
--email	通过邮箱验证码登录
--code	验证码（与 --email 配合实现非交互登录）
--force	跳过确认直接覆盖已有配置（适用于 CI/CD）

从源码看，Node 实现每次执行命令时都会做一次快速校验：cli/node/src/index.ts 中的 getBackendAndConfig 先加载配置，若 API key 缺失则直接报错提示运行 mem0 init 或设置 MEM0_API_KEY；随后以 5 秒超时竞态调用 backend.ping() 验证 key 有效性，AuthError 会终止进程，而网络问题仅告警后继续执行——这也解释了为什么 mem0 status 能作为连接自检命令使用。

全部命令一览

命令	说明
mem0 init	设置向导——邮箱登录或手动配置 API key
mem0 add	从文本、JSON 消息数组、文件或 stdin 添加记忆
mem0 search	用自然语言搜索记忆
mem0 list	列出记忆，支持过滤与分页
mem0 get	按 ID 获取单条记忆
mem0 update	更新记忆文本或元数据
mem0 delete	删除单条记忆、某作用域下全部记忆或整个实体
mem0 import	从 JSON 文件批量导入记忆
mem0 config	查看或修改 CLI 配置
mem0 entity	列出或删除实体（users、agents、apps、runs）
mem0 event	查看后台处理事件（批量删除、大批量 add 任务）
mem0 status	验证 API 连接并显示当前项目

任意命令支持 mem0 <command> --help 查看详细用法，mem0 --version 打印版本（仅在子命令之前有效）。

mem0 add：四种输入来源

mem0 add "I prefer dark mode" --user-id alice
mem0 add --file conversation.json --user-id alice
echo "Loves hiking on weekends" | mem0 add --user-id alice

标志	说明
-u, --user-id	限定到某个用户
--agent-id	限定到某个 agent
--messages	以 JSON 传入会话消息数组
-f, --file	从 JSON 文件读取消息
-m, --metadata	自定义元数据（JSON）
--categories	分类（JSON 数组或逗号分隔）
--graph / --no-graph	启用或禁用图谱记忆抽取
-o, --output	输出格式：text、json、quiet

mem0 search：语义检索与调参

mem0 search "dietary restrictions" --user-id alice
mem0 search "preferred tools" --user-id alice --output json --top-k 5

标志	说明
-u, --user-id	按用户过滤
-k, --top-k	返回条数（默认 10）
--threshold	最低相似度分数（默认 0.3）
--rerank	启用重排序
--keyword	使用关键词搜索替代语义搜索
--filter	高级过滤表达式（JSON）
--graph / --no-graph	启用或禁用搜索中的图谱召回
-o, --output	输出格式：text、json、table

mem0 list / get / update

# 列表：支持分类、日期区间与分页
mem0 list --user-id alice
mem0 list --user-id alice --category preferences --output json
mem0 list --user-id alice --after 2024-01-01 --page-size 50

标志	说明
-u, --user-id	按用户过滤
--page	页码（默认 1）
--page-size	每页条数（默认 100）
--category	按分类过滤
--after / --before	创建时间过滤（YYYY-MM-DD）
-o, --output	输出格式：text、json、table

get 直接按 ID 取回单条记忆；update 支持三种写法：位置参数传新文本、--metadata '{"priority": "high"}' 更新元数据、或通过 stdin 传入新文本（echo "new text" | mem0 update <memory-id>）。

mem0 delete：三级删除粒度

# 删除单条记忆
mem0 delete <memory-id>

# 删除某用户全部记忆
mem0 delete --all --user-id alice --force

# 删除整个项目的所有记忆
mem0 delete --all --project --force

# 预览将被删除的内容（不实际删除）
mem0 delete --all --user-id alice --dry-run

标志	说明
--all	删除匹配作用域过滤条件的全部记忆
--entity	删除实体及其所有记忆
--project	与 --all 联用：删除项目级全部记忆
--dry-run	仅预览不删除
--force	跳过确认提示

批量导入、配置、实体与事件

# 批量导入：文件为 JSON 数组，每项含 memory（或 text/content）
# 及可选的 user_id、agent_id、metadata 字段
mem0 import data.json --user-id alice

# 查看/修改本地配置（show 会对密钥打码）
mem0 config show
mem0 config get api_key
mem0 config set user_id bob

# 实体管理
mem0 entity list users
mem0 entity list agents --output json
mem0 entity delete --user-id alice --force

# 后台事件检查（批量删除、大批量 add 产生的异步事件）
mem0 event list
mem0 event status <event-id>

# 连接自检
mem0 status

Agent 模式：为工具循环设计的输出协议

在任何命令上以全局标志传入 --agent（别名 --json），即可获得专为 AI Agent 工具循环设计的输出：

mem0 --agent search "user preferences" --user-id alice
mem0 --agent add "User prefers dark mode" --user-id alice
mem0 --agent list --user-id alice
mem0 --agent delete --all --user-id alice --force

每条命令返回相同的信封（envelope）结构：

{
  "status": "success",
  "command": "search",
  "duration_ms": 134,
  "scope": { "user_id": "alice" },
  "count": 2,
  "data": [
    { "id": "abc-123", "memory": "User prefers dark mode", "score": 0.97, "created_at": "2026-01-15", "categories": ["preferences"] }
  ]
}

Agent 模式与 --output json 的三点关键差异：

• 清洗后的 data：只保留 agent 需要的字段（id、memory、score 等），没有内部 API 噪音；
• 无人面向输出：spinner、颜色、横幅被完全抑制；
• 错误也是 JSON：错误写入 stdout，形如 {"status": "error", "command": "...", "error": "..."}，并伴随非零退出码。

此外，mem0 help --json 可以以 JSON 形式输出完整命令树，方便 Agent 自行发现可用命令。

从源码可以印证这套协议的真实实现：

1. 信封构造：cli/node/src/output.ts 的 formatJsonEnvelope 按 status（默认 success）→ command → duration_ms → scope → count → error → data 的顺序拼装信封。平台若标记当前账号为未认领的 Agent Mode 账户，还会把通知折叠进 mem0_notice 字段，使消费方无需解析 HTTP 头即可感知；
2. 字段清洗：sanitizeAgentData 按命令名白名单挑选字段——search 只保留 id/memory/score/created_at/categories/expiration_date，add 对 PENDING 状态只保留 status/event_id（异步任务需要跟踪事件），这与文档中"no internal API noise"的描述完全一致；
3. 模式开关：cli/node/src/index.ts 中 checkAgentMode 读取根级 --json / --agent 选项并调用 setAgentMode(true)，即该标志必须是命令之前的全局标志。

行为测试可见 cli/node/tests/agent-mode.test.ts 与 Python 侧的 cli/python/tests/test_agent_mode.py，双端各自验证信封结构与错误路径。

输出格式

用 --output 控制结果的展示方式：

格式	说明
text	人类可读，带颜色与排版（默认）
json	结构化 JSON，可直接管道给 jq（原始 API 响应）
table	表格形式（list 的默认格式）
quiet	极简——仅输出 ID 或状态码
agent	带清洗字段的 JSON 信封（由 --agent/--json 设置）

Node 端的实现位于 cli/node/src/output.ts：formatMemoriesText 渲染带 Score/ID/Category 详情行的人类可读列表，formatMemoriesTable 基于 cli-table3 生成表格（list 默认走此路径，超长文本自动截断为 57 字符加省略号），formatJson 则以两空格缩进打印原始响应。

环境变量

变量	说明
MEM0_API_KEY	API key（覆盖配置文件）
MEM0_BASE_URL	API base URL
MEM0_USER_ID	默认用户 ID
MEM0_AGENT_ID	默认 agent ID
MEM0_APP_ID	默认 app ID
MEM0_RUN_ID	默认 run ID
MEM0_ENABLE_GRAPH	启用图谱记忆（true / false）

优先顺序为：环境变量 > 配置文件 > 默认值。这一行为在 Node 实现中有明确体现——cli/node/src/config.ts 文件头部注释写明的优先级是「CLI flags > 环境变量 > 配置文件（~/.mem0/config.json）> 默认值」，loadConfig 先读取配置文件、再逐项用 process.env.MEM0_* 覆盖，而 getBackendAndConfig 接收的 --api-key / --base-url 命令行覆盖参数则在两者之上生效。

几个源码层面的补充细节：

• 配置默认指向 https://api.mem0.ai（DEFAULT_BASE_URL），可用 --base-url 或 MEM0_BASE_URL 指向自建/私有端点；
• 配置文件写入后权限固定为 0600、目录为 0700（saveConfig），且 mem0 config show 会对密钥打码（保留前 4 后 4 位）；
• config get/set 支持点号路径与短别名两种写法，如 platform.api_key 与 api_key 等价，映射表见 KEY_MAP；
• 作用域解析遵循「显式 ID 优先、不混入其他实体的默认值」策略：resolveIds 注释说明，只要传了任意一个显式 ID，就只用显式 ID（避免默认值过度过滤）；完全没传时才回退到配置中的默认值。

双语言实现与开发入口

语言	目录	包	文档
TypeScript	cli/node/	@mem0/cli	README
Python	cli/python/	mem0-cli	README

两套实现共享 cli/ 下的统一规格（CLI_SPECIFICATION.md / cli-spec.json），并在命令层保持同名同参：Python 端的命令模块位于 cli/python/src/mem0_cli/commands/（init_cmd.py、memory.py、entities.py、events_cmd.py 等），与 Node 端 cli/node/src/commands/ 的 init.ts、memory.ts、entities.ts、events.ts 一一对应。

本地开发方式：

# Node（cli/node，需 Node.js 18+）
cd cli/node
pnpm install
pnpm dev --help                # 开发模式，直接运行 TypeScript
pnpm build && node dist/index.js --help   # 或先构建再运行

# Python（cli/python）
cd cli/python
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python -m mem0_cli --help

小结

mem0 CLI 的价值在于把 Mem0 Platform 的完整记忆操作（add / search / list / get / update / delete / import / entity / event）收敛到一个 mem0 命令之后，并通过三个层次满足不同消费者：text/table 服务人类交互，json 服务脚本与 jq 管道，--agent 信封模式服务 AI Agent 的工具循环。配合环境变量与 ~/.mem0/config.json 的四级配置优先级，同一份命令序列可以无缝跑在本地开发、CI 和 Agent 编排环境之中。本文所有命令、默认值与优先级结论均以上述仓库文档与 cli/node/src、cli/python/src 源码为准。