MindMemOS CLI 使用说明

August 18, 2026 · View on GitHub

1. 简介

mindmemos 是随 MindMemOS Python SDK（mindmemos_sdk）一起发布的命令行工具，用于在终端中直接操作记忆服务：写入与检索记忆、管理 SDK 注册的 Skill、检查本地配置与连通性。

它是 SDK 的薄封装：所有命令都读取本地配置文件（~/.mindmemos/settings.json），通过 HTTP 调用 mindmemos 服务，因此使用时无需手动拼接请求、也不需要在命令中重复填写服务地址。

2. 安装

pip install mindmemos-sdk

安装后确认命令可用：

mindmemos --help

命令通过 project.scripts 暴露为全局可用的 mindmemos 可执行文件。

3. 快速上手

3.1 配置认证

首次使用前，运行 mindmemos auth 配置服务地址、API key 与默认用户：

mindmemos auth

交互式依次输入三项配置：

配置项	本地自部署服务	官方云服务
`Base URL`	`http://127.0.0.1:8000`	`https://mindmemos.cn`
`API key`	`config/mindmemos/api_keys.yaml` 中已启用的 key	从官网申请的 key
`User id`	当前用户的稳定标识，例如 `u_123`	当前用户的稳定标识，例如 `u_123`

也可以一次性传入参数跳过交互：

mindmemos auth --base-url http://127.0.0.1:8000 --api-key dev-api-key-001 --user-id u_123

配置保存到 ~/.mindmemos/settings.json。本地服务会根据 API key 自动确定 project_id，无需在命令中指定。

3.2 检查配置与连通性

# 查看当前配置（API key 默认打码）
mindmemos config show

# 完整显示 API key
mindmemos config show --show-secret

# 检查配置是否有效、服务是否连通
mindmemos doctor

3.3 写入一条记忆

mindmemos memory add --content "我喜欢喝冰美式。"

3.4 检索记忆

mindmemos memory search "用户喜欢喝什么咖啡？" --top-k 5

写入、检索的更多参数见下文「记忆命令」；CLI 仅做调用与结果展示，记忆的完整提取、打分、存储逻辑由服务端完成。

4. 命令总览

mindmemos
├── auth                  交互式配置 API key、用户与服务地址
├── config                查看 / 重置本地配置
│   ├── show
│   └── reset
├── memory                记忆相关操作
│   ├── add               写入一条对话消息作为记忆
│   ├── search            检索记忆
│   ├── get               列出 / 过滤当前项目下的记忆
│   ├── update            更新指定记忆内容
│   ├── delete            删除指定记忆
│   ├── feedback          提交显式 / 隐式反馈
│   └── dreaming          触发记忆演进管线
├── skill                 管理 SDK 注册的 Skill
│   ├── register          注册并上传本地 Skill
│   ├── list              列出已注册 Skill
│   ├── show              查看单个 Skill
│   ├── evolve            触发云端 Skill 演进
│   ├── push              上传本地改动为新版本
│   ├── pull              拉取版本元数据（不改动文件）
│   ├── update            更新一个或全部 Skill
│   ├── rollback          回滚到指定版本
│   ├── history           查看版本历史
│   ├── diff              查看版本差异
│   └── unregister        移除注册（可同时删除文件）
└── doctor                检查 SDK 配置与连通性

每个命令都支持 --help 查看完整参数说明：

mindmemos memory add --help

5. 记忆命令（`mindmemos memory`）

记忆命令使用 mindmemos auth 配置好的凭据，无需重复输入。

5.1 写入记忆 `add`

最常用的方式是传入单条消息内容：

mindmemos memory add --content "我喜欢喝冰美式。"

指定消息角色（默认 user）：

mindmemos memory add --content "记住这个偏好" --role system

多轮消息以 JSON 传入（此时 --content / --role 被忽略）。可内联或从文件读取：

# 内联 JSON
mindmemos memory add --messages-json \
  '[{"role":"user","content":"我喜欢喝冰美式。"},{"role":"assistant","content":"好的，记住了。"}]'

# 从文件读取
mindmemos memory add --messages-json-file ./messages.json

异步模式（立即返回 request_id，不等待提取完成）：

mindmemos memory add --content "我喜欢喝冰美式。" --async

其他可选参数：

参数	说明
`--user-id`	覆盖配置中的默认用户
`--app-id` / `--agent-id` / `--session-id`	上下文标识，供细分与过滤使用
`--metadata-json`	业务元数据（JSON 对象）
`--skill-context-json`	Skill 上下文数组，覆盖 SDK 自动检测
`--json`	以机器可读 JSON 输出完整结果

示例输出：

Added 1 memory item(s):
- [did] m_8f3a: 我喜欢喝冰美式。

5.2 检索记忆 `search`

mindmemos memory search "用户喜欢喝什么咖啡？" --top-k 5

常用参数：

参数	说明
`--top-k`	返回结果条数，默认 `10`
`--search-strategy`	检索策略，`fast`（默认）或 `agentic`
`--rerank`	开启重排
`--score-threshold`	重排相关度阈值（0-1），需配合 `--rerank`
`--filter`	过滤 DSL（JSON 对象字符串）
`--user-id` 等	覆盖请求上下文
`--json`	以 JSON 输出完整结果

5.3 列出与过滤 `get`

列出当前项目下的记忆，可选过滤：

# 列出最近 20 条
mindmemos memory get --top-k 20

# 按过滤 DSL 过滤
mindmemos memory get --filter '{"field":"value"}'

5.4 更新与删除

# 更新指定记忆的内容
mindmemos memory update <memory_id> --content "新内容"

# 删除指定记忆（-y 跳过二次确认）
mindmemos memory delete <memory_id> --yes

5.5 反馈 `feedback`

默认运行隐式反馈，由服务端分析近期写入并生成反馈；也可通过 --text 提交显式反馈：

# 隐式反馈
mindmemos memory feedback

# 显式反馈，需同时给出产生该反馈的消息
mindmemos memory feedback --text "这条记忆不正确" \
  --messages-json '[{"role":"user","content":"..."}]'

5.6 记忆演进 `dreaming`

触发记忆演进（dreaming）管线，选择同步或异步：

# 异步排队（默认）
mindmemos memory dreaming --async

# 同步等待完成
mindmemos memory dreaming --sync

6. Skill 命令（`mindmemos skill`）

mindmemos skill 管理已在 SDK 注册、可由云端演进（evolve）的本地 Skill。

注册一个本地 Skill（路径可为目录或 SKILL.md 文件）：

mindmemos skill register ./my-skill
# 指定别名，便于后续命令使用
mindmemos skill register ./my-skill --alias my-skill

常用操作：

# 列出 / 查看已注册 Skill
mindmemos skill list
mindmemos skill show <skill-id-or-alias>

# 触发云端演进（默认同步，--async 改为排队）
mindmemos skill evolve <skill-id-or-alias> --sync

# 推送本地改动为新版本；拉取版本元数据
mindmemos skill push <skill-id-or-alias>
mindmemos skill pull <skill-id-or-alias>

# 更新一个或全部 Skill（--all 更新全部，-y 跳过确认）
mindmemos skill update <skill-id-or-alias> --yes
mindmemos skill update --all --yes

# 撤销注册（--delete-files 同时删除本地文件）
mindmemos skill unregister <skill-id-or-alias> --delete-files --yes

版本管理：

# 查看版本历史
mindmemos skill history <skill-id-or-alias>

# 回滚到指定版本
mindmemos skill rollback <skill-id-or-alias> --to <version-id> --yes

# 查看两个版本间的差异
mindmemos skill diff <skill-id-or-alias> --from <version-id> --to <version-id>

在提交 update / rollback 等可能改动本地文件的操作前，命令会先展示变更计划并请求确认。

7. 配置管理（`mindmemos config`）

# 查看当前配置
mindmemos config show
mindmemos config show --show-secret   # 显示完整 API key

# 重置并删除本地配置
mindmemos config reset
mindmemos config reset --yes          # 跳过确认

配置文件位于 ~/.mindmemos/settings.json，也可通过环境变量 MINDMEMOS_CONFIG_DIR 指定其他配置目录。

API key 属于敏感信息，默认在 config show 中打码显示（config show --show-secret 才会完整展示）。

8. 故障排查

现象	可能原因与处理
No SDK config at … Run `mindmemos auth` first.	尚未配置认证，先运行 `mindmemos auth`
No api_key configured	API key 缺失，重新运行 `mindmemos auth`
transport: not ready …	`doctor` 检测到服务不可达。确认服务已启动，且 `base_url` 正确：本地自部署为 `http://127.0.0.1:8000`，云端为 `https://mindmemos.cn`
服务返回认证错误	API key 无效或未启用，核对云端的 key 或 `config/mindmemos/api_keys.yaml` 中的本地 key
插件环境报 `ENOENT`	GUI 启动的进程不继承终端 PATH，`mindmemos` 需显式配置绝对路径或用 `uv run mindmemos` 包装，详见 OpenClaw 插件集成

可随时运行 mindmemos doctor 一键检查配置与连通性。