Memory Storage Service CLI usage-Tablestore(Tablestore)-阿里云帮助中心

tablestore-agent-cli manages memory stores, writes and searches memories, audits requests, and runs a visual Dashboard. Use it for local debugging, operations, and automation.

Installation

Install the CLI globally with npm. Node.js 18 or later is required. Memory consolidation (memory dream) requires CLI version 0.2.5 or later.

npm install -g @tablestore/tablestore-agent-cli
tablestore-agent-cli version

Configuration

Configure access credentials, Tablestore instance, and memory service defaults before first use. All settings persist to a local configuration file.

Configure access credentials

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

Configure the Tablestore instance

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

If ots_endpoint and ots_instance_name are not set, the CLI creates and reuses a managed instance automatically when you run doctor or any command.

Set memory service defaults

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'

Once set, you can omit these parameters in subsequent commands.

Configuration file and environment variables

Configuration file path:

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

Environment variables override the configuration file:

Environment variable	Configuration item
`TABLESTORE_ACCESS_KEY_ID`	`access_key_id`
`TABLESTORE_ACCESS_KEY_SECRET`	`access_key_secret`
`TABLESTORE_ENDPOINT`	`ots_endpoint`
`TABLESTORE_INSTANCE_NAME`	`ots_instance_name`
`TABLESTORE_REGION`	`region`
`TABLESTORE_MEMORY_STORE_NAME`	`memory_store_name`
`TABLESTORE_MEMORY_APP_ID`	`memory_app_id`
`TABLESTORE_MEMORY_TENANT_ID`	`memory_tenant_id`
`TABLESTORE_MEMORY_AGENT_ID`	`memory_agent_id`
`TABLESTORE_MEMORY_RUN_ID`	`memory_run_id`

Diagnostics

Run doctor memory to verify credentials, instance configuration, and memory service connectivity. Returns a non-zero exit code on failure.

tablestore-agent-cli doctor memory

Memory store management

A memory store holds long-term and short-term memories, backed by tables and indexes on a Tablestore instance.

Create a memory store

tablestore-agent-cli memory create --store agent_memory --description "Agent long-term memory store"

Secondary indexes initialize asynchronously after creation. Wait for initialization to complete before writing or searching.

List memory stores

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

ls is an alias for list. Returns one page at a time. Use nextToken from the response to fetch more.

View a memory store

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

show is an alias for describe.

Update a memory store

tablestore-agent-cli memory update --store agent_memory --description "New description"

Delete a memory store

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

rm is an alias for delete. Prompts for confirmation in a TTY. Pass -y to skip.

Write memories

Each write requires a full scope of four parts: app-id, tenant-id, agent-id, and run-id. Wildcards (*) are not allowed in write scopes.

Write text

Pass preprocessed text directly with --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 "The user likes coffee"

Write synchronously

Writes are asynchronous by default — the server extracts memories in the background. To make a memory immediately searchable, use --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 "The user prefers concise answers" \
  --sync

Write from a message file

Pass conversation messages with --messages-file. The file must contain a JSON array:

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

Attach metadata

Pass a JSON string with --metadata to attach custom business fields:

tablestore-agent-cli memory add \
  --store agent_memory \
  --app-id app-001 \
  --text "The user likes Sichuan food" \
  --metadata '{"source":"chat","topic":"preference"}'

Search long-term memories

Use memory search for semantic search. tenant-id, agent-id, and run-id support the wildcard * to aggregate across scopes.

tablestore-agent-cli memory search \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --agent-id '*' \
  --run-id '*' \
  --query "What food does the user like" \
  --top-k 5

--top-k defaults to 10. Valid range: 1-50.

Disable reranking:

tablestore-agent-cli memory search \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --query "User preferences" \
  --disable-rerank

Reranking is on by default. Pass --disable-rerank to sort by vector distance only.

Filter by metadata:

tablestore-agent-cli memory search \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --query "User preferences" \
  --metadata '{"source":"chat"}'

Each results element contains a memory unit and its score. Fields in unit use snake_case. For more information, see Memory Storage API reference.

Manage long-term memories

Query, update, or delete individual memory units. Get the memory-id from the memory add response or list-units. Pass the same full scope used at write time — all four parts (app-id, tenant-id, agent-id, and run-id) — no wildcard *.

List memory units

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 is an alias for list-units.

Get a single memory

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 is an alias for get.

Update a single memory

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 "The user prefers coffee and concise answers"

Delete a single memory

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 is an alias for delete-unit.

Short-term memories and request audits

Query short-term memories

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

Short-term memory queries require all four scope parts (app-id, tenant-id, agent-id, and run-id). No wildcard * allowed. ls-msgs is an alias for msg-list.

Query request audits

Filter audit records by operation type with --operation. tenant-id, agent-id, and run-id support the wildcard *:

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

ls-reqs is an alias for req-list.

List scopes

memory scope-list (alias ls-scopes) lists existing scopes in a memory store so you can discover which agents and sessions have produced memories under an app or tenant. tenant-id, agent-id, and run-id support the wildcard *:

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

Add --all to automatically paginate and deduplicate on the client side. --max-pages caps the number of pages (default 20).

Track async tasks

memory add writes asynchronously by default. Use the returned requestId to track the memory extraction task.

Get a single task:

tablestore-agent-cli memory task get \
  --store agent_memory \
  --request-id <requestId>

List tasks, optionally filtered by status (queued, running, completed, failed, needs_reconcile):

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

show is an alias for task get, and ls is an alias for task list. During the task index build after the first write, task get may briefly return a conflict error — retry a moment later.

Memory consolidation (Dream)

The memory dream subcommands create and manage consolidation tasks that deduplicate, merge, and refine existing memories, and can also extract skills and user profiles.

Create a consolidation task

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

Common options: --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. Use --scopes-file <path> for multi-scope consolidation (mutually exclusive with the single-scope options).

Query consolidation tasks

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

View and apply actions

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 (alias ls-actions) supports filters such as --status, --action, --min-confidence, --max-confidence, and --order-by. dream apply also accepts --action-ids-file <path>, a JSON array file of action IDs.

Cancel a running consolidation task:

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

Output for scripts

Use -q (or --quiet) to output only the data field, for easier pipeline processing:

tablestore-agent-cli -q memory search \
  --store agent_memory \
  --app-id app-001 \
  --tenant-id user-001 \
  --query "What drinks does the user like"

Dashboard

The CLI includes a built-in web Dashboard for visual management and debugging.

tablestore-agent-cli dashboard start
tablestore-agent-cli dashboard start -p 9999
tablestore-agent-cli dashboard start --host 0.0.0.0

The Dashboard listens on 127.0.0.1:3000 by default. Use -p for a custom port and --host 0.0.0.0 to allow remote access.