Quick start

Console

The AgentStorage console provides a visual interface for creating a memory store, adding and retrieving memories, viewing short-term and long-term memories, and organizing memories with Dream — no coding required.

Log on to the AgentStorage console, select a region, and create an AgentStorage instance. You can then create a memory store and add and retrieve memories in the console.

For the complete procedure, see Console guide.

CLI

Use the CLI to configure credentials, manage memory stores, add memories, and verify retrieval from the command line.

1. Install the CLI. Node.js 18 or later is required.

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

2. Configure AccessKey credentials, the region, and the Tablestore instance.

   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'
   tablestore-agent-cli configure set ots_endpoint 'https://<instance>.cn-beijing.ots.aliyuncs.com'
   tablestore-agent-cli configure set ots_instance_name '<instance-name>'

3. Diagnose the Memory Storage configuration and connectivity.

   tablestore-agent-cli doctor memory

4. Create a structured memory store.

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

5. Add a memory and wait for memory extraction to finish.

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

6. Retrieve long-term memories. Set agentId and runId to * to search across 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 beverages does the user like?" \
     --top-k 5

7. View short-term memories for the current session. Short-term memory queries require the complete four-level Scope and do not support wildcards.

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

--sync waits for memory extraction to finish. Index visibility might be delayed. If the first search returns no results, try again later.

For more CLI commands and memory store operations, see Agent Storage CLI and Memory store operations.

Agent Storage SDK

The following Python and TypeScript examples use an API key to initialize the client, create a memory store, add a memory, and run a search.

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 a memory store
client.create_memory_store({"memoryStoreName": "agent_memory"})

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

# 3. Run a 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 a memory store
await client.createMemoryStore({ memoryStoreName: 'agent_memory' });

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

// 3. Run a 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}`);
}

Tablestore native SDK

Tablestore native SDKs are available for Python and Node.js. Use them to add Memory Storage to existing Tablestore applications. The native SDKs currently support only AccessKey authentication.

pip install tablestore

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 a memory store
client.create_memory_store({"memoryStoreName": "agent_memory"})

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

# 3. Run a 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

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>",
});

async function main() {
  const scope = {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "assistant",
    runId: "session-001",
  };

  await client.createMemoryStore({ memoryStoreName: "agent_memory" });

  await client.addMemories({
    memoryStoreName: "agent_memory",
    scope,
    text: "The user enjoys 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.score.toFixed(4)}] ${item.unit.text}`);
  }
}

main().catch(console.error);

For more information about the native SDKs, see Python SDK and Node.js SDK.

AI agent framework

To use Memory Storage with AI agent frameworks such as OpenClaw, Hermes, and Claude, install the corresponding plugin. The plugin lets the agent read from and write to memory stores without manual SDK calls.

For integration steps, see Agent ecosystem integration.