:Agent Storage SDK

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' });

# 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);
}

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);