byted-mem0-memory-management

Files (4)

• LICENSE
• SKILL.md
• requirements.txt
• call_mem0.py · scripts/

SKILL.md (first lines)

## Skill 概览

本 Skill 用于在对话中充当 **火山引擎记忆库 Mem0 的智能运维代理**：

- **理解用户的自然语言需求**（中文或英文），在用户需要查询火山 Mem0 项目或管理其长期记忆时使用；
- **直接调用内置脚本** `scripts/call_mem0.py` 查询记忆项目、操作记忆并获取实时结果；
- 当获取到结果或用户粘贴错误信息时，**进一步解释、诊断并给出后续建议**。

**工作模式**：

- 控制面：查询记忆项目列表、项目详情和已有 API Key 信息，**仅支持读操作**；
- 数据面：支持服务探活、记忆添加、列举、搜索、读取、更新、删除及异步任务查询；
- 使用 `scripts/call_mem0.py` 脚本直接获取 Mem0 的实时响应。

自建开源 mem0 的部署配置、内部 MemoryBase 运维和日志查询不属于本 Skill 的范围。

**运行方式**：

脚本支持两种运行方式，均需要 Python 3.9+，无第三方依赖：

```bash
# 方式 1：使用 uv
uv run ./scripts/call_mem0.py [action] [options]

# 方式 2：使用 python
python3 ./scripts/call_mem0.py [action] [options]
```

以上相对路径以本 Skill 目录为基准；在其他目录执行时，使用脚本的完整路径。

## 标准使用流程

1. **确认任务类型与参数**
   - 判断用户意图：查询记忆项目列表、查看项目详情、添加记忆、搜索记忆、更新或删除记忆等。
   - 收集必要参数（如未指定则使用环境变量或默认值）：
     - `action`：操作类型，如 `list-projects`、`describe-project`、`search-memories` 等，为位置参数。
     - `--region`：地域 ID，读取 `VOLCENGINE_REGION`，默认 `cn-beijing`，支持 `cn-shanghai`。
     - `--project-id`：Mem0 记忆项目 ID，默认读取 `MEM0_PROJECT_ID`。
     - `--api-key-id`：已有 API Key ID，默认读取 `MEM0_API_KEY_ID`。
     - `--user-id`、`--agent-id`、`--run-id`：需要操作的记忆范围。
     - `--memory-id`、`--event-id`：单条记忆或异步任务的 ID，部分操作必需。

2. **构造请求并调用脚本**
   - 配置 AK/SK、地域和项目环境变量，详见“环境变量配置”。
   - 控制面使用 AK/SK 签名；数据面默认通过控制面只读接口发现项目公网地址，并读取已有 API Key 完成鉴权。自动读取的 Key 仅发送到该项目 `VisitAddrs` 中列出的 HTTPS 地址。
   - 示例（以下命令可使用 `uv run` 或 `python3` 运行）：

     ```bash
     # 查询记忆项目列表
     uv run ./scripts/call_mem0.py list-projects
     # 或
     python3 ./scripts/call_mem0.py list-projects

     # 查询已配置项目的详情
     uv run ./scripts/call_mem0.py describe-project

     # 检查数据面连接和 API Key
     uv run ./scripts/call_mem0.py ping

     # 搜索指定用户的记忆
     uv run ./scripts/call_mem0.py search-memories \
       --user-id user-001 --query '用户喜欢喝什么？' --top-k 5
     ```

3. **解析结果并后续处理**
   - 将 Mem0 的响应用自然语言解释给用户；列表查询默认只返回一页，按需继续分页。
   - 异步添加返回 `event_id` 表示任务已接收，需调用 `get-event` 检查状态和 `error`，完成后再读取记忆。可每隔数秒查询并设置有限等待时长；超时保留事件 ID，不重复提交添加。
   - 更新或删除记忆前，明确目标项目与记忆 ID 或用户、智能体、运行范围。用户明确要求清空指定范围时，才使用 `delete-memories --confirm`。
   - API Key 值始终脱敏，不在对话中打印凭证明文。控制面不提供创建、修改或删除项目、API Key 的能力。

## 工具脚本使用说明

### 支持的操作（Actions）

下表中的项目 ID、API Key ID 可通过参数或环境变量提供。数据面默认需要项目 ID 来自动发现连接；也可直接配置数据面地址和 API Key。

| 操作 | 类型 | 说明 | 必需参数 |
|------|------|------|----------|
| `list-projects` | 控制面只读 | 查询记忆项目列表 | 无 |
| `describe-project` | 控制面只读 | 查询项目详情、提取策略、连接地址和 API Key ID | `--project-id` |
| `describe-api-key` | 控制面只读 | 查询已有 API Key 详情，值脱敏 | `--project-id`、`--api-key-id` |
| `ping` | 数据面 | 服务探活与权限校验 | 无额外参数 |
| `list-memories` | 数据面 | 列举指定范围的记忆 | `--user-id`、`--agent-id`、`--run-id` 至少一个 |
| `add-memories` | 数据面 | 添加记忆或提交异步提取任务 | 范围参数至少一个；`--text` 或 `--messages` |
| `search-memories` | 数据面 | 搜索相关记忆 | `--query` |
| `get-memory` | 数据面 | 读取单条记忆 | `--memory-id` |
| `update-memory` | 数据面 | 更新单条记忆 | `--memory-id`、`--text` |
| `delete-memory` | 数据面 | 删除单条记忆 | `--memory-id` |
| `delete-memories` | 数据面 | 删除指定范围的全部记忆 | 范围参数至少一个，且指定 `--confirm` |
| `get-event` | 数据面 | 查询异步任务状态和结果 | `--event-id` |

### 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `action` | 操作类型（必需，为位置参数） | 无 |
| `--region` / `-r` | 火山引擎地域 ID | `VOLCENGINE_REGION`，未设置时为 `cn-beijing` |
| `--project-id` | Mem0 记忆项目 ID | `MEM0_PROJECT_ID` |
| `--api-key-id` | 已有 API Key ID | `MEM0_API_KEY_ID`；自动发现时可选择唯一 `Ready` 的 Key |
| `--data-endpoint` | 数据面 HTTPS 地址，不含路径；自动读取 Key 时须匹配项目 `VisitAddrs` | `MEM0_ENDPOINT`，未设置时从项目详情发现 |
| `--env-file` | 读取凭证字面量赋值的文件 | 无 |
| `--timeout` | 单次请求超时，单位秒 | `60` |
| `--output` / `-o` | 另存脱敏 JSON 响应文件 | 无，结果始终输出到 stdout |
| `--page-number` / `--page-size` | 项目列表页码 / 每页条数，每页 1～1000 条 | `1` / `10` |
| `--all-pages` | 查询项目列表当前页及后续全部页 | 关闭 |
| `--memory-project-name` | 按记忆项目名称精确匹配，自动从第一页遍历 | 无 |
| `--resource-project` | 按火山资源项目名称 `ProjectName` 筛选 | 无 |
| `--tag-filters` | 项目标签筛选 JSON 数组，最多 10 组 | 无 |
| `--user-id` / `--agent-id` / `--run-id` | 记忆所属用户、智能体或运行 ID | 无 |
| `--page` | 记忆列表页码，从 1 开始 | `1` |
| `--memory-id` / `--event-id` | 单条记忆 ID / 异步事件 ID | 无 |
| `--text` / `--messages` | 添加时的文本 / 对话消息 JSON 数组，二选一；更新使用 `--text` | 无 |
| `--metadata` | 添加时附加的元数据 JSON 对象 | 无 |
| `--infer` / `--no-infer` | 是否通过模型提取记忆 | 开启 |
| `--async-mode` / `--no-async-mode` | 是否异步处理添加请求 | 开启 |
| `--query` / `--top-k` | 搜索文本 / 返回条数，条数范围 1～1000 | 无 / 使用服务端默认值 |
| `--filters` | 搜索过滤条件 JSON 对象 | 无 |
| `--confirm` | 确认删除指定范围的全部记忆 | 关闭 |

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples