Intégrer la mémoire dans les agents

Contrat Navin Memory Provider

Le contrat est décrit par contracts/v1/memory-provider.schema.json. Une instance de moteur annonce un ensemble déclaratif de capacités : schema_version, provider (builtin, mem0 ou cognee), engine_instance, capabilities, et leur partage en memory et knowledge. La lecture des capacités ne demande aucun identifiant du moteur ; elle ajoute isolation, la garantie de séparation pour le tenant de l'appelant, et session_memory, vrai pour builtin seulement.

Groupe	Capacités
Mémoire	remember, recall, search, update, forget, list, get, purge, get_health, get_capabilities
Connaissances	ingest_knowledge, build_graph, search_graph, get_relations, delete_dataset

builtin et mem0 annoncent toutes les capacités de mémoire ; cognee annonce forget, list, purge, get_health, get_capabilities et toutes les capacités de connaissances. Une opération hors de l'ensemble annoncé répond memory_capability_unsupported (422) ; un moteur injoignable répond memory_engine_unavailable (502). Le contexte de chaque opération ($defs.context du schéma) est construit côté serveur.

Instances de moteur

Toutes les routes sont sous /v1/memory.

Méthode et chemin	Rôle requis	Effet
GET /engines	authentifié	builtin, les instances mem0 et cognee rendues par le Manager, les instances déclarées
GET /engines/{engine_id}/capabilities	authentifié	capacités, isolation, session_memory
GET /engines/{engine_id}/health	tenant_admin, developer, security_officer ou auditor	santé du moteur
POST /engines	platform_admin	déclare une instance : id, provider (mem0 ou cognee), base_url, tenant_id (instance dédiée), credential_ref (openbao:// ou env://), access_control, tls_verify, timeout_seconds, manager_cluster, manager_service
DELETE /engines/{engine_id}	platform_admin	retire une instance déclarée
PUT /engines/{engine_id}/credential	tenant_admin	clé du tenant sur une instance partagée (credential_ref en openbao://)
DELETE /engines/{engine_id}/credential	tenant_admin	retire cette clé

Chaque appel vers un moteur passe par le client de sortie contrôlé (hôte et port déclarés seulement, redirections refusées), avec la vérification TLS (autorité du Manager de EAI_MEMORY_ENGINES_CA_FILE en plus des autorités par défaut), un délai et l'en-tête traceparent. Le HTTP simple est refusé en staging et en production sauf EAI_MEMORY_ENGINES_ALLOW_HTTP.

Politique de mémoire de l'agent

Méthode et chemin	Relation OpenFGA	Effet
GET /agents/{agent_id}/policy	viewer	politique en vigueur
PUT /agents/{agent_id}/policy	editor	nouvelle version de la politique
GET /agents/{agent_id}/policy/versions	viewer	versions précédentes
POST /agents/{agent_id}/policy/restore	editor	restaure la version version

Le corps de PUT porte engine (builtin par défaut, mem0, cognee ou hybrid), mem0_instance, cognee_instance et policy :

Champ de policy	Défaut	Rôle
modes	session, long_term, agent actifs ; shared, knowledge_graph inactifs	modes de mémoire permis
write_scopes, read_scopes	session, user, agent	portées où l'agent écrit et lit, parmi session, user, agent, shared_agents, project, team, organization, global
default_scope	user	portée d'une écriture sans portée
allowed_kinds	toutes	episodic, semantic, procedural, preference, fact
max_classification	confidential	classification la plus haute acceptée
allow_personal_data	true	refus des données personnelles quand false
retention_days, legal_hold	aucune, false	durée de vie et conservation légale
infer	false	extraction des faits par le LLM du moteur
shared_with, teams, global_access	vides, false	partage avec d'autres agents et équipes
required_isolation	logical	garantie minimale exigée de l'instance (voir Sécurité)
recall_top_k	8	nombre d'éléments d'un rappel

Un changement de moteur et un partage sont audités (memory.engine.change, memory.share). La mémorisation suit cette politique : rien n'écrit toutes les conversations dans les moteurs.

Mémoires

Ces routes demandent la relation can_invoke sur l'agent (ou d'être l'agent).

Méthode et chemin	Champs principaux	Effet
POST /agents/{agent_id}/memories	content, scope, kind (fact par défaut), classification, session_id, team, retention_days, legal_hold, source	mémorise (201)
GET /agents/{agent_id}/memories	scope, limit, cursor, include_content (false par défaut)	liste paginée
POST /agents/{agent_id}/recall	query, scopes, top_k, session_id	rappel encadré comme données non fiables
POST /agents/{agent_id}/memories/search	mêmes champs	recherche
GET /agents/{agent_id}/memories/{item_id}	-	lit un élément
PATCH /agents/{agent_id}/memories/{item_id}	content	met à jour
DELETE /agents/{agent_id}/memories/{item_id}	-	oublie un élément
POST /agents/{agent_id}/memories/purge	scope, confirm, team, session_id	purge une portée (confirmation requise)
POST /agents/{agent_id}/memories/export	scopes	exporte les mémoires autorisées

Connaissances et graphe

Méthode et chemin	Champs principaux	Effet
POST /agents/{agent_id}/knowledge	texts (1 à 50), scope (agent par défaut), team, dataset_id, classification, retention_days, legal_hold, build_graph	ingestion (201)
GET /agents/{agent_id}/knowledge/datasets	scope, limit, cursor	jeux de données
POST /agents/{agent_id}/knowledge/graph	dataset_ids	construit le graphe (cognify)
POST /agents/{agent_id}/knowledge/search	query, dataset_ids, top_k (10), search_type (CHUNKS, CHUNKS_LEXICAL, SUMMARIES, RAG_COMPLETION, GRAPH_COMPLETION)	recherche dans les connaissances
GET /agents/{agent_id}/knowledge/datasets/{dataset_id}/relations	-	entités et relations
DELETE /agents/{agent_id}/knowledge/datasets/{dataset_id}	-	supprime le jeu de données

Mode hybride

Avec engine à hybrid, Mem0 garde les faits et les mémoires, Cognee les connaissances et les relations. Une écriture va à un seul moteur : une mémoire à Mem0, une ingestion de connaissances à Cognee. Un rappel interroge les deux, fusionne les résultats, les déduplique par contenu et garde chaque source. La mémoire de session reste toujours dans builtin, jamais dans Mem0 ni dans Cognee.