接口介绍
按主键更新一条已存在的原子记忆。通过
id 定位目标，传入要更新的字段值，系统按"全量覆盖"语义替换对应字段：目标定位：通过
id 指定目标原子记忆主键（必填）。正文更新：通过
content 传入更新后的原子记忆正文全量值（必填，整体覆盖旧内容）。背景更新：通过
background 传入更新后的上下文背景信息（可选）。None（即不传）表示本次不更新背景；显式传入空串 "" 则代表清空背景。项 | 值 |
HTTP 方法与路径 | POST /v2/atomic/update |
HTTP 文档 | |
函数签名 | update_atomic(id, content, *, background=None) |
说明：
原子记忆不提供手动写入接口——原子记忆由系统自动沉淀产生，本接口仅用于在已沉淀原子记忆上做内容订正，不支持"按 id 不存在则创建"的 upsert 语义。若
id 不属于当前调用上下文，统一返回业务错误码 404。使用示例
# 仅更新正文result = client.update_atomic(id="atom-aaaa",content="用户偏好关西线路（已更新）",)# 同时更新正文和背景result = client.update_atomic(id="atom-aaaa",content="用户偏好关西线路（已更新）",background="2026 年 5 月对话补充",)# 清空背景result = client.update_atomic(id="atom-aaaa",content="用户偏好关西线路（已更新）",background="",)
说明：
请求参数
参数名 | 类型 | 必填 | 描述说明 |
id | str | 是 | 目标原子记忆 ID。需要修改的记忆片段的唯一主键标识。 |
content | str | 是 | 新的记忆正文（全量覆盖）。传入更新后的完整文本。注意：该操作为全量更新，会直接覆盖原有的记忆内容。 |
background | str | 否 | 新的上下文背景信息。用于调整该记忆产生的背景或补充说明。为了防止误操作，其传值规则如下： 不更新：传 None（或不传该字段），系统将保留原背景不变。 清空：显式传入空字符串 ""，系统将彻底清除原背景。 |
返回信息
返回字典包含被更新主键、最新时间戳与请求追踪 ID：
{"id": "atom-aaaa","updated_at": "2026-05-22T14:30:00+08:00","trace_id": "tr-xxxxxxxx-xxxxxxxx"}
字段名 | 类型 | 说明 |
id | str | 新创建或被操作的原子记忆主键 ID。系统生成的唯一标识符（格式如 "atom-xxxx"），后续对该条记忆的更新、删除或查询操作都需要传入此 ID。 |
updated_at | str | 最后修改时间戳。采用 ISO 8601 标准格式（例如 "2026-05-22T14:30:00+08:00"）。代表该条原子记忆在服务端写入成功并正式生效的最新时间。 |
trace_id | str | 请求追踪 ID。用于全链路日志排查。该值与 HTTP 响应头中的 x-trace-id 保持一致，常用于审计高频写操作或排查数据入库异常。 |
错误处理
错误码 | 触发场景 | 处理建议 |
400 | id 或 content 为空。 | 请校验入参后重试。 |
404 | id 不存在或不属于当前调用上下文。 | 请校验目标合法性。 |
500 | 服务端错误。 | 记录 trace_id 后重试或上报。 |
