新增记忆

前置条件

• 已创建 Project，并获得服务端可用的 API Key。
• 已创建 Session，且 Session 绑定到正确的用户标识。
• 已决定哪些信息可以长期保存，哪些只应留在当前请求或业务系统中。
• 如果 Message 来自图片或 video，已经由上游系统转成文本描述、转写、摘要或 metadata。

写入会话 Message

一次请求可以写入一条或多条 Message。Message 至少需要包含 role 和 content。

JavaScript

await session.addMessages([
  {
    role: "user",
    content: "我下周三要去上海出差，请帮我记住。",
    metadata: {
      source: "chat"
    },
    timestamp: "2026-04-24T10:30:00Z"
  }
]);

Python

session.add_messages([
    {
        "role": "user",
        "content": "我下周三要去上海出差，请帮我记住。",
        "metadata": {},
        "timestamp": "2026-04-24T10:30:00Z",
    }
])

cURL

curl -X POST "http://localhost:8000/api/sessions/session_xxx/messages" \
  -H "Authorization: Api-Key your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "我下周三要去上海出差，请帮我记住。",
        "metadata": {
          "source": "chat"
        },
        "timestamp": "2026-04-24T10:30:00Z"
      }
    ]
  }'

字段说明

字段	必填	说明
messages[].role	是	消息角色，例如 user、assistant、system。
messages[].content	是	原始文本内容。GUMem 会从这里抽取 Facts。
messages[].metadata	否	业务元数据，例如来源、页面、附件引用、业务对象 ID。
messages[].timestamp	否	Message 发生时间。建议使用 ISO 8601 格式。
messages[].id	否	调用方提供的 Message ID。不传时由服务端生成。
sync	否	是否同步等待后续 Memory 处理完成。默认异步返回，适合在线对话写入；需要立即验证处理结果时设为 true。

Session 已经绑定用户身份时，不应在写入请求中临时覆盖用户归属。Memory 的归属边界应由 Session、Project 和服务端身份系统决定。

写入参数配置

下一步

阅读 查询记忆 了解如何召回刚写入的 Memory。