Memory Storage HTTP JSON API reference - - Centre de documentation Alibaba Cloud

Memory Storage met à disposition 30 API via HTTP JSON pour la gestion des magasins de mémoire, des mémoires à long et court terme, des journaux d'audit, des tâches asynchrones, de la consolidation de mémoire (Dream), de la mémoire de fichiers et des vues de fichiers. Utilisez ces API pour des intégrations personnalisées sans recourir à un SDK.

Liste des API

Toutes les API sont regroupées par catégorie :

Gestion des magasins de mémoire

API

Description

CreateMemoryStore

Créez un magasin de mémoire.

GetMemoryStore

Consultez les détails d'un magasin de mémoire.

UpdateMemoryStore

Mettez à jour la description d'un magasin de mémoire.

DeleteMemoryStore

Supprimez un magasin de mémoire.

ListMemoryStores

Listez les magasins de mémoire.

Mémoire à long terme

API

Description

AddMemories

Écrivez des messages de conversation ou du texte pour générer des mémoires à long terme.

SearchMemories

Recherchez dans les mémoires à long terme.

ListMemories

Listez les mémoires à long terme.

GetMemory

Consultez une entrée de mémoire à long terme.

UpdateMemory

Mettez à jour une entrée de mémoire à long terme.

DeleteMemory

Supprimez une entrée de mémoire à long terme.

Mémoire à court terme et audit

API

Description

ListMemoryStoreMessages

Interrogez les mémoires à court terme (messages de conversation originaux).

ListMemoryStoreRequests

Interrogez les journaux d'audit des requêtes adressées au magasin de mémoire.

Tâches asynchrones et Scope

API

Description

GetMemoryTask

Interrogez l'état et le résultat d'une tâche d'extraction asynchrone.

ListMemoryTasks

Listez les tâches d'extraction asynchrones.

ListMemoryStoreScopes

Listez les Scopes présents dans un magasin de mémoire.

Consolidation de mémoire (Dream)

API

Description

CreateMemoryDreamTask

Créez une tâche de consolidation de mémoire.

GetMemoryDreamTask

Interrogez la progression d'une tâche de consolidation de mémoire.

ListMemoryDreamTasks

Listez les tâches de consolidation de mémoire.

ListMemoryDreamActions

Listez les actions proposées générées par une tâche de consolidation de mémoire.

ApplyMemoryDreamActions

Appliquez les actions de consolidation de mémoire proposées.

CancelMemoryDreamTask

Annulez une tâche de consolidation de mémoire.

Mémoire de fichiers et vues de fichiers

API

Description

AddItem

Ajoutez un fichier de mémoire.

ListItems

Listez les fichiers par préfixe de chemin avec pagination.

GetItem

Consultez le contenu du fichier ou uniquement ses métadonnées.

UpdateItem

Mettez à jour le contenu d'un fichier ou renommez-le.

DeleteItem

Supprimez un fichier.

ListItemVersions

Listez les versions historiques d'un fichier avec pagination.

GetItemVersion

Consultez une version historique d'un fichier.

RedactItemVersion

Censurez de manière irréversible une version historique d'un fichier.

Objets communs

Structures de données partagées entre les requêtes et les réponses des API.

Scope

Un Scope définit la hiérarchie de propriété des données de mémoire.

Champ

Type

Description

appId

string

L'identifiant de l'application.

tenantId

string

L'identifiant du locataire ou de l'utilisateur.

agentId

string

L'identifiant de l'agent.

runId

string

L'identifiant de la session, de l'exécution ou de la tâche.

Les champs Scope requis et la prise en charge du caractère générique * varient selon l'API.

Scénario

Champs requis

Règles relatives au caractère générique *

Écriture (AddMemories)

appId

Les champs vides sont renseignés avec __default__. Le caractère générique * n'est pas autorisé.

Recherche dans les mémoires à long terme (SearchMemories)

appId et tenantId

agentId et runId prennent en charge le caractère générique *.

Interrogation des mémoires à court terme (ListMemoryStoreMessages)

Les quatre champs Scope

Le caractère générique * n'est pas autorisé.

Consultation, mise à jour ou suppression d'une entrée de mémoire à long terme (GetMemory, UpdateMemory, DeleteMemory)

Les quatre champs Scope

Le caractère générique * n'est pas autorisé.

Mémoire de fichiers et vues de fichiers (API Item)

Les quatre champs Scope

Le caractère générique * n'est pas autorisé.

Opérations de liste (ListMemories, ListMemoryStoreScopes, ListMemoryTasks, ListMemoryStoreRequests, et ListMemoryDreamTasks)

Aucun. Nous vous recommandons de fournir au moins appId. Les champs vides sont traités comme __default__.

Le caractère générique * est pris en charge à chaque niveau de la hiérarchie.

Exemple :

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

Message

Le champ messages de AddMemories utilise la structure suivante.

Champ

Type

Obligatoire

Description

role

string

Oui

Le rôle du message, tel que user, assistant ou system.

content

string

Oui

Le contenu du message.

messageId

string

Non

L'ID du message. Longueur maximale : 256 caractères.

timestamp

string

Non

L'horodatage au format RFC 3339.

metadata

object

Non

Métadonnées au niveau du message. Les clés et les valeurs doivent être des chaînes.

Metadata

Paires clé-valeur de type chaîne servant de tags métier. Les API de recherche utilisent les métadonnées pour un filtrage par correspondance exacte.

Contrainte

Valeur

Nombre maximal de clés par requête

Longueur maximale d'une clé

64 caractères

Longueur maximale d'une valeur

1 024 caractères

Exemple :

{
  "source": "chat",
  "topic": "preference"
}

Gestion des magasins de mémoire

CreateMemoryStore

Créez un magasin de mémoire.

Paramètres de la requête

Champ

Type

Obligatoire

Description

memoryStoreName

string

Oui

Le nom du magasin de mémoire. Le nom ne peut contenir que des lettres, des chiffres et des traits de soulignement (_) et sa longueur est limitée à 32 caractères.

description

string

Non

La description du magasin de mémoire. Longueur maximale : 1 024 octets en UTF-8.

extractInstructions

string

Non

Instructions d'extraction de mémoire personnalisées injectées dans l'invite d'extraction et influençant l'extraction ultérieure des mémoires à long terme dans le magasin de mémoire. Longueur maximale : 4 096 caractères.

storageMode

string

Non

La capacité de mémoire : ots (par défaut, mémoires structurées), file+ots (mémoires structurées et vues de fichiers en lecture seule) ou filemem (saisie et gestion directes des fichiers de mémoire). Cette valeur ne peut pas être modifiée après la création du magasin de mémoire.

Exemple de requête

{
  "memoryStoreName": "agent_memory",
  "description": "Long-term memory store for the agent",
  "extractInstructions": "Focus on the user's dietary preferences and travel habits"
}

Pour créer un magasin de mémoire destiné à l'ajout direct de fichiers de mémoire :

{
  "memoryStoreName": "agent_files",
  "storageMode": "filemem"
}

Exemple de réponse

{
  "otsInstance": "mem-test-01",
  "memoryStoreName": "agent_memory",
  "description": "Long-term memory store for the agent",
  "extractInstructions": "Focus on the user's dietary preferences and travel habits",
  "storageMode": "ots",
  "createdAt": "2026-06-17T07:19:48.935Z",
  "updatedAt": "2026-06-17T07:19:48.935Z"
}

GetMemoryStore

Consultez les détails d'un magasin de mémoire.

Paramètres de la requête

Champ

Type

Obligatoire

Description

memoryStoreName

string

Oui

Le nom du magasin de mémoire.

Exemple de requête

{
  "memoryStoreName": "agent_memory"
}

UpdateMemoryStore

Mettez à jour la description du magasin de mémoire ou les instructions d'extraction personnalisées. Cette API utilise la sémantique PATCH : les champs non fournis restent inchangés et une chaîne vide efface le champ correspondant.

Paramètres de la requête

Champ

Type

Obligatoire

Description

memoryStoreName

string

Oui

Le nom du magasin de mémoire.

description

string

Non

La nouvelle description. Longueur maximale : 1 024 octets en UTF-8. Transmettez une chaîne vide pour effacer la description, ou omettez ce champ pour conserver la description actuelle.

extractInstructions

string

Non

Les nouvelles instructions d'extraction personnalisées. Longueur maximale : 4 096 caractères. Pour effacer la valeur, transmettez une chaîne vide. Pour conserver la valeur actuelle, ne transmettez pas ce champ.

DeleteMemoryStore

Supprimez un magasin de mémoire.

Avertissement

La suppression d'un magasin de mémoire entraîne la suppression définitive de toutes ses données. Cette action est irréversible. Procédez avec prudence dans les environnements de production.

Paramètres de la requête

Champ

Type

Obligatoire

Description

memoryStoreName

string

Oui

Le nom du magasin de mémoire.

ListMemoryStores

Répertorie les mémoires.

Request parameters

Field

Type

Required

Description

limit

int

Le nombre maximal d'entrées à renvoyer.

nextToken

string

Le jeton de pagination pour la page suivante.

Long-term memory

AddMemories

Écrit des messages de conversation ou du texte. Les messages bruts sont stockés sous forme de mémoires à court terme, tandis que les mémoires à long terme sont extraites de l'entrée.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Le nom de la mémoire cible.

scope

object

Yes

Le Scope. Le paramètre appId est requis pour les opérations d'écriture. Le caractère générique * n'est pas autorisé.

messages

array

One of messages and text

Un tableau contenant jusqu'à 20 messages de conversation. Le contenu total peut atteindre 32 000 octets en UTF-8.

text

string

One of messages and text

Le contenu textuel. Longueur maximale : 32 000 octets en UTF-8.

metadata

object

Métadonnées au niveau de l'écriture. Maximum : 16 clés, clés de 64 caractères, valeurs de 1 024 caractères.

sync

boolean

Indique s'il faut attendre de manière synchrone la fin de l'extraction de la mémoire. Valeur par défaut : false.

referenceTime

string

L'heure de référence de la session, ou ancre « as-of », au format RFC 3339. Si ce champ est défini, les messages sans timestamp utilisent cette valeur comme heure d'événement au lieu de l'heure actuelle du serveur. Utilisez ce champ pour les importations historiques ou par lots.

Pour connaître les limites de AddMemories, consultez la rubrique Limitations et notes.

Lorsque reconcile_enabled est activé, le pipeline d'écriture récupère d'abord les candidats vectoriels existants. Le même appel DecideMemoryActions sélectionne ensuite ADD, NOOP, UPDATE, DELETE ou MERGE. L'opération MERGE ne déclenche pas d'appel de modèle supplémentaire.

Le paramètre côté serveur reconcile_merge_mode contrôle le comportement de fusion en ligne : off (par défaut) ne propose pas de fusions, shadow valide et observe les propositions sans les appliquer, et safe_auto applique les fusions sûres. Une fusion n'est acceptée que pour un résultat à haute confiance contenant deux ou trois sources, y compris la nouvelle mémoire, au sein du même Scope complet à quatre niveaux. Le service vérifie de manière conservatrice les entités, les locuteurs, la polarité, les types, les heures explicites, les métadonnées et les versions.

En mode off ou shadow, ou lorsqu'une proposition est rejetée ou jugée non sûre, la nouvelle mémoire d'origine continue d'être traitée comme une opération ADD. Si le ré-encodage par lot échoue pour un plan accepté ou si le format de la réponse n'est pas valide, tous les plans du lot reviennent à leurs opérations ADD d'origine et l'écriture se poursuit.

Si PutMemories échoue pour un lot contenant un résultat de fusion, l'API renvoie une erreur de persistance et n'effectue pas de suppression par comparaison et échange (CAS) des sources. L'écriture ne doit pas être considérée comme une opération ADD réussie.

Une fois qu'un résultat de fusion est persisté, les erreurs de finalisation des sources ne sont pas fatales pour l'écriture et le nouveau résultat reste stocké. Une erreur ErrConflict ou une autre erreur CAS ou backend survenant avant l'application de la ligne laisse généralement la source ancienne correspondante valide pour une nouvelle tentative ou Dream. D'autres sources peuvent toujours se terminer indépendamment.

Une erreur d'application de ligne typée ou de persistance d'événement indique que le marqueur de suppression (tombstone) de la source est persisté et que la suppression est reflétée dans le cache, mais que l'événement d'audit reste incomplet. Une relecture idempotente du même plan de finalisation ou une réparation des opérations comble l'écart d'événement. Dream ne reconstruit pas les événements d'audit en ligne. Il gère les anciennes sources valides, les mémoires stockées en double et la convergence.

Les opérations de source réussies ne font pas l'objet d'un retour arrière. La déduplication sémantique au moment de la recherche peut masquer les doublons temporaires pendant la transition.

Utilisez UPDATE lorsqu'un état change et qu'un état de remplacement existe. N'utilisez DELETE que pour rétracter un état lorsqu'aucun remplacement n'existe. N'utilisez pas MERGE dans l'un ou l'autre cas. Dream gère des ensembles de sources plus volumineux, des opérations inter-sessions, des conflits complexes et des réparations.

Request example: Write messages

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "messages": [
    {
      "role": "user",
      "content": "I like coffee."
    },
    {
      "role": "assistant",
      "content": "Got it. I'll remember that."
    }
  ],
  "metadata": {
    "source": "chat"
  },
  "sync": true
}

Request example: Write text

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001"
  },
  "text": "The user likes coffee and prefers concise responses."
}

Response fields

Field

Description

requestId

L'ID de la requête.

status

Le statut de la requête. Les écritures asynchrones renvoient généralement running.

acceptedMessages

Le nombre de messages acceptés.

scope

Le Scope utilisé pour l'écriture.

memoryStoreName

Le nom de la mémoire.

memcellsCreated

Renvoyé pour les écritures synchrones. Le nombre de memcells créées.

unitsCreated

Renvoyé pour les écritures synchrones. Le nombre d'unités de mémoire à long terme créées.

SearchMemories

Recherche des mémoires à long terme.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Le nom de la mémoire cible.

query

string

Yes

Le texte de la requête.

scope

object

Yes

Le Scope. Les paramètres appId et tenantId sont requis. Les paramètres agentId et runId prennent en charge le caractère générique *.

contextScope

object

Le Scope complet de la session actuelle, utilisé comme signal de classement souple. Les quatre champs doivent contenir des valeurs exactes sans le caractère générique *, et les valeurs doivent être incluses dans scope. Si ce champ est omis, le comportement de recherche existant est préservé.

topK

int

Le nombre maximal de résultats à renvoyer. Valeur par défaut : 10. Maximum : 50. Le filtrage par pertinence ou la déduplication sémantique peuvent entraîner un nombre de résultats inférieur à topK.

enableRerank

boolean

Indique s'il faut activer le reclassement. Valeur par défaut : true.

includeEvidence

boolean

Indique s'il faut inclure les preuves de source de mémoire à court terme (champ evidence) dans le résultat. Valeur par défaut : false.

minSimilarity

float

Le seuil de pertinence dans la plage 0~1. Valeur par défaut : 0, ce qui désactive le filtrage. Une valeur supérieure à 0 filtre les résultats dont le score results[].score est inférieur au seuil. Lorsque le reclassement est activé, le score correspond au score de pertinence du reclassement. Sinon, le score correspond à la similarité cosinus normalisée.

metadata

object

Filtres de métadonnées pour la correspondance exacte. Les clés et les valeurs doivent être des chaînes de caractères.

Lorsque search_semantic_dedup_enabled est activé sur le serveur, la déduplication sémantique s'applique uniquement au pool fusionné actuel des candidats de mémoire à long terme pour l'API publique SearchMemories. Les recherches de réponses et internes ne sont pas affectées.

La déduplication s'exécute avant le reclassement et l'expansion des preuves. Elle utilise un regroupement conservateur complet basé sur la structure et conserve un représentant par cluster. Par conséquent, les mémoires à long terme en double ne consomment pas le budget de reclassement, tandis que les evidence à court terme restent indépendantes. La déduplication n'étend pas candidateK, n'exécute pas une seconde recherche, ne génère pas d'embeddings supplémentaires, ne remplit pas les résultats a posteriori et n'utilise pas le clustering LLM. topK représente le nombre maximal de résultats. Les résultats incomplets sont acceptés et les résultats ne sont pas remplis a posteriori à partir du même cluster.

La déduplication sémantique ne modifie pas les lignes stockées ni les résultats de ListMemories. Dream continue de nettoyer les doublons historiques.

Request example

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "*",
    "runId": "*"
  },
  "contextScope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "query": "What beverage does the user like?",
  "topK": 5,
  "enableRerank": true,
  "includeEvidence": true,
  "metadata": {
    "source": "chat"
  }
}

Response fields

Field

Description

results

La liste des résultats de recherche.

results[].unit

L'unité de mémoire à long terme. Consultez le tableau suivant pour les définitions des champs.

results[].score

Le score de pertinence canonique dans la plage 0~1. Cette valeur correspond au score de pertinence du reclassement lorsque celui-ci est activé, et à la similarité cosinus normalisée lorsqu'il est désactivé. minSimilarity filtre toujours sur ce champ en premier. Le classement souple de session ne modifie pas ce champ.

results[].similarity

La similarité cosinus normalisée entre la requête et la mémoire dans la plage 0~1. Ce champ est fourni à titre de référence et est égal à score lorsque le reclassement est désactivé.

results[].rankingScore

Le score de classement final facultatif. Ce champ est renvoyé uniquement lorsque le mode d'affinité de session côté serveur est on et que la requête inclut un contextScope valide. Les résultats sont triés selon ce champ.

results[].rankingSignals

Détails de classement facultatifs incluant sameSession et sessionAffinityWeight côté serveur. Ce champ est renvoyé avec rankingScore.

results[].source

La source de la correspondance. Exemple : vector ou vector+text.

evidence

La liste des preuves de source à court terme renvoyée lorsque includeEvidence=true. Chaque élément utilise la même structure que results. La valeur est [] lorsqu'aucune preuve n'est disponible.

scope

Le Scope utilisé pour la requête.

memoryStoreName

Le nom de la mémoire.

Le tableau suivant décrit les champs dans results[].unit. ListMemories et GetMemory renvoient les mêmes champs de mémoire. Les vecteurs d'embedding ne sont pas renvoyés.

Field

Description

id

L'ID de l'unité de mémoire à long terme.

conversation_key

La clé de conversation associée.

scope

Le Scope auquel appartient la mémoire. L'objet contient appId, tenantId, agentId et runId.

memcell_id

L'ID de la memcell.

unit_type

Le type de mémoire, tel que atomic_fact, entity_fact ou temporal_anchor.

title

Le titre de la mémoire. Longueur maximale : 64 caractères. Pour les données héritées ou un champ vide, les clients peuvent afficher text comme solution de repli.

text

Le texte de la mémoire.

search_text

Le texte utilisé pour la recherche.

keywords

Une liste pouvant contenir jusqu'à huit mots-clés. Chaque mot-clé peut comporter jusqu'à 32 caractères.

source_turn_ids

La liste des ID de messages sources.

type_label

Le libellé du type.

date_bucket

Le compartiment de date.

metadata

L'objet de métadonnées contenant les paires clé-valeur fournies lors de l'écriture.

metadata_json

Les métadonnées au format de chaîne JSON.

metadata_flat

La chaîne de métadonnées aplatie utilisée pour le filtrage.

deleted

Indique si la mémoire est supprimée.

created_at

L'heure de création.

effective_at

L'heure effective décrite par le fait, l'événement ou le plan. Cette heure peut être antérieure ou postérieure à l'heure d'écriture de la mémoire.

updated_at

L'heure de la dernière mise à jour de la mémoire sur le serveur.

time_source

La source temporelle, telle que explicit_event, source_message, legacy_created_at ou manual.

time_precision

La précision originale de effective_at : second, day, month, year ou unknown.

salience

Le score de saillance.

version

Le numéro de version.

speaker

Le locuteur associé à la mémoire. Renvoyé lorsque ce champ n'est pas vide.

topic

Le libellé du sujet. Renvoyé lorsque ce champ n'est pas vide.

entities

La liste des entités connexes. Renvoyée lorsque ce champ n'est pas vide.

time_anchor

Les informations d'ancre temporelle. Renvoyées lorsque ce champ n'est pas vide.

source_turn_refs

La liste des références de messages sources. Chaque élément contient messageId et timestampMs. Renvoyée lorsque ce champ n'est pas vide.

superseded_by / supersedes_id

La chaîne de remplacement créée lorsqu'une mémoire est fusionnée ou mise à jour. Renvoyée lorsque ce champ n'est pas vide.

dream_id / dream_action_id / dream_reason / dream_source_message_ids / dream_source_memory_ids

Les champs de provenance d'une mémoire générée ou modifiée par Dream. Renvoyés lorsque ces champs ne sont pas vides.

La même session reçoit une pondération souple limitée. Pour une correspondance exacte avec le contextScope complet, rankingScore = score + (1-score) × sessionAffinityWeight. Pour les autres résultats, rankingScore est égal à score. Le serveur contrôle la pondération, qui est par défaut de 0.10 et peut aller jusqu'à 0.25. Les requêtes ne peuvent pas remplacer la pondération. Ce signal permet de départager les candidats ayant une pertinence similaire et ne remplace pas la pertinence sémantique ni le seuil minSimilarity.

Note de compatibilité : les serveurs hérités rejettent strictement les champs JSON inconnus, y compris contextScope. Lors d'une mise à niveau progressive, mettez à niveau toutes les répliques de service avant que les clients n'envoient ce champ. Un SDK en lecture seule peut effectuer une nouvelle tentative unique sans contextScope uniquement après avoir reçu une erreur explicite de champ inconnu. N'utilisez pas cette solution de repli pour les API d'écriture.

ListMemories

Répertorie les mémoires à long terme.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

scope

object

Yes

Périmètre (Scope). Le caractère générique * est pris en charge par hiérarchie et doit respecter la règle du préfixe gauche : tous les champs situés après * doivent également être * ou vides. Les champs vides sont traités comme __default__. Nous vous recommandons de fournir au moins appId.

limit

int

Nombre maximal d'entrées à renvoyer.

nextToken

string

Jeton de pagination pour la page suivante.

Request example

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "*",
    "agentId": "*",
    "runId": "*"
  },
  "limit": 20
}

La réponse renvoie les mémoires à long terme dans le tableau memories. Chaque mémoire possède les mêmes champs que results[].unit dans SearchMemories. Les réponses paginées incluent nextToken.

GetMemory

Récupère une entrée de mémoire à long terme.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

memoryId

string

Yes

ID de la mémoire.

scope

object

Yes

Périmètre (Scope) complet. Les quatre champs sont obligatoires. Le caractère générique * n'est pas autorisé.

UpdateMemory

Met à jour une mémoire à long terme en utilisant la sémantique PATCH. Les champs non fournis restent inchangés. Transmettez une chaîne vide pour title ou un tableau vide pour keywords afin d'effacer le champ. Au moins un champ modifiable est requis.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

memoryId

string

Yes

ID de la mémoire.

scope

object

Yes

Périmètre (Scope) complet. Les quatre champs sont obligatoires. Le caractère générique * n'est pas autorisé.

text

string

Nouveau texte de la mémoire.

metadata

object

Nouvelles métadonnées.

title

string

Nouveau titre de la mémoire. Longueur maximale : 64 caractères.

keywords

array

Liste contenant jusqu'à huit nouveaux mots-clés. Chaque mot-clé peut comporter jusqu'à 32 caractères.

effectiveAt

string

Provide with timePrecision

Nouvelle date d'effet. Utilisez le format RFC 3339 lorsque la précision est second. Pour day, month et year, utilisez respectivement YYYY-MM-DD, YYYY-MM et YYYY.

timePrecision

string

Provide with effectiveAt

Précision temporelle : second, day, month ou year.

Si memory_unit_v2_write_enabled est désactivé sur le serveur, une mise à jour incluant title, keywords, effectiveAt ou timePrecision renvoie 409 CONFLICT. Ce comportement empêche les réplicas de versions mixtes d'écraser mutuellement leurs champs V2.

DeleteMemory

Supprime une entrée de mémoire à long terme.

Avertissement

La suppression d'une entrée de mémoire à long terme est irréversible. Procédez avec prudence dans les environnements de production.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

memoryId

string

Yes

ID de la mémoire.

scope

object

Yes

Périmètre (Scope) complet. Les quatre champs sont obligatoires. Le caractère générique * n'est pas autorisé.

Short-term memory and audit

ListMemoryStoreMessages

Interroge les mémoires à court terme (messages de conversation originaux).

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

scope

object

Yes

Périmètre (Scope) complet. Les quatre champs sont obligatoires. Le caractère générique * n'est pas autorisé.

limit

int

Nombre maximal d'entrées à renvoyer.

nextToken

string

Jeton de pagination pour la page suivante.

minTimestamp

string

Date la plus ancienne au format RFC 3339.

maxTimestamp

string

Date la plus récente au format RFC 3339.

Request example

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "limit": 100
}

Response example

{
  "session": {
    "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
    "messages": [
      {
        "messageId": "d0d9dd778a27e8cde773a243a5bab13c",
        "role": "user",
        "speaker": "user",
        "content": "[10:00 AM on May 13, 2026] I prefer a window seat for future business trips.",
        "timestamp": "2026-05-13T10:00:00Z",
        "metadata": { "channel": "chat", "source": "chat" }
      }
    ]
  }
}

Si le magasin de mémoire existe mais qu'aucun message n'existe pour le périmètre (Scope), l'opération renvoie 200 avec une liste messages vide.

ListMemoryStoreRequests

Interroge les enregistrements d'audit des requêtes adressées au magasin de mémoire.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

scope

object

Yes

Périmètre (Scope). Le caractère générique * est pris en charge à chaque niveau de la hiérarchie.

operation

string

Nom de l'opération, tel que AddMemories ou SearchMemories.

limit

int

Nombre maximal d'entrées à renvoyer.

nextToken

string

Jeton de pagination pour la page suivante.

minTimestamp

string

Date la plus ancienne au format RFC 3339.

maxTimestamp

string

Date la plus récente au format RFC 3339.

Request example

{
  "memoryStoreName": "agent_memory",
  "scope": {
    "appId": "app-001",
    "tenantId": "*",
    "agentId": "*",
    "runId": "*"
  },
  "operation": "AddMemories",
  "limit": 50
}

Response fields

Field

Description

requestId

ID de la requête.

operation

Nom de l'opération.

scope

Périmètre (Scope) utilisé dans la requête.

requestSummary

Résumé de la requête.

responseStatus

État de la réponse.

latencyMs

Latence de traitement en millisecondes.

targetId

ID cible de l'opération, tel qu'un ID de mémoire.

createdAt

Date de création de l'enregistrement.

Asynchronous tasks and Scope

GetMemoryTask

Interroge l'état et le résultat d'une tâche d'extraction asynchrone. Transmettez le requestId renvoyé par AddMemories.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

requestId

string

Yes

ID de la requête renvoyé par AddMemories.

scope

object

Valide le périmètre (Scope) de la tâche. Le caractère générique * est pris en charge à n'importe quel niveau.

Request example

{
  "memoryStoreName": "agent_memory",
  "requestId": "4b41a912f8c8a66202896e880a505d4a"
}

Response example

{
  "memoryStoreName": "agent_memory",
  "task": {
    "requestId": "4b41a912f8c8a66202896e880a505d4a",
    "eventType": "ingest",
    "memoryStoreName": "agent_memory",
    "conversationKey": "app-001/user-001/assistant/session-001",
    "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
    "status": "completed",
    "acceptedMessages": 2,
    "derivedMemcellId": "98ebdf1de01b620bfa96f55c8925061f",
    "derivedUnitIds": ["9ce29432d101aab04253a862c8a11022", "6172bac2ca37b6b82f5224de116f030f"],
    "createdAt": "2026-06-17T07:19:59.962Z",
    "updatedAt": "2026-06-17T07:20:08.749Z",
    "finishedAt": "2026-06-17T07:20:08.749Z"
  }
}

Valeurs valides pour le status de la tâche : queued, running, completed, failed et needs_reconcile. Pendant la construction de l'index des tâches d'ingestion après la première écriture, cette API peut renvoyer 409 CONFLICT (ingest task index is still building, please retry shortly). Réessayez la requête après un court délai.

ListMemoryTasks

Répertorie les tâches d'extraction asynchrone.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

scope

object

Yes

Portée (Scope). Le caractère générique * est pris en charge à tous les niveaux.

status

string

Filtre par statut de tâche : queued, running, completed, failed ou needs_reconcile.

limit

int

Nombre maximal d'entrées à renvoyer. Valeur par défaut : 50. Maximum : 100.

nextToken

string

Jeton de pagination pour la page suivante.

minTimestamp

string

Date et heure les plus anciennes, exprimées sous forme d'horodatage Unix en millisecondes (le format RFC 3339 n'est pas pris en charge).

maxTimestamp

string

Date et heure les plus récentes, exprimées sous forme d'horodatage Unix en millisecondes (le format RFC 3339 n'est pas pris en charge).

Request example

{
  "memoryStoreName": "agent_memory",
  "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" },
  "limit": 5
}

La réponse renvoie les objets de tâche dans le tableau tasks. Chaque objet contient les mêmes champs que l'objet task renvoyé par GetMemoryTask.

ListMemoryStoreScopes

Répertorie les portées (Scopes) existantes dans un magasin de mémoire afin d'identifier les agents et les sessions ayant généré des mémoires pour une application ou un locataire.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

scope

object

Yes

Portée (Scope). Le caractère générique * est pris en charge à tous les niveaux.

limit

int

Nombre maximal d'entrées à renvoyer. Valeur par défaut : 100. Maximum : 100.

nextToken

string

Jeton de pagination pour la page suivante.

Request example

{
  "memoryStoreName": "agent_memory",
  "scope": { "appId": "app-001", "tenantId": "*", "agentId": "*", "runId": "*" },
  "limit": 10
}

Response example

{
  "memoryStoreName": "agent_memory",
  "scope": { "appId": "app-001", "tenantId": "*", "agentId": "*", "runId": "*" },
  "scopes": [
    { "appId": "app-001", "tenantId": "user-001", "agentId": "__default__", "runId": "__default__" },
    { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "session-001" }
  ]
}

Memory consolidation (Dream)

CreateMemoryDreamTask

Créez une tâche asynchrone de consolidation de mémoire (Dream) afin d'affiner et de fusionner les mémoires stockées, puis d'en extraire des compétences ou des profils. Pour consulter le flux de travail complet, reportez-vous à la rubrique Consolidation de la mémoire.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

scopes

array

Yes

Liste des portées (Scopes) à organiser. Jusqu'à 20 portées.

taskType

string

Type de tâche : memory (valeur par défaut), skill ou profile.

applyMode

string

Mode d'application : proposal (valeur par défaut, génère uniquement des propositions) ou safe_auto (applique automatiquement les actions sûres). Ce champ est pris en charge uniquement lorsque taskType=memory.

scopeOutputMode

string

Portée (Scope) des résultats de consolidation : preserve_scope (valeur par défaut) ou promote_scope.

confidenceThresholds

object

Seuils de confiance pour l'application automatique de chaque action. Les clés valides sont add, update et merge. Les valeurs vont de 0~1.

minTimestamp / maxTimestamp

string

Plage temporelle pour l'organisation, exprimée sous forme d'horodatages Unix en millisecondes (le format RFC 3339 n'est pas pris en charge).

maxSessions / maxMessages / maxMemories

int

Échelle d'entrée maximale. Pour connaître les plages valides, consultez la documentation sur les limites.

expandedScopeLimit

int

Limite d'expansion de la portée (Scope), comprise entre 0~1000.

instructions

string

Instructions de consolidation personnalisées. Longueur maximale : 4 000 octets en UTF-8.

incremental

boolean

Indique s'il faut poursuivre la consolidation incrémentielle à partir du dernier point de repère réussi. Valeur par défaut : false, ce qui effectue une consolidation complète.

clientToken

string

Jeton d'idempotence.

Request example

{
  "memoryStoreName": "agent_memory",
  "scopes": [ { "appId": "app-001", "tenantId": "user-001" } ],
  "taskType": "memory",
  "applyMode": "proposal"
}

Response example

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "status": "queued",
  "createdAt": "2026-06-17T07:21:25.329Z"
}

GetMemoryDreamTask

Interrogez la progression et le résumé des résultats d'une tâche de consolidation de mémoire.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

dreamId

string

Yes

ID de la tâche de consolidation de mémoire.

Response example

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "taskType": "memory",
  "applyMode": "proposal",
  "scopeOutputMode": "preserve_scope",
  "status": "completed",
  "actions": { "total": 2, "proposed": 2, "applied": 0, "skipped": 0, "failed": 0 },
  "input": { "scopes": [ { "appId": "app-001", "tenantId": "user-001", "agentId": "__default__", "runId": "__default__" } ], "sessionCount": 1, "messageCount": 1, "memoryCount": 2, "incremental": false },
  "lastError": "",
  "createdAt": "2026-06-17T07:21:25.329Z",
  "updatedAt": "2026-06-17T07:21:32.276Z",
  "finishedAt": "2026-06-17T07:21:32.276Z"
}

Valeurs valides pour le status de la tâche : queued, running, planning, applying, completed, completed_with_failures, failed et cancelled.

ListMemoryDreamTasks

Répertorie les tâches de consolidation de mémoire.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

scope

object

Yes

Portée (Scope). Le caractère générique * est pris en charge à tous les niveaux.

status

string

Filtre par statut de tâche.

limit

int

Nombre maximal d'entrées à renvoyer. Valeur par défaut : 50. Maximum : 100.

nextToken

string

Jeton de pagination pour la page suivante.

minTimestamp / maxTimestamp

string

Plage temporelle exprimée sous forme d'horodatages Unix en millisecondes. Le format RFC 3339 n'est pas pris en charge.

La réponse renvoie les objets de tâche dans le tableau tasks. Chaque objet inclut des champs tels que dreamId, status, taskType, actionCount, proposedCount, confidenceThresholds et createdAt.

ListMemoryDreamActions

Répertorie les actions proposées générées par les tâches de consolidation. Utilisez l'un des deux modes de requête mutuellement exclusifs : interrogez par dreamId ou par scope et actionType pour les actions EMIT_SKILL ou EMIT_PROFILE.

Request parameters

Field

Type

Required

Description

memoryStoreName

string

Yes

Nom du magasin de mémoire.

dreamId

string

ID de la tâche de consolidation de mémoire. Ce paramètre est mutuellement exclusif avec scope.

scope

object

Requête par portée (Scope), mutuellement exclusive avec dreamId. Lorsque ce champ est utilisé, actionType est obligatoire et prend uniquement en charge EMIT_SKILL ou EMIT_PROFILE.

actionType

string

Obligatoire pour une requête par scope. Valeurs valides : EMIT_SKILL et EMIT_PROFILE.

targetScope

object

Filtre par portée (Scope) cible de l'action. Le caractère générique * est pris en charge par hiérarchie.

sourceMemoryId

string

Filtre par ID de mémoire source de l'action.

status

string

Filtre par statut d'action : proposed, applied, skipped ou failed.

action

string

Filtre par type d'action : ADD, UPDATE, DELETE, MERGE ou NOOP.

minConfidence / maxConfidence

float

Filtre de confiance compris entre 0~1.

orderBy

string

Ordre de tri : created_at_asc (valeur par défaut), created_at_desc ou confidence_desc.

limit

int

Nombre maximal d'entrées à renvoyer. Valeur par défaut : 100. Maximum : 100.

nextToken

string

Jeton de pagination pour la page suivante.

Request example

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "limit": 20
}

Exemple de réponse

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "actions": [
    {
      "dreamId": "2a528008111f5dc3500c73fd965089f7",
      "actionId": "968768529cdfde8d56686a71e1c28227",
      "action": "UPDATE",
      "status": "proposed",
      "targetScope": { "appId": "app-001", "tenantId": "user-001", "agentId": "__default__", "runId": "__default__" },
      "targetMemoryId": "d16fd038835d89ae8586f7814e5256c1",
      "newMemory": { "text": "User prefers concise responses.", "unitType": "atomic_fact" },
      "reason": "Rewritten as a more accurate atomic_fact.",
      "confidence": 0.95,
      "createdAt": "2026-06-17T07:21:32.161Z"
    }
  ]
}

ApplyMemoryDreamActions

Applique les actions proposées générées par une tâche de consolidation de la mémoire lorsque applyMode=proposal.

Paramètres de requête

Champ

Type

Obligatoire

Description

memoryStoreName

string

Oui

Nom du magasin de mémoire.

dreamId

string

Oui

ID de la tâche de consolidation de la mémoire.

actionIds

array

Oui

Liste des ID d'action à appliquer. Maximum : 100 ID par requête.

applier

string

Non

Identifiant de l'appliquant. Cette valeur est enregistrée dans le journal d'audit.

Exemple de requête

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "actionIds": ["968768529cdfde8d56686a71e1c28227", "a0f4715245920ea7b6a34c1828c6f1ae"]
}

Exemple de réponse

{
  "memoryStoreName": "agent_memory",
  "dreamId": "2a528008111f5dc3500c73fd965089f7",
  "applied": 2,
  "failed": 0,
  "results": [
    { "actionId": "968768529cdfde8d56686a71e1c28227", "status": "applied", "memoryId": "bd14a67ed215c114896325d912c8fa71" },
    { "actionId": "a0f4715245920ea7b6a34c1828c6f1ae", "status": "applied", "memoryId": "fa253856113f78d51a3b84a1fdf2d110" }
  ]
}

Les actions EMIT_SKILL et EMIT_PROFILE sont écrites directement par la tâche de consolidation et ne supportent pas l'application manuelle. Toute requête incluant un ID d'action de ce type est rejetée.

CancelMemoryDreamTask

Annule une tâche de consolidation de la mémoire qui n'est pas terminée.

Paramètres de requête

Champ

Type

Obligatoire

Description

memoryStoreName

string

Oui

Nom du magasin de mémoire.

dreamId

string

Oui

ID de la tâche de consolidation de la mémoire.

API de mémoire de fichier et de vue de fichier

La mémoire de fichier et les vues de fichier partagent huit API Item. Chaque API utilise une requête POST avec un corps JSON et une URL fixe. Les chemins d'URL dynamiques et les paramètres de requête ne sont pas utilisés.

Pour les fichiers de mémoire ajoutés directement, vous pouvez ajouter, lire, mettre à jour, renommer et supprimer des fichiers, ainsi que consulter ou expurger les versions historiques.
Pour les mémoires structurées, utilisez les mêmes API de liste et de lecture pour accéder aux vues de fichier en lecture seule générées par le service. La présence de readOnly: true dans une réponse ListItems indique que la vue est en lecture seule.

Le SDK Agent Storage fournit automatiquement le type Item. Lorsque vous appelez directement l'API HTTP, indiquez explicitement les champs communs suivants.

Champs de requête communs

Champ

Type

Obligatoire

Description

type

string

Oui

La valeur est fixée à memoryfile. Une valeur manquante ou différente renvoie 400 VALIDATION_ERROR.

memoryStoreName

string

Oui

Nom du magasin de mémoire cible.

scope

object

Oui

Portée (Scope) propriétaire du fichier. Fournissez des valeurs exactes pour appId, tenantId, agentId et runId. Les caractères génériques ne sont pas pris en charge.

Exemple de champs communs :

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  }
}

Objet de réponse Item

Champ

Type

Description

type

string

Valeur fixe memoryfile. Une réponse de fichier unique renvoie ce champ au niveau supérieur.

itemId

string

Identifiant stable du fichier utilisé pour interroger les versions historiques.

path

string

Chemin du fichier au sein de la portée (Scope).

content

string

Contenu du fichier. ListItems et les lectures de métadonnées uniquement ne renvoient pas ce champ. La lecture du contenu d'un fichier vide renvoie une chaîne vide.

contentSha256

string

Empreinte SHA-256 du contenu en hexadécimal minuscule sans préfixe.

contentSizeBytes

int64

Taille du contenu en octets UTF-8.

latestSeq

int64

Numéro de séquence de la dernière modification du fichier.

createdAt

string

Date de création du fichier au format RFC 3339.

updatedAt

string

Date de la dernière mise à jour du fichier au format RFC 3339.

Objet de réponse ItemVersion

Champ

Type

Description

type

string

Valeur fixe memoryfile. Une réponse de version unique renvoie ce champ au niveau supérieur.

versionId

string

ID de la version.

itemId

string

ID du fichier.

versionSeq

int64

Numéro de séquence de la version. Fournissez ce champ avec versionId lors de la lecture ou de l'expurgation d'une version.

operation

string

Opération ayant créé la version : created, modified ou deleted.

path

string

Chemin du fichier pour la version. La valeur est une chaîne vide après expurgation.

content

string

Contenu de la version. Les listes de versions et les versions expurgées ne renvoient pas ce champ.

contentSha256

string

Empreinte du contenu de la version. La valeur est une chaîne vide après expurgation.

contentSizeBytes

int64

Taille du contenu de la version en octets. La valeur est 0 après expurgation.

sessionId

string

Identifiant de la session appelante ayant créé la version. Ce champ est omis si aucune valeur n'a été fournie.

createdAt

string

Date de création de la version au format RFC 3339.

redacted

bool

Indique si la version est expurgée. Renvoyé uniquement après expurgation.

redactedAt

string

Date de la première expurgation au format RFC 3339. Renvoyé uniquement après expurgation.

redactedBy

string

sessionId issu de la première demande d'expurgation. Renvoyé si la requête a fourni sessionId.

AddItem

Ajoute un fichier de mémoire. Les chemins de fichier doivent être uniques au sein d'une même portée (Scope).

Paramètres de requête

En plus des champs de requête communs, cette API prend en charge les champs suivants.

Champ

Type

Obligatoire

Description

path

string

Oui

Chemin du fichier. Le service ajoute un / initial s'il est absent.

content

string

Non

Contenu du fichier en UTF-8, qui peut être vide. Si ce champ est omis, un fichier vide est créé.

sessionId

string

Non

Identifiant de la session appelante ou de l'opération à enregistrer dans la version.

Exemple de requête

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/preferences.md",
  "content": "# User preferences\n\n- Prefers Americano coffee\n",
  "sessionId": "session-001"
}

Exemple de réponse

{
  "type": "memoryfile",
  "itemId": "fmem_019c12345678abcd1234",
  "path": "/profile/preferences.md",
  "content": "# User preferences\n\n- Prefers Americano coffee\n",
  "contentSha256": "40556ec6bfcf74438386488feea9221a99adbb1e8d2950720c4e228b532b1ece",
  "contentSizeBytes": 37,
  "latestSeq": 1784786400123456,
  "createdAt": "2026-07-23T10:00:00Z",
  "updatedAt": "2026-07-23T10:00:00Z"
}

ListItems

Répertorie les fichiers par ordre de chemin octet par octet avec pagination. Les entrées de liste n'incluent pas content.

Paramètres de requête

Champ

Type

Obligatoire

Description

pathPrefix

string

Non

Répertorie uniquement les fichiers sous le préfixe de chemin spécifié. Une valeur vide répertorie tous les fichiers.

nextToken

string

Non

Jeton de pagination opaque renvoyé sur la page précédente. Utilisez le jeton avec le pathPrefix d'origine.

limit

int

Non

Nombre d'entrées par page. Par défaut : 100. Maximum : 500.

Exemple de requête

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "pathPrefix": "/profile/",
  "limit": 100
}

Exemple de réponse

{
  "type": "memoryfile",
  "items": [
    {
      "itemId": "fmem_019c12345678abcd1234",
      "path": "/profile/preferences.md",
      "contentSha256": "40556ec6bfcf74438386488feea9221a99adbb1e8d2950720c4e228b532b1ece",
      "contentSizeBytes": 37,
      "latestSeq": 1784786400123456,
      "createdAt": "2026-07-23T10:00:00Z",
      "updatedAt": "2026-07-23T10:00:00Z"
    }
  ],
  "nextToken": "L3Byb2ZpbGUvcHJlZmVyZW5jZXMubWQ"
}

Un nextToken vide ou omis indique qu'il ne reste plus de fichiers. Une vue de fichier en lecture seule générée à partir de mémoires structurées renvoie également "readOnly": true au niveau supérieur. La mémoire de fichier ajoutée directement ne renvoie pas ce champ.

GetItem

Récupère un fichier par son chemin. Par défaut, la réponse inclut le contenu du fichier. Vous pouvez également récupérer uniquement les métadonnées.

Paramètres de requête

Champ

Type

Obligatoire

Description

path

string

Oui

Chemin du fichier.

includeContent

bool

Non

Indique s'il faut renvoyer content. Par défaut : true. Définissez ce champ sur false pour renvoyer uniquement les métadonnées.

Exemple de requête

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/preferences.md"
}

Exemple de réponse

{
  "type": "memoryfile",
  "itemId": "fmem_019c12345678abcd1234",
  "path": "/profile/preferences.md",
  "content": "# User preferences\n\n- Prefers Americano coffee\n",
  "contentSha256": "40556ec6bfcf74438386488feea9221a99adbb1e8d2950720c4e228b532b1ece",
  "contentSizeBytes": 37,
  "latestSeq": 1784786400123456,
  "createdAt": "2026-07-23T10:00:00Z",
  "updatedAt": "2026-07-23T10:00:00Z"
}

Lorsque includeContent=false, la réponse présente la même structure mais omet content. La lecture du contenu d'un fichier vide renvoie explicitement "content": "".

UpdateItem

Met à jour le contenu d'un fichier ou renomme celui-ci. Vous devez fournir exactement l'un des paramètres suivants : content ou newPath. Si vous indiquez les deux paramètres simultanément ou aucun des deux, l'API renvoie une erreur 400 VALIDATION_ERROR.

Request parameters

Field

Type

Required

Description

path

string

Yes

Chemin actuel du fichier.

content

string

Conditionally required

Nouveau contenu au format UTF-8 (peut être une chaîne vide). Ce paramètre est incompatible avec newPath.

newPath

string

Conditionally required

Nouveau chemin après le renommage du fichier. Ce paramètre est incompatible avec content.

overwrite

bool

Indique si un renommage peut remplacer un fichier de destination existant. Valeur par défaut : false.

expectedSha256

string

Empreinte numérique actuelle du contenu. Si cette valeur ne correspond pas, l'API renvoie l'erreur 409 SHA_MISMATCH.

sessionId

string

Identifiant de la session ou de l'opération de l'appelant.

Update content example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/preferences.md",
  "content": "# User preferences\n\n- Prefers latte\n",
  "expectedSha256": "40556ec6bfcf74438386488feea9221a99adbb1e8d2950720c4e228b532b1ece"
}

Rename example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/preferences.md",
  "newPath": "/profile/user-preferences.md",
  "overwrite": false,
  "expectedSha256": "b43e966f005c2ada265e69892da99a473648cad24dea25cdd13848e586f1a7dc"
}

Ces deux opérations renvoient l'élément mis à jour dans son intégralité, y compris le champ content. Si vous omettez le paramètre expectedSha256, le service effectue un nombre limité de tentatives protégées sur l'état le plus récent au lieu d'écraser le fichier inconditionnellement. En cas de forte concurrence, l'erreur 409 SHA_MISMATCH peut toujours se produire. Si plusieurs rédacteurs modifient le même chemin, transmettez l'empreinte numérique issue de la dernière lecture.

DeleteItem

Supprime le fichier actuel et conserve une version de suppression interrogeable.

Request parameters

Field

Type

Required

Description

path

string

Yes

Chemin du fichier à supprimer.

expectedSha256

string

Empreinte numérique actuelle du contenu utilisée pour la protection contre les accès concurrents.

sessionId

string

Identifiant de la session ou de l'opération de l'appelant.

Request example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "path": "/profile/user-preferences.md",
  "expectedSha256": "b43e966f005c2ada265e69892da99a473648cad24dea25cdd13848e586f1a7dc"
}

Response example

{
  "type": "memoryfile"
}

ListItemVersions

Répertorie les versions historiques d'un fichier par ordre chronologique inverse, avec pagination. Les entrées de la liste n'incluent pas le champ content.

Request parameters

Field

Type

Required

Description

itemId

string

Yes

ID du fichier.

path

string

Chemin actuel du fichier. Ce champ n'est généralement pas requis.

nextToken

string

Jeton de pagination opaque renvoyé sur la page précédente.

limit

int

Nombre d'entrées par page. Valeur par défaut : 100. Maximum : 500.

operation

string

Filtre par created, modified ou deleted.

Request example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "itemId": "fmem_019c12345678abcd1234",
  "limit": 20
}

Response example

{
  "type": "memoryfile",
  "versions": [
    {
      "versionId": "fmver_019c12349999abcd5678",
      "itemId": "fmem_019c12345678abcd1234",
      "versionSeq": 1784786700123456,
      "operation": "modified",
      "path": "/profile/user-preferences.md",
      "contentSha256": "b43e966f005c2ada265e69892da99a473648cad24dea25cdd13848e586f1a7dc",
      "contentSizeBytes": 31,
      "sessionId": "session-001",
      "createdAt": "2026-07-23T10:05:00Z"
    }
  ]
}

GetItemVersion

Récupère une version historique. Indiquez les paramètres itemId, versionId et versionSeq obtenus depuis la réponse d'une liste.

Request parameters

Field

Type

Required

Description

itemId

string

Yes

ID du fichier.

versionId

string

Yes

ID de la version.

versionSeq

int64

Yes

Numéro de séquence de la version, qui doit être supérieur à 0.

Request example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "itemId": "fmem_019c12345678abcd1234",
  "versionId": "fmver_019c12349999abcd5678",
  "versionSeq": 1784786700123456
}

Response example

{
  "type": "memoryfile",
  "versionId": "fmver_019c12349999abcd5678",
  "itemId": "fmem_019c12345678abcd1234",
  "versionSeq": 1784786700123456,
  "operation": "modified",
  "path": "/profile/user-preferences.md",
  "content": "# User preferences\n\n- Prefers latte\n",
  "contentSha256": "b43e966f005c2ada265e69892da99a473648cad24dea25cdd13848e586f1a7dc",
  "contentSizeBytes": 31,
  "sessionId": "session-001",
  "createdAt": "2026-07-23T10:05:00Z"
}

Une version expurgée renvoie toujours le code 200 et inclut les champs d'expurgation et d'audit, mais ne renvoie pas le champ content.

RedactItemVersion

Expurge de manière irréversible une version historique. L'expurgation ne modifie pas le fichier actuel, ne change pas la valeur de latestSeq et ne crée pas de nouvelle version.

Request parameters

Field

Type

Required

Description

itemId

string

Yes

ID du fichier.

versionId

string

Yes

ID de la version.

versionSeq

int64

Yes

Numéro de séquence de la version, qui doit être supérieur à 0.

sessionId

string

Identifiant de l'appelant ayant effectué l'expurgation, enregistré dans le champ redactedBy.

Request example

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "itemId": "fmem_019c12345678abcd1234",
  "versionId": "fmver_019c12349999abcd5678",
  "versionSeq": 1784786700123456,
  "sessionId": "privacy-job-001"
}

Response example

{
  "type": "memoryfile",
  "versionId": "fmver_019c12349999abcd5678",
  "itemId": "fmem_019c12345678abcd1234",
  "versionSeq": 1784786700123456,
  "operation": "modified",
  "path": "",
  "contentSha256": "",
  "contentSizeBytes": 0,
  "sessionId": "session-001",
  "createdAt": "2026-07-23T10:05:00Z",
  "redacted": true,
  "redactedAt": "2026-07-23T11:00:00Z",
  "redactedBy": "privacy-job-001"
}

Les requêtes d'expurgation sont idempotentes. Une requête répétée renvoie l'état d'expurgation actuel. Les champs redactedAt et redactedBy conservent les valeurs de la première requête aboutie.

File capability differences

Operation

File memory

File views of structured memories

Ajouter, mettre à jour, renommer ou supprimer

Pris en charge

Renvoie l'erreur 409 READ_ONLY_STORE

Lister ou lire

Pris en charge

Pris en charge. L'opération ListItems renvoie readOnly: true.

Lister, lire ou expurger les versions historiques

Pris en charge

Non disponible. Renvoie l'erreur 400.

Common file API errors

HTTP status code

Error code

Condition

400

VALIDATION_ERROR

Le type d'élément, l'étendue (Scope), le chemin, le curseur de pagination, la branche de mise à jour ou les paramètres de version ne sont pas valides, ou la vue de fichier actuelle ne fournit pas les fonctionnalités de gestion des versions.

400

INVALID_PARAMETER

Une API d'élément est appelée pour un magasin de mémoire qui ne fournit pas les fonctionnalités de fichier.

404

NOT_FOUND

Le fichier ou la version historique n'existe pas.

409

PATH_EXISTS

Le nouveau chemin ou la destination du renommage existe déjà.

409

SHA_MISMATCH

La valeur expectedSha256 ne correspond pas au contenu actuel, ou une mise à jour hautement concurrente ne peut pas aboutir.

409

LOCK_CONFLICT

Une modification concurrente est en cours pour la même étendue (Scope). Réessayez après un court délai d'attente.

409

QUOTA_EXCEEDED

Le nombre de fichiers dans l'étendue (Scope) actuelle a atteint la limite.

409

READ_ONLY_STORE

Une requête tente de modifier une vue de fichier en lecture seule générée à partir de mémoires structurées.

413

PAYLOAD_TOO_LARGE

Le contenu du fichier dépasse la limite de taille par fichier.

En cas d'erreurs SHA_MISMATCH ou LOCK_CONFLICT, lisez le dernier fichier avant de décider de réessayer. Pour connaître toutes les limites des API de fichier, consultez la rubrique Limitations et notes. Pour l'intégration du SDK, reportez-vous à la documentation Agent Storage SDK.