Tous les produits
Search

Ce produit

    Tablestore:Structured memory

    Centre de documentation

    Tablestore:Structured memory

    Dernière mise à jour :Sep 25, 2026

    Gérez la mémoire à long terme dans un magasin de mémoire : écriture, recherche, récupération, liste, mise à jour et suppression.

    Prérequis

    • Un magasin de mémoire a été créé avec le type d'entrée messages et un type de sortie incluant structured. Consultez la rubrique Gestion des magasins de mémoire.

    • SDK Agent Storage installé : Python ≥ 1.0.10, TypeScript ≥ 0.0.13

    Écriture en mémoire

    Écrivez des messages de conversation ou du texte dans le magasin de mémoire. Le service enregistre les messages originaux sous forme de mémoire à court terme et extrait la mémoire à long terme structurée de manière asynchrone.

    • Le champ scope.appId est obligatoire et ne peut pas être défini sur * ; lorsque tenantId/agentId/runId sont vides, ils prennent la valeur __default__. Les caractères génériques ne sont pas autorisés lors des opérations d'écriture.

    • Le paramètre messages prend en charge jusqu'à 20 éléments pour une taille totale ≤ 32 000 octets ; vous pouvez également utiliser text (≤ 32 000 octets), mais pas les deux simultanément.

    • Par défaut, l'opération est asynchrone (sync=false) : les messages originaux sont immédiatement disponibles pour interrogation, tandis que la mémoire structurée est générée en arrière-plan. Enregistrez l'identifiant requestId renvoyé et appelez GetMemoryTask pour suivre la tâche d'extraction.

    • Les magasins de mémoire incluant la sortie file ne prennent en charge que les écritures asynchrones ; sync=true s'applique uniquement aux magasins sans sortie file, sinon l'erreur INVALID_PARAMETER est renvoyée.

    Console

    1. Connectez-vous à la console Agent Storage, ouvrez le magasin de mémoire cible, accédez à la page Long-term memory et cliquez sur Write memory.

    2. Renseignez le champ Scope (application, locataire, agent, session).

    3. Saisissez les messages de conversation (rôle + contenu) ou du texte brut.

    4. Cliquez sur OK. Le service extrait la mémoire structurée de manière asynchrone.

    SDK

    Python

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

    TypeScript

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

    API

    Appelez AddMemories pour écrire en mémoire. Pour connaître l'ensemble des champs, consultez la rubrique Écriture de mémoires.

    Recherche en mémoire

    Utilisez le langage naturel pour rechercher dans la mémoire structurée et les fichiers de mémoire générés par le service. Les résultats sont triés par pertinence.

    • La recherche cible la mémoire structurée et les fichiers de mémoire générés par le service ; la mémoire de fichier gérée directement n'est pas incluse dans le périmètre de recherche (lisez-la via le chemin indiqué dans la rubrique Mémoire de fichier ou créez-en une via la rubrique Compilation des connaissances (Wiki)).

    • Le paramètre query prend en charge jusqu'à 8 192 caractères Unicode ; scope.appId est obligatoire et ne peut pas être défini sur *. Les autres champs doivent être explicitement définis sur * pour agir comme des caractères génériques.

    Console

    1. Ouvrez le magasin de mémoire cible, accédez à la page Memory search et définissez des valeurs spécifiques pour l'application et le locataire (l'agent et la session peuvent être définis sur « All »).

    2. Saisissez le texte de requête dans le champ Search query, définissez la valeur Top K et, si nécessaire, enable reranking ou développez l'option Advanced search.

    3. Cliquez sur Search. Les résultats s'affichent par catégorie (mémoire structurée, mémoire de fichier et preuves de recherche), incluant le score de pertinence, le score de similarité et la méthode de rappel.

    SDK

    Python

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

    TypeScript

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

    API

    Appelez SearchMemories pour rechercher en mémoire. Pour connaître l'ensemble des champs, consultez la rubrique Recherche de mémoires.

    Liste des mémoires

    Parcourez la liste de la mémoire à long terme selon un Scope spécifié, page par page.

    • Le paramètre scope prend en charge la correspondance par préfixe gauche (le côté droit doit également être * ou vide) ; une seule requête analyse jusqu'à 100 Scopes.

    • La valeur par défaut de limit est 50 et prend en charge un maximum de 100 ; nextToken doit être utilisé avec la même combinaison scope + filter.

    Console

    Sur la page Long-term memory, définissez le Scope. La liste affiche le contenu de la mémoire, le type, l'heure de création et les actions.

    SDK

    Python

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

    TypeScript

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

    API

    Appelez ListMemories pour lister la mémoire. Pour connaître l'ensemble des champs, consultez la rubrique Liste des mémoires.

    Récupération d'une mémoire

    Récupérez les détails d'une mémoire à long terme spécifiée.

    Console

    Dans la liste Long-term memory, cliquez sur View pour la mémoire cible afin de consulter son ID, son contenu, son texte de recherche, son Scope, son type, sa saillance et sa version.

    SDK

    Python

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

    TypeScript

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

    API

    Appelez GetMemory pour récupérer la mémoire. Pour connaître l'ensemble des champs, consultez la rubrique Interrogation de la mémoire.

    Mise à jour d'une mémoire

    Mettez à jour le texte, les métadonnées et d'autres champs d'une mémoire à long terme spécifiée.

    • Le champ metadata est mis à jour par écrasement ; transmettre {} efface toutes les métadonnées.

    • Les paramètres effectiveAt et timePrecision doivent être transmis conjointement.

    Console

    La console ne permet pas de modifier individuellement la mémoire à long terme. Utilisez le SDK ou l'API pour effectuer les mises à jour.

    SDK

    Python

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

    TypeScript

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

    API

    Appelez UpdateMemory pour mettre à jour la mémoire. Pour connaître l'ensemble des champs, consultez la rubrique Mise à jour d'une mémoire.

    Suppression d'une mémoire

    Important

    La suppression d'une seule mémoire à long terme est irréversible.

    Console

    La console ne permet pas de supprimer individuellement la mémoire à long terme. Utilisez le SDK ou l'API pour effectuer la suppression. Pour effacer toutes les données d'un magasin, supprimez l'intégralité du magasin de mémoire.

    SDK

    Python

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

    TypeScript

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

    API

    Appelez DeleteMemory pour supprimer la mémoire. Pour connaître l'ensemble des champs, consultez la rubrique Suppression de la mémoire.

    Documents connexes