Tablestore:Mémoire de fichiers

1. Créer un magasin de mémoire

Créez un magasin de mémoire qui produit à la fois une mémoire structurée et des fichiers :

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="your-api-key",
    ots_endpoint="https://your-instance.cn-beijing.ots.aliyuncs.com",
    ots_instance_name="your-instance-name",
)

client.create_memory_store({
    "memoryStoreName": "agent_memory",
    "description": "Conversation memory for an agent",
    "inputType": "messages",
    "outputTypes": ["structured", "file"],
})

2. Écrire des conversations

Écrivez des messages de conversation dans le magasin de mémoire. Le service génère des fichiers en lecture seule de manière asynchrone.

resp = client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "shopping-app",
        "tenantId": "user-001",
        "agentId": "shopping-assistant",
        "runId": "session-001",
    },
    "messages": [
        {"role": "user", "content": "I usually drink Americano coffee without sugar."},
        {"role": "assistant", "content": "Okay, I will remember your beverage preference."},
    ],
    "sync": False,
})
request_id = resp["requestId"]

3. Attendre la fin de la génération des fichiers

Interrogez l'état de la tâche de génération pour confirmer que le service a généré les fichiers en lecture seule.

task = client.get_memory_task({
    "memoryStoreName": "agent_memory",
    "requestId": request_id,
})
print(task["task"]["status"])

Lorsque task.status est completed, toutes les sorties configurées ont été générées. Pour les magasins de mémoire à double sortie, la tâche globale est completed uniquement après la génération de la mémoire structurée et des fichiers.

4. Lister et lire les fichiers

Utilisez le périmètre exact à quatre niveaux de l'opération d'écriture pour parcourir les fichiers en lecture seule générés par le service. Les fichiers générés par le service ne prennent pas en charge les périmètres avec caractères génériques.

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

page = client.list_items({
    "type": "memoryfile",
    "memoryStoreName": "agent_memory",
    "scope": scope,
    "limit": 20,
})

# Get the actual path from items, then read the content
for entry in page["items"]:
    item = client.get_item({
        "type": "memoryfile",
        "memoryStoreName": "agent_memory",
        "scope": scope,
        "path": entry["path"],
        "view": "full",
    })
    print(item["path"], item["content"])

L'appel des interfaces de création, de mise à jour, de renommage ou de suppression sur ces fichiers renvoie 409 READ_ONLY_STORE. Pour modifier le contenu, continuez à écrire des conversations ou maintenez la mémoire source via les interfaces de mémoire structurée.

Préparer l'environnement

• Obtenez l'exécutable Linux agent-memory-fuse correspondant à l'architecture de votre environnement d'exécution et ajoutez les permissions d'exécution.

• FUSE est activé dans le noyau Linux et l'utilisateur actuel ou le conteneur peut accéder à /dev/fuse.

• fusermount3 est installé. Sur certains systèmes, le nom de la commande est fusermount.

• Un magasin de mémoire de fichiers avec storageMode=filemem a été créé. Préparez le endpoint HTTPS de l'instance, le nom de l'instance et le périmètre complet à quatre niveaux.

• Une clé API, un AccessKey ou des identifiants temporaires STS sont prêts. Les clés API doivent être utilisées avec des endpoints HTTPS.

L'exécution dans un conteneur nécessite généralement de mapper /dev/fuse et d'accorder CAP_SYS_ADMIN ou des permissions de montage d'espace utilisateur équivalentes. Utilisez une configuration avec le principe du moindre privilège en fonction de votre environnement d'exécution.

chmod +x ./agent-memory-fuse
mkdir -p /mnt/agent-memory

Monter la mémoire de fichiers

Exécutez la commande suivante. Le périmètre dans l'exemple correspond à l'objet scope du démarrage rapide. Utilisez des guillemets pour entourer le périmètre complet afin d'éviter que le shell n'interprète incorrectement les caractères spéciaux.

./agent-memory-fuse mount \
  --endpoint https://your-instance.cn-beijing.ots.aliyuncs.com \
  --instance your-instance-name \
  --credential apikey:your-api-key \
  --store agent_files \
  --scope 'app-001#user-001#assistant#session-001' \
  --session fuse-session-001 \
  /mnt/agent-memory

La commande de montage s'exécute au premier plan et gère le cycle de vie du montage. Le journal suivant indique que le chargement initial du répertoire et le montage ont réussi.

mounted /mnt/agent-memory: store=agent_files files=1 readOnly=false

Maintenez ce processus en cours d'exécution et accédez au répertoire monté depuis un autre terminal ou processus métier. En production, utilisez systemd ou un système d'orchestration de conteneurs pour gérer le processus. Ne terminez pas brutalement le processus tant que le montage est encore utilisé.

Les principaux paramètres sont les suivants.

--credential contient des informations sensibles. L'exemple montre uniquement le format du paramètre. N'écrivez pas d'identifiants réels dans le code, les images, les journaux ou les scripts partagés. Privilégiez les identifiants à courte durée de vie avec des permissions restreintes.

Lire et écrire des fichiers

Une fois le montage réussi, vous pouvez lire, créer, modifier, renommer et supprimer des fichiers comme dans un répertoire classique.

# View existing server-side files
find /mnt/agent-memory -type f
cat /mnt/agent-memory/profile/preferences.md

# Create or update files
mkdir -p /mnt/agent-memory/projects/alpha
printf '%s\n' '# Project decisions' '' '- Use an event-driven architecture' \
  > /mnt/agent-memory/projects/alpha/decisions.md
cat /mnt/agent-memory/projects/alpha/decisions.md

# Rename and delete files
mv /mnt/agent-memory/projects/alpha/decisions.md \
  /mnt/agent-memory/projects/alpha/architecture.md
rm /mnt/agent-memory/projects/alpha/architecture.md

Les fichiers sont synchronisés avec le serveur lors de flush, fsync ou close. Les applications de production doivent vérifier les valeurs de retour de fsync et close. Certaines redirections de shell ne signalent pas les erreurs lors de l'étape close. Pour les écritures importantes, relisez le fichier après achèvement pour confirmer.

Les répertoires sont formés à partir des préfixes de chemin de fichier. Les répertoires contenant des fichiers peuvent être restaurés entre les processus et les remontages. Les répertoires vides existent uniquement au sein du processus de montage actuel.

Montage en lecture seule

Si l'agent a seulement besoin de lire la mémoire, ajoutez --read-only avant l'argument du répertoire de montage.

./agent-memory-fuse mount \
  --endpoint https://your-instance.cn-beijing.ots.aliyuncs.com \
  --instance your-instance-name \
  --credential apikey:your-api-key \
  --store agent_files \
  --scope 'app-001#user-001#assistant#session-001' \
  --session fuse-reader-001 \
  --read-only \
  /mnt/agent-memory

Pour les vues de fichiers en lecture seule générées à partir de la mémoire structurée, le serveur bascule automatiquement le montage en lecture seule. Les opérations d'écriture sur un montage en lecture seule renvoient EROFS.

Rotation des identifiants STS

Lors du montage avec des identifiants STS, vous pouvez effectuer la rotation complète de l'AccessKey ID, de l'AccessKey Secret et du STS Token sans démonter le répertoire. Le fournisseur d'identifiants doit écrire le JSON suivant sur la sortie standard et le canaliser vers la commande de rotation.

{"accessKeyId":"new-access-key-id","accessKeySecret":"new-access-key-secret","stsToken":"new-sts-token"}

your-credential-provider | \
  ./agent-memory-fuse rotate-credential --mountpoint /mnt/agent-memory

La commande de rotation lit les identifiants depuis l'entrée standard pour éviter de placer de nouveaux identifiants dans les arguments de ligne de commande. Une commande réussie indique que les nouveaux identifiants ont été installés dans le processus de montage local. La validité des identifiants sera confirmée lors des requêtes de fichiers suivantes. Seuls les processus de confiance peuvent accéder au point de montage et effectuer la rotation des identifiants.

Démonter la mémoire de fichiers

Après avoir terminé les opérations sur les fichiers et fermé tous les fichiers ouverts, exécutez la commande suivante.

./agent-memory-fuse umount /mnt/agent-memory

Une fois le démontage réussi, le processus de montage au premier plan se termine. Si le système ne dispose ni de fusermount3 ni de fusermount, la commande de démontage renvoie une erreur. Installez d'abord les outils userspace FUSE.

Limites et dépannage

• Seul le texte UTF-8 valide est pris en charge. La taille maximale d'un seul fichier est de 100 KiB. Le dépassement de ces limites renvoie respectivement EILSEQ ou EFBIG.

• Chaque périmètre prend en charge un maximum de 2 000 fichiers actuels par défaut. Lorsque le quota est atteint, les écritures renvoient ENOSPC.

• Lorsque plusieurs clients modifient simultanément le même fichier, les handles de fichier obsolètes peuvent renvoyer ESTALE. Rouvrez et lisez le dernier contenu avant de décider de réessayer.

• Des identifiants invalides ou un STS Token expiré renvoient EACCES. Effectuez une rotation des identifiants ou remontez avec des identifiants valides.

• Une limitation de débit du service ou une brève indisponibilité peut renvoyer EAGAIN. L'outil effectue d'abord des tentatives limitées. Les applications doivent toujours utiliser des stratégies de backoff pour gérer les erreurs finales.

• Les liens symboliques, les liens physiques, les ACL, les attributs étendus, les fichiers clairsemés et les verrous de fichiers inter-sessions ne sont pas pris en charge.

• Si vous voyez operation not permitted ou si vous ne pouvez pas ouvrir /dev/fuse, vérifiez le mappage des périphériques, les permissions de l'utilisateur actuel et les capacités de montage du conteneur.

• Si vous voyez une erreur initial directory load, vérifiez si le endpoint, le nom de l'instance, les identifiants, le nom du magasin de mémoire et le périmètre correspondent.

Lire uniquement les métadonnées

current = client.get_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "includeContent": False,
})
print(current["contentSha256"], current["updatedAt"])

Mettre à jour le contenu d'un fichier

updated = client.update_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "content": "# User preferences\n\n- Prefers latte\n- Prefers concise responses\n",
    "expectedSha256": current["contentSha256"],
})

Renommer un fichier

renamed = client.update_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "newPath": "/profile/user-preferences.md",
    "expectedSha256": updated["contentSha256"],
})

Lister les fichiers avec pagination

next_token = None
while True:
    request = {
        "memoryStoreName": "agent_files",
        "scope": scope,
        "pathPrefix": "/profile/",
        "limit": 100,
    }
    if next_token:
        request["nextToken"] = next_token

    page = client.list_items(request)
    for entry in page["items"]:
        print(entry["path"])

    next_token = page.get("nextToken")
    if not next_token:
        break

Supprimer un fichier

client.delete_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/user-preferences.md",
    "expectedSha256": renamed["contentSha256"],
})

Caviarder les versions historiques

RedactItemVersion efface le chemin, le contenu, le hachage de contenu et la taille d'un instantané historique. Il conserve le type d'opération, la séquence de version, l'heure de création et les informations d'audit de caviardage. Les requêtes répétées sont idempotentes. Le caviardage ne modifie pas le fichier actuel et ne crée pas de nouvelle version.

redacted = client.redact_item_version({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "itemId": version["itemId"],
    "versionId": version["versionId"],
    "versionSeq": version["versionSeq"],
    "sessionId": "privacy-job-001",
})
print(redacted["redacted"], redacted["redactedAt"])

Après le caviardage, l'appel à GetItemVersion renvoie toujours la version, mais elle n'inclut plus content.