CLI 使用介绍

配置访问凭证

tablestore-agent-cli configure set access_key_id '...'
tablestore-agent-cli configure set access_key_secret '...'
tablestore-agent-cli configure set region 'cn-beijing'

配置表格存储实例

tablestore-agent-cli configure set ots_endpoint 'https://<instance>.cn-beijing.ots.aliyuncs.com'
tablestore-agent-cli configure set ots_instance_name '<instance-name>'

未配置 ots_endpoint 与 ots_instance_name 时，CLI 会在执行 doctor 或实际操作时自动创建并复用托管表格存储实例。

配置记忆服务默认值

tablestore-agent-cli configure set memory_store_name 'agent_memory'
tablestore-agent-cli configure set memory_app_id 'app-001'
tablestore-agent-cli configure set memory_tenant_id 'tenant-001'
tablestore-agent-cli configure set memory_agent_id 'agent-001'
tablestore-agent-cli configure set memory_run_id 'run-001'

配置默认值后，后续命令可省略对应参数。

配置文件与环境变量

配置文件路径：

~/.config/tablestore-agent-cli/config.toml

环境变量优先级高于配置文件，对应关系如下：

创建记忆库

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

记忆库创建后会异步初始化二级索引，需等待约 1 分钟索引就绪后才能正常写入和检索。

列出记忆库

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

ls 是 list 的别名。该命令单页返回，如需翻页继续读取，请使用响应中的 nextToken。

查看记忆库

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

show 是 describe 的别名。

更新记忆库

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

删除记忆库

tablestore-agent-cli memory delete --store agent_memory
tablestore-agent-cli memory rm --store agent_memory -y

rm 是 delete 的别名。TTY 环境下删除会提示确认，传入 -y 跳过确认。

写入文本

通过 --text 直接传入预加工的文本：

tablestore-agent-cli memory add \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001 \
  --text "用户喜欢喝咖啡"

同步写入

默认写入为异步模式，文本由服务端在后台抽取记忆。需要写入完成后立即可检索时使用 --sync：

tablestore-agent-cli memory add \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001 \
  --text "用户偏好简洁的回答风格" \
  --sync

通过消息文件写入

通过 --messages-file 传入对话消息列表，文件内容必须为 JSON 数组：

tablestore-agent-cli memory add \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001 \
  --messages-file ./messages.json

附加元数据

通过 --metadata 传入 JSON 字符串，附加业务自定义字段：

tablestore-agent-cli memory add \
  --store agent_memory \
  --app-id app-001 \
  --text "用户喜欢川菜" \
  --metadata '{"source":"chat","topic":"preference"}'

列出记忆单元

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>

ls-units 是 list-units 的别名。

获取单条记忆

tablestore-agent-cli memory get \
  --store agent_memory \
  --memory-id mem-001 \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001

cat 是 get 的别名。

更新单条记忆

tablestore-agent-cli memory update-unit \
  --store agent_memory \
  --memory-id mem-001 \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001 \
  --text "用户偏好咖啡，且喜欢简洁回答"

删除单条记忆

tablestore-agent-cli memory delete-unit \
  --store agent_memory \
  --memory-id mem-001 \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001

rm-unit 是 delete-unit 的别名。

查询短期记忆

tablestore-agent-cli memory msg-list \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id assistant \
  --run-id session-001

短期记忆查询要求 Scope 四级（app-id、tenant-id、agent-id、run-id）全部填写，不允许使用通配符 *。ls-msgs 是 msg-list 的别名。

查询请求审计

按 --operation 过滤指定操作类型的请求审计记录，Scope 中 tenant-id、agent-id、run-id 支持反引号包裹的通配符 *：

tablestore-agent-cli memory req-list \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id '*' \
  --agent-id '*' \
  --run-id '*' \
  --operation AddMemories

ls-reqs 是 req-list 的别名。

创建整理任务

tablestore-agent-cli memory dream create \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --apply-mode proposal

常用选项：--apply-mode proposal|safe_auto、--scope-output-mode preserve_scope|promote_scope、--instructions <text>、--confidence-thresholds、--max-sessions、--max-messages、--max-memories、--min-timestamp、--max-timestamp。多 Scope 整理使用 --scopes-file <path>（与单 Scope 选项互斥）。

查询整理任务

tablestore-agent-cli memory dream get --store agent_memory --dream-id <dreamId>
tablestore-agent-cli memory dream list --store agent_memory --app-id app-001 --tenant-id user-001

查看与应用整理动作

tablestore-agent-cli memory dream actions \
  --store agent_memory \
  --dream-id <dreamId> \
  --status proposed

tablestore-agent-cli memory dream apply \
  --store agent_memory \
  --dream-id <dreamId> \
  --action-ids <actionId1>,<actionId2>

dream actions（别名 ls-actions）支持 --status、--action、--min-confidence、--max-confidence、--order-by 等过滤条件；dream apply 也可通过 --action-ids-file <path> 传入包含动作 ID 的 JSON 数组文件。

取消进行中的整理任务：

tablestore-agent-cli memory dream cancel \
  --store agent_memory \
  --dream-id <dreamId>