Tablestore:Structured memory

Prerequisites

• A memory store has been created with the input type messages and an output type that includes structured. See Memory store management.

• Agent Storage SDK installed: Python ≥ 1.0.10, TypeScript ≥ 0.0.13

Write memory

Write conversation messages or text to the memory store. The service saves the original messages as short-term memory and asynchronously extracts structured long-term memory.

• scope.appId is required and cannot be *; when tenantId/agentId/runId are empty, they are filled with __default__. Wildcard characters are not allowed in write operations.

• messages supports up to 20 items with a total size ≤ 32,000 bytes; alternatively, you can use text (≤ 32,000 bytes), but not both.

• By default, the operation is asynchronous (sync=false): original messages are immediately available for query, while structured memory is produced in the background. Save the returned requestId and call GetMemoryTask to track the extraction task.

• Memory stores that include file output only support asynchronous writes; sync=true only applies to stores without file output, otherwise the error INVALID_PARAMETER is returned.

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.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "app-001",
        "tenantId": "user-001",
        "agentId": "assistant",
        "runId": "session-001",
    },
    "messages": [
        {"role": "user", "content": "I like drinking Americano coffee"},
        {"role": "assistant", "content": "Got it. I've noted your preference."},
    ],
})

print(f"requestId: {resp.get('requestId')}, status: {resp.get('status')}")

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.addMemories({
  memoryStoreName: 'agent_memory',
  scope: {
    appId: 'app-001',
    tenantId: 'user-001',
    agentId: 'assistant',
    runId: 'session-001',
  },
  messages: [{ role: 'user', content: 'I like drinking Americano coffee' }],
});

console.log(resp.requestId, resp.status);

Search memory

Use natural language to search structured memory and service-generated memory files, returning results sorted by relevance.

• The search targets structured memory and service-generated memory files; directly managed file memory is not included in search scope (read via the path in File memory or create one via Knowledge compilation (Wiki)).

• query supports up to 8,192 Unicode characters; scope.appId is required and cannot be *. Other fields must be explicitly set to * to act as wildcards.

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

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,
    "enableRerank": True,
})

for hit in result.get("results", []):
    unit = hit.get("unit", {})
    print(f"[score={hit.get('score'):.4f}] {unit.get('text', '')[:80]}")

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 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 hit of result.results) {
  console.log(`[score=${hit.score.toFixed(4)}] ${hit.unit?.text?.slice(0, 80)}`);
}

List memory

Paginate through the long-term memory list under a specified Scope.

• scope supports left-prefix wildcard matching (the right side must also be * or empty); a single request scans up to 100 Scopes.

• limit defaults to 50 and supports a maximum of 100; nextToken must be used with the same scope + filter combination.

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_memories({
    "memoryStoreName": "agent_memory",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "*", "runId": "*"},
    "limit": 50,
})

for m in resp.get("memories", []):
    print(f"[{m.get('type_label')}] {m.get('text', '')[:60]} (id={m.get('id')})")

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.listMemories({
  memoryStoreName: 'agent_memory',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: '*', runId: '*' },
  limit: 50,
});

for (const m of resp.memories) {
  console.log(`[${m.type_label}] ${m.text?.slice(0, 60)} (id=${m.id})`);
}

Retrieve memory

Retrieve the details of a specified long-term memory.

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.get_memory({
    "memoryStoreName": "agent_memory",
    "memoryId": "<memory-id>",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001"},
})

m = resp.get("memory", {})
print(f"Type: {m.get('type_label')}, Content: {m.get('text')}, Salience: {m.get('salience')}")

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.getMemory({
  memoryStoreName: 'agent_memory',
  memoryId: '<memory-id>',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: 'assistant', runId: 'session-001' },
});

const m = resp.memory;
console.log(m.type_label, m.text, m.salience);

Update memory

Update the text, metadata, and other fields of a specified long-term memory.

• metadata is updated by overwrite; passing {} clears all metadata.

• effectiveAt and timePrecision must be passed together.

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

client.update_memory({
    "memoryStoreName": "agent_memory",
    "memoryId": "<memory-id>",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001"},
    "text": "The user likes drinking latte",
    "metadata": {"source": "profile"},
})

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

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

await client.updateMemory({
  memoryStoreName: 'agent_memory',
  memoryId: '<memory-id>',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: 'assistant', runId: 'session-001' },
  text: 'The user likes drinking latte',
  metadata: { source: 'profile' },
});

Delete memory

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

client.delete_memory({
    "memoryStoreName": "agent_memory",
    "memoryId": "<memory-id>",
    "scope": {"appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001"},
})

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

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

await client.deleteMemory({
  memoryStoreName: 'agent_memory',
  memoryId: '<memory-id>',
  scope: { appId: 'app-001', tenantId: 'user-001', agentId: 'assistant', runId: 'session-001' },
});

Related documents

• Memory store management

• Short-term memory

• File memory

• Memory Dream