全部产品
Search

搜索本产品

    表格存储：记忆库操作

    文档中心

    表格存储：记忆库操作

    更新时间：Jul 02, 2026

    本文档介绍命令行工具中记忆库（Agent Memory）相关的命令及参数，覆盖记忆库管理、记忆写入、记忆检索、记忆单元管理、审计查询和 Scope 使用规则。

    前置条件

    • 已完成命令行工具的安装与访问凭证配置。具体操作，请参见命令行工具。

    • 推荐预先配置默认 scope（如 memory_store_name、memory_app_id 等），以便后续命令省略对应参数。

    记忆库管理

    记忆库是 Agent 长期记忆的存储容器，支持写入、检索、审计的全流程操作。

    创建记忆库

    tablestore-agent-cli memory create --store agent_memory --description "长期记忆库"

    如果已通过 configure set memory_store_name 配置默认记忆库名，可省略 --store：

    tablestore-agent-cli configure set memory_store_name agent_memory
tablestore-agent-cli memory create --description "长期记忆库"

    列出记忆库

    tablestore-agent-cli memory ls
tablestore-agent-cli memory list --limit 50 --next-token <token>

    memory ls 是 memory list 的别名。

    说明

    记忆库的 list 命令不会自动翻页，仅返回单页结果。如需获取下一页，请将响应中的 nextToken 通过 --next-token 参数传入。

    查看记忆库

    tablestore-agent-cli memory describe --store agent_memory
tablestore-agent-cli memory show --store agent_memory

    memory show 是 memory describe 的别名。

    更新记忆库描述

    tablestore-agent-cli memory update --store agent_memory --description "新的描述"

    删除记忆库

    重要

    删除记忆库会清除其下全部记忆数据，且不可恢复。请谨慎操作。

    tablestore-agent-cli memory delete --store agent_memory   # TTY 环境下会提示确认
tablestore-agent-cli memory rm --store agent_memory -y    # 跳过确认

    memory rm 是 memory delete 的别名。

    写入记忆

    向指定 scope 写入一条或多条记忆。

    单条文本写入

    tablestore-agent-cli memory add --store agent_memory --app-id app-001 --text "用户喜欢麻婆豆腐"

    同步等待提取完成

    默认情况下，写入命令异步返回。如需等待记忆提取完成后再返回，使用 --sync 参数：

    tablestore-agent-cli memory add --store agent_memory --app-id app-001 --text "用户偏好川菜" --sync

    通过 JSON 文件批量写入

    tablestore-agent-cli memory add --store agent_memory --app-id app-001 --messages-file ./messages.json

    messages.json 需包含一个 JSON 数组。

    附加元数据

    tablestore-agent-cli memory add --store agent_memory --app-id app-001 --text "用户偏好川菜" --metadata '{"source":"chat","confidence":"high"}'

    参数说明

    参数

    必填

    默认值

    说明

    --store

    否

    配置项 memory_store_name

    记忆库名称。

    --app-id

    未配置默认值时必填

    配置项 memory_app_id

    scope 中最关键的参数，用于业务隔离。

    --tenant-id

    否

    配置项 memory_tenant_id

    租户 ID。

    --agent-id

    否

    配置项 memory_agent_id

    Agent ID。

    --run-id

    否

    配置项 memory_run_id

    单次会话或运行 ID。

    --text

    二选一

    —

    记忆文本内容。

    --messages-file

    二选一

    —

    批量写入的 JSON 文件路径。

    --metadata

    否

    —

    Metadata JSON 字符串。必须是 string key / string value 的对象。与 --metadata-file 互斥。

    --metadata-file

    否

    —

    Metadata JSON 文件路径。

    --sync

    否

    false

    是否等待提取完成。
    重要

    写入命令的 scope 参数不允许使用通配符 *。

    记忆检索

    针对指定 scope 执行语义检索。

    基础检索

    tablestore-agent-cli memory search --store agent_memory --app-id app-001 --tenant-id tenant-001 --query "用户喜欢什么食物" --top-k 5

    关闭重排

    tablestore-agent-cli memory search --store agent_memory --app-id app-001 --tenant-id tenant-001 --query "用户偏好" --disable-rerank

    通过 Metadata 过滤

    tablestore-agent-cli memory search --store agent_memory --app-id app-001 --tenant-id tenant-001 --query "用户偏好" --metadata '{"source":{"equals":"chat"}}'

    参数说明

    参数

    默认值

    说明

    --top-k

    10

    返回结果数量。取值范围 0~50。

    --enable-rerank

    true

    是否启用重排。使用 --disable-rerank 关闭。

    --metadata

    —

    Metadata 过滤 JSON 字符串。与 --metadata-file 互斥。

    --metadata-file

    —

    Metadata 过滤 JSON 文件路径。
    说明

    检索命令的 scope 参数允许使用通配符 *。

    返回示例

    {"items":[{"memory":{"id":"mem-001","text":"用户喜欢麻婆豆腐"},"score":0.91}],"totalCount":1}

    管理记忆单元

    记忆单元（Memory Unit）是记忆库的最小数据单位。

    列出记忆单元

    tablestore-agent-cli memory list-units --store agent_memory --app-id app-001
tablestore-agent-cli memory ls-units --store agent_memory --app-id app-001 --limit 20 --next-token <token>

    memory ls-units 是 memory list-units 的别名。该命令仅返回单页结果，如需翻页请手动传入 --next-token。

    查看记忆单元

    tablestore-agent-cli memory get --store agent_memory --memory-id mem-001 --app-id app-001
tablestore-agent-cli memory cat --store agent_memory --memory-id mem-001 --app-id app-001

    memory cat 是 memory get 的别名。

    更新记忆单元

    # 更新文本
tablestore-agent-cli memory update-unit --store agent_memory --memory-id mem-001 --app-id app-001 --text "用户强烈偏好辛辣食物"

# 更新 Metadata
tablestore-agent-cli memory update-unit --store agent_memory --memory-id mem-001 --app-id app-001 --metadata '{"confidence":"very_high"}'

    --text 和 --metadata 至少需要指定一个。

    删除记忆单元

    tablestore-agent-cli memory delete-unit --store agent_memory --memory-id mem-001 --app-id app-001
tablestore-agent-cli memory rm-unit --store agent_memory --memory-id mem-001 --app-id app-001 -y

    memory rm-unit 是 memory delete-unit 的别名。

    Scope 通配符使用规则

    命令

    是否允许通配符 *

    list-units / ls-units

    允许

    get / cat

    不允许

    update-unit

    不允许

    delete-unit / rm-unit

    不允许

    审计：消息与请求

    查看原始消息记录

    tablestore-agent-cli memory msg-list --store agent_memory --app-id app-001
tablestore-agent-cli memory ls-msgs --store agent_memory --app-id app-001

    memory ls-msgs 是 memory msg-list 的别名。

    查看请求审计记录

    tablestore-agent-cli memory req-list --store agent_memory --app-id app-001
tablestore-agent-cli memory req-list --store agent_memory --app-id app-001 --operation AddMemories
tablestore-agent-cli memory ls-reqs --store agent_memory --app-id app-001

    memory ls-reqs 是 memory req-list 的别名。--operation 用于按操作类型过滤，如 AddMemories、SearchMemories 等。

    参数说明

    参数

    默认值

    说明

    --limit

    msg-list: 200；req-list: 50

    单页返回数量。

    --next-token

    —

    翻页 token。

    --operation

    —

    操作类型过滤。仅 req-list 支持。
    说明

    审计类命令仅返回单页结果，如需获取后续数据请手动传入 --next-token。

    Scope 层级与通配符

    记忆库的 scope 由四级 ID 组成，层级从大到小依次为：

    appId  →  tenantId  →  agentId  →  runId

    Scope 参数

    是否必填

    说明

    --app-id

    未配置默认值时必填

    业务应用 ID。scope 中最关键的参数。

    --tenant-id

    否

    租户 ID。

    --agent-id

    因命令而异（详见下方）

    Agent ID。

    --run-id

    否

    单次会话或运行 ID。

    --agent-id 必填规则：以下命令实际调用时要求 --agent-id 必传（即使已通过 configure set memory_agent_id 配置默认值，也需要显式传入）：

    • get / cat

    • update-unit

    • delete-unit / rm-unit

    • msg-list / ls-msgs

    其余命令（add、search、list-units、req-list 等）可省略 --agent-id，Server 将使用配置项或默认值。

    通配符 * 的使用规则：

    • 允许使用通配符的命令：检索类（search）、列表类（list-units、msg-list、req-list）。

    • 不允许使用通配符的命令：写入类（add）、单条获取（get）、更新（update-unit）、删除（delete-unit）。

    分页说明

    记忆库的所有 list 类命令仅返回单页结果，不会自动翻页。如需继续获取，请手动将响应中的 nextToken 通过 --next-token 参数传入：

    tablestore-agent-cli memory list-units --store agent_memory --app-id app-001 --next-token <token>

    这与知识库的 kb list、kb doc-list 自动翻页行为不同，使用时请注意区分。