Using the memory store with the Node.js SDK - Tablestore

Install the SDK

Install the SDK with npm. Requires version 5.6.5 or later.

npm install tablestore@^5.6.5

Initialize the client

Initialize TableStore.Client with the instance endpoint, AccessKey pair, and instance name.

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

Parameters:

Parameter	Description
`endpoint`	The Tablestore instance endpoint. Format: `https://<instance>.<region>.ots.aliyuncs.com`.
`accessKeyId`	Your Alibaba Cloud or RAM user AccessKey ID.
`secretAccessKey`	Your Alibaba Cloud or RAM user AccessKey Secret.
`instancename`	The Tablestore instance name.

Create a memory store

Use createMemoryStore to create a memory store for agent long-term memories.

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

Secondary indexes are initialized asynchronously after creation. Write and search operations become available after indexing completes.

Write memories

Pass conversation messages in the messages field or preprocessed text in the text field. Both require a full scope: appId, tenantId, agentId, and runId.

Write conversation messages

Pass multi-turn conversations in messages. The service extracts long-term memories in the background.

await client.addMemories({
  memoryStoreName: "agent_memory",
  scope: {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "assistant",
    runId: "session-001",
  },
  messages: [
    { role: "user", content: "I like coffee." },
    { role: "assistant", content: "Got it. I've noted that." },
  ],
  metadata: {
    source: "chat",
  },
  sync: true,
});

Parameters:

Parameter	Description
`memoryStoreName`	The target memory store name.
`scope`	The memory scope. All four segments are required.
`messages`	Conversation messages, each with a `role` and `content` field.
`metadata`	Custom metadata for business tagging.
`sync`	Synchronous extraction. Default: `false`. When disabled, the API saves raw messages and returns immediately while extraction runs in the background.

Write text

Write preprocessed text directly as a memory, bypassing conversation extraction.

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

Search long-term memories

Use searchMemories to perform vector search within a scope. Use * for agentId and runId to search across agents and sessions.

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,
  enableRerank: true,
});

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

Parameters:

query: Search query text.
topK: Maximum results to return. Default: 10. Valid range: 1-50.
enableRerank: Enable reranking. Default: true.

Each entry in the results array contains a matched memory unit and a score. The unit object uses snake_case field names, as documented in Memory Storage API reference.

Manage long-term memories

List, get, update, and delete long-term memories. Single-memory operations require all four scope segments and do not support wildcards (*).

List memories

List memories matching a scope. agentId and runId support wildcards (*).

const result = await client.listMemories({
  memoryStoreName: "agent_memory",
  scope: {
    appId: "app-001",
    tenantId: "*",
    agentId: "*",
    runId: "*",
  },
  limit: 20,
});

Get a memory

Retrieve a memory by memoryId. All four scope segments are required.

const memory = await client.getMemory({
  memoryStoreName: "agent_memory",
  memoryId: "mem-001",
  scope: {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "assistant",
    runId: "session-001",
  },
});

Update a memory

Update a memory's text or metadata. All four scope segments are required.

await client.updateMemory({
  memoryStoreName: "agent_memory",
  memoryId: "mem-001",
  scope: {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "assistant",
    runId: "session-001",
  },
  text: "The user prefers coffee and concise answers.",
  metadata: {
    source: "manual",
  },
});

Delete a memory

Delete a memory. All four scope segments are required.

await client.deleteMemory({
  memoryStoreName: "agent_memory",
  memoryId: "mem-001",
  scope: {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "assistant",
    runId: "session-001",
  },
});

Query short-term memories

Short-term memories are raw conversation messages. All four scope segments (appId, tenantId, agentId, runId) are required. Wildcards (*) are not supported.

const messages = await client.listMemoryStoreMessages({
  memoryStoreName: "agent_memory",
  scope: {
    appId: "app-001",
    tenantId: "user-001",
    agentId: "assistant",
    runId: "session-001",
  },
  limit: 100,
});

Query request audit logs

Use listMemoryStoreRequests to query audit logs of memory store API calls. Filter by scope and operation type (operation).

const requests = await client.listMemoryStoreRequests({
  memoryStoreName: "agent_memory",
  scope: {
    appId: "app-001",
    tenantId: "*",
    agentId: "*",
    runId: "*",
  },
  operation: "AddMemories",
  limit: 50,
});

Parameters:

operation: The operation type, such as AddMemories or SearchMemories.
limit: Maximum entries to return.