Mémoire d’agent gérée (hérité)

attention

Ancien

Il s’agit d’une version antérieure du magasin de mémoire d’agent géré qui sera bientôt abandonnée. N’y créez pas de nouveaux agents. Pour la mémoire d’agent à long terme, utilisez plutôt Mémoire d’agent gérée.

La mémoire d'agent managée offre à vos agents une mémoire à long terme d'une conversation à l'autre. Databricks gère l'infrastructure et isole les mémoires de chaque périmètre, de sorte que vous n'avez pas à gérer vous-même le stockage ou le partitionnement.

Avec la mémoire gérée, vos agents peuvent :

• Mémorisez les préférences des utilisateurs, les décisions passées et le contexte cumulé au fil des conversations.
• Sécurisez ces connaissances grâce à la gouvernance Unity Catalog.
• Partagez la mémoire entre les agents et les projets.
• Améliorez leur précision et leur efficacité au fil du temps.

Prérequis

• Un workspace Databricks avec Unity Catalog activé.
• Le privilège CREATE MEMORY STORE sur le schéma parent pour créer des magasins de mémoire.

Fonctionnement de la mémoire gérée

La mémoire managée comporte deux niveaux :

• Un magasin de mémoire est un élément sécurisable Unity Catalog qui fait office de conteneur pour les entrées de mémoire. Un magasin de mémoire hérite des mêmes gouvernance, contrôle d'accès et traçabilité que n'importe quel autre asset Unity Catalog.
• Une entrée de mémoire correspond à un élément de contenu individuel stocké dans un magasin de mémoire. Chaque entrée est identifiée par une portée et un chemin. La portée détermine à quel utilisateur appartient une entrée, et le chemin organise les entrées au sein d'une portée, de la même manière qu'un chemin d'accès de fichier (par exemple, /memories/preferences.md).

Portée

La portée détermine comment rendre une mémoire privée pour un utilisateur ou partagée au sein d’un groupe. Votre application définit une portée lors de chaque lecture et écriture, et une recherche renvoie uniquement les entrées dont la portée correspond. Choisissez la stratégie qui correspond à ce que votre agent doit retenir :

• Mémoire privée pour chaque utilisateur : définissez le périmètre sur l'identité vérifiée de l'utilisateur final. Chaque utilisateur obtient sa propre partition et ne voit que ses propres entrées. La valeur user_client résout l'ID de l'utilisateur final pour vous.

  • Exemple : un agent d’assistance mémorise les préférences de communication et les tickets passés d’un utilisateur.

• Mémoire partagée pour un groupe : définissez le scope sur une clé fixe de votre choix, telle qu’un ID d’organisation, d’équipe ou de projet. Chaque utilisateur lit et écrit les mêmes mémoires.

  • Exemple : Un agent d’équipe mémorise un glossaire partagé de termes d’entreprise et de politiques internes.

• Mémoire divisée par un autre élément : constituez la portée à partir de vos propres valeurs, telles qu'un ID de tenant ou un composite user_id:project.

  • Exemple : Une application multi-tenant sépare la mémoire de chaque client, ou la mémoire d'un seul utilisateur est isolée par projet.

Un seul agent peut combiner des stratégies au sein d’une même conversation. Par exemple, il peut lire la mémoire privée d’un utilisateur et la mémoire d’équipe partagée dans la même requête.

Définissez le périmètre dans le code de votre application, à partir du contexte de l’appelant de confiance que la requête ne peut pas corrompre : l’identité vérifiée de l’utilisateur final issue du jeton OBO pour la mémoire par utilisateur, ou une clé de tenant, d’équipe ou de projet de confiance pour la mémoire partagée. Ne laissez jamais le modèle le choisir. Si votre stratégie de périmètre dépend d’une identité d’utilisateur final, rejetez les requêtes qui en sont dépourvues au lieu de vous rabattre sur un périmètre partagé. La compétencemanaged-memory vous guide tout au long de cette configuration.

La portée sépare les mémoires, mais elle n'accorde pas l'accès au magasin. Un appelant a toujours besoin du privilège READ MEMORY STORE ou WRITE MEMORY STORE pour l'ouvrir. Voir Contrôle de l'accès à la mémoire.

attention

La portée est la limite d'isolation entre les utilisateurs, mais il ne s'agit pas d'un contrôle d'accès. Le Service Principal de l'application Databricks peut lire toutes les portées, veillez donc à protéger ses identifiants en conséquence.

Ce que l’agent enregistre et rappelle

La mémoire gérée fournit le magasin de mémoire et les APIs pour la lecture et l’écriture d’entrées. Votre application contrôle ce que l’agent enregistre, le moment où il récupère la mémoire et la façon dont il utilise les résultats.

Définissez ce comportement dans l’invite système de l’agent : indiquez à l’agent quelles informations durables enregistrer et à quel moment les récupérer. La compétence managed-memory et le Template conservent cette invite système dans une constante nommée MEMORY_INSTRUCTIONS. Le périmètre est configuré séparément dans le code d’application sécurisé et n’est jamais choisi par le modèle.

Adaptez la formulation à votre stratégie de périmètre. Voici un exemple pour la stratégie par utilisateur :

You have durable, cross-session memory about whoever (or whatever) this conversation is scoped to. Use it deliberately, not by reflex.

Recall whenever the answer is about the user or calls for personalized information — anything that might draw on preferences, decisions, or workflows they've shared before — and you don't already have it from this conversation; also list once before saving, to find the right existing topic. Don't tell the user you don't know their preferences without checking — list_memories first. Skip memory only when the answer truly doesn't depend on who's asking (general knowledge, math, coding) or you already have what you need. A `[has_contents]` entry has a body to get_memory; one without is fully captured by its description. Open a memory with get_memory before you state its specifics, and never assert a fact that isn't stored — if nothing relevant is stored, just answer without it. Don't re-list what you've already seen this turn.

Save only what will still matter in a future, unrelated conversation — a stable preference, fact, decision, or ongoing project the user actually stated or decided. Don't save your own suggestions or guesses, passing chatter, secrets, or anything scoped to this chat ("for now", a one-off label).
- Write each memory so it stands on its own out of context, under one broad, stable /memories/... topic per subject with the specifics inside it.
- Check the list first and update_memory an existing topic instead of minting a near-duplicate.
- For a very broad question that touches many memories, summarize from the list's descriptions; reserve get_memory for the specific entry you actually need.
- If the user's info changes or contradicts what's stored, update or replace it rather than keeping both — but don't rewrite a memory that already says the same thing.
- delete_memory what's stale.
- Briefly tell the user whenever you save, update, or delete.

Commencez avec les compétences de mémoire gérée

Le moyen le plus simple d’ajouter une mémoire gérée à un agent consiste à utiliser la compétence Claude Code managed-memory. La compétence gère toute la configuration pour vous et fonctionne à la fois avec le SDK OpenAI Agents et LangGraph.

Intégrez la compétence à votre projet de l’une des deux manières suivantes :

Start from a template

La compétence est intégrée aux Template d’application Databricks. Créez l’échafaudage d’un nouvel agent à partir de l’un des Template d’agent, puis recherchez la compétence sous .claude/skills/managed-memory/.

1. Clonez le repository des Template :

   Bash

   git clone https://github.com/databricks/app-templates.git

2. Parcourez le app-templates, puis sélectionnez un Template d’agent pour start. Par exemple, pour utiliser le Template OpenAI Agents SDK :

   Bash

   cd app-templates/agent-openai-agents-sdk

remarque

Pour les Template d'application « advanced », après le déploiement, vous devez accorder les privilèges Lakebase Postgres au Service Principal de l'application, faute de quoi la configuration de la session renverra une erreur 502.

3. Une fois la compétence dans votre projet, décrivez ce que vous souhaitez et votre assistant de code s'occupe du reste :

prompt

Add Databricks managed long-term memory to my agent.

Add the skill to an existing project

Si vous possédez déjà un projet d'agent, ajoutez-lui la compétence.

1. Créez le répertoire des compétences s’il n’existe pas :

   Bash

   mkdir -p .claude/skills/managed-memory

2. Download the SKILL.md file depuis le répertoire de compétencesmanaged-memory et enregistrez-le dans .claude/skills/managed-memory/.

3. Une fois la compétence dans votre projet, décrivez ce que vous souhaitez et votre assistant de code s'occupe du reste :

prompt

Add Databricks managed long-term memory to my agent.

Créer et utiliser un magasin de mémoire manuellement

Cette section montre comment créer et utiliser un magasin de mémoire sans la compétence Claude Code managed-memory.

L’exemple suivant configure une mémoire gérée pour un agent de support client qui stocke les préférences d’un utilisateur et les récupère lors d’une conversation ultérieure.

1. Générez un jeton OAuth à l’aide de la CLI Databricks pour appeler les APIs :

   Bash

   databricks auth login --host ${DATABRICKS_HOST}
   databricks auth token

2. Créez un magasin de mémoire pour conserver les souvenirs de votre agent :

   Bash

   curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "support_agent_memory",
       "catalog_name": "main",
       "schema_name": "default",
       "description": "Long-term memory for the customer support agent"
     }'

3. Écrivez une entrée de mémoire après que l'agent a appris quelque chose sur un utilisateur. Le paramètre scope partitionne l'entrée pour un utilisateur unique. Utilisez le champ contents pour le texte complet de la mémoire et le champ description comme court résumé qui améliore la recherche :

   Bash

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries?scope=user-123" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "path": "/memories/preferences.md",
       "contents": "Prefers email communication. Timezone: PST. Has an Enterprise subscription.",
       "description": "User 123 communication preferences and account details"
     }'

4. Recherchez les entrées de mémoire pour cet utilisateur dans une conversation ultérieure afin de récupérer ce que l’agent a appris :

   Bash

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries:search" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "scope": "user-123",
       "query": "communication preferences"
     }'

Pour l’API REST complète, y compris les Endpoint, les champs de requête et les champs de réponse, consultez la documentation de référence de l’API Memory.

Ajouter une mémoire à un agent avec des conversations

Le workflow REST ci-dessus appelle directement le magasin de mémoire et les APIs d’entrée. Lorsque vous créez un agent sur un endpoint de service des modèles Databricks, connectez plutôt un magasin de mémoire à une conversation avec le client compatible OpenAI dans le SDK databricks-openai.

Une conversation est un état de conversation compatible avec OpenAI (l’historique d’exécution des messages et des appels d’outils), pris en charge par un magasin de mémoire et épinglé à un seul scope. Réutilisez la même conversation d’une requête à l’autre pour donner à l’agent la mémoire des tours précédents.

1. Liez un magasin de mémoire existant et un scope à une nouvelle conversation. memory_store.name est le nom à trois niveaux du magasin, et scope partitionne l’état de la conversation, généralement par utilisateur final :

   Python

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   workspace_client = WorkspaceClient()
   user_id = str(workspace_client.current_user.me().id)
   
   client = DatabricksOpenAI(workspace_client=workspace_client, use_ai_gateway=True)
   
   conversation = client.conversations.create(
       extra_body={
        "memory_store": {"name": "main.default.support_agent_memory"},
        "scope": {"kind": "user", "value": user_id},
    },
   )

2. Transmettre l'ID de conversation à responses.create. L'agent lit et écrit l'état de la conversation dans le magasin de mémoire lié sous cette portée :

   Python

   response = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "What is the average NYC taxi price?"}],
       stream=True,
   )
   
   for event in response:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)

3. Réutilisez le même ID de conversation lors des requêtes ultérieures pour que l’agent se souvienne des tours précédents. Ne créez pas de nouvelle conversation par tour :

   Python

   followup = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "Restate the average taxi price you found, and how it was calculated."}],
       stream=True,
   )
   
   for event in followup:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)

Pour en savoir plus sur les endpoints de conversation et les champs de requête, consultez APIs Conversation.

Contrôle de l'accès à la mémoire

Les magasins de mémoire sont des éléments sécurisables Unity Catalog. Les privilèges suivants contrôlent l’accès :

Privilège	S’applique à	Description
CREATE MEMORY STORE	Schéma parent	Créer de nouveaux magasins de mémoire sous un schéma.
READ MEMORY STORE	Magasin de mémoire	Lire les métadonnées d’un magasin de mémoire et ses entrées.
WRITE MEMORY STORE	Magasin de mémoire	Créer, mettre à jour et supprimer des entrées de mémoire dans un magasin.
MANAGE	Magasin de mémoire	Update or delete the memory store itself. Accorder des autorisations à d’autres utilisateurs.
USE SCHEMA	Schéma parent	Lister les magasins de mémoire dans un schéma.

Privilège	S’applique à	Description
CREATE MEMORY STORE	Schéma parent	Créer de nouveaux magasins de mémoire sous un schéma.
READ MEMORY STORE	Magasin de mémoire	Lire les métadonnées d’un magasin de mémoire et ses entrées.
WRITE MEMORY STORE	Magasin de mémoire	Créer, mettre à jour et supprimer des entrées de mémoire dans un magasin.
MANAGE	Magasin de mémoire	Update or delete the memory store itself. Accorder des autorisations à d’autres utilisateurs.
USE SCHEMA	Schéma parent	Lister les magasins de mémoire dans un schéma.

Implémenter une mémoire à court terme

Les APIs d’entrée de mémoire fournissent une mémoire à long terme en tant d’outils à utiliser par votre agent. Pour doter votre agent d’une mémoire à court terme gérée dans une session, Databricks recommande de lier votre magasin de mémoire à une conversation. Vous pouvez également :

• Conservez la mémoire de session de votre framework d’agents, telle que le parameter OpenAI session= ou un point de contrôle LangGraph.
• Utilisez des sessions d’agents gérées pour le magasin d’historique des conversations.

Recommandations de sécurité

Databricks fournit le magasin gouverné, le chiffrement, les primitives d’isolation et la piste d’audit. En tant que développeur d’applications, Databricks recommande ce qui suit :

• Utilisez la portée par utilisateur default (user_client) sauf si vous avez une raison précise de cloisonner différemment (par exemple, une mémoire par projet ou par compte).
• Accordez le privilège minimal : seul le service principal Databricks de votre agent a besoin de WRITE MEMORY STORE. Accordez READ MEMORY STORE de manière restrictive et évitez les attributions larges à des utilisateurs humains ou à de grands groupes.
• Protégez l’identifiant de Service Principal Databricks de l’application : il s’agit de la clé du plan de données du magasin. Traitez-le comme n’importe quel identifiant de service à haute valeur : utilisez des jetons à durée de vie courte, évitez de l’enregistrer dans les journaux et ajoutez des défenses SSRF à votre application.

Limitations

• Les entrées de mémoire fournissent uniquement une mémoire à long terme. Pour l’historique des conversations, consultez les sessions d’agent gérées.
• Les magasins et les entrées de mémoire sont créés et gérés exclusivement via l'API REST Unity Catalog ; il n'existe pas de SDK Python pour ces APIs. Pour utiliser un magasin de mémoire à partir d'un agent, connectez-le à une conversation avec le client compatible OpenAI. Consultez Ajouter de la mémoire à un agent avec des conversations.

Étapes suivantes

• Référence de l’API Memory