memos-cloud-server

MemOS Cloud Server 技能

此技能允许 Agent 与 MemOS Cloud API 交互，以进行记忆搜索、添加、删除、知识库管理和反馈。

⚠️ 设置与安全规则（必须阅读）

执行任何 API 操作前，请确保已配置以下环境变量。每个变量都有一个归属层级——负责设置该变量的一方——这决定了是否可以在调用时覆盖该变量。

变量	必填	归属层级	可在每次调用时覆盖？	备注
MEMOS_API_KEY	是	用户 / 部署密钥	否	身份验证令牌。绝不可向大模型泄露。
MEMOS_USER_ID	是	用户 / 宿主平台	否	必须具有确定性（经过哈希处理的电子邮件、员工 ID）。不要使用随机 ID 或每个会话独有的 ID。
MEMOS_CLOUD_URL	否	部署	否	API 基础 URL。默认值：https://memos.memtensor.cn/api/openmem/v1。
MEMOS_AGENT_ID	否	宿主平台（按进程注入）	是——通过 add_message / add_feedback 上的 --agent-id 传入	隔离各 Agent 的记忆。单个全局环境变量仅支持每台设备使用一个 Agent；若要在同一设备上运行多个 Agent，可由宿主平台按进程注入此变量，或在每次调用时传入 --agent-id。
MEMOS_APP_ID	否	宿主平台	是——通过 add_message / add_feedback 上的 --app-id 传入	隔离各应用的记忆。与 MEMOS_AGENT_ID 存在相同的多租户注意事项。
MEMOS_ALLOW_PUBLIC	否	管理员 / 安全策略	否	true/false，默认值为 false。这是安全边界——绝不要让大模型在每次调用时切换此设置。
MEMOS_ASYNC_MODE	否	部署	否	true/false，默认值为 true。决定 add_message 是否会在处理完成前返回。

多 Agent 隔离模式：优先由宿主平台按进程注入环境变量（每个 Agent 都有独立的进程树和不同的 MEMOS_AGENT_ID）。如果平台无法注入环境变量，则改为在每次调用时传入 --agent-id / --app-id——CLI 标志的优先级高于环境变量。这些值必须由编排器 / 平台提供；大模型不得自行编造。

如果缺少必需变量，请提示用户在重试前进行配置（全局配置或按进程配置）。

⚠️ 强制工作流（必须遵循）

始终启用（无需用户主动选择）

此系统会在每轮对话中自动运行。不要等待用户说“使用记忆”“搜索记忆”或“记住这个”。Agent 负责自动调用这些工具。

每轮对话：3 步工作流（自动调用）

Every user message (including greetings, simple questions, ANYTHING)
  → 1) search_memory (AUTO, BEFORE answering — even for simple questions)
  → 2) Answer (use only relevant memories; ignore noise)
  → 3) add_message (AUTO, AFTER answering — save conversation history)

身份与偏好查询（必须执行）

当用户询问有关自身的问题时，同时调用 search_memory 和 get_user_profile：

• “我喜欢什么？”
• “我是谁？”
• “你对我了解什么？”
• “我有什么偏好？”
• 任何有关用户身份、习惯或偏好的问题（不限语言）

工具选择规则（严格遵循）

用户意图	正确工具	错误工具
任何问题（回答前自动调用）	search_memory	-
身份 / 偏好查询（“我喜欢什么？”）	search_memory + get_user_profile	-
新信息 / 记住某件事	add_message	不要使用 add_feedback
修改 / 更正现有记忆	add_feedback	不要使用 add_message
删除记忆（未指定 ID）	search → delete → add_feedback	不要使用 add_message
删除记忆（已指定 ID）	直接调用 delete	-

修改工作流

当用户想要修改一条记忆时：

1. 使用自然语言中的更正内容调用 add_feedback
2. 示例：feedback_content = "User prefers dark mode, not light mode"
3. 禁止：不要调用 add_message 来“替换”旧记忆

删除流程（无 ID）

当用户想要删除一条记忆，但没有 ID 时：

1. search_memory — 查找相关记忆 ID
2. delete — 使用找到的 ID 删除
3. add_feedback — 确认删除意图（例如：“用户想删除关于 X 的记忆”）
4. 重要：feedback_content 必须是用户的自然语言意图，而非“ID [x, y]”之类的技术细节

删除流程（有 ID）

当用户提供了特定的记忆 ID 时：

1. delete — 直接使用这些 ID 删除

禁止的操作

• 不要使用 add_message 修改／更新已有记忆
• 不要将 add_message 用作“删除旧记忆 + 添加新记忆”的变通方法
• 不要在 feedback_content 中包含记忆 ID 或技术元数据
• 如果 add_feedback 似乎失败，不要重试（发起后不再处理）
• 默认不要传递 --agent-id／--app-id。除非满足以下任一条件，否则省略这两个标志：（a）用户在本轮明确告知要使用的 ID；或（b）系统提示／编排器上下文明确提供了 ID。绝不要编造、猜测或沿用之前轮次中的 ID。省略这些标志时，环境变量（如果已设置）会透明地生效。
• 不要尝试在调用时覆盖 MEMOS_ALLOW_PUBLIC — 这是部署方拥有的安全边界。

不应调用的情况（负面触发条件）

默认策略是“每轮都先搜索再回答”。仅在以下少数情况下跳过调用：

• 用户明确选择本轮不搜索（例如：“不要搜索记忆”“跳过记忆”“不使用记忆回答”）。
• 本轮只是纯粹的工具／系统操作，不包含语义内容（例如，用户只粘贴了一段要修复的堆栈跟踪，且没有要求个性化处理）。
• 缺少必需的环境变量（MEMOS_API_KEY、MEMOS_USER_ID）— 请先提示用户进行配置，而不是调用 API。
• 本轮先前的调用已返回所需记忆；不要针对同一查询调用两次 search_memory。

如有疑问，优先调用 — 误报代价低，遗漏上下文代价高。

---

🧵 对话 ID 策略（必须遵循）

conversation_id 用于将属于同一聊天会话的记忆归组。服务器使用它来：（a）根据会话内上下文为 search_memory 结果加权；（b）为 add_feedback 提供锚点，以便更正能够针对正确会话的记忆；（c）让 add_message 累积连贯的轮次历史。

稳定性规则：在一个聊天会话内，每次 search／add_message／add_feedback 调用都必须使用相同的 conversation_id。不同会话之间必须轮换。

如何生成（按优先级排序）

1. 宿主提供的 ID — 如果编排器／平台公开了会话 ID（环境变量、CLI 参数、框架变量），直接通过 --conversation-id 传入。这是最可靠的方式。
2. 从首条消息生成 — 如果没有可用的会话 ID，选取当前聊天会话中的第一条用户消息，并在本会话之后的每次调用中将完全相同的字符串传给 --conversation-first-message。脚本会对 user_id + first_message 进行 MD5 哈希，以确定性方式生成 ID，因此相同输入始终会得到相同 ID（参见 payloads.py::generate_conversation_id）。
3. 绝不要将本轮用户消息作为 --conversation-first-message 传入。这样会导致每轮都重新轮换 ID，并悄然破坏反馈和上下文加权。

“新对话”的含义

仅在以下情况下才应该生成新的 conversation_id：

• 宿主平台开启了新的聊天会话／清除了历史记录，或者
• 用户明确表示“新话题”“重新开始”／“我们聊点完全不同的”，且你决定舍弃之前的上下文。

不得仅仅因为以下原因生成新 ID：

• 用户在对话中途更换话题（仍属于同一会话）。
• Agent 自身的上下文窗口被截断（从逻辑上讲仍是同一会话）。
• 你忘记了之前的 ID（根据相同的首条消息重新生成 — 不要编造新的 ID）。

Agent 操作清单

• 会话开始：逐字记录会话中的第一条用户消息，将其作为会话锚点，并保存在工作笔记中。
• 本会话中的每次后续调用：对 --conversation-first-message 重用完全相同的锚点字符串（或者重用主机提供的已解析 conversation_id）。
• 反馈／更正：必须使用写入目标记忆时所用的同一个 conversation_id（或同一个锚点首条消息）。
• 检测到新聊天：丢弃旧锚点，记录新会话的第一条用户消息，然后重新开始。

---

🛠 核心命令

通过 scripts/memos_cloud.py 执行操作。该脚本会自动读取环境变量；所有请求和响应均使用 JSON。

---

1. 搜索记忆（/search/memory）

搜索与用户查询相关的长期记忆。

python3 scripts/memos_cloud.py search [user_id] "<query>" [options]

选项：

• --conversation-id <id> — 用于上下文加权的会话 ID。请参阅会话 ID 策略（必须遵循）。
• --conversation-first-message "<msg>" — 会话锚点（当前会话的第一条用户消息，本会话中的每次调用均重用此消息）。通过 MD5 派生稳定的 conversation_id。不要传入当前轮次的消息——这会导致每轮轮换 ID，破坏上下文加权。
• --filter '<json>' — JSON 字符串格式的筛选条件
• --knowledgebase-ids "<ids>" — 以逗号分隔的知识库 ID，或 "all"
• --memory-limit-number <n> — 事实记忆的最大数量（默认 9，最大 25）
• --include-preference <bool> — 启用偏好回忆（默认 true）
• --preference-limit-number <n> — 偏好记忆的最大数量（默认 9，最大 25）
• --include-tool-memory <bool> — 启用工具记忆回忆（默认 false）
• --tool-memory-limit-number <n> — 工具记忆的最大数量（默认 6，最大 25）
• --include-skill <bool> — 启用技能回忆（默认 false）
• --skill-limit-number <n> — 技能的最大数量（默认 6，最大 25）
• --relativity <float> — 相关性阈值 0-1（默认 0.45）

示例：

python3 scripts/memos_cloud.py search "$MEMOS_USER_ID" "Python related project experience"
python3 scripts/memos_cloud.py search "$MEMOS_USER_ID" "tools" --include-tool-memory true --include-skill true

---

2. 添加消息（/add/message）

存储多轮对话中的高价值内容。

python3 scripts/memos_cloud.py add_message [user_id] [conversation_id] '<messages_json>' [options]

选项：

• --conversation-first-message "<msg>" — conversation_id 位置参数的替代项。必须是会话锚点（当前会话的第一条用户消息），且本会话中的每次调用均重用此消息。请参阅会话 ID 策略（必须遵循）。每轮传入不同的字符串会悄然将对话拆分为许多单轮会话。
• --tags "<tags>" — 以逗号分隔的标签
• --info '<json>' — JSON 字符串格式的自定义元数据
• --allow-knowledgebase-ids "<ids>" — 以逗号分隔的知识库 ID，用于指定记忆写入范围
• --agent-id "<id>" — 可选覆盖 MEMOS_AGENT_ID。默认省略；仅当用户或编排器上下文明确提供该 ID 时才传入。
• --app-id "<id>" — 可选覆盖 MEMOS_APP_ID。规则与 --agent-id 相同。

agent_id / app_id 的解析顺序：CLI 标志（仅在明确提供时）> 环境变量 > 未设置。

仅限环境变量的选项（无法针对单次调用覆盖）：

• allow_public 来自 MEMOS_ALLOW_PUBLIC
• async_mode 来自 MEMOS_ASYNC_MODE

示例：

# Preferred: host-supplied conversation_id, reused for the whole session
python3 scripts/memos_cloud.py add_message "$MEMOS_USER_ID" "$SESSION_ID" '[{"role":"user","content":"I like apples"},{"role":"assistant","content":"Okay, I noted that"}]'

# Fallback: derive a stable id from the session's FIRST user message.
# Reuse the EXACT same --conversation-first-message string on every call this session
# (search / add_message / add_feedback). Do NOT substitute the current turn's message.
ANCHOR="What's the weather?"   # captured once at session start
python3 scripts/memos_cloud.py add_message "$MEMOS_USER_ID" --conversation-first-message "$ANCHOR" '[{"role":"user","content":"What's the weather?"}]'
python3 scripts/memos_cloud.py add_message "$MEMOS_USER_ID" --conversation-first-message "$ANCHOR" '[{"role":"user","content":"And tomorrow?"}]'

---

3. 删除记忆（/delete/memory）

按以逗号分隔的记忆 ID 删除已存储的记忆。

python3 scripts/memos_cloud.py delete "<memory_ids>"

示例：

python3 scripts/memos_cloud.py delete "id1,id2,id3"

---

4. 添加反馈（/add/feedback）

添加反馈，以更正或强化记忆。用于用户希望修改或删除记忆时。

python3 scripts/memos_cloud.py add_feedback [user_id] [conversation_id] "<feedback_content>" [options]

选项：

• --conversation-first-message "<msg>" — conversation_id 位置参数的替代项。必须使用写入目标记忆时所用的同一个会话锚点（否则反馈不会关联到正确的会话）。请参阅会话 ID 策略。
• --allow-knowledgebase-ids "<ids>" — 以逗号分隔的知识库 ID
• --feedback-time "<time>" — 反馈时间字符串
• --agent-id "<id>" — 可选覆盖 MEMOS_AGENT_ID。默认省略；仅在用户或编排器上下文明确提供 ID 时传入。
• --app-id "<id>" — 可选覆盖 MEMOS_APP_ID。规则与 --agent-id 相同。

agent_id / app_id 的解析顺序：CLI 标志（仅在明确提供时）> 环境变量 > 未设置。

仅限环境变量的选项（不可逐次调用覆盖）：

• allow_public，来自 MEMOS_ALLOW_PUBLIC

示例：

# Same session anchor as the add_message calls in this session:
python3 scripts/memos_cloud.py add_feedback "$MEMOS_USER_ID" --conversation-first-message "$ANCHOR" "The previous answer was not detailed enough"

# Or with an explicit id from the host:
python3 scripts/memos_cloud.py add_feedback "$MEMOS_USER_ID" "$SESSION_ID" "The previous answer was not detailed enough"

---

5. 添加知识库文档（/add/knowledgebase-file）

将文件上传到知识库。支持在线 URL、本地文件和标准输入。

python3 scripts/memos_cloud.py add_kb_doc <knowledgebase_id> <file1> [file2 ...] [--type document|skill]
python3 scripts/memos_cloud.py add_kb_doc <knowledgebase_id> --stdin [--name filename.ext] [--type document|skill]

参数：

• knowledgebase_id：目标知识库 ID。
• files：URL（https://example.com/doc.pdf）或本地文件路径（自动检测 mime_type，内容会自动转换为 base64）。
• --stdin：从标准输入读取 base64 内容。对于大型文件，建议使用此选项，以避免将文件内容加载到 Agent 上下文中。
• --name：标准输入内容的文件名（使用 --stdin 时建议提供，以便服务端推断 mime type）。
• --type：document（默认）或 skill。

---

6. 获取用户资料（/get/memory）

检索整合后的用户记忆资料——事实性记忆、偏好和工具轨迹。

python3 scripts/memos_cloud.py get_user_profile [user_id] [options]

选项：

• --page <n> — 页码（默认值为 1）
• --size <n> — 每页数量（默认值为 10，最大值为 50）
• --filter '<json>' — JSON 字符串格式的筛选条件
• --include-preference <bool> — 是否包含偏好记忆（默认值为 true）
• --include-tool-memory <bool> — 是否包含工具记忆（默认值为 false）

示例：

python3 scripts/memos_cloud.py get_user_profile "$MEMOS_USER_ID"
python3 scripts/memos_cloud.py get_user_profile "$MEMOS_USER_ID" --include-tool-memory true --page 2

---

7. 创建知识库（/create/knowledgebase）

创建一个用于存放结构化文档的命名容器。

python3 scripts/memos_cloud.py create_kb "<name>" [--description "<desc>"]

示例：

python3 scripts/memos_cloud.py create_kb "My Project KB" --description "Project documentation"

---

8. 获取知识库文档（/get/knowledgebase-file）

获取文档元数据/详情。两种互斥模式：

# By file IDs
python3 scripts/memos_cloud.py get_kb_docs --file-ids "id1,id2"

# By knowledge base ID (with optional filters)
python3 scripts/memos_cloud.py get_kb_docs --knowledgebase-id "kb-1" [--type document|skill] [--page 1] [--page-size 20]

---

9. 删除知识库文档（/delete/knowledgebase-file）

根据文件 ID 从知识库中删除指定文档。

python3 scripts/memos_cloud.py delete_kb_docs "<file_ids>"

示例：

python3 scripts/memos_cloud.py delete_kb_docs "file-id-1,file-id-2"

---

10. 移除知识库（/delete/knowledgebase）

从当前项目中移除知识库。

python3 scripts/memos_cloud.py remove_kb "<knowledgebase_id>"

示例：

python3 scripts/memos_cloud.py remove_kb "kb-123"