Aller au contenu principal

E-10 Gestionnaire de mémoire

Brique E: Données, RAG, contexte, mémoire. Version anglaise: E-10-memory-manager

1. Rôle et responsabilités​

Mémoire de session et persistante (utilisateur, agent, projet) avec ACL, TTL, classification et effacement.

  • Écrire avec contrôle DLP et politique d'écriture
  • Rechercher sémantiquement (E-07)
  • Expirer et effacer (E-12)

2. Position dans l'architecture et interactions​

  • Appelants: Agents, Context Manager, SDK.
  • Chemin d'exécution: Synchrone.
  • Toute interaction passe par l'API Control Plane v1 (/v1) derrière la passerelle API (D-14).

3. Composant open source et partie développée​

  • Open source: PostgreSQL + Qdrant
  • Développé: Entièrement développé.
  • Intégration externe via un adaptateur eai/integrations/<system>.py avec repli in-process lorsque l'URL n'est pas configurée.

4. Modèle de données​

Tables (schéma eai, RLS tenant_id):

  • eai.memory_items

Colonnes communes : id uuid, tenant_id uuid NOT NULL, created_at, updated_at ; politique RLS current_setting('app.tenant_id', true)::uuid.

5. Contrat​

  • Contrat appliqué: memory-contract
  • Schéma JSON: contracts/v1/memory-contract.schema.json
  • Champs clés: scope, kind, content, content_ref, embedding_ref, classification, acl, ttl_seconds, expires_at, write, deletion, version
  • Validation : POST /v1/contracts/{name}/validate ; application d'un manifeste : POST /v1/manifests/apply.

6. Endpoints API​

  • POST /v1/memory
  • GET /v1/memory
  • GET /v1/memory/{id}
  • DELETE /v1/memory/{id}
  • POST /v1/memory/search

Requête POST /v1/memory:

{
  "scope": { "type": "user", "id": "usr_42" },
  "kind": "preference",
  "content": "Préfère le français",
  "classification": "internal",
  "ttl_seconds": 7776000
}

Réponse:

{
  "memory_id": "mem_5",
  "version": 1,
  "expires_at": "2025-04-10T10:00:00Z"
}

7. Exemples SDK​

Python:

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_xxx_secret")
m = client.memory.write(scope={"type": "user", "id": "usr_42"}, kind="preference", content="Préfère le français")
client.memory.delete(m["memory_id"])

TypeScript:

import { EnterpriseAI } from "@enterprise-ai/sdk";

const client = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY });
const m = await client.memory.write({ scope: { type: "user", id: "usr_42" }, kind: "preference", content: "Prefers French" });

Java:

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .build();
JsonNode m = client.memory().write(Map.of("scope", Map.of("type", "user", "id", "usr_42"), "kind", "preference", "content", "Prefers French"));

Go:

c, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
m, _ := c.Memory.Write(ctx, map[string]any{"scope": map[string]any{"type": "user", "id": "usr_42"}, "kind": "preference", "content": "Prefers French"})

8. Configuration​

  • Variables d'environnement: EAI_DATABASE_URL
  • Clés Helm: controlPlane.config, controlPlane.secrets

9. Contrôles de sécurité​

  • Aucun secret ni donnée restricted en mémoire persistante
  • ACL OpenFGA par item
  • Toutes les requêtes portent le tenant issu du credential ; RLS PostgreSQL
  • Chaque mutation et décision de politique écrit un événement d'audit chaîné

10. Observabilité​

  • Métriques Prometheus: eai_memory_items{scope}, eai_memory_writes_total
  • Traces: spans OpenTelemetry avec conventions sémantiques GenAI (gen_ai.operation.name, gen_ai.agent.id, gen_ai.tool.name), attributs eai.tenant_id, eai.run_id, propagation traceparent.
  • Actions d'audit: memory.create, memory.delete

11. Unités FinOps​

  • Items stockés, embeddings, recherches.
  • Émis comme Usage Event (POST /v1/finops/usage) avec tenant, projet, agent et run.

12. Modes de défaillance et résilience​

  • Version optimiste (409 sur conflit)
  • Erreurs normalisées (enveloppe error, message_i18n en/fr)

13. Adoption autonome (client d'un client)​

  • enterprise_ai.memory + Control Plane.
  • SDK: enterprise_ai.privacy / dlp / knowledge_bases / memory / retention / lineage
  • Déploiement minimal : chart Helm avec controlPlane.enabled=true et PostgreSQL ; les composants externes désactivés utilisent leur repli in-process.

14. Tests d'acceptation​

  1. Item expiré non retourné
  2. Écriture d'un IBAN bloquée
  3. Accès inter-tenant refusé
  4. Erreur renvoyée en fr avec Accept-Language: fr