mem0 Python CLI 实战指南：从 mem0-cli 安装配置到记忆管理与 Agent 模式

本文基于 mem0 官方 Python CLI 的文档 cli/python/README.md 展开，系统讲解 mem0-cli 的安装方式、配置体系与优先级规则、全部命令（init / add / search / list / get / update / delete / import / config / entity / event / status）的完整参数用法，并结合仓库源码剖析 Agent 模式的 JSON 信封实现与数据净化机制。读完本文，你可以在终端或 CI/CD 中完成记忆的增删改查，并能让 AI Agent 以结构化 JSON 输出安全地驱动整套工作流。

安装与运行前提

mem0-cli 是 mem0（AI Agent 的记忆层）的官方命令行工具，Python 实现要求 Python 3.10 及以上。这一约束在 pyproject.toml 中以 requires-python = ">=3.10" 声明，同时列出了三个核心运行时依赖：typer>=0.9.0（命令框架）、rich>=13.0.0（终端美化渲染）、httpx>=0.24.0（HTTP 客户端）。

使用 pipx 安装（推荐）

pipx install mem0-cli

使用 pip 安装

pip install mem0-cli

注意：在 macOS 上使用 Homebrew 安装的 Python 时，在虚拟环境之外执行 pip install 会因 PEP 668 的 externally-managed-environment 机制而失败。此时应改用 pipx，或在虚拟环境中安装。

安装后得到的可执行入口是 mem0，它由 pyproject.toml 中的 [project.scripts] 段落注册：mem0 = "mem0_cli.app:main"，最终指向 app.py 中的 Typer 应用入口。

配置体系：文件、环境变量与优先级

理解 CLI 的配置行为是正确使用的关键。config.py 的模块 docstring 明确给出了配置优先级（从高到低）：

1. CLI 命令行标志（--api-key、--base-url 等）
2. 环境变量（MEM0_API_KEY 等）
3. 配置文件（~/.mem0/config.json）
4. 内置默认值

从源码可以看到几个值得注意的实现细节：

• 配置路径：CONFIG_DIR = ~/.mem0，CONFIG_FILE = ~/.mem0/config.json，默认 API 地址为 https://api.mem0.ai，配置文件带版本号 CONFIG_VERSION = 1，为未来格式演进留了余地。
• 安全权限：ensure_config_dir() 创建目录时会执行 os.chmod(CONFIG_DIR, stat.S_IRWXU)（即 0700，仅属主可读写执行）；save_config() 写入配置后会把文件权限设为 0600（仅属主可读写），因为文件中保存着 API 密钥等敏感信息。
• 结构化的配置模型：配置被组织为四个 dataclass——PlatformConfig（API key、base_url、用户邮箱等）、DefaultsConfig（user_id / agent_id / app_id / run_id 四个作用域默认值）、TelemetryConfig、AgentRushConfig，统一封装在 Mem0Config 中。
• 密钥同步：save_config() 在写入 config.json 后，会尽力调用 plugin_sync.py 的 sync_api_key()，把当前密钥同步到插件生态的注入点；这是"尽力而为"操作，任何 IO 错误都会被吞掉，config.json 始终是唯一权威来源。

README 声明的优先级顺序（环境变量 > 配置文件 > 默认值）正是 load_config() 函数的实现逻辑：先读文件，再逐项用 MEM0_API_KEY、MEM0_BASE_URL 等环境变量覆盖。

快速上手

首次使用通过 mem0 init 完成初始化：

# 交互式设置向导
mem0 init

# 或通过邮箱登录
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

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

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

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

命令详解

mem0 init：交互式设置向导

提示输入 API key 与默认用户 ID，检测到已有配置时会先请求确认。

mem0 init
mem0 init --api-key m0-xxx --user-id alice
mem0 init --email [e-mail]

在 CI/CD 等无交互场景中用 --force 跳过确认提示：

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

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

mem0 add：添加记忆

支持四种输入来源：直接文本、JSON 消息数组、文件、stdin。

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

源码中 add 命令还支持作用域解析的通用逻辑：app.py 中的 _resolve_ids() 会按"显式传入 > 配置默认值"的顺序为 user_id / agent_id / app_id / run_id 解析最终作用域，这与配置优先级体系是一致的。

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	启用重排序（仅 Platform 支持）
--keyword	使用关键词搜索而非语义搜索
--filter	高级过滤表达式（JSON）
--graph / --no-graph	启用或禁用搜索中的图记忆
-o, --output	输出格式：text、json、table

--threshold 的默认值 0.3 与 --rerank 的 "Platform only" 限制都可以从 app.py 中的 Typer 选项定义得到印证（threshold: float = typer.Option(0.3, "--threshold", ...)）。

mem0 list：列出记忆

支持过滤与分页：

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	创建日期之后（YYYY-MM-DD）
--before	创建日期之前（YYYY-MM-DD）
-o, --output	输出格式：text、json、table

mem0 get / mem0 update

mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789
mem0 get 7b3c1a2e-4d5f-6789-abcd-ef0123456789 --output json

mem0 update <memory-id> "Updated preference text"
mem0 update <memory-id> --metadata '{"priority": "high"}'
echo "new text" | mem0 update <memory-id>

update 支持更新记忆文本、元数据，也可以从 stdin 读取新文本。

mem0 delete：单条、批量与级联删除

delete 是危险等级最高的命令，因此实现了三层防护语义。从 app.py 的参数定义可以看到互斥校验：memory ID、--all、--entity 三者只能使用其一，否则报错 "Only one of memory ID, --all, or --entity may be used at a time."。

# 删除单条记忆
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	跳过确认提示

mem0 import：批量导入

从 JSON 文件批量导入记忆：

mem0 import data.json --user-id alice

文件应为 JSON 数组，每项包含 memory（或 text 或 content）字段，以及可选的 user_id、agent_id、metadata 字段。

mem0 config：查看与修改本地配置

mem0 config show              # 显示当前配置（密钥自动打码）
mem0 config get api_key       # 获取单个值
mem0 config set user_id bob   # 设置值

config show 会对密钥做脱敏显示，对应 config.py 中的 redact_key()（形如 m0-xxx...xxx，未设置时显示 (not set)）。

mem0 entity：实体管理

列出或删除实体（users、agents、apps、runs）：

mem0 entity list users
mem0 entity list agents --output json
mem0 entity delete --user-id alice --force

mem0 event：后台事件查询

查看异步操作（如批量删除、大批量 add 任务）产生的后台处理事件：

mem0 event list
mem0 event status <event-id>

标志	说明
-o, --output	输出格式：text、json

mem0 status：连接验证

mem0 status

验证 API 连接并显示当前项目信息。

Agent 模式：为 AI Agent 设计的结构化输出

mem0-cli 的定位是 "Built for AI agents"：在任意命令上附加全局标志 --agent（或别名 --json），即可得到专为程序化消费设计的 JSON 输出——字段经过净化、无颜色和 spinner、错误也以 JSON 形式输出。

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

每个命令返回统一形状的信封：

{
  "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"] }
  ]
}

与 --output json 的区别（源码级解析）

Agent 模式并非简单地输出原始 JSON，output.py 中的实现揭示了三个关键差异：

1. 数据净化（sanitization）：sanitize_agent_data() 按命令白名单式地投影字段。例如 search 只保留 id, memory, score, created_at, categories, expiration_date；add 在异步任务处于 PENDING 状态时只返回 status 和 event_id，否则返回 id, memory, event。这样 Agent 拿到的只有它需要的字段，没有内部 API 噪音。
2. 零人类输出：format_agent_envelope() 直接 console.print_json()，spinner、颜色、banner 全部被抑制。
3. 错误即 JSON：失败时向 stdout 输出 {"status": "error", "command": "...", "error": "..."} 并以非零退出码结束，Agent 无需解析 stderr 文本即可感知失败。

此外，信封中还可能携带 mem0_notice 字段：当平台判定当前密钥属于"未认领的 Agent Mode 账号"时，会把提示信息放入 JSON 信封内，让消费输出的 Agent 无需检查 HTTP 响应头即可看到。

命令自发现

mem0 help --json

返回完整命令树的 JSON 结构，便于需要自我发现能力的 Agent 直接读取可用命令与参数说明。app.py 内部为每条命令维护了对应的参数描述字典（如 delete 各标志的说明），help --json 正是基于这些元数据组装输出。

输出格式总览

通过 --output 控制结果展示方式：

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

text / table / json 等渲染逻辑集中在 output.py：format_memories_text() 输出编号列表加 ID/Score/日期/类别摘要行，format_memories_table() 使用 rich Table 渲染带边框的表格，长文本截断为 57 字符加省略号。

全局标志

以下标志在所有命令上可用：

标志	说明
--json	启用 Agent 模式：结构化 JSON 信封输出，无颜色与 spinner
--agent	--json 的别名
--api-key	本次请求覆盖已配置的 API key
--base-url	本次请求覆盖已配置的 API base URL
-o, --output	设置输出格式

mem0 --version 打印 CLI 版本，且只能在子命令之前使用。从 app.py 的 main_callback 可以看到：--json/--agent 是挂在根回调上的 Typer Option，命中后调用 set_agent_mode(True)（状态定义在 state.py），从而在整条命令执行链路上生效。

环境变量

变量	说明
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）

优先级规则：环境变量 > 配置文件 > 默认值。config.py 的 load_config() 中，MEM0_API_KEY、MEM0_BASE_URL、MEM0_USER_ID、MEM0_AGENT_ID、MEM0_APP_ID、MEM0_RUN_ID 六个变量在文件加载后被逐一读取并覆盖对应字段，这一实现与上表完全对应。

开发、测试与发布

本地开发

cd cli/python
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# 开发期间运行
python -m mem0_cli --help
mem0 add "test memory" --user-id alice

[dev] 可选依赖包含 pytest、pytest-asyncio 与 ruff（见 pyproject.toml）。仓库配套了完整的测试套件，例如 tests/test_agent_mode.py 专门覆盖 Agent 模式的信封输出行为，tests/test_config.py 覆盖配置加载与优先级，tests/test_option_parity.py 则校验命令行选项与文档的一致性，可作为验证各标志行为的参考。

发布流程

1. 更新 pyproject.toml 中的 version（当前仓库中的版本为 0.2.12）；
2. 创建带 tag cli-v<version> 的 Release（如 cli-v0.2.1）。

预发布版本使用 beta 版本号（如 0.2.1b1）并勾选 pre-release 选项。

小结

mem0-cli（Python）以极小的依赖面（typer + rich + httpx）提供了一套完整的记忆管理命令行：init 建立身份与默认作用域，add / search / list / get / update / delete / import 覆盖记忆全生命周期，config / entity / event / status 提供运维配套能力。其两个核心设计值得借鉴：一是明确的四级配置优先级加 0600/0700 安全文件权限，让密钥管理在终端环境里既方便又安全；二是 --agent/--json 模式通过字段白名单净化、统一信封结构与"错误即 JSON"的约定，使 CLI 的输出对 AI Agent 的工具循环天然友好。相关实现可进一步阅读 app.py、config.py 与 output.py，跨端行为规范可参考 CLI 规范文档。