Install and use tablestore-agent-cli for Knowledge Base and Memory - Tablestore

tablestore-agent-cli is the command-line tool for Knowledge Base and Memory (memory store). Use it to manage Knowledge Base and Memory resources.

Installation

Install the CLI globally from the npm registry.

Prerequisite: Node.js 18 or later.

npm install -g @tablestore/tablestore-agent-cli --registry=https://registry.npmjs.org/
tablestore-agent-cli version

npm package: https://www.npmjs.com/package/@tablestore/tablestore-agent-cli.

Configuration

Use the configure set command to save access credentials and resource settings. You can also configure the CLI from the Dashboard — see the Dashboard section for details.

Required: AccessKey

Configure the AccessKey ID and AccessKey Secret for your Alibaba Cloud account. To obtain an AccessKey, see Create an AccessKey.

tablestore-agent-cli configure set access_key_id 'LTAI5t...'
tablestore-agent-cli configure set access_key_secret 'xxx'

Optional configuration

Configure the following resources as needed.

Tablestore instance

tablestore-agent-cli configure set ots_endpoint 'https://xxx.cn-beijing.ots.aliyuncs.com'
tablestore-agent-cli configure set ots_instance_name 'xxx'

If no Tablestore instance is configured, the CLI automatically creates and reuses a managed instance. For details, see Managed instance auto-creation.

To specify a region, configure region:

tablestore-agent-cli configure set region 'cn-beijing'

OSS bucket

Only the document upload feature of Knowledge Base requires an OSS bucket.

Note

Knowledge Base requires read and write permissions on the OSS bucket. To grant them, click Authorize Tablestore to access OSS.

tablestore-agent-cli configure set oss_endpoint 'https://oss-cn-hangzhou.aliyuncs.com'
tablestore-agent-cli configure set oss_bucket_name 'my-bucket'

Memory default scope

After you configure the default scope for Memory, you can omit the corresponding parameters in Memory commands.

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'

Verify connectivity

Run the doctor command to check the configuration and connectivity.

tablestore-agent-cli doctor          # Full diagnosis
tablestore-agent-cli doctor kb       # Knowledge Base only
tablestore-agent-cli doctor memory   # Memory only

Each check returns pass, warn, fail, or skip. The exit code is 0 when all checks pass, and 1 when any check fails.

If a required Tablestore instance or OSS bucket is not configured, doctor automatically creates and reuses a managed one. For details, see Managed instance auto-creation.

Examples

After you install and configure the CLI, run the following commands to explore the core capabilities of Knowledge Base and Memory.

Knowledge Base example: create a knowledge base and upload a document

# Create a knowledge base
tablestore-agent-cli kb create --name my_kb --description "Product documentation knowledge base"

# Add a local document
tablestore-agent-cli kb doc-add --kb my_kb --file ./report.pdf

# Semantic search
tablestore-agent-cli kb retrieve --kb my_kb --query "System architecture design"

Memory example: write and retrieve a memory

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

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

# Retrieve memories
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

Dashboard

The CLI includes a web Dashboard that you can use to configure the CLI, manage Knowledge Base and Memory resources, and debug retrieval.

Start the Dashboard

tablestore-agent-cli dashboard start                     # Listens on 127.0.0.1:3000 by default
tablestore-agent-cli dashboard start -p 9999             # Custom port
tablestore-agent-cli dashboard start --host 0.0.0.0      # Custom bind address

After the Dashboard starts, open the address shown in the terminal in a browser.

Memory scope selection rules

After you open a memory store in the Dashboard, the default scope is */*/*/*. This scope supports only two operations: list all long-term memories and request audit.

To retrieve memories, specify AppId and TenantId. AgentId and RunId accept a specific value or the wildcard *.

To add a memory, specify a value for each of AppId, TenantId, AgentId, and RunId.

Advanced configuration

Configuration file location

The configuration file is stored at ~/.config/tablestore-agent-cli/config.toml.

Environment variables

Environment variables take precedence over the configuration file.

Environment variable	Configuration key
`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_OSS_ENDPOINT`	`oss_endpoint`
`TABLESTORE_OSS_BUCKET_NAME`	`oss_bucket_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`

Managed instance auto-creation

If ots_endpoint and ots_instance_name are not configured, the CLI automatically creates and reuses a managed Tablestore instance in the Beijing region. The instance is created the first time you run doctor or invoke a command that requires an instance. The managed instance uses a public endpoint and is created asynchronously. The CLI caches the result in the [managed_ots] section of the configuration file so subsequent commands reuse the same instance. When you set an explicit target, the managed cache is cleared automatically.

OSS buckets behave the same way. They are created on demand during upload flows such as doctor kb or kb doc-add, and are cached in the [managed_oss] section of the configuration file.

Multi-instance management

You can save multiple named instances in a single configuration file and switch between them with the CLI or the switcher at the top of the Dashboard.

# Configure the AccessKey for a specific instance
tablestore-agent-cli configure set --instance prod access_key_id 'LTAI...'

# Switch the active instance
tablestore-agent-cli configure use prod

# Show the current configuration
tablestore-agent-cli configure show

Use named instances to switch between environments such as production, staging, and testing.