Quick start

Install the CLI

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

Configure credentials

tablestore-agent-cli configure set access_key_id '<AccessKey ID>'
tablestore-agent-cli configure set access_key_secret '<AccessKey Secret>'
tablestore-agent-cli configure set region 'cn-beijing'

If you already have a Tablestore instance, set the instance endpoint and name:

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 automatically creates and reuses a managed Tablestore instance when needed.

Verify the configuration

tablestore-agent-cli doctor memory

Create a memory store

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

After the memory store is created, wait about 1 minute for index initialization before writing or searching memory.

Write a memory

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 and prefers concise responses" \
  --sync

--sync waits for memory extraction to complete before returning. In production, omit this flag to use the default asynchronous write.

Search long-term memory

appId and tenantId are required for all long-term memory searches. Set agentId and runId to * to search across all agents and sessions.

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

View short-term memory

Short-term memory returns raw conversation messages. All four scope levels — appId, tenantId, agentId, and runId — are required. Wildcards (*) are not allowed.

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

Install the SDK

pip install "tablestore>=6.4.5"

Sample code

The following example uses create_memory_store, add_memories, and search_memories. All scope fields (appId, tenantId, agentId, runId) identify the conversation context. During search, appId and tenantId are required; set agentId and runId to "*" to search across all agents and sessions.

import os
from tablestore import OTSClient

client = OTSClient(
    "https://<instance>.cn-beijing.ots.aliyuncs.com",
    os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_ID"),
    os.environ.get("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
    "<instance-name>",
)

client.create_memory_store({
    "memoryStoreName": "agent_memory",
    "description": "Agent long-term memory store",
})

client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "app-001",
        "tenantId": "user-001",
        "agentId": "assistant",
        "runId": "session-001",
    },
    "messages": [
        {"role": "user", "content": "I like drinking coffee"},
        {"role": "assistant", "content": "OK, I'll remember that"},
    ],
    "sync": True,
})

result = client.search_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "app-001",
        "tenantId": "user-001",
        "agentId": "*",
        "runId": "*",
    },
    "query": "What beverages does the user like",
    "topK": 5,
})

for item in result.get("results", []):
    print(item["unit"]["text"], item["score"])

The search result for this example looks similar to:

The user likes coffee. 0.87

Each result includes the extracted memory text and its relevance score.

Install the SDK

npm install tablestore@^5.6.5

Sample code

The following example uses createMemoryStore, addMemories, and searchMemories. During search, appId and tenantId are required; set agentId and runId to "*" to search across all agents and sessions.

const TableStore = require("tablestore");

const client = new TableStore.Client({
  accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
  secretAccessKey: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
  endpoint: "https://<instance>.cn-beijing.ots.aliyuncs.com",
  instancename: "<instance-name>",
});

async function main() {
  await client.createMemoryStore({
    memoryStoreName: "agent_memory",
    description: "Agent long-term memory store",
  });

  await client.addMemories({
    memoryStoreName: "agent_memory",
    scope: {
      appId: "app-001",
      tenantId: "user-001",
      agentId: "assistant",
      runId: "session-001",
    },
    text: "The user likes coffee and prefers concise responses",
    sync: true,
  });

  const result = await client.searchMemories({
    memoryStoreName: "agent_memory",
    scope: {
      appId: "app-001",
      tenantId: "user-001",
      agentId: "*",
      runId: "*",
    },
    query: "What beverages does the user like",
    topK: 5,
  });

  for (const item of result.results || []) {
    console.log(item.unit.text, item.score);
  }
}

main().catch(console.error);

The search result for this example looks similar to:

The user likes coffee and prefers concise responses. 0.87

Each result includes the extracted memory text and its relevance score.