mem0 CLI 完整实战指南：在终端与 Agent 流水线中操作 Mem0 记忆层

2026-09-07 12:22:16作者：盛欣凯Ernestine

Mem0 CLI（对应 npm 包 @mem0/cli、PyPI 包 mem0-cli）是 Mem0 记忆平台官方提供的命令行工具，让开发者、AI Agent 与 CI/CD 流水线可以在终端中直接对记忆执行增、查、列、改、删等操作。本文以本仓库 skills/mem0-cli 技能包为骨架，结合 cli/python 与 cli/node 两套 CLI 源码、统一规格 cli-spec.json 及配套测试，系统讲解安装配置、Agent/JSON 模式、实体作用域解析、输出格式矩阵与脚本化工作流，读完即可在 shell、Agent 循环与 CI 中把 mem0 当"命令"一样使用。

1. mem0 CLI 是什么：先认清它的定位

Mem0 将自身定义为"AI Agent 的记忆层（The Memory Layer for AI Agents）"，提供能够跨会话持久化的上下文。mem0 CLI 正是这一能力的终端入口：它只面向 Mem0 云端 Platform 的记忆操作，负责把命令翻译成对 Mem0 Platform REST API 的调用。

这一边界在 SKILL.md 中写得很明确：当用户在终端/Shell 中执行 mem0 add/search/list/get/init/config/import 等命令时才应触发；而如果用户问的是 Python/TypeScript SDK 的代码级集成，则属于 mem0 技能；问的是 Vercel AI SDK 提供方，则属于 mem0-vercel-ai-sdk 技能。使用前先明确这一点，可以避免把 CLI 与 SDK 的使用方式混淆。

从源码结构看，Python 端的命令实现集中在 cli/python/src/mem0_cli/commands（add/search/get/list/update/delete 位于 memory.py，初始化位于 init_cmd.py），并基于 config.py 管理本地配置。

2. 安装与运行环境

mem0 CLI 有两套等价实现，任选一种即可：

# Node.js 方式（npm 全局安装）
npm install -g @mem0/cli

# Python 方式（pip 安装）
pip install mem0-cli

运行前提与版本事实：

Node 端：要求 Node.js 18+。
Python 端：以本仓库 cli/python/pyproject.toml 为准，requires-python = ">=3.10"，当前版本号为 0.2.12，依赖 typer、rich、httpx；安装后通过 [project.scripts] 的 mem0 = "mem0_cli.app:main" 提供 mem0 命令。
两个包安装后都提供同名的 mem0 可执行文件，命令、选项、输出格式完全一致（具体机制见第 9 节"Node 与 Python 双实现对齐"）。

验证是否装好并连通服务：

mem0 --version
mem0 status -o json

mem0 status 会调用 GET /v1/ping/ 校验连通性与认证状态，JSON 输出形如：

{
  "status": "success",
  "command": "status",
  "duration_ms": 112,
  "data": { "connected": true, "backend": "platform", "base_url": "https://api.mem0.ai" }
}

3. 初始化与三种认证方式

mem0 CLI 提供三类认证路径，分别适合人类开发者、AI Agent 自助引导和脚本化 CI。

3.1 直接设置环境变量（最快）

export MEM0_API_KEY="m0-xxx"

随后所有命令都会自动携带该密钥，无需执行 init。也可以在 mem0 init 交互向导中配置。API Key 可在 Mem0 Platform 控制台的 API Keys 页面获取。

3.2 `mem0 init` 交互式向导（适合人类）

mem0 init

从 init_cmd.py 的实现看，交互流程包括：打印品牌横幅 → 检查 ~/.mem0/config.json 是否已有 API Key（存在则询问是否覆盖）→ 以掩码形式（逐字符回显 *，支持退格与 Ctrl+U 清空）提示输入 API Key → 提示默认用户 ID（默认值 mem0-cli）→ 调用 status 端点校验连接 → 以 0600 权限写回配置文件 → 打印成功信息。

若当前不是交互终端（non-TTY）且未提供足够参数，会打印如下提示并以错误退出：

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

init 也支持完全非交互式写法：

# 全非交互：直接保存 API Key + 默认用户 ID
mem0 init --api-key m0-xxx --user-id alice

# 已有配置时强制覆盖
mem0 init --api-key m0-xxx --user-id alice --force

# 邮箱验证码登录（交互式等待验证码）
mem0 init --email alice@company.com

# 邮箱验证码登录（全非交互）
mem0 init --email alice@company.com --code 482901

邮箱登录流程走 POST /api/v1/auth/email_code/ 发送 6 位验证码；若同时给出 --code 则立即校验，成功后服务端返回 API Key、org_id、project_id 一并写入配置；该方式不能与 --api-key 混用（邮箱未注册时会自动创建新账户）。

3.3 Agent Mode：AI Agent 免邮箱自助引导（核心场景）

面向 AI 编程代理（如 Claude Code、Cursor、Codex、Cline、Aider 等），SKILL 文档推荐一条无需邮箱、无需打开 Dashboard 的自助初始化命令：

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

其中 <your-name> 换成调用方 Agent 的自称，例如 claude-code、cursor。从 SKILL.md 与命令参考可知：

该流程向 /api/v1/auth/agent_mode/ 发起请求，数秒内签发一枚 shadow API Key，立即可用；
若漏传 --agent-caller，可事后补跑 mem0 identify <your-name>，它 PATCH /api/v1/auth/agent_mode/caller/（携带 Authorization: Token <current-api-key> 与 {agent_caller}），操作幂等、可重复执行且不影响已有记忆；
服务端会对 Agent 名称做清洗：转小写、剔除 [a-z0-9._/-] 之外的字符、截断至 32 字符；
仅作用于尚未被人类认领的 Agent Mode Key（配置中 platform.agent_mode=true 表示仍处于未认领状态）。

Agent 自助引导完成后，应把下面这句话打印给人类用户，引导其认领所有权：

Mem0 memory is running in Agent Mode. Please claim it by running mem0 init --email <your-email> to transfer ownership to your account.

人类用户认领后同一个 API Key 继续有效——Agent 运行不中断、记忆不丢失，只是所有权从临时 shadow Key 转移到人类账户名下。

安全纪律：不要把 API Key、.env 或 ~/.mem0/config.json 提交进任何仓库（详见第 4.1 节的权限设计）。

4. 配置系统：配置文件、环境变量与优先级

4.1 配置文件位置与权限

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

严格权限确保 API Key 不会被同机其他用户读取。该行为在 config.py 中有据可查：ensure_config_dir() 执行 os.chmod(CONFIG_DIR, stat.S_IRWXU)（即 0700），save_config() 落盘后执行 os.chmod(CONFIG_FILE, stat.S_IRUSR | stat.S_IWUSR)（即 0600）。

4.2 配置文件 Schema 与字段参考

SKILL 配套的 configuration.md 给出如下基础结构（Python 源码 config.py 中还有 user_email、agent_mode、agent_caller 等附加字段，用于承载 Agent Mode 状态）：

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

字段	类型	默认值	说明
`version`	integer	`1`	配置 Schema 版本（源码中 `CONFIG_VERSION = 1`）
`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
`platform.base_url`	string	`"https://api.mem0.ai"`	API 请求基地址

4.3 环境变量与优先级规则

环境变量覆盖配置文件、但被命令行参数覆盖：

环境变量	对应配置路径	类型	默认
`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	`""`

配置值的解析优先级（从高到低）：

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）

这一优先级在 config.py 的 load_config() 中落地实现：先读文件，再逐项用环境变量覆盖，而 CLI 层的 flag 又在其上的调用层覆盖结果。示例：配置文件里 user_id="bob"、环境变量 MEM0_USER_ID=charlie，命令行再传 --user-id alice，则最终生效值为 alice。

4.4 `mem0 config` 子命令族

运行时查看与修改配置（API Key 始终脱敏显示）：

mem0 config show                  # 表格形式展示当前配置
mem0 config show -o json          # JSON 形式
mem0 config get platform.api_key  # 打印脱敏后的 key，如 m0-a...mnop
mem0 config get defaults.user_id  # 打印 alice
mem0 config set defaults.user_id alice
mem0 config set platform.base_url https://api.mem0.ai
mem0 config clear                 # 删除 ~/.mem0/config.json

点号路径（dotted key）完整映射：

点号键	节	字段
`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

（Python 端 config.py 还额外支持不带节前缀的短别名，如 api_key、user_id，由 SHORT_KEY_ALIASES 映射到完整点号键。）

类型强制规则（config.py 的 set_nested_value）：布尔字段接受 true/1/yes（不区分大小写）视为真、其余为假；整数字段用 int() 解析，失败则报错。

API Key 脱敏规则（redact_key / redactKey）：

条件	输出示例
空串	`(not set)`
长度 ≤ 8	前 2 字符 + `*`，如 `m0-abc` → `m0*`
长度 > 8	前 4 字符 + `...` + 后 4 字符，如 `m0-abcdefghijklmnop` → `m0-a...mnop`

5. 命令速查与完整 CRUD 实战

先看 SKILL.md 中的"Quick Reference"（针对用户 alice 的最小可用示例）：

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

# 语义搜索
mem0 search "preferences" --user-id alice

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

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

# 更新某条记忆的文本
mem0 update <memory-id> "new text"

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

# 删除某用户的全部记忆（需 --force 跳过确认）
mem0 delete --all --user-id alice --force

下面按命令逐一展开参数与行为。所有命令还支持一组全局选项（见 command-reference.md）：

全局 Flag	类型	说明
`--json` / `--agent`	boolean	Agent 模式：stdout 输出结构化 JSON 信封（二者互为别名）
`-o, --output <format>`	string	输出格式，各命令支持范围见输出矩阵（第 7 节）
`--api-key <key>`	string	本次调用覆盖 API Key，优先级高于环境变量与配置文件
`--base-url <url>`	string	覆盖 API 基地址（默认 `https://api.mem0.ai`）
`--version`	boolean	打印版本后退出

5.1 `mem0 add`：写入记忆

mem0 add [text] [OPTIONS]

选项	类型	默认	说明
`-u, --user-id <id>`	string	-	作用域：用户
`--agent-id <id>`	string	-	作用域：Agent
`--app-id <id>`	string	-	作用域：应用
`--run-id <id>`	string	-	作用域：运行
`--messages <json>`	string	-	会话消息 JSON 数组，如 `'[{"role":"user","content":"..."}]'`
`-f, --file <path>`	path	-	从 JSON 文件读取消息
`-m, --metadata <json>`	string	-	自定义元数据 JSON，如 `'{"source":"cli"}'`
`--no-infer`	boolean	false	跳过推断，原样存储文本
`--categories <cats>`	string	-	分类，JSON 数组或逗号分隔字符串
`--expires <date>`	string	-	过期时间 `YYYY-MM-DD`，需为未来日期（源码 `_validate_expires` 校验）
`--immutable`	boolean	false	标记为不可变记忆
`-o, --output <fmt>`	string	`text`	`text` / `json` / `quiet`

输入优先级：--file > --messages > 位置参数 text > stdin（管道且无文本时）。纯文本内容会被包装为 [{"role": "user", "content": "<text>"}] 再发送给 API，而 --messages/--file 提供的消息原样透传。

返回事件语义（每次写入 API 都会按记忆逐条返回 event 字段）：

事件	含义
`ADD`	新建记忆
`UPDATE`	更新已有记忆（去重合并）
`DELETE`	移除已有记忆（出现矛盾信息）
`NOOP`	无需变化
`PENDING`	已进入后台异步处理

示例：

mem0 add "allergic to nuts" -u alice -m '{"source":"onboarding"}'
mem0 add --messages '[{"role":"user","content":"I like Python"}]' -u alice
mem0 add --file conversation.json -u alice -o json
echo "I prefer dark mode" | mem0 add -u alice
mem0 add "temporary note" -u alice --expires 2025-12-31
mem0 add "important fact" -u alice --immutable
mem0 add "uses vim" -u alice --categories "tools,preferences"

5.2 `mem0 search`：语义检索

mem0 search <query> [OPTIONS]

选项	类型	默认	说明
`-u/--agent-id/--app-id/--run-id`	string	-	按实体过滤
`-k, --top-k, --limit <n>`	integer	10	最大返回条数
`--threshold <score>`	float	0.1	最低相似度阈值（0.0 ~ 1.0）
`--rerank`	boolean	false	开启重排序提升相关性（Platform 专属能力）
`--filter <json>`	string	-	高级过滤表达式（支持 AND/OR）
`--fields <list>`	string	-	逗号分隔的返回字段白名单
`-o, --output <fmt>`	string	`text`	`text` / `json` / `table`

query 为必填，但在管道场景下回退到 stdin 读取。

mem0 search "tools" -u alice -o json -k 5
mem0 search "dietary restrictions" -u alice --threshold 0.5
mem0 search "project setup" -u alice --rerank
mem0 search "preferences" -u alice --filter '{"categories":{"contains":"food"}}'
echo "preferences" | mem0 search -u alice

5.3 `mem0 list`：分页列出

mem0 list [OPTIONS]

选项	类型	默认	说明
`-u/--agent-id/--app-id/--run-id`	string	-	按实体过滤
`--page <n>`	integer	1	页码
`--page-size <n>`	integer	100	每页条数
`--category <name>`	string	-	按分类过滤
`--after <date>`	string	-	创建时间晚于 `YYYY-MM-DD`
`--before <date>`	string	-	创建时间早于 `YYYY-MM-DD`
`-o, --output <fmt>`	string	`table`	`text` / `json` / `table`

mem0 list -u alice
mem0 list --category prefs --after 2024-01-01 -o json
mem0 list -u alice --page 2 --page-size 50
mem0 list --before 2024-06-01 -o table

5.4 `mem0 get` / `mem0 update`

# 按 UUID 取单条记忆
mem0 get <memory_id>
mem0 get <memory_id> -o json

# 更新文本、元数据或二者同时
mem0 update <memory_id> "new text"
mem0 update <memory_id> --metadata '{"priority":"high"}'
mem0 update <memory_id> "new text" -m '{"priority":"high"}'
echo "new text" | mem0 update <memory_id>

update 的文本参数在"stdin 被管道且未提供 --metadata"时回退到 stdin。

5.5 `mem0 delete`：三种互斥的删除模式

mem0 delete [memory_id] [OPTIONS]

选项	类型	默认	说明
`--all`	boolean	false	删除作用域内全部记忆
`--entity`	boolean	false	连实体带其全部记忆一起删除（级联）
`--project`	boolean	false	配合 `--all`：删除项目内全部记忆（发送通配 ID）
`--dry-run`	boolean	false	只展示将被删除的内容，不真正删除
`--force`	boolean	false	跳过 `[y/N]` 确认提示
`-u/--agent-id/--app-id/--run-id`	string	-	作用域

三种模式互斥：不能把 <memory_id> 与 --all/--entity 组合，也不能把 --all 与 --entity 组合；三者都不提供时会打印用法提示并以错误退出。

单条删除：mem0 delete <memory_id>——按 UUID 删一条；
批量删除：mem0 delete --all [scope]——删除匹配作用域的全部记忆；加 --project 时发送 DELETE /v1/memories/ 且 user_id=*&agent_id=*&app_id=*&run_id=*（通配实体 ID），API 返回异步响应，CLI 打印 "Deletion started. Memories will be removed in the background."；
实体级联：mem0 delete --entity [scope]——把实体本身及其全部记忆一起删除。

--dry-run 行为：单条模式会先抓取并展示该记忆然后打印 "No changes made."；--all 模式列出匹配条数与总数；--entity 模式仅展示受影响作用域。所有破坏性模式在缺少 --force 时都会弹出 [y/N] 确认，其中 --all --project 的提示会明确警告这是项目级全删。

mem0 delete abc-123-def-456
mem0 delete --all -u alice --force
mem0 delete --all --project --force
mem0 delete --entity -u alice --force
mem0 delete abc-123 --dry-run
mem0 delete --all -u alice --dry-run

5.6 `mem0 import`：JSON 批量导入

mem0 import <file_path> [OPTIONS]

选项	类型	默认	说明
`-u, --user-id <id>`	string	-	覆盖所有导入项的 user_id
`--agent-id <id>`	string	-	覆盖所有导入项的 agent_id
`-o, --output <fmt>`	string	`text`	`text` / `json`

文件格式为 JSON 数组（或单个对象），每项通过 memory、text 或 content 字段承载文本，可选 user_id、agent_id、metadata；CLI 层传入的 --user-id/--agent-id 会覆盖逐项值。导入会对每项依次调用 add API，完成后汇报 added 与 failed 计数。

[
  { "memory": "Prefers dark mode", "user_id": "alice" },
  { "text": "Allergic to nuts", "metadata": { "source": "intake" } },
  { "content": "Uses VS Code" }
]

mem0 import memories.json --user-id alice
mem0 import data.json -u alice -o json

JSON 输出的 data 形如 {"added": 42, "failed": 0, "duration_s": 3.14}。

5.7 实体与事件管理命令

mem0 entity list <entity_type>——列出某类实体，entity_type 取值 users/agents/apps/runs，输出 Name/ID 与 Created 两列表格；行为是调用 GET /v1/entities/ 后按类型映射客户端过滤。

mem0 entity list users
mem0 entity list agents -o json

mem0 entity delete——级联删除实体及其全部记忆，至少需要一个实体 ID（--user-id 等），支持 --dry-run/--force：

mem0 entity delete --user-id alice --force
mem0 entity delete --user-id alice --dry-run
mem0 entity delete --agent-id bot1 --force

mem0 event list / mem0 event status——查看后台异步处理的进度。事件表格列包含 Event ID（前 8 字符）、Type、Status（带颜色）、Latency、Created；状态取值 PENDING/SUCCEEDED/FAILED/PROCESSING。

mem0 event list
mem0 event list --output json
mem0 event status evt-abc-123
mem0 event status evt-abc-123 --output json

6. 实体作用域解析与过滤器构建

6.1 实体 ID 解析的"全有或全无"规则

CLI 提供四维作用域：user_id、agent_id、app_id、run_id。解析规则是 SKILL.md 与 command-reference.md 共同强调的关键行为：

只要显式传了任意一个作用域 flag（如 --user-id），CLI 就只用显式给出的 ID，不再混入配置文件/环境变量里的其余默认值；一个作用域 flag 都不传时，所有已配置默认值全部生效。

设计动机：如果用户传 --user-id alice、而配置里还有 agent_id=bot1，用户期望的是"只查 Alice 的记忆"，而非"Alice 且 bot1 的交集"。

if any(user_id, agent_id, app_id, run_id) were passed as flags:
    use only the explicitly provided IDs (others = null)
else:
    use all configured defaults

该规则适用于 resolveIds: true 的命令：add、search、list、delete、import。这一行为在 cli/cli-spec.json 规格中被两套实现共同引用，并可通过 test_option_parity.py 等双实现对齐测试印证。

6.2 过滤器构建（search / list）

若用户通过 --filter 提供了含 AND 或 OR 键的预构建过滤表达式，则原样透传给 API；
否则 CLI 自行组装一组 AND 条件：每个实体 ID 生成一条 {"user_id": "alice"} 式条件；分类条件为 {"categories": {"contains": "<category>"}}；日期条件为 {"created_at": {"gte": "YYYY-MM-DD"}} 与/或 {"created_at": {"lte": "YYYY-MM-DD"}}；
恰好 1 条条件时以单对象发送（不加包裹）；
2 条及以上时包裹为 {"AND": [cond1, cond2, ...]}；
0 条条件时不发送 filter。

另外在 cli-spec.json 的配置段可以看到 defaults.enable_graph 字段及其环境变量 MEM0_ENABLE_GRAPH（布尔，默认 false），说明双端实现还具备知识图谱三元组相关的开关能力（enable_graph 在规格层与 graph 相关请求选项联动），需要时可通过点号键与配置命令查看。

7. Agent / JSON 模式：给 LLM 吃的标准输出

当传入 --json 或 --agent（二者互为别名）时，每条命令都会把结果包装进一个统一 JSON 信封输出到 stdout；spinner、进度条等交互元素全部写入 stderr，保证 stdout 永远是干净、可被解析的 JSON。

成功信封：

{
  "status": "success",
  "command": "search",
  "duration_ms": 245,
  "scope": { "user_id": "alice" },
  "count": 3,
  "error": null,
  "data": [
    { "id": "mem-abc", "memory": "User prefers dark mode", "score": 0.92 }
  ]
}

失败信封：

{
  "status": "error",
  "command": "search",
  "error": "Authentication failed. Your API key may be invalid or expired.",
  "data": null
}

信封字段说明：

字段	说明
`status`	`"success"` 或 `"error"`
`command`	命令名，如 `"search"`、`"add"`、`"list"`
`duration_ms`	耗时毫秒数（可选）
`scope`	生效中的实体作用域，为空时省略（可选）
`count`	结果条数（视命令而定，可选）
`error`	出错时的错误字符串，成功为 `null`
`data`	命令返回数据；出错时为 `null`

各命令在 Agent 模式下的 data 形状（清洗后）：

命令	`data` 形状
`add`	`[{id, memory, event}]`，若为 PENDING 则为 `[{status, event_id}]`
`search`	`[{id, memory, score, created_at, categories}]`
`list`	`[{id, memory, created_at, categories}]`
`get`	`{id, memory, created_at, updated_at, categories, metadata}`
`update`	`{id, memory}`
`delete`	原始 API 响应
`entity list`	`[{name, type, count}]`
`event list`	`[{id, event_type, status, latency, created_at}]`
`event status`	`{id, event_type, status, latency, created_at, updated_at, results}`
`status`	`{connected, backend, base_url}`
`config show`	配置对象（Key 已脱敏）
`import`	`{added, failed, duration_s}`

例如 Agent 模式下的搜索返回完整形态（含多结果时）：

{
  "status": "success",
  "command": "search",
  "duration_ms": 187,
  "scope": { "user_id": "alice" },
  "count": 2,
  "error": null,
  "data": [
    { "id": "mem-abc", "memory": "User prefers dark mode", "score": 0.95, "created_at": "2025-01-15T10:00:00Z", "categories": ["preferences"] },
    { "id": "mem-def", "memory": "User likes monospace fonts", "score": 0.82, "created_at": "2025-01-15T10:01:00Z", "categories": ["preferences"] }
  ]
}

由于 stderr/stdout 严格分离，这一模式非常适合被 LLM 工具调用（function calling）、Agent 框架或脚本以子进程方式消费。出错时也返回合法 JSON 的 "status": "error" 信封，方便调用方统一分支处理，无需解析人类可读文本。

输出模式支持矩阵

命令	`text`	`json`	`table`	`quiet`	默认
`add`	Y	Y	-	Y	`text`
`search`	Y	Y	Y	-	`text`
`get`	Y	Y	-	-	`text`
`list`	Y	Y	Y	-	`table`
`update`	Y	Y	-	Y	`text`
`delete`	Y	Y	-	Y	`text`
`import`	Y	Y	-	-	`text`
`config show`	Y	Y	-	-	`text`
`config get`	raw	-	-	-	raw
`config set`	msg	-	-	-	msg
`entity list`	-	Y	Y	-	`table`
`entity delete`	Y	Y	-	Y	`text`
`event list`	Y（表格）	Y	-	-	`table`
`event status`	Y	Y	-	-	`text`
`status`	Y	Y	-	-	`text`

--json/--agent 会覆盖 --output 设定，统一走 JSON 信封。

8. Node 与 Python 双实现对齐：一份规格，两套运行时

mem0 CLI 的一个显著工程特征是双端同构。SKILL 文档明确说明：Node.js（@mem0/cli）与 Python（mem0-cli）两套 CLI 都按同一份规格文件 cli/cli-spec.json 实现，二者共享：

完全一致的命令名、参数与 flag；
完全一致的输出格式（text、json、table、quiet）；
完全一致的实体 ID 解析、图谱三态（graph tri-state）与过滤表达式构建逻辑；
完全一致的错误消息与退出码。

本仓库中可核验的实现证据包括：

Python 端：cli/python/src/mem0_cli（入口 mem0_cli.app:main，CRUD 在 commands/memory.py，配置在 config.py）；
Node 端：cli/node/src；
对齐测试：test_option_parity.py（Python 端双实现参数一致性测试），以及 CLI 目录下 Python/Node 两套同名测试集（如 test_commands.py、cli/node/tests/commands.test.ts）对命令行为做镜像验证。

因此选型的决策点只有一个：你的机器上已经装好了哪个运行时，行为上没有差别。

stdin 检测在两端的实现（workflows.md 记载）：Python 用 not sys.stdin.isatty()（Python 源码 memory.py 中实际以 fstat 判断 S_ISFIFO/S_ISREG 识别管道与文件重定向），Node 用 !process.stdin.isTTY；读取方法分别是 sys.stdin.read().strip() 与 fs.readFileSync(0, "utf-8").trim()。

9. 脚本化工作流：stdin、管道、批量与 CI/CD

9.1 stdin 管道输入

当命令行没给文本参数、且输入来自管道（非 TTY）时，CLI 从 stdin 读取——适用于 add、search、update。触发 stdin 需要同时满足全部条件：无文本位置参数；add 无 --messages 且无 --file；update 无 --metadata；stdin 是管道。由此可推出三条行为：

交互终端里执行 mem0 add --user-id alice 不会挂起等待输入，而是打印用法错误；
echo "text" | mem0 add --user-id alice 会正确读取管道内容；
mem0 add "explicit text" --user-id alice 永远优先使用显式文本，即便 stdin 是管道。

# 单行管道
echo "I prefer dark mode" | mem0 add --user-id alice

# 多行内容
cat <<EOF | mem0 add --user-id alice
The user prefers dark mode in all applications.
They also like monospace fonts for code editing.
EOF

# 把另一条命令的输出直接记忆化
git log --oneline -5 | mem0 add --user-id ci-bot --metadata '{"source":"git"}'

# 搜索与更新同样支持管道
echo "preferences" | mem0 search --user-id alice
echo "Updated: prefers dark mode AND high contrast" | mem0 update abc-123-def-456

9.2 JSON 输出 + jq

-o json 给出的是"裸 JSON 数组/对象"，适合接 jq 二次加工：

# 只取记忆文本
mem0 list --user-id alice --output json | jq '.[] | .memory'

# 取记忆 ID
mem0 list --user-id alice -o json | jq '.[].id'

# 统计条数
mem0 list --user-id alice -o json | jq 'length'

# 按分类过滤
mem0 list --user-id alice -o json | jq '[.[] | select(.categories[]? == "preferences")]'

# 抽取搜索分数
mem0 search "tools" --user-id alice -o json | jq '.[] | {memory, score}'

9.3 批量操作模式

# 批量删除（先取 ID 再逐个删）
mem0 list --user-id alice -o json | jq -r '.[].id' | while read id; do
  mem0 delete "$id" --force
done

# 逐行批量添加
while IFS= read -r line; do
  mem0 add "$line" --user-id alice
done < memories.txt

# 在用户之间复制记忆
mem0 list --user-id alice -o json | jq -r '.[].memory' | while IFS= read -r mem; do
  mem0 add "$mem" --user-id bob
done

# 导出全量记忆
mem0 list --user-id alice -o json > alice_memories.json

# 遍历全部分页
page=1
while true; do
  result=$(mem0 list --user-id alice -o json --page "$page" --page-size 100)
  count=$(echo "$result" | jq 'length')
  if [ "$count" -eq 0 ]; then break; fi
  echo "$result"
  page=$((page + 1))
done

9.4 CI/CD 流水线模式

把构建/部署/测试上下文当作记忆沉淀下来，供后续 Agent 或人检索：

# 存构建上下文
mem0 add "Build #${BUILD_NUMBER} deployed ${APP_VERSION} to ${ENVIRONMENT} at $(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --agent-id "ci-bot" \
  --metadata "{\"build_number\":\"${BUILD_NUMBER}\",\"version\":\"${APP_VERSION}\",\"env\":\"${ENVIRONMENT}\"}"

# 检索部署历史
mem0 search "deployment to production" --agent-id ci-bot -o json -k 10

# 连通性自检
if mem0 status -o json | jq -e '.data.connected' > /dev/null 2>&1; then
  echo "mem0 is connected"
else
  echo "mem0 connection failed" >&2
  exit 1
fi

# 非交互初始化（CI 环境）
mem0 init --api-key "$MEM0_API_KEY" --user-id ci-bot --force

# 或者干脆只用环境变量，连 init 都省掉
export MEM0_API_KEY="$MEM0_API_KEY"
mem0 add "CI run started" --user-id ci-bot

# 存储测试结果摘要
test_summary=$(cat test-results.txt | head -20)
mem0 add "$test_summary" --agent-id ci-bot --metadata '{"type":"test-results"}' --categories "ci,testing"

9.5 Shell 错误处理与常见模式

set -e  # 出错即退出

# 状态检查失败即退出
mem0 status > /dev/null 2>&1

# 带错误分支的添加
if mem0 add "test memory" --user-id alice 2>/dev/null; then
  echo "Memory added successfully"
else
  echo "Failed to add memory" >&2
  exit 1
fi

# Agent 模式下抓取新建记忆的 ID
result=$(mem0 add "new fact" --user-id alice --agent 2>/dev/null)
memory_id=$(echo "$result" | jq -r '.data[0].id // empty')
if [ -n "$memory_id" ]; then
  echo "Created memory: $memory_id"
fi

# 先搜后加（命中则跳过）
count=$(mem0 search "dark mode" --user-id alice --agent 2>/dev/null | jq '.count // 0')
if [ "$count" -eq 0 ]; then
  mem0 add "User prefers dark mode" --user-id alice
fi

# quiet 模式静默执行
mem0 add "background note" --user-id alice --output quiet 2>/dev/null
mem0 delete --all --user-id temp-user --force --output quiet 2>/dev/null

# 用环境变量做默认作用域
export MEM0_USER_ID="alice"
export MEM0_API_KEY="m0-xxx"
mem0 add "prefers dark mode"   # 无需再写 --user-id
mem0 search "preferences"
mem0 list

关于超时：CLI 对全部 API 请求使用 30 秒超时（见 workflows.md），长脚本应自行处理超时分支。

9.6 多用户 Agent 封装脚本

面向"一个 Agent 服务多个用户"的场景，SKILL 给出一个可直接改造的 Bash 封装：

#!/bin/bash
# agent_memory.sh -- manage memories for the current conversation
USER_ID="$1"
ACTION="$2"
shift 2

case "$ACTION" in
  recall)   mem0 search "$*" --user-id "$USER_ID" --agent 2>/dev/null ;;
  remember) mem0 add "$*" --user-id "$USER_ID" --agent 2>/dev/null ;;
  forget)   mem0 delete --all --user-id "$USER_ID" --force --agent 2>/dev/null ;;
  history)  mem0 list --user-id "$USER_ID" --agent 2>/dev/null ;;
  *)
    echo '{"status":"error","error":"Unknown action: '"$ACTION"'"}' >&2
    exit 1
    ;;
esac

用法：

./agent_memory.sh alice recall "dietary preferences"
./agent_memory.sh alice remember "allergic to shellfish"
./agent_memory.sh alice history

10. 异步处理、边界情况与排错

Mem0 的记忆写入采用异步后台处理，这是新手最容易踩的坑，务必记住 SKILL 中列出的边界情况：

10.1 异步处理延迟

mem0 add 之后，记忆是异步处理的。立即搜索刚写入的内容可能查不到，建议等待 2~3 秒再查：

mem0 add "new preference" --user-id alice
sleep 3
mem0 search "new preference" --user-id alice

更严谨的做法是用事件系统轮询完成状态：

# add 后在 Agent 输出里抓 event_id
result=$(mem0 add "new preference" --user-id alice --agent 2>/dev/null)
event_id=$(echo "$result" | jq -r '.data[0].event_id // empty')

if [ -n "$event_id" ]; then
  while true; do
    status=$(mem0 event status "$event_id" --agent 2>/dev/null | jq -r '.data.status')
    if [ "$status" = "SUCCEEDED" ] || [ "$status" = "FAILED" ]; then
      break
    fi
    sleep 1
  done
fi

想整体观察后台处理进度可随时 mem0 event list。

10.2 `--all` 与 `--entity` 删除模式的区别

mem0 delete --all -u alice：删除用户 alice 的全部记忆，保留实体；
mem0 delete --entity -u alice：把实体 alice 本身及其全部记忆一并级联删除。

二者互斥（详见第 5.5 节三种模式）。

10.3 实体 ID 解析陷阱

一旦显式传了任一作用域 flag（如 --user-id），CLI 只使用显式 ID，忽略配置文件里的其余默认 ID；反之，一个 flag 都不传时，全部配置默认值一起生效（详见第 6.1 节）。

10.4 stdin 检测陷阱

交互终端中不带文本直接 mem0 add -u alice 不会挂起，而是直接报用法错误；只有管道重定向输入才会触发 stdin 读取（详见第 9.1 节）。

10.5 认证失败与超时

错误信封中会直接给出可操作的诊断信息，例如 Authentication failed. Your API key may be invalid or expired.——此时应检查 MEM0_API_KEY/--api-key/配置文件三者中实际生效的优先级（第 4.3 节），并用 mem0 config show 查看当前配置（Key 已脱敏）。

11. 深入验证路径

若想进一步核对上述行为，可在仓库内沿以下路径继续：

命令全参考：skills/mem0-cli/references/command-reference.md（全部命令、flag、选项矩阵、输出模式矩阵、Agent 信封字段表、过滤构建规则）；
配置全参考：skills/mem0-cli/references/configuration.md（配置文件 Schema、init 向导各流程、环境变量表、脱敏规则、点号键映射）；
工作流配方：skills/mem0-cli/references/workflows.md（stdin 细节、批量、CI/CD、多用户脚本、异步延迟处理）；
CLI 技能定义：skills/mem0-cli/SKILL.md；
Python 实现：cli/python/src/mem0_cli/commands、cli/python/src/mem0_cli/config.py；
Node 实现：cli/node/src；
双实现统一规格：cli/cli-spec.json（API 端点、配置默认、品牌与帮助文本等）；
Python CLI 测试：cli/python/tests（含双实现对齐测试 test_option_parity.py）；
Node CLI 测试：cli/node/tests。