新增记忆

不要直接把 Summary 当作调用方需要手写的数据。更稳妥的做法是写入有来源、有时间、有业务上下文的 Message，让 GUMem 负责后续加工。

前置条件

• 已创建 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": {
            "source": "chat"
        },
        "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。不传时由服务端生成。

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

写入后发生什么

写入成功后，GUMem 会按配置执行后续处理：

1. 保存原始 Message。
2. 从 Message 中抽取 Facts，并保留来源 Message、时间范围、实体和标签。
3. 如果启用长期记忆写入，把 Facts 生成 Summary。
4. 将 Summary 归入 Topic，并更新 Topic 摘要。
5. 把 Facts、Summary 和 Topic 写入检索索引，供 Query Memory 使用。

如果长期写入被关闭，GUMem 只生成 Facts，不继续生成 Summary 和 Topic。

适合写入的内容

• 用户明确表达的长期偏好、约束、身份信息或目标。
• 会影响未来推荐、工具调用、风险判断或回复方式的信息。
• 有审计价值的行为结果，例如搜索、筛选、收藏、跳过、工具调用完成结果。
• 图片或 video 经过上游处理后的文本描述、转写、摘要或关键 metadata。

不适合写入的内容

• 只对当前请求有效的临时状态。
• 没有证据支撑的模型推断。
• 应由业务数据库保存的强一致数据，例如订单状态、权限、账单、库存。
• 没有治理策略的敏感信息。

检查结果

新增 Message 后，可以通过 Query Memory 验证相关信息是否进入召回上下文。刚写入的 Message 可能先进入近期上下文，长期 Summary 和 Topic 需要等待后续处理完成。

下一步

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