# API Mémoire

Lisez et écrivez de la mémoire via les contrats REST et MCP documentés avec des limites de périmètre explicites.

- Canonical: https://docs.xmemo.dev/fr/docs/api/memory
- Locale: fr-FR
- Content-Locale: fr-FR
- Canonical-Content-Digest: 446b069541121da293fcc920696cb4e6d4e9fd7cc186d28bbbc1c688a7b3ffcc
- Edition-Digest: da694aed0669049cfa7eae8dcab0975701436d815ab13eaf83f6bd77b57f3df2
- Source-Revision: sha256:004c0ac7668443326dc253ae102d38bbd116e9cc540e7df7d066772f28b3a152

## Points de terminaison et périmètres de mémoire publics

Les exemples ci-dessous utilisent les chemins /v1 présents dans le contrat OpenAPI validé. Authentifiez-vous avec X-API-Key (ou le format Bearer accepté par le serveur) ; les opérations de lecture nécessitent un jeton capable de lire et les écritures un jeton capable d'écrire. Le schéma de réponse OpenAPI est intentionnellement non typé pour la plupart des points de terminaison de mémoire, de sorte que les clés d'implémentation documentées sont indiquées séparément lorsque le serveur les renvoie actuellement. GET /v1/memories renvoie actuellement un objet avec memories (tableau) et total (nombre), mais ces propriétés ne sont pas déclarées dans OpenAPI.

- Créer/capturer : POST /v1/remember et POST /v1/memories (201).
- Lister : GET /v1/memories avec limit, offset et path (200).
- Rechercher : GET /v1/memories/search ; GET /v1/recall est la même opération de recherche (200).
- Assembler le contexte : POST /v1/recall/context (200).
- Mettre à jour : PATCH /v1/memories/{memory_id} ; supprimer : DELETE /v1/memories/{memory_id}.
- Oublier : POST /v1/memories/{memory_id}/forget ; restaurer : POST /v1/memories/{memory_id}/restore ; terminer le rappel : POST /v1/reminders/{reminder_id}/complete.

## Schémas de requête de création

POST /v1/remember accepte MemoryRememberRequest ; POST /v1/memories accepte MemoryStoreRequest. Les deux requièrent content (chaîne) et path (chaîne). Les champs facultatifs dans les schémas OpenAPI incluent metadata (objet), source (chaîne ou null), logic_path (chaîne ou null), embedding (tableau de nombres ou null), bucket (chaîne, valeur par défaut public), memory_id, semantic_key, memory_type, version, status, superseded_by, embedding_provider, embedding_model, embedding_dimension, importance, confidence, expires_at, scope, team_id et provenance. MemoryRememberRequest déclare en outre dedupe (booléen, valeur par défaut true) ; MemoryStoreRequest définit memory_type sur semantic et importance/confidence sur 0.5/1.0 par défaut.

```http
POST /v1/remember
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "content": "The actual text to remember.",
  "path": "projects/memory-os/decisions",
  "scope": "memory-os",
  "source": "codex",
  "metadata": { "kind": "decision" }
}
```

## Schémas de réponse de création

Le contenu de la réponse 201 d'OpenAPI est un objet JSON non typé pour les deux opérations de création. L'implémentation actuelle de remember renvoie {id: string, status: "remembered"} ; l'implémentation de store renvoie l'identifiant de la mémoire créée. Considérez-les comme un comportement d'implémentation, et non comme un schéma plus strict que ce que déclare le document OpenAPI validé.

```json
{
  "id": "<memory-id>",
  "status": "remembered"
}
```

## Recherche et rappel

GET /v1/memories/search et GET /v1/recall partagent l'opération Rechercher dans les mémoires et renvoient Cache-Control: no-store, private. Les filtres affinent la récupération et ne peuvent pas élargir ce que le jeton autorise.

```http
GET /v1/memories/search?query=current%20MCP%20decision&limit=5&scope=memory-os&explain=true
X-API-Key: <your-assigned-api-key>
```

## Paramètres de requête et réponse de recherche

Les paramètres de requête OpenAPI sont query (chaîne, obligatoire), limit (entier, valeur par défaut 5), threshold (nombre ou null), path (chaîne, valeur par défaut %), bucket (chaîne, valeur par défaut %), scope (chaîne ou null), team_id (chaîne ou null), memory_type (chaîne, valeur par défaut %), status (chaîne, valeur par défaut active), explain (booléen, valeur par défaut false), prefer_working (booléen, valeur par défaut false) et candidate_count (entier ou null). OpenAPI laisse la réponse 200 sous forme d'objet JSON non typé ; l'implémentation renvoie actuellement results (tableau) et coverage (nombre), et peut ajouter keyguard_decrypt_grant_ids le cas échéant.

- Structure de réponse actuellement observée : { results: [...], coverage: number }.
- La spécification ne déclare pas de maximum pour la limite de recherche ou candidate_count ; les clients doivent utiliser des valeurs prudentes et gérer les erreurs de validation.

## Schémas de requête et de réponse de contexte

POST /v1/recall/context accepte RecallContextRequest. query (chaîne) est obligatoire ; path et bucket valent par défaut %, memory_type vaut auto, status vaut active, max_items vaut 8, max_tokens vaut 1500, prefer_working vaut true, include_knowledge vaut false, et scope, team_id, threshold et limit acceptent la valeur null. La réponse 200 OpenAPI est un objet non typé ; l'implémentation standard pour un propriétaire authentifié renvoie un objet de contexte value-density-v2 avec version, query, retrieval_plan, budget, items, context_text et answer_status. La branche d'agent temporaire renvoie la version 1.0 avec les mêmes champs fondamentaux query/budget/items/context_text.

```http
POST /v1/recall/context
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "query": "recent progress on memory-os",
  "scope": "memory-os",
  "memory_type": "auto",
  "status": "active",
  "max_items": 8,
  "max_tokens": 1500,
  "prefer_working": true
}
```

## Schémas de mise à jour et d'oubli de mémoire

PATCH /v1/memories/{memory_id} accepte MemoryUpdateRequest : tous les champs sont facultatifs, et content, path, metadata, source, logic_path, embedding, bucket, semantic_key, memory_type, status, superseded_by, embedding_provider, embedding_model, embedding_dimension, importance, confidence, expires_at, scope, team_id, provenance, supersession_reason, merge_metadata (valeur par défaut true), merge_provenance (valeur par défaut true) et detect_conflicts (valeur par défaut true) sont déclarés. DELETE /v1/memories/{memory_id} accepte le mode de requête (valeur par défaut soft_delete) et reason ; mode=hard_delete et mode=redact sont irréversibles, et memory:write est accepté par les règles de compatibilité afin que les jetons d'écriture puissent supprimer définitivement les enregistrements. POST /v1/memories/{memory_id}/forget accepte MemoryForgetRequest avec mode (valeur par défaut soft_delete), reason, replacement_content et metadata. POST /v1/memories/{memory_id}/restore restaure les enregistrements supprimés de manière réversible. Les réponses 200 pour ces opérations de cycle de vie sont typées dans le schéma public OpenAPI.

```http
POST /v1/memories/<memory-id>/forget
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "mode": "soft_delete",
  "reason": "No longer needed"
}
```

## Pagination, erreurs et limites de débit

Seul GET /v1/memories expose la pagination de liste dans OpenAPI : limit vaut 100 par défaut et offset 0, avec un filtre de chemin facultatif. La recherche utilise limit plutôt qu'offset ; le contexte utilise max_items/max_tokens plutôt que des curseurs de page. L'erreur de validation documentée est HTTPValidationError : {detail: [{loc: (string|integer)[], msg: string, type: string}]}. Les échecs d'autorisation au moment de l'exécution utilisent le contrat d'erreur partagé sur la page Authentification. L'environnement d'exécution applique la politique memory_write de 180 par minute aux écritures/mutations de cycle de vie et la politique memory_search de 300 par minute aux lectures de recherche, rappel, contexte et mémoire, au sein d'une fenêtre de 60 secondes lorsqu'elle est activée ; les quotas sont configurables et absents d'OpenAPI.

```json
{
  "version": "value-density-v2",
  "query": "recent progress on memory-os",
  "retrieval_plan": {},
  "budget": {
    "max_items": 8,
    "max_tokens": 1500,
    "used_items": 3,
    "used_tokens": 412,
    "skipped_items": 0,
    "filtered_items": 0,
    "structured_skipped_items": 0,
    "budget_skipped_items": 0,
    "truncated_items": 0,
    "candidate_items": 3,
    "selection_strategy": "top-primary-plus-stable-value-density",
    "budget_tradeoff": false,
    "token_scope": "context_text"
  },
  "items": [],
  "context_text": "",
  "answer_status": "no_confirmed_answer"
}
```