记忆存储服务结构记忆写入与管理 - 表格存储

前提条件

已创建输入类型为 messages、输出类型含 structured 的记忆库。参见记忆库管理。
已安装Agent Storage SDK：Python ≥ 1.0.10，TypeScript ≥ 0.0.13

写入记忆

将对话消息或文本写入记忆库，服务保存原始消息为短期记忆，并异步提取结构化长期记忆。

scope.appId 必填且不能为 *；tenantId/agentId/runId 为空时补为 __default__，写入不允许使用通配符。
messages 最多 20 条、总大小 ≤ 32000 字节；也可用 text（≤ 32000 字节）二选一。
默认异步执行（sync=false）：原始消息立即可查，结构记忆在后台产出。保存返回的 requestId，调用 GetMemoryTask 跟踪抽取任务。
含 file 输出的记忆库只支持异步写入；sync=true 仅适用于无 file 输出的库，否则报 INVALID_PARAMETER。

控制台

登录Agent Storage控制台，打开目标记忆库，进入长期记忆页，点击写入记忆。
填写 Scope（应用、租户、智能体、会话）。
输入对话消息（角色 + 内容）或纯文本。
点击确定，服务异步提取结构记忆。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "app-001",
        "tenantId": "user-001",
        "agentId": "assistant",
        "runId": "session-001",
    },
    "messages": [
        {"role": "user", "content": "我喜欢喝美式咖啡"},
        {"role": "assistant", "content": "好的，已记下你的偏好。"},
    ],
})

print(f"requestId: {resp.get('requestId')}, status: {resp.get('status')}")

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.addMemories({
  memoryStoreName: 'agent_memory',
  scope: {
    appId: 'app-001',
    tenantId: 'user-001',
    agentId: 'assistant',
    runId: 'session-001',
  },
  messages: [{ role: 'user', content: '我喜欢喝美式咖啡' }],
});

console.log(resp.requestId, resp.status);

API

调用 AddMemories 写入记忆。完整字段参见写入记忆。

检索记忆

用自然语言检索结构记忆和服务生成的记忆文件，返回按相关性排序的结果。

检索对象是结构化记忆和服务生成的记忆文件；直接管理的文件记忆不在检索范围（按文件记忆的路径读取或建知识编译（Wiki））。
query 最长 8192 个 Unicode 字符；scope.appId 必填且不能为 *，其他字段显式传 * 才通配。

控制台

打开目标记忆库，进入记忆检索页，设置应用和租户的具体值（智能体和会话可选“全部”）。
在检索问题 输入查询文本，设置Top K，按需启用重排序或展开高级检索。
点击搜索，结果按“结构记忆/文件记忆/检索证据”分类展示，含相关度、相似度和召回方式。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

result = client.search_memories({
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "*", "runId": "*"},
    "query": "用户喜欢什么饮品",
    "topK": 5,
    "enableRerank": True,
})

for hit in result.get("results", []):
    unit = hit.get("unit", {})
    print(f"[score={hit.get('score'):.4f}] {unit.get('text', '')[:80]}")

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const result = await client.searchMemories({
  memoryStoreName: 'agent_memory',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: '*', runId: '*' },
  query: '用户喜欢什么饮品',
  topK: 5,
  enableRerank: true,
});

for (const hit of result.results) {
  console.log(`[score=${hit.score.toFixed(4)}] ${hit.unit?.text?.slice(0, 80)}`);
}

API

调用 SearchMemories 检索记忆。完整字段参见检索记忆。

列出记忆

分页查询指定 Scope 下的长期记忆列表。

scope 支持左前缀通配（右侧也需为 * 或空）；单次请求最多扫描 100 个 Scope。
limit 默认 50、最大 100；nextToken 必须与相同的 scope + filter 配套使用。

控制台

在长期记忆页设置 Scope 后，列表展示记忆内容、类型、创建时间和操作。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.list_memories({
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "*", "runId": "*"},
    "limit": 50,
})

for m in resp.get("memories", []):
    print(f"[{m.get('type_label')}] {m.get('text', '')[:60]} (id={m.get('id')})")

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.listMemories({
  memoryStoreName: 'agent_memory',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: '*', runId: '*' },
  limit: 50,
});

for (const m of resp.memories) {
  console.log(`[${m.type_label}] ${m.text?.slice(0, 60)} (id=${m.id})`);
}

API

调用 ListMemories 列出记忆。完整字段参见列出记忆。

查询记忆

查询指定长期记忆的详情。

控制台

在长期记忆列表中点击目标记忆的查看，查看 ID、内容、检索文本、Scope、类型、重要度和版本。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

resp = client.get_memory({
    "memoryStoreName": "agent_memory",
    "memoryId": "<memory-id>",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001"},
})

m = resp.get("memory", {})
print(f"类型: {m.get('type_label')}, 内容: {m.get('text')}, 重要度: {m.get('salience')}")

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const resp = await client.getMemory({
  memoryStoreName: 'agent_memory',
  memoryId: '<memory-id>',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: 'assistant', runId: 'session-001' },
});

const m = resp.memory;
console.log(m.type_label, m.text, m.salience);

API

调用 GetMemory 查询记忆。完整字段参见查询记忆。

更新记忆

更新指定长期记忆的文本、元数据等字段。

metadata 采用覆盖式更新，传入 {} 会清空所有元数据。
effectiveAt 与 timePrecision 必须同时传入。

控制台

控制台不支持编辑单条长期记忆，请使用 SDK 或 API 完成更新。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

client.update_memory({
    "memoryStoreName": "agent_memory",
    "memoryId": "<memory-id>",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001"},
    "text": "用户喜欢喝拿铁",
    "metadata": {"source": "profile"},
})

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

await client.updateMemory({
  memoryStoreName: 'agent_memory',
  memoryId: '<memory-id>',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: 'assistant', runId: 'session-001' },
  text: '用户喜欢喝拿铁',
  metadata: { source: 'profile' },
});

API

调用 UpdateMemory 更新记忆。完整字段参见更新记忆。

删除记忆

重要

删除单条长期记忆不可逆。

控制台

控制台不支持删除单条长期记忆，请使用 SDK 或 API 完成删除；如需清空整库数据，可删除整个记忆库。

SDK

Python

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

client.delete_memory({
    "memoryStoreName": "agent_memory",
    "memoryId": "<memory-id>",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001"},
})

TypeScript

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

await client.deleteMemory({
  memoryStoreName: 'agent_memory',
  memoryId: '<memory-id>',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: 'assistant', runId: 'session-001' },
});

API

调用 DeleteMemory 删除记忆。完整字段参见删除记忆。

表格存储：结构记忆

前提条件

写入记忆

控制台

SDK

Python

TypeScript

API

检索记忆

控制台

SDK

Python

TypeScript

API

列出记忆

控制台

SDK

Python

TypeScript

API

查询记忆

控制台

SDK

Python

TypeScript

API

更新记忆

控制台

SDK

Python

TypeScript

API

删除记忆

控制台

SDK

Python

TypeScript

API

相关文档