All Products
Search

This Product

    Tablestore:Write and recall your first memory

    Document Center

    Tablestore:Write and recall your first memory

    Last Updated:Sep 24, 2026

    This example uses the Python SDK to create a structured memory store, write a conversation, and recall the long-term memory extracted by the service across sessions.

    Prerequisites

    Step 1: Install the SDK

    pip install "tablestore-agent-storage>=1.0.10"

    Step 2: Create a client and memory store

    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.create_memory_store({
    "memoryStoreName": "agent_memory",
    "description": "Agent long-term memory",
})

    When the memory store type is not specified, a memory store that takes messages as input and outputs structured memory is created by default. To explicitly select the output, use inputType and outputTypes. inputType cannot be modified after creation.

    Step 3: Write messages

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

response = client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": scope,
    "messages": [
        {"role": "user", "content": "I usually drink Americanos, no sugar."},
        {"role": "assistant", "content": "Got it, I will remember your drink preference."},
    ],
    "sync": True,
})
print(response.get("memoryIds", []))

    The service first saves the raw messages, then extracts long-term memory. The example uses sync=True for immediate verification. After the synchronous write completes, the memoryIds array in the response directly returns the generated long-term memory IDs, and returns an empty array when no long-term memory is generated. Production writes typically keep the default asynchronous mode and use the requestId in the response to query the extraction task.

    Step 4: Search long-term memory across sessions

    response = client.search_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "shopping-app",
        "tenantId": "user-001",
        "agentId": "shopping-assistant",
        "runId": "*",
    },
    "query": "What are the user's coffee preferences?",
    "topK": 5,
})

for item in response.get("results", []):
    print(f"[{item['score']:.4f}] {item['unit']['text']}")

    runId="*" searches across sessions under the same application, user, and Agent. Index refresh may introduce a brief delay; if the first search after a synchronous write returns no results, try again later.

    Step 5: Pass results to the Agent

    Select only a small number of memories relevant to the current task to add to the model context. For example:

    Known user preferences:
- The user usually drinks Americanos, no sugar.

Answer the current question based on these preferences. If the memory conflicts with the current request, the user's explicit statement in this round takes precedence.

    Do not concatenate the entire memory store directly into the prompt. Keep the memory ID, Scope, and score of each result for troubleshooting and auditing.

    Next steps