全部产品
Search
文档中心

表格存储:记忆存储API

更新时间:Jul 09, 2026

通过 HTTP JSON 协议直接调用记忆存储服务,覆盖记忆库管理、长期记忆读写、短期记忆与审计查询、记忆整理(Dream)任务,适用于无 SDK 的自定义集成场景。

接口列表

按功能分类,全部接口如下。

记忆库管理

接口

说明

CreateMemoryStore

创建记忆库。

GetMemoryStore

获取记忆库详情。

UpdateMemoryStore

更新记忆库描述。

DeleteMemoryStore

删除记忆库。

ListMemoryStores

列出记忆库。

长期记忆

接口

说明

AddMemories

写入对话消息或文本,并生成长期记忆。

SearchMemories

检索长期记忆。

ListMemories

列出长期记忆。

GetMemory

获取单条长期记忆。

UpdateMemory

更新单条长期记忆。

DeleteMemory

删除单条长期记忆。

短期记忆与审计

接口

说明

ListMemoryStoreMessages

查询短期记忆,即原始会话消息。

ListMemoryStoreRequests

查询记忆库请求审计记录。

异步任务与 Scope

接口

说明

GetMemoryTask

查询异步抽取任务状态与结果。

ListMemoryTasks

列出异步抽取任务。

ListMemoryStoreScopes

列出记忆库中已存在的 Scope。

记忆整理(Dream)

接口

说明

CreateMemoryDreamTask

创建记忆整理任务。

GetMemoryDreamTask

查询记忆整理任务进度。

ListMemoryDreamTasks

列出记忆整理任务。

ListMemoryDreamActions

列出整理任务产生的动作(提案)。

ApplyMemoryDreamActions

应用整理动作提案。

CancelMemoryDreamTask

取消记忆整理任务。

通用对象

记忆库接口在请求和响应中复用以下数据结构。

Scope

Scope 表示记忆数据的归属层级,由四级字段组成。

字段

类型

说明

appId

string

应用标识。

tenantId

string

租户或用户标识。

agentId

string

Agent 标识。

runId

string

会话、运行或任务标识。

不同接口对 Scope 字段的必填性和通配符 * 支持规则不同。

场景

必填字段

通配符 * 规则

写入(AddMemories

appId

其他字段为空时补 __default__,不允许使用 *

检索长期记忆(SearchMemories

appIdtenantId

agentIdrunId 可使用 *

查询短期记忆(ListMemoryStoreMessages

四级 Scope 全部必填

不允许使用 *

获取、更新、删除单条长期记忆(GetMemoryUpdateMemoryDeleteMemory

四级 Scope 全部必填

不允许使用 *

列表查询(ListMemoriesListMemoryStoreRequests

appId

支持按层级使用 *

示例:

{
  "appId": "app-001",
  "tenantId": "user-001",
  "agentId": "assistant",
  "runId": "session-001"
}

Message

AddMemories 接口的 messages 字段使用以下结构。

字段

类型

必填

说明

role

string

消息角色,例如 userassistantsystem

content

string

消息内容。

messageId

string

消息 ID,最长 256 个字符。

timestamp

string

RFC3339 格式时间。

metadata

object

消息级元数据,键和值均为字符串。

Metadata

Metadata 为字符串键值对,用于附加业务标签。在检索接口中,Metadata 用于字符串键值的精确匹配过滤。

限制项

取值

单次请求最多键数

16 个

键长度上限

64 个字符

值长度上限

1024 个字符

示例:

{
  "source": "chat",
  "topic": "preference"
}

CreateMemoryStore

创建一个记忆库。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称,只能包含字母、数字和下划线,最长 32 个字符。

description

string

记忆库描述,最长 1024 个字符。

extractInstructions

string

记忆库自定义抽取指令,最长 4096 个字符。

请求示例

{
  "memoryStoreName": "agent_memory",
  "description": "Agent 长期记忆库",
  "extractInstructions": "重点关注用户的饮食偏好与出行习惯"
}

GetMemoryStore

获取记忆库详情。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

请求示例

{
  "memoryStoreName": "agent_memory"
}

UpdateMemoryStore

更新记忆库描述。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

description

string

新描述,最长 1024 个字符。

extractInstructions

string

新的自定义抽取指令,最长 4096 个字符;传空字符串清除,不传保持不变。

DeleteMemoryStore

删除记忆库。

警告

删除记忆库会一并删除该记忆库下的全部数据,操作不可逆。生产环境请谨慎执行。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

ListMemoryStores

列出记忆库。

请求参数

字段

类型

必填

说明

limit

int

返回数量。

nextToken

string

下一页标记。

AddMemories

写入对话消息或文本。服务保存原始消息作为短期记忆,并从输入中提取长期记忆。

请求参数

字段

类型

必填

说明

memoryStoreName

string

目标记忆库名称。

scope

object

Scope。写入时 appId 必填,不允许使用通配符 *

messages

array

text 二选一

对话消息数组,最多 20 条;总内容长度不超过 32000 个字符。

text

string

messages 二选一

文本内容,最长 32000 个字符。

metadata

object

写入级元数据,最多 16 个键,键最长 64 个字符,值最长 1024 个字符。

sync

boolean

是否同步等待记忆抽取完成,默认 false

各项上限的完整说明,请参见 限制与注意事项

请求示例:写入消息

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "messages": [
    {
      "role": "user",
      "content": "我喜欢喝咖啡"
    },
    {
      "role": "assistant",
      "content": "好的,我记住了"
    }
  ],
  "metadata": {
    "source": "chat"
  },
  "sync": true
}

请求示例:写入文本

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001"
  },
  "text": "用户喜欢喝咖啡,偏好简洁的回答风格"
}

响应字段

字段

说明

requestId

请求 ID。

status

请求状态。异步写入通常返回 running

acceptedMessages

接收的消息数量。

scope

实际写入使用的 Scope。

memoryStoreName

记忆库名称。

memcellsCreated

同步写入时返回,表示创建的记忆片段数量。

unitsCreated

同步写入时返回,表示创建的长期记忆单元数量。

SearchMemories

检索长期记忆。

请求参数

字段

类型

必填

说明

memoryStoreName

string

目标记忆库名称。

query

string

查询文本。

scope

object

Scope。检索时 appIdtenantId 必填,agentIdrunId 可使用通配符 *

topK

int

返回数量,默认 10,取值范围 1~50

includeEvidence

boolean

是否在结果中附带短期记忆源证据(evidence 字段),默认 false

minSimilarity

float

相似度过滤阈值,取值范围 0~1,默认 0(不过滤);大于 0 时过滤掉归一化余弦相似度低于该值的结果。

enableRerank

boolean

是否启用 Rerank,默认 true

metadata

object

元数据精确匹配过滤条件,键和值均为字符串。

topK 取值上限的完整说明,请参见 限制与注意事项

请求示例

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "*",
    "runId": "*"
  },
  "query": "用户喜欢什么饮品",
  "topK": 5,
  "enableRerank": true,
  "includeEvidence": true,
  "metadata": {
    "source": "chat"
  }
}

响应字段

字段

说明

results

检索结果列表。

results[].unit

长期记忆单元,字段定义见下表。

results[].score

相关性分数。

results[].similarity

查询与记忆的归一化余弦相似度(0~1),用于 minSimilarity 过滤。

results[].source

命中来源,例如 vectorvector+text

evidence

includeEvidence=true 时返回的短期记忆源证据列表;无可用证据时为 []。元素结构与 results 类似,但仅包含 unitscoresource,不含 similarity

scope

查询使用的 Scope。

memoryStoreName

记忆库名称。

results[].unit 内部字段如下。

字段

说明

id

长期记忆单元 ID。

conversation_key

关联的会话键。

scope

记忆所属 Scope,对象包含 appIdtenantIdagentIdrunId 四个字段。

memcell_id

记忆片段 ID。

unit_type

记忆单元类型。

text

记忆文本。

search_text

用于检索的文本。

source_turn_ids

来源消息 ID 列表。

type_label

类型标签。

date_bucket

日期分桶。

metadata_json

元数据,JSON 字符串。

deleted

是否已删除。

created_at

创建时间。

salience

显著性分数。

version

版本号。

ListMemories

列出长期记忆。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

scope

object

Scope。appIdtenantId 必填,agentIdrunId 可使用通配符 *

limit

int

返回数量。

nextToken

string

下一页标记。

请求示例

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "*",
    "agentId": "*",
    "runId": "*"
  },
  "limit": 20
}

GetMemory

获取单条长期记忆。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

memoryId

string

记忆 ID。

scope

object

完整 Scope,4 字段全部必填,不允许使用通配符 *

UpdateMemory

更新单条长期记忆。textmetadata 至少提供一个。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

memoryId

string

记忆 ID。

scope

object

完整 Scope,4 字段全部必填,不允许使用通配符 *

text

string

新记忆文本。

metadata

object

新元数据。

DeleteMemory

删除单条长期记忆。

警告

删除单条长期记忆为不可逆操作。生产环境请谨慎执行。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

memoryId

string

记忆 ID。

scope

object

完整 Scope,4 字段全部必填,不允许使用通配符 *

ListMemoryStoreMessages

查询短期记忆,即原始会话消息。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

scope

object

完整 Scope,4 字段全部必填,不允许使用通配符 *

limit

int

返回数量。

nextToken

string

下一页标记。

minTimestamp

string

最小时间,RFC3339 格式。

maxTimestamp

string

最大时间,RFC3339 格式。

请求示例

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "limit": 100
}

响应示例

{
  "session": {
    "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
    "messages": [
      {
        "messageId": "d0d9dd778a27e8cde773a243a5bab13c",
        "role": "user",
        "speaker": "user",
        "content": "[10:00 AM on 13 May, 2026] 我以后出差都优先订靠窗座位",
        "timestamp": "2026-05-13T10:00:00Z",
        "metadata": { "channel": "chat", "source": "chat" }
      }
    ]
  }
}

记忆库存在但该 Scope 暂无消息时,返回 200 与空的 messages 列表。

ListMemoryStoreRequests

查询记忆库请求审计记录。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

scope

object

Scope,可按层级使用通配符 *

operation

string

操作名称,例如 AddMemoriesSearchMemories

limit

int

返回数量。

nextToken

string

下一页标记。

minTimestamp

string

最小时间,RFC3339 格式。

maxTimestamp

string

最大时间,RFC3339 格式。

请求示例

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "*",
    "agentId": "*",
    "runId": "*"
  },
  "operation": "AddMemories",
  "limit": 50
}

响应字段

字段

说明

requestId

请求 ID。

operation

操作名称。

scope

请求使用的 Scope。

requestSummary

请求摘要。

responseStatus

响应状态。

latencyMs

处理耗时,单位毫秒。

targetId

操作目标 ID,例如记忆 ID。

createdAt

记录创建时间。

GetMemoryTask

查询异步抽取任务的状态与结果,传入 AddMemories 返回的 requestId

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

requestId

string

AddMemories 返回的请求 ID。

scope

object

校验任务归属的 Scope,可按层级使用 *

请求示例

{
  "memoryStoreName": "agent_memory",
  "requestId": "4b41a912f8c8a66202896e880a505d4a"
}

响应示例

{
  "memoryStoreName": "agent_memory",
  "task": {
    "requestId": "4b41a912f8c8a66202896e880a505d4a",
    "eventType": "ingest",
    "memoryStoreName": "agent_memory",
    "conversationKey": "app-001/user-001/assistant/session-001",
    "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
    "status": "completed",
    "acceptedMessages": 2,
    "derivedMemcellId": "b1bb4faec235b0d55bc8830da8ffa9f2",
    "derivedUnitIds": ["88432eb9d28e0787791625da916d6a20", "480230ab0806e88fd69e0804599552a4"],
    "createdAt": "2026-06-17T07:19:59.962Z",
    "updatedAt": "2026-06-17T07:20:08.749Z",
    "finishedAt": "2026-06-17T07:20:08.749Z"
  }
}

任务状态 status 取值:queuedrunningcompletedfailedneeds_reconcile。首次写入后任务索引建立期间,本接口可能返回 409 CONFLICTingest task index is still building, please retry shortly),稍后重试即可。

ListMemoryTasks

列出异步抽取任务。响应在 tasks 数组中返回任务对象,元素结构与 GetMemoryTask 响应中的 task 一致。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

scope

object

Scope,可按层级使用 *

status

string

任务状态过滤:queuedrunningcompletedfailedneeds_reconcile

limit

int

返回数量,默认 50,最大 100

nextToken

string

下一页标记。

minTimestamp

string

最小时间,Unix 毫秒时间戳(不支持 RFC3339)。

maxTimestamp

string

最大时间,Unix 毫秒时间戳(不支持 RFC3339)。

请求示例

{
  "memoryStoreName": "agent_memory",
  "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
  "limit": 5
}

ListMemoryStoreScopes

列出记忆库中已存在的 Scope,可查看某应用或租户下有哪些 Agent 和会话产生过记忆。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

scope

object

Scope,可按层级使用 *

limit

int

返回数量,默认 100,最大 100

nextToken

string

下一页标记。

请求示例

{
  "memoryStoreName": "agent_memory",
  "scope": { "appId": "app-001", "tenantId": "*", "agentId": "*", "runId": "*" },
  "limit": 10
}

响应示例

{
  "memoryStoreName": "agent_memory",
  "scope": { "appId": "app-001", "tenantId": "*", "agentId": "*", "runId": "*" },
  "scopes": [
    { "appId": "app-001", "tenantId": "user-001", "agentId": "__default__", "runId": "__default__" },
    { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" }
  ]
}

CreateMemoryDreamTask

创建记忆整理(Dream)任务,对已写入记忆进行二次提炼、归并与技能/画像提取。任务异步执行。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

scopes

array

待整理的 Scope 列表,最多 20 个。

taskType

string

任务类型:memory(默认)、skillprofile

applyMode

string

应用模式:proposal(默认,仅生成提案)、safe_auto(自动应用安全动作)。仅 taskType=memory 支持。

scopeOutputMode

string

整理结果归属:preserve_scope(默认)、promote_scope

confidenceThresholds

object

各动作的自动应用置信度阈值,键为 addupdatemerge,值取值范围 0~1

minTimestamp / maxTimestamp

string

整理的时间范围,Unix 毫秒时间戳(不支持 RFC3339)。

maxSessions / maxMessages / maxMemories

int

输入规模上限,取值范围见限制文档。

expandedScopeLimit

int

Scope 展开上限,0~1000

instructions

string

自定义整理指令,最长 4000 个字符。

incremental

boolean

是否增量整理,默认 false(全量);为 true 时从上次成功位置继续处理。

clientToken

string

幂等 Token。

请求示例

{
  "memoryStoreName": "agent_memory",
  "scopes": [ { "appId": "app-001", "tenantId": "user-001" } ],
  "taskType": "memory",
  "applyMode": "proposal"
}

响应示例

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "status": "queued",
  "createdAt": "2026-06-17T07:21:25.329Z"
}

GetMemoryDreamTask

查询记忆整理任务的进度与结果概览。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

dreamId

string

整理任务 ID。

请求示例

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7"
}

响应示例

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "taskType": "memory",
  "applyMode": "proposal",
  "scopeOutputMode": "preserve_scope",
  "status": "completed",
  "actions": { "total": 2, "proposed": 2, "applied": 0, "skipped": 0, "failed": 0 },
  "input": { "scopes": [ { "appId": "app-001", "tenantId": "user-001", "agentId": "__default__", "runId": "__default__" } ], "sessionCount": 1, "messageCount": 1, "memoryCount": 2, "incremental": false },
  "lastError": "",
  "createdAt": "2026-06-17T07:21:25.329Z",
  "updatedAt": "2026-06-17T07:21:32.276Z",
  "finishedAt": "2026-06-17T07:21:32.276Z"
}

任务状态 status 取值:queuedrunningplanningapplyingcompletedcompleted_with_failuresfailedcancelled

ListMemoryDreamTasks

列出记忆整理任务。响应在 tasks 数组中返回任务对象,包含 dreamIdstatustaskTypeactionCountproposedCountconfidenceThresholdscreatedAt 等字段。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

scope

object

Scope,可按层级使用 *

status

string

任务状态过滤。

limit

int

返回数量,默认 50,最大 100

nextToken

string

下一页标记。

minTimestamp / maxTimestamp

string

时间范围,Unix 毫秒时间戳(不支持 RFC3339)。

请求示例

{
  "memoryStoreName": "agent_memory",
  "scope": { "appId": "app-001", "tenantId": "*", "agentId": "*", "runId": "*" },
  "limit": 10
}

ListMemoryDreamActions

列出整理任务产生的动作(提案)。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

dreamId

string

整理任务 ID(与 scope 二选一)。

scope

object

按 Scope 查询(与 dreamId 二选一),此时 actionType 必填且仅支持 EMIT_SKILLEMIT_PROFILE

status

string

动作状态过滤:proposedappliedskippedfailed

action

string

动作类型过滤:ADDUPDATEDELETEMERGENOOP

minConfidence / maxConfidence

float

置信度过滤,0~1

orderBy

string

排序:created_at_asc(默认)、created_at_descconfidence_desc

limit

int

返回数量,默认 100,最大 100

nextToken

string

下一页标记。

请求示例

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "limit": 20
}

响应示例

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "actions": [
    {
      "dreamId": "2a528008111f5dc3500c73fd965089f7",
      "actionId": "968768529cdfde8d56686a71e1c28227",
      "action": "UPDATE",
      "status": "proposed",
      "targetScope": { "appId": "app-001", "tenantId": "user-001", "agentId": "__default__", "runId": "__default__" },
      "targetMemoryId": "d16fd038835d89ae8586f7814e5256c1",
      "newMemory": { "text": "User prefers concise responses.", "unitType": "atomic_fact" },
      "reason": "改写为更准确的 atomic_fact 表述。",
      "confidence": 0.95,
      "createdAt": "2026-06-17T07:21:32.161Z"
    }
  ]
}

两种查询模式互斥:按 dreamId 查询该任务下所有动作;按 scope + actionType(仅 EMIT_SKILLEMIT_PROFILE)查询该范围内累积生成的技能或画像。

ApplyMemoryDreamActions

应用记忆整理任务产生的提案动作(applyMode=proposal 时)。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

dreamId

string

整理任务 ID。

actionIds

array

待应用的动作 ID 列表,不可为空,单次最多 100 个。

applier

string

应用者标识,记录在审计中。

请求示例

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "actionIds": ["968768529cdfde8d56686a71e1c28227", "a0f4715245920ea7b6a34c1828c6f1ae"]
}

响应示例

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "applied": 2,
  "failed": 0,
  "results": [
    { "actionId": "968768529cdfde8d56686a71e1c28227", "status": "applied", "memoryId": "bd14a67ed215c114896325d912c8fa71" },
    { "actionId": "a0f4715245920ea7b6a34c1828c6f1ae", "status": "applied", "memoryId": "fa253856113f78d51a3b84a1fdf2d110" }
  ]
}

EMIT_SKILLEMIT_PROFILE 动作由整理任务直接写入,没有手动 apply 流程,混入此类动作 ID 会被拒绝。actionIds 为空数组时返回 403。

CancelMemoryDreamTask

取消尚未完成的记忆整理任务。

请求参数

字段

类型

必填

说明

memoryStoreName

string

记忆库名称。

dreamId

string

整理任务 ID。

请求示例

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7"
}

响应示例

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "status": "cancelled",
  "taskType": "memory"
}

仅可取消未完成的任务;已进入终态(completedfailedcancelled)的任务,响应仍返回 200,status 保持原值,任务本身不做处理。