Tablestore:Écrire et rappeler votre premier souvenir

Prérequis

• Vous avez créé une instance AgentStorage. Le magasin de mémoire sera créé dans cette instance.

• Vous disposez du nom AgentStorage, de l'endpoint et de la clé API.

Étape 1 : Installez le SDK

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

Étape 2 : Créez un client et un magasin de mémoire

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

Si vous ne spécifiez pas le type de magasin de mémoire, le système crée par défaut un magasin qui prend des messages en entrée et produit une mémoire structurée. Pour sélectionner explicitement la sortie, utilisez inputType et outputTypes. Vous ne pouvez pas modifier inputType après la création.

Étape 3 : Écrivez des 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", []))

Le service enregistre d'abord les messages bruts, puis extrait la mémoire à long terme. L'exemple utilise sync=True pour une vérification immédiate. Une fois l'écriture synchrone terminée, le tableau memoryIds de la réponse renvoie directement les ID de mémoire à long terme générés, ou un tableau vide si aucune mémoire à long terme n'est générée. En production, conservez généralement le mode asynchrone par défaut et utilisez le requestId de la réponse pour interroger la tâche d'extraction.

Étape 4 : Recherchez la mémoire à long terme entre les 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="*" effectue une recherche entre les sessions pour la même application, le même utilisateur et le même Agent. L'actualisation de l'index peut entraîner un bref délai ; si la première recherche après une écriture synchrone ne renvoie aucun résultat, réessayez plus tard.

Étape 5 : Transmettez les résultats à l'Agent

Sélectionnez uniquement quelques mémoires pertinentes pour la tâche actuelle afin de les ajouter au contexte du modèle. Par exemple :

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.

Ne concaténez pas l'intégralité du magasin de mémoire directement dans l'invite. Conservez l'ID de mémoire, le Scope et le score de chaque résultat pour le dépannage et l'audit.

Étapes suivantes

• En savoir plus sur les messages à court terme, la mémoire à long terme, le Scope et les tâches asynchrones : Memory Storage Service

• Utilisez TypeScript, CLI ou Dashboard : Agent Storage SDK, Command-line tool