Tablestore:Agent Storage SDK

Differences from Tablestore SDK

Agent Storage SDK is separate from Tablestore SDK and focuses on agent storage. The following table lists the key differences.

Installation and configuration

pip install tablestore-agent-storage

npm install @tablestore/agent-storage

from tablestore_agent_storage import AgentStorageClient

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

resp = client.list_memory_stores({})
for store in resp["stores"]:
    print(store["memoryStoreName"])

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

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

const resp = await client.listMemoryStores({});
for (const store of resp.stores) {
  console.log(store.memoryStoreName);
}

curl -X POST 'https://<instance>.<region>.ots.aliyuncs.com/ListMemoryStores' \
  -H 'x-ots-instancename: <instance-name>' \
  -H 'x-ots-apikey: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{}'

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    access_key_id="<AccessKey ID>",
    access_key_secret="<AccessKey Secret>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
    # Configure OSS to use Knowledge Base features
    oss_endpoint="https://oss-<region>.aliyuncs.com",
    oss_bucket_name="<bucket-name>",
)

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

const client = new AgentStorageClient({
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
  accessKeyId: process.env.OTS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OTS_ACCESS_KEY_SECRET,
});

Knowledge Base examples

Knowledge Base automatically chunks and vectorizes documents and supports hybrid retrieval for enterprise question answering and retrieval-augmented generation (RAG). Source documents are stored in OSS, while Tablestore handles chunk indexing and retrieval. Configure OSS and Tablestore before use.

If you do not specify an embedding model when you create a knowledge base, the SDK uses Alibaba Cloud Model Studio text-embedding-v4 with 1,024 dimensions. Hybrid retrieval, which combines vector search and full-text search, is enabled by default.

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    access_key_id="<AccessKey ID>",
    access_key_secret="<AccessKey Secret>",
    oss_endpoint="https://oss-<region>.aliyuncs.com",
    oss_bucket_name="<bucket-name>",
    ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
    ots_instance_name="<instance-name>",
)

# 1. Create a knowledge base. The default embedding model is Model Studio
#    text-embedding-v4, and the default retrieval method is hybrid retrieval.
client.create_knowledge_base({
    "knowledgeBaseName": "product_kb",
    "description": "Product knowledge base",
})

# 2. Upload local documents. The SDK uploads files to OSS before chunking
#    and vectorization.
client.upload_documents({
    "knowledgeBaseName": "product_kb",
    "documents": [
        {
            "documentId": "doc-guide-001",
            "filePath": "./docs/product-overview.txt",
        },
        {
            "documentId": "doc-guide-002",
            "filePath": "./docs/sdk-intro.txt",
        },
    ],
})

# 3. List documents in the knowledge base
resp = client.list_documents({
    "knowledgeBaseName": "product_kb",
    "maxResults": 10,
})
for doc in resp["data"]["documentDetails"]:
    print(doc.get("documentId"), doc.get("ossKey"), doc.get("status"))

# 4. Retrieve documents
from tablestore_agent_storage.models import RetrieveRequest, RetrievalQuery

req = RetrieveRequest(
    knowledge_base_name="product_kb",
    retrieval_query=RetrievalQuery(text="What is Agent Storage SDK used for?"),
)
result = client.retrieve(req)
for hit in result["data"]["retrievalResults"]:
    print(hit)

# 5. Delete documents
client.delete_documents({
    "knowledgeBaseName": "product_kb",
    "documents": [{"documentId": "doc-guide-001"}],
})

# 6. Delete the knowledge base
client.delete_knowledge_base({"knowledgeBaseName": "product_kb"})

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

const client = new NodeAgentStorageClient({
  accessKeyId: '<AccessKey ID>',
  accessKeySecret: '<AccessKey Secret>',
  endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
  instanceName: '<instance-name>',
  ossEndpoint: 'https://oss-<region>.aliyuncs.com',
  ossBucketName: '<bucket-name>',
  ossAccessKeyId: '<AccessKey ID>',
  ossAccessKeySecret: '<AccessKey Secret>',
});

// 1. Create a knowledge base. The default embedding model is Model Studio
//    text-embedding-v4, and the default retrieval method is hybrid retrieval.
await client.createKnowledgeBase({
  knowledgeBaseName: 'product_kb',
  description: 'Product knowledge base',
});

// 2. Upload local documents. The SDK uploads files to OSS before chunking
//    and vectorization. The service generates docId during upload. The
//    TypeScript SDK does not accept a custom documentId.
await client.uploadDocuments({
  knowledgeBaseName: 'product_kb',
  documents: [
    { filePath: './docs/product-overview.txt' },
    { filePath: './docs/sdk-intro.txt' },
  ],
});

// 3. List documents in the knowledge base
const resp = await client.listDocuments({
  knowledgeBaseName: 'product_kb',
  maxResults: 10,
});
for (const doc of resp.data.documentDetails) {
  console.log(doc.docId, doc.ossKey, doc.status);
}

// 4. Retrieve documents
const result = await client.retrieve({
  knowledgeBaseName: 'product_kb',
  retrievalQuery: { text: 'What is Agent Storage SDK used for?' },
});
for (const hit of result.data.retrievalResults) {
  console.log(hit);
}

// 5. Delete documents by the ossKey returned in the previous step
await client.deleteDocuments({
  knowledgeBaseName: 'product_kb',
  documents: [{ ossKey: '<oss-key-from-list>' }],
});

// 6. Delete the knowledge base
await client.deleteKnowledgeBase({ knowledgeBaseName: 'product_kb' });

Document chunking and vectorization run asynchronously after upload. Query the status field with list_documents (listDocuments in TypeScript) to check indexing progress.

Memory Store examples

Memory Store persists multi-turn conversation memories for AI agents and supports vector-based semantic retrieval. SDK methods correspond to REST API operations. Python methods use snake_case, TypeScript methods use camelCase, and parameters match the API specification.

# 1. Create a memory store
client.create_memory_store({
    "memoryStoreName": "agent_memory",
    "description": "Long-term memory store for agents",
    "extractInstructions": "Focus on the user's dietary preferences and travel habits",
})

# 2. Write memories
client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "app-001",
        "tenantId": "user-001",
        "agentId": "assistant",
        "runId": "session-001",
    },
    "messages": [
        {"role": "user", "content": "I like Americano coffee"},
    ],
    "sync": True,
})

# 3. Search memories
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,
    "includeEvidence": True,
    "minSimilarity": 0.3,
})
for hit in result["data"]["memories"]:
    print(hit["content"], hit["similarity"])

# 4. List scopes in the memory store
scopes = client.list_memory_store_scopes({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "app-001",
        "tenantId": "*",
        "agentId": "*",
        "runId": "*",
    },
})
for scope in scopes["scopes"]:
    print(scope)

# 5. List memory stores
resp = client.list_memory_stores({})
for store in resp["stores"]:
    print(store["memoryStoreName"])

// 1. Create a memory store
await client.createMemoryStore({
  memoryStoreName: 'agent_memory',
  description: 'Long-term memory store for agents',
});

// 2. Write memories
await client.addMemories({
  memoryStoreName: 'agent_memory',
  scope: {
    appId: 'app-001',
    tenantId: 'user-001',
    agentId: 'assistant',
    runId: 'session-001',
  },
  messages: [{ role: 'user', content: 'I like Americano coffee' }],
  sync: true,
});

// 3. Search memories
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,
  includeEvidence: true,
});
for (const hit of result.data.memories) {
  console.log(hit.content, hit.similarity);
}

// 4. List scopes in the memory store
const scopes = await client.listMemoryStoreScopes({
  memoryStoreName: 'agent_memory',
  scope: { appId: 'app-001', tenantId: '*', agentId: '*', runId: '*' },
});
for (const scope of scopes.scopes) {
  console.log(scope);
}

The SDK also provides methods for updating and deleting memory stores, getting and updating individual memories, querying asynchronous tasks, and consolidating memories with Dream. For all operations and parameters, see Memory Storage API.

File memory examples

File memory organizes long-term context by file path and can store user profiles, conversation summaries, and agent work files. The SDK automatically adds the memoryfile type required by Item APIs. Specify only the memory store, scope, path, and content.

All file operations require a complete four-level scope with appId, tenantId, agentId, and runId. The * wildcard is not supported.

The following examples assume that the client is initialized.

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

client.create_memory_store({
    "memoryStoreName": "agent_files",
    "storageMode": "filemem",
})

created = client.add_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "content": "# User preferences\n\n- Likes Americano coffee\n",
})

page = client.list_items({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "pathPrefix": "/profile/",
})

current = client.get_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "includeContent": False,
})

updated = client.update_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "content": "# User preferences\n\n- Likes latte\n",
    "expectedSha256": current["contentSha256"],
})

renamed = client.update_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "newPath": "/profile/user-preferences.md",
    "expectedSha256": updated["contentSha256"],
})

versions = client.list_item_versions({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "itemId": created["itemId"],
    "limit": 20,
})
version = versions["versions"][0]

snapshot = client.get_item_version({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "itemId": version["itemId"],
    "versionId": version["versionId"],
    "versionSeq": version["versionSeq"],
})

client.redact_item_version({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "itemId": version["itemId"],
    "versionId": version["versionId"],
    "versionSeq": version["versionSeq"],
    "sessionId": "privacy-job-001",
})

client.delete_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/user-preferences.md",
    "expectedSha256": renamed["contentSha256"],
})

print(page["items"], snapshot.get("content"))

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

await client.createMemoryStore({
  memoryStoreName: 'agent_files',
  storageMode: 'filemem',
});

const created = await client.addItem({
  memoryStoreName: 'agent_files',
  scope,
  path: '/profile/preferences.md',
  content: '# User preferences\n\n- Likes Americano coffee\n',
});

const page = await client.listItems({
  memoryStoreName: 'agent_files',
  scope,
  pathPrefix: '/profile/',
});

const current = await client.getItem({
  memoryStoreName: 'agent_files',
  scope,
  path: '/profile/preferences.md',
  includeContent: false,
});

const updated = await client.updateItem({
  memoryStoreName: 'agent_files',
  scope,
  path: '/profile/preferences.md',
  content: '# User preferences\n\n- Likes latte\n',
  expectedSha256: current.contentSha256,
});

const renamed = await client.updateItem({
  memoryStoreName: 'agent_files',
  scope,
  path: '/profile/preferences.md',
  newPath: '/profile/user-preferences.md',
  expectedSha256: updated.contentSha256,
});

const versions = await client.listItemVersions({
  memoryStoreName: 'agent_files',
  scope,
  itemId: created.itemId,
  limit: 20,
});
const version = versions.versions[0];

const snapshot = await client.getItemVersion({
  memoryStoreName: 'agent_files',
  scope,
  itemId: version.itemId,
  versionId: version.versionId,
  versionSeq: version.versionSeq,
});

await client.redactItemVersion({
  memoryStoreName: 'agent_files',
  scope,
  itemId: version.itemId,
  versionId: version.versionId,
  versionSeq: version.versionSeq,
  sessionId: 'privacy-job-001',
});

await client.deleteItem({
  memoryStoreName: 'agent_files',
  scope,
  path: '/profile/user-preferences.md',
  expectedSha256: renamed.contentSha256,
});

console.log(page.items, snapshot.content);

expectedSha256 is an optional concurrency-control parameter. If multiple callers might modify the same path, pass the latest contentSha256. If the digest does not match, read the latest file before deciding whether to retry.

File view examples

After you create a memory store in file+ots mode, use structured memory APIs to write, search, and update memories. Item APIs provide read access to service-generated file views.

client.create_memory_store({
    "memoryStoreName": "agent_memory",
    "storageMode": "file+ots",
})

List files with a complete scope and read file content by path.

page = client.list_items({
    "memoryStoreName": "agent_memory",
    "scope": scope,
})

for entry in page["items"]:
    item = client.get_item({
        "memoryStoreName": "agent_memory",
        "scope": scope,
        "path": entry["path"],
    })
    print(item["path"], item["content"])