記憶儲存服務快速開始：Dashboard、SDK 與 Agent 四種接入方式 - Tablestore

通過命令列工具 Dashboard、Agent Storage SDK、Tablestore 原生 SDK 或 AI Agent 生態快速接入記憶儲存服務，為 AI Agent 構建長期記憶與語義檢索能力。

前提條件

已開通 Tablestore 服務並建立執行個體。當前記憶儲存服務僅支援華北2（北京）地區。
已擷取 AccessKey ID 與 AccessKey Secret，或已建立 API Key。API Key 建立方式參見API Key 管理。

通過命令列工具 Dashboard

命令列工具 tablestore-agent-cli 內建基於 Next.js 的 Web Dashboard，提供憑證配置、記憶庫管理、記憶寫入與檢索調試的可視化介面，無需編碼即可完成端到端的記憶庫操作。

安裝命令列工具。要求 Node.js 18 及以上版本。

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

啟動 Dashboard。預設監聽 127.0.0.1:3000。
```
tablestore-agent-cli dashboard start
```
在瀏覽器開啟 http://127.0.0.1:3000，在 Dashboard 介面中完成以下操作：
- 配置 Tablestore 訪問憑證（AccessKey 或 API Key）。
- 建立記憶庫、寫入記憶、執行語義檢索。

如需通過命令列完成上述操作或使用更多進階功能（例如 Scope 隔離、記憶整理 Dream、審計查詢等），參見命令列工具和記憶庫操作。

通過 Agent Storage SDK

Agent Storage SDK 提供 Python 與 TypeScript 兩種語言，使用 API Key 認證，無需管理 AccessKey 金鑰組。以下最簡樣本展示如何完成建立記憶庫、寫入記憶、執行檢索這 3 個步驟。

Python

安裝 SDK：

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. 建立記憶庫
client.create_memory_store({"memoryStoreName": "agent_memory"})

# 2. 寫入記憶
client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": scope,
    "text": "使用者喜歡喝咖啡，偏好簡潔的回答風格",
    "sync": True,
})

# 3. 執行語義檢索
result = client.search_memories({
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "*", "runId": "*"},
    "query": "使用者喜歡什麼飲品",
    "topK": 5,
})
for item in result.get("results", []):
    unit = item["unit"]
    print(f"[{item['score']:.4f}] {unit['text']}")

TypeScript

安裝 SDK：

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. 建立記憶庫
await client.createMemoryStore({ memoryStoreName: 'agent_memory' });

// 2. 寫入記憶
await client.addMemories({
  memoryStoreName: 'agent_memory',
  scope,
  text: '使用者喜歡喝咖啡，偏好簡潔的回答風格',
  sync: true,
});

// 3. 執行語義檢索
const result: any = await client.searchMemories({
  memoryStoreName: 'agent_memory',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: '*', runId: '*' },
  query: '使用者喜歡什麼飲品',
  topK: 5,
});
for (const item of result.results ?? []) {
  console.log(`[${item.score.toFixed(4)}] ${item.unit.text}`);
}

完整 SDK 用法（Scope 隔離、Rerank 重排、記憶整理 Dream、非同步任務等），參見Agent Storage SDK。

通過 Tablestore 原生 SDK

Tablestore 原生 SDK 提供 Python 與 Node.js 兩種語言，將記憶儲存能力與已有的 Tablestore 應用整合。原生 SDK 目前僅支援 AccessKey 認證。

Python

安裝 SDK（要求 tablestore 版本 6.4.7 及以上）：

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. 建立記憶庫
client.create_memory_store({"memoryStoreName": "agent_memory"})

# 2. 寫入記憶
client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": scope,
    "text": "使用者喜歡喝咖啡，偏好簡潔的回答風格",
    "sync": True,
})

# 3. 執行語義檢索
result = client.search_memories({
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "*", "runId": "*"},
    "query": "使用者喜歡什麼飲品",
    "topK": 5,
})
for item in result.get("results", []):
    unit = item["unit"]
    print(f"[{item['score']:.4f}] {unit['text']}")

Node.js

安裝 SDK（要求 tablestore 版本 5.6.5 及以上）：

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. 建立記憶庫
await client.createMemoryStore({ memoryStoreName: "agent_memory" });

// 2. 寫入記憶
await client.addMemories({
  memoryStoreName: "agent_memory",
  scope,
  text: "使用者喜歡喝咖啡，偏好簡潔的回答風格",
  sync: true,
});

// 3. 執行語義檢索
const result = await client.searchMemories({
  memoryStoreName: "agent_memory",
  scope: { appId: "app-001", tenantId: "user-001", agentId: "*", runId: "*" },
  query: "使用者喜歡什麼飲品",
  topK: 5,
});
for (const item of result.results ?? []) {
  console.log(`[${item.score.toFixed(4)}] ${item.unit.text}`);
}

完整原生 SDK 用法參見Python SDK 使用介紹和Node.js SDK 使用介紹。

接入 AI Agent 架構

如果在 OpenClaw、Hermes、Claude 等 AI Agent 架構中使用記憶儲存，可通過對應外掛程式讓 Agent 直接讀寫記憶庫，無需手動編寫 SDK 調用代碼。

各架構的詳細整合步驟參見Agent 生態整合。