Tablestore:Quick start

Prerequisites

Before you begin, make sure that you have:

• A Tablestore instance in the China (Beijing) region — the only region where Tablestore Agent Memory is currently available

• AccessKey credentials (an AccessKey ID and an AccessKey Secret), or an API key (to create an API key, see API key management)

Use the CLI Dashboard

The tablestore-agent-cli command-line tool includes a built-in Next.js Web Dashboard. Use the Dashboard to configure credentials, manage memory stores, and test memory writes and searches — no code required.

1. Install the CLI (requires Node.js 18 or later):

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

2. Start the Dashboard. It listens on 127.0.0.1:3000 by default.

   tablestore-agent-cli dashboard start

3. Open http://127.0.0.1:3000 in a browser and complete the following steps in the Dashboard:

   • Configure Tablestore access credentials (an AccessKey pair or an API key).

   • Create a memory store, add memories, and run a semantic search.

For command-line operations and advanced features such as Scope isolation, memory consolidation with Dream, and audit queries, see Agent Storage CLI and Memory store operations.

Use the Agent Storage SDK

The Agent Storage SDK is available for Python and TypeScript. It authenticates with an API key, so you do not need to manage AccessKey pairs. The following minimal examples cover the three core steps: create a memory store, add memories, and search memories.

pip install tablestore-agent-storage

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="<your-api-key>",
    ots_endpoint="https://<instance>.cn-beijing.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

scope = {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001",
}

# 1. Create memory store
client.create_memory_store({"memoryStoreName": "agent_memory"})

# 2. Add memory
client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": scope,
    "text": "The user enjoys coffee and prefers concise responses.",
    "sync": True,
})

# 3. Perform semantic search
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", []):
    unit = item["unit"]
    print(f"[{item['score']:.4f}] {unit['text']}")

npm install @tablestore/agent-storage

import { AgentStorageClient } from '@tablestore/agent-storage';

const client = new AgentStorageClient({
  apiKey: '<your-api-key>',
  endpoint: 'https://<instance>.cn-beijing.ots.aliyuncs.com',
  instanceName: '<instance-name>',
});

const scope = {
  appId: 'app-001',
  tenantId: 'user-001',
  agentId: 'assistant',
  runId: 'session-001',
};

// 1. Create memory store
await client.createMemoryStore({ memoryStoreName: 'agent_memory' });

// 2. Add memory
await client.addMemories({
  memoryStoreName: 'agent_memory',
  scope,
  text: 'The user enjoys coffee and prefers concise responses.',
  sync: true,
});

// 3. Perform semantic search
const result: any = 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.score.toFixed(4)}] ${item.unit.text}`);
}

For full SDK usage, including Scope isolation, Rerank reranking, memory consolidation with Dream, and asynchronous tasks, see Agent Storage SDK.

Use the Tablestore native SDK

The Tablestore native SDK is available for Python and Node.js. Use it to add long-term memory to existing Tablestore applications. The native SDK currently supports only AccessKey authentication.

pip install "tablestore>=6.4.7"

from tablestore import OTSClient

client = OTSClient(
    "https://<instance>.cn-beijing.ots.aliyuncs.com",
    "<AccessKey ID>",
    "<AccessKey Secret>",
    "<instance-name>",
)

scope = {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001",
}

# 1. Create memory store
client.create_memory_store({"memoryStoreName": "agent_memory"})

# 2. Add memory
client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": scope,
    "text": "The user enjoys coffee and prefers concise responses.",
    "sync": True,
})

# 3. Perform semantic search
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", []):
    unit = item["unit"]
    print(f"[{item['score']:.4f}] {unit['text']}")

npm install tablestore@^5.6.5

const TableStore = require("tablestore");

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

const scope = {
  appId: "app-001",
  tenantId: "user-001",
  agentId: "assistant",
  runId: "session-001",
};

// 1. Create memory store
await client.createMemoryStore({ memoryStoreName: "agent_memory" });

// 2. Add memory
await client.addMemories({
  memoryStoreName: "agent_memory",
  scope,
  text: "The user enjoys coffee and prefers concise responses.",
  sync: true,
});

// 3. Perform semantic search
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.score.toFixed(4)}] ${item.unit.text}`);
}

For full native SDK usage, see Python SDK and Node.js SDK.

Use an AI agent framework

To add long-term memory to an AI agent framework such as OpenClaw, Hermes, or Claude, install the plugin for that framework. The plugin lets the agent read from and write to the memory store directly, without writing SDK code.

For integration steps for each framework, see Agent ecosystem integration.