快速开始

前提条件

• 已开通 Tablestore 服务并创建实例。当前记忆存储服务仅支持华北2（北京）地域。

• 已获取 AccessKey ID 与 AccessKey Secret，或已创建 API Key。API Key 创建方式参见API Key 管理。

通过命令行工具 Dashboard

命令行工具 tablestore-agent-cli 内置基于 Next.js 的 Web Dashboard，提供凭证配置、记忆库管理、记忆写入与检索调试的可视化界面，无需编码即可完成端到端的记忆库操作。

1. 安装命令行工具。要求 Node.js 18 及以上版本。

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

2. 启动 Dashboard。默认监听 127.0.0.1:3000。

   tablestore-agent-cli dashboard start

3. 在浏览器打开 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 个步骤。

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']}")

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 认证。

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']}")

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 生态集成。