Agent Memory

Agent Memory 允许第三方应用将用户活动事件上报到 SecondMe。当你的应用观察到用户在外部平台的行为（发帖、回帖、执行操作）时，可以发送结构化事件，让 SecondMe 分身构建更丰富的用户记忆。

用户会在动态时间线中看到这些事件 — 每个事件展示 actionLabel（动作标签）、displayText（摘要文本）、importance（重要程度）以及一个跳转回原始内容的链接。请围绕这些展示要素来设计你的事件。

Base URL: https://api.mindverse.com/gate/lab

上报记忆事件

上报一条 Agent 记忆事件。

POST /api/secondme/agent_memory/ingest

参数	类型	必需	说明
channel	ChannelInfo	是	事件来源渠道
action	string	是	描述发生了什么的动作标识。开放字符串 — 使用简短、有描述性的名称，如 `post_created`、`reply`、`liked`、`endorsed`、`notification_received` 等
refs	RefItem[]	是	证据引用（至少 1 项）
display_text	string	强烈建议	用户可读的摘要文本，显示在动态时间线中。强烈建议提供 — 如果省略，服务端会尝试自动生成
action_label	string	建议	人类可读的动作标签（如 "回复了帖子"、"发现了匹配"），与事件一起展示
importance	number	建议	重要性评分，范围 0.0-1.0。`importance >= 0.7` 的事件会被标记为"重要"。详见重要性等级
payload	Payload	建议	扩展数据，详见下方说明
event_time	integer	否	事件时间戳（毫秒），默认使用服务器时间
event_desc	string	否	开发者描述（不展示给用户）
idempotency_key	string	否	自定义幂等键，用于去重。详见幂等性

ChannelInfo

描述事件发生的来源渠道。

字段	类型	必需	说明
kind	string	是	资源类型标识（如 `thread`、`post`、`comment`、`channel`、`document`）
id	string	建议	来源平台上的渠道对象 ID（如帖子 ID、频道 ID）
url	string	建议	渠道或资源的直接链接
platform	string	否	由 OAuth 应用的 Client ID 自动填充，请勿手动设置
meta	object	否	附加渠道元数据（任意 JSON）

RefItem

每个 ref 是指向触发事件的源内容的证据指针。

字段	类型	必需	说明
object_type	string	是	引用对象的类型（如 `thread_reply`、`post`、`comment`、`message`）
object_id	string	是	引用对象在来源平台上的唯一标识
type	string	否	引用类型，默认为 `"external_action"`
platform	string	否	平台标识，不传则继承 `channel.platform`
url	string	否	引用对象的直接链接
content_preview	string	否	引用内容的短文本预览
snapshot	RefSnapshot	否	内容快照，用于证据留存

RefSnapshot

事件发生时对源内容的捕获快照。

字段	类型	必需	说明
text	string	是	证据原文内容
captured_at	integer	否	捕获时间戳（毫秒）
hash	string	否	内容完整性哈希（如 `sha256:...`）

Payload

payload 对象用于携带扩展数据。其中 jumpUrl 字段尤为重要 — 它提供用户从动态时间线点击跳转回原始内容的链接。

字段	类型	建议	说明
jumpUrl	string	是	跳转回源内容的 URL。在用户的动态时间线中显示为可点击链接
tags	string[]	否	自定义分类标签（如 `["ai", "discussion"]`）

你可以包含任何与你应用相关的附加字段（如 postId、commentId、authorName）。这些数据会原样存储，可供后续查询使用。

请求示例

示例 1：推荐写法（包含常用字段）

curl -X POST "https://api.mindverse.com/gate/lab/api/secondme/agent_memory/ingest" \
  -H "Authorization: Bearer lba_at_your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": {
      "kind": "thread",
      "id": "thread_12345",
      "url": "https://community.example.com/threads/12345"
    },
    "action": "reply",
    "action_label": "回复了帖子",
    "display_text": "在 AI 趋势讨论中发表了回复：Transformer 架构将继续主导",
    "importance": 0.7,
    "refs": [
      {
        "object_type": "thread_reply",
        "object_id": "reply_67890",
        "url": "https://community.example.com/threads/12345#reply-67890",
        "snapshot": {
          "text": "我认为 Transformer 架构将继续主导 NLP 领域。稀疏注意力机制带来的效率提升尤其值得关注。",
          "captured_at": 1711900800000
        }
      }
    ],
    "payload": {
      "jumpUrl": "https://community.example.com/threads/12345#reply-67890",
      "tags": ["ai", "discussion"]
    }
  }'

示例 2：最小化事件（仅必填字段）

curl -X POST "https://api.mindverse.com/gate/lab/api/secondme/agent_memory/ingest" \
  -H "Authorization: Bearer lba_at_your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": {
      "kind": "post"
    },
    "action": "post",
    "refs": [
      {
        "object_type": "post",
        "object_id": "post_abc123"
      }
    ]
  }'

响应

成功 (200)

{
  "code": 0,
  "data": {
    "eventId": 12345,
    "isDuplicate": false
  }
}

字段	类型	说明
eventId	number	事件 ID。返回 `0` 表示事件重复或无效
isDuplicate	boolean	是否为重复事件

幂等性

系统会自动对事件进行去重。如果你未提供 idempotency_key，服务端会使用以下规则自动生成：

sha256("external:" + platform + ":" + objectType + ":" + objectId + ":" + userId)

当检测到重复事件时：

eventId 返回 0
isDuplicate 返回 true
原始事件不会被修改

你也可以提供自定义的 idempotency_key 来控制去重行为。当同一个 object_type + object_id 组合可能合理产生多个事件时，自定义幂等键会很有用。

错误码

错误码	HTTP 状态码	说明
auth.token.invalid	401	Token 无效或已过期
oauth2.scope.insufficient	403	缺少 `agent_memory` 权限
agent.memory.write.disabled	403	该用户的 Agent Memory 写入已禁用
apikey.permission.denied	403	API Key 缺少所需权限
invalid.param	400	无效的请求参数（如缺少必填字段、refs 为空等）

重要性等级

importance 字段控制事件在用户动态时间线中的展示方式：

分数范围	前端展示	使用场景
`0.0 - 0.3`	正常显示，可能在摘要中被过滤	低价值事件（如页面浏览、被动浏览）
`0.3 - 0.69`	正常显示在时间线中	常规操作（如点赞、收藏）
`0.7 - 1.0`	被视为"重要"事件，计入每日重要事件统计，可能被特别展示或高亮	有价值的互动（如发帖、回复、有意义的发现）

importance >= 0.7 是关键分界线 — 达到或超过此值的事件被归类为重要事件，纳入用户的每日汇总。

最佳实践

始终提供 display_text 和 action_label。这是用户在动态时间线中看到的内容。如果省略，服务端会尝试自动生成，但可能与你期望的文案不一致。
希望事件被标记为重要时，设置 importance >= 0.7。常规事件使用 0.0 - 0.69。
在 payload.jumpUrl 中提供跳转链接，让用户可以从时间线直接导航回原始内容。
尽量提供 snapshot.text — 这能让分身直接获取原始内容，实现更好的回忆和总结。
不要手动设置 channel.platform — 它会从你的 OAuth 应用注册信息中自动填充。
将自定义标签放入 payload.tags（字符串数组）。没有顶层的 tag 字段。
妥善处理 isDuplicate: true 的响应 — 这不是错误，只是确认事件已存在。