Memory store CLI reference - Tablestore agent CLI - Tablestore

Prerequisites

The command-line tool is installed and access credentials are configured. For details, see Agent Storage CLI.
Configure default scope values such as memory_store_name and memory_app_id so that you can omit these parameters in subsequent commands.

Scope levels and wildcards

A memory store scope consists of four levels of IDs, from broadest to narrowest:

appId  →  tenantId  →  agentId  →  runId

Scope parameter	Required	Description
`--app-id`	Required when no default is configured	The application ID. The primary scope parameter used to isolate applications.
`--tenant-id`	No	The tenant ID.
`--agent-id`	Command-dependent (see below)	The agent ID.
`--run-id`	No	The session or run ID.

When --agent-id is required: Pass --agent-id explicitly for the following commands, even when a default is set with configure set memory_agent_id:

get / cat
update-unit
delete-unit / rm-unit
msg-list / ls-msgs

For all other commands (such as add, search, list-units, and req-list), you can omit --agent-id; the server uses the configured default value.

Wildcard * usage:

Command category	Typical commands	Wildcard `` allowed*
Retrieval	`search`	Yes
List	`list-units` / `ls-units`, `msg-list` / `ls-msgs`, `req-list` / `ls-reqs`	Yes
Write	`add`	No
Single-record get	`get` / `cat`	No
Update	`update-unit`	No
Delete	`delete-unit` / `rm-unit`	No

Pagination

All list commands for the memory store (including memory list, list-units, msg-list, and req-list) return a single page of results and do not paginate automatically. To fetch more results, pass the nextToken from the response as --next-token:

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

Memory store list commands do not paginate automatically, unlike kb list and kb doc-list.

Manage memory stores

A memory store holds an agent's long-term memories and supports writing, retrieval, and audit operations.

Create a memory store

tablestore-agent-cli memory create --store agent_memory --description "Long-term memory store"

If a default memory store name is set with configure set memory_store_name, you can omit --store:

tablestore-agent-cli configure set memory_store_name agent_memory
tablestore-agent-cli memory create --description "Long-term memory store"

List memory stores

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

memory ls is an alias for memory list. See Pagination for pagination behavior.

View a memory store

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

memory show is an alias for memory describe.

Update the description

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

Delete a memory store

Important

Deleting a memory store removes all memory data it contains and cannot be undone.

tablestore-agent-cli memory delete --store agent_memory   # Prompts for confirmation in a TTY
tablestore-agent-cli memory rm --store agent_memory -y    # Skips confirmation

memory rm is an alias for memory delete.

Write memories

Write one or more memories to a specified scope. For --app-id and other scope parameter descriptions, see Scope levels and wildcards.

Write a single text memory

tablestore-agent-cli memory add --store agent_memory --app-id app-001 --text "The user likes mapo tofu"

Wait synchronously for extraction to finish

By default, write commands return asynchronously. To block until memory extraction completes, add the --sync flag:

tablestore-agent-cli memory add --store agent_memory --app-id app-001 --text "The user prefers Sichuan cuisine" --sync

Batch write from a JSON file

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

messages.json must contain a JSON array.

Attach metadata

tablestore-agent-cli memory add --store agent_memory --app-id app-001 --text "The user prefers Sichuan cuisine" --metadata '{"source":"chat","confidence":"high"}'

Parameters

Parameter	Required	Default	Description
`--store`	No	`memory_store_name` configuration item	The memory store name.
`--app-id`	Required when no default is configured	`memory_app_id` configuration item	The primary scope parameter used to isolate applications.
`--tenant-id`	No	`memory_tenant_id` configuration item	The tenant ID.
`--agent-id`	No	`memory_agent_id` configuration item	The agent ID.
`--run-id`	No	`memory_run_id` configuration item	The session or run ID.
`--text`	One of two	—	The memory text content.
`--messages-file`	One of two	—	Path to a JSON file for bulk writes.
`--metadata`	No	—	Metadata as a JSON string. Must be an object with string keys and string values. Mutually exclusive with `--metadata-file`.
`--metadata-file`	No	—	Path to a metadata JSON file.
`--sync`	No	`false`	Whether to wait for extraction to complete.

Important

Wildcard * is not allowed in scope parameters of write commands. For all wildcard rules, see Scope levels and wildcards.

Search memories

Run a semantic search within a specified scope. Wildcard * is allowed in scope parameters of search commands.

Basic search

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

Disable reranking

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

Filter by metadata

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

Response example

{"items":[{"memory":{"id":"mem-001","text":"The user likes mapo tofu"},"score":0.91}],"totalCount":1}

Parameters

Parameter	Default	Description
`--top-k`	`10`	Number of results to return. Valid range: 0–50.
`--enable-rerank`	`true`	Whether to enable reranking. Use `--disable-rerank` to turn it off.
`--metadata`	—	Metadata filter as a JSON string. Mutually exclusive with `--metadata-file`.
`--metadata-file`	—	Path to a metadata filter JSON file.

Manage memory units

A memory unit is the atomic record stored in a memory store. For per-command wildcard * support, see Scope levels and wildcards.

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>

memory ls-units is an alias for memory list-units. See Pagination for pagination behavior.

View a memory unit

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

Update a memory unit

# Update the text
tablestore-agent-cli memory update-unit --store agent_memory --memory-id mem-001 --app-id app-001 --text "The user strongly prefers spicy food"

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

Specify at least one of --text or --metadata.

Delete a memory unit

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

Audit messages and requests

View raw message records

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

View request audit records

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 is an alias for memory req-list. Use --operation to filter by operation type, such as AddMemories or SearchMemories.

Parameters

Parameter	Default	Description
`--limit`	`msg-list`: 200; `req-list`: 50	Number of results per page.
`--next-token`	—	Pagination token. See Pagination for pagination behavior.
`--operation`	—	Operation type filter. Only applies to `req-list`.