> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# API Memory

L'API Memory fournit des méthodes permettant de gérer les fils de conversation et l'historique des messages dans Mastra.

## Obtenir tous les fils

Récupérez tous les fils de mémoire d'une ressource donnée :

```typescript
const threads = await mastraClient.listMemoryThreads({
  resourceId: 'resource-1',
  agentId: 'agent-1', // Optional - can be omitted if storage is configured
})
```

Lorsque `agentId` est omis et que le stockage est configuré sur le serveur, les fils sont récupérés directement depuis le stockage. Cela s'avère utile lorsque plusieurs agents partagent les mêmes fils (par exemple, dans les workflows comprenant plusieurs étapes d'agent).

## Créer un nouveau fil

Créez un nouveau fil de mémoire :

```typescript
const thread = await mastraClient.createMemoryThread({
  title: 'New Conversation',
  metadata: { category: 'support' },
  resourceId: 'resource-1',
  agentId: 'agent-1',
})
```

## Travailler avec un fil précis

Obtenez une instance d'un fil de mémoire précis :

```typescript
const thread = mastraClient.getMemoryThread({ threadId: 'thread-id', agentId: 'agent-id' })
```

## Méthodes des fils

### Obtenir les détails d'un fil

Récupérez les détails d'un fil précis :

```typescript
const details = await thread.get()
```

### Mettre à jour un fil

Mettez à jour les propriétés d'un fil :

```typescript
const updated = await thread.update({
  title: 'Updated Title',
  metadata: { status: 'resolved' },
  resourceId: 'resource-1',
})
```

### Supprimer un fil

Supprimez un fil et ses messages :

```typescript
await thread.delete()
```

### Cloner un fil

Créez une copie d'un fil avec tous ses messages :

```typescript
const { thread: clonedThread, clonedMessages } = await thread.clone()
```

Clonez-le avec des options :

```typescript
const { thread: clonedThread, clonedMessages } = await thread.clone({
  newThreadId: 'custom-clone-id',
  title: 'Cloned Conversation',
  metadata: { branch: 'experiment-1' },
  options: {
    messageLimit: 10, // Only clone last 10 messages
  },
})
```

Clonez-le en filtrant les messages :

```typescript
const { thread: clonedThread } = await thread.clone({
  options: {
    messageFilter: {
      startDate: new Date('2024-01-01'),
      endDate: new Date('2024-01-31'),
    },
  },
})
```

La réponse du clonage comprend :

- `thread` : le nouveau fil cloné, accompagné des métadonnées de clonage
- `clonedMessages` : tableau des messages clonés avec de nouveaux identifiants

## Opérations sur les messages

### Enregistrer des messages

Enregistrez des messages dans la mémoire :

```typescript
const result = await mastraClient.saveMessageToMemory({
  messages: [
    {
      role: 'user',
      content: 'Hello!',
      id: '1',
      threadId: 'thread-1',
      resourceId: 'resource-1',
      createdAt: new Date(),
      format: 2,
    },
  ],
  agentId: 'agent-1',
})

// result.messages contains the saved messages
console.log(result.messages)
```

### Récupérer les messages d'un fil

Obtenez les messages associés à un fil de mémoire :

```typescript
// Get all messages in the thread (paginated)
const result = await thread.listMessages()
console.log(result.messages) // Array of messages
console.log(result.total) // Total count
console.log(result.hasMore) // Whether more pages exist

// Get messages with pagination
const result = await thread.listMessages({
  page: 0,
  perPage: 20,
})

// Get messages with ordering
const result = await thread.listMessages({
  orderBy: { field: 'createdAt', direction: 'ASC' },
})

// Get messages with shallow metadata filters
const result = await thread.listMessages({
  filter: {
    metadata: {
      category: 'billing',
      escalated: true,
      priority: 2,
      archivedAt: null,
    },
  },
})
```

Les filtres de métadonnées ne correspondent qu'aux valeurs scalaires de premier niveau : `string`, `number` fini, `boolean` et `null`. Chaque paire clé-valeur doit correspondre selon une logique AND. `null` ne correspond qu'aux clés explicitement définies sur `null`. Les clés de métadonnées doivent commencer par une lettre ou un trait de soulignement et ne contenir que des caractères alphanumériques ou des traits de soulignement. Leur longueur est limitée à 128 caractères. Les clés de prototype réservées telles que `__proto__`, `constructor` et `prototype` ne sont pas autorisées. Les performances dépendent du backend de stockage du serveur, et des filtres de métadonnées arbitraires peuvent nécessiter l'analyse des messages candidats.

### Supprimer des messages

Supprimez un ou plusieurs messages d'un fil :

```typescript
// Delete a single message
const result = await thread.deleteMessages('message-id')

// Delete multiple messages
const result = await thread.deleteMessages(['message-1', 'message-2', 'message-3'])

// Returns: { success: true, message: "Message deleted successfully" }
```

## Mémoire de travail

La mémoire de travail permet aux agents de conserver des informations persistantes sur les utilisateurs d'une interaction à l'autre. Sa portée peut se limiter à un fil précis ou s'étendre à tous les fils d'une ressource (utilisateur).

### Obtenir la mémoire de travail

Récupérez la mémoire de travail actuelle d'un fil :

```typescript
const workingMemory = await mastraClient.getWorkingMemory({
  agentId: 'agent-1',
  threadId: 'thread-1',
  resourceId: 'user-123', // Optional, required for resource-scoped memory
})
```

La réponse comprend :

- `workingMemory` : le contenu actuel de la mémoire de travail (chaîne ou null)
- `source` : indique si la mémoire provient de la portée `"thread"` ou `"resource"`
- `workingMemoryTemplate` : le modèle utilisé pour la mémoire de travail (s'il est configuré)
- `threadExists` : indique si le fil existe

### Mettre à jour la mémoire de travail

Mettez à jour le contenu de la mémoire de travail d'un fil :

```typescript
await mastraClient.updateWorkingMemory({
  agentId: 'agent-1',
  threadId: 'thread-1',
  workingMemory: `# User Profile
- Name: John Doe
- Location: New York
- Preferences: Prefers formal communication
`,
  resourceId: 'user-123', // Optional, required for resource-scoped memory
})

// Returns: { success: true }
```

Pour une mémoire de travail dont la portée est une ressource, vous devez fournir le paramètre `resourceId`. Il permet à la mémoire de persister dans tous les fils de conversation de cet utilisateur.

### Obtenir l'état de la mémoire

Vérifiez l'état du système de mémoire :

```typescript
const status = await mastraClient.getMemoryStatus('agent-id')
```