Integrate the memory in the agents

Navin Memory Provider contract

The contract is described by contracts/v1/memory-provider.schema.json. An engine instance announces a declarative set of capabilities: schema_version, provider (builtin, mem0 or cognee), engine_instance, capabilities, and their split into memory and knowledge. Reading the capabilities needs no credential of the engine; it adds isolation, the separation guaranteed for the tenant of the caller, and session_memory, true for builtin only.

Group	Capabilities
Memory	remember, recall, search, update, forget, list, get, purge, get_health, get_capabilities
Knowledge	ingest_knowledge, build_graph, search_graph, get_relations, delete_dataset

builtin and mem0 announce every memory capability; cognee announces forget, list, purge, get_health, get_capabilities and every knowledge capability. An operation outside the announced set answers memory_capability_unsupported (422); an unreachable engine answers memory_engine_unavailable (502). The context of each operation ($defs.context of the schema) is built server side.

Engine instances

Every route is under /v1/memory.

Method and path	Required role	Effect
GET /engines	authenticated	builtin, the mem0 and cognee instances rendered by the Manager, the declared instances
GET /engines/{engine_id}/capabilities	authenticated	capabilities, isolation, session_memory
GET /engines/{engine_id}/health	tenant_admin, developer, security_officer or auditor	engine health
POST /engines	platform_admin	declares an instance: id, provider (mem0 or cognee), base_url, tenant_id (dedicated instance), credential_ref (openbao:// or env://), access_control, tls_verify, timeout_seconds, manager_cluster, manager_service
DELETE /engines/{engine_id}	platform_admin	removes a declared instance
PUT /engines/{engine_id}/credential	tenant_admin	key of the tenant on a shared instance (credential_ref as openbao://)
DELETE /engines/{engine_id}/credential	tenant_admin	removes this key

Each call to an engine goes through the guarded egress client (declared host and port only, redirects refused), with TLS verification (the Manager CA of EAI_MEMORY_ENGINES_CA_FILE on top of the default authorities), a timeout and the traceparent header. Plain HTTP is refused in staging and production unless EAI_MEMORY_ENGINES_ALLOW_HTTP.

Agent memory policy

Method and path	OpenFGA relation	Effect
GET /agents/{agent_id}/policy	viewer	current policy
PUT /agents/{agent_id}/policy	editor	new version of the policy
GET /agents/{agent_id}/policy/versions	viewer	previous versions
POST /agents/{agent_id}/policy/restore	editor	restores the version version

The body of PUT carries engine (builtin by default, mem0, cognee or hybrid), mem0_instance, cognee_instance and policy:

Field of policy	Default	Role
modes	session, long_term, agent on; shared, knowledge_graph off	memory modes allowed
write_scopes, read_scopes	session, user, agent	scopes where the agent writes and reads, among session, user, agent, shared_agents, project, team, organization, global
default_scope	user	scope of a write without a scope
allowed_kinds	all	episodic, semantic, procedural, preference, fact
max_classification	confidential	highest classification accepted
allow_personal_data	true	personal data refused when false
retention_days, legal_hold	none, false	lifetime and legal hold
infer	false	fact extraction by the LLM of the engine
shared_with, teams, global_access	empty, false	sharing with other agents and teams
required_isolation	logical	minimal guarantee required from the instance (see Security)
recall_top_k	8	number of items of a recall

A change of engine and a share are audited (memory.engine.change, memory.share). Memorization follows this policy: nothing writes every conversation to the engines.

Memories

These routes need the relation can_invoke on the agent (or to be the agent).

Method and path	Main fields	Effect
POST /agents/{agent_id}/memories	content, scope, kind (fact by default), classification, session_id, team, retention_days, legal_hold, source	remembers (201)
GET /agents/{agent_id}/memories	scope, limit, cursor, include_content (false by default)	paginated list
POST /agents/{agent_id}/recall	query, scopes, top_k, session_id	recall framed as untrusted data
POST /agents/{agent_id}/memories/search	same fields	search
GET /agents/{agent_id}/memories/{item_id}	-	reads one item
PATCH /agents/{agent_id}/memories/{item_id}	content	updates
DELETE /agents/{agent_id}/memories/{item_id}	-	forgets one item
POST /agents/{agent_id}/memories/purge	scope, confirm, team, session_id	purges a scope (confirmation required)
POST /agents/{agent_id}/memories/export	scopes	exports the authorized memories

Knowledge and graph

Method and path	Main fields	Effect
POST /agents/{agent_id}/knowledge	texts (1 to 50), scope (agent by default), team, dataset_id, classification, retention_days, legal_hold, build_graph	ingestion (201)
GET /agents/{agent_id}/knowledge/datasets	scope, limit, cursor	datasets
POST /agents/{agent_id}/knowledge/graph	dataset_ids	builds the graph (cognify)
POST /agents/{agent_id}/knowledge/search	query, dataset_ids, top_k (10), search_type (CHUNKS, CHUNKS_LEXICAL, SUMMARIES, RAG_COMPLETION, GRAPH_COMPLETION)	search in the knowledge
GET /agents/{agent_id}/knowledge/datasets/{dataset_id}/relations	-	entities and relations
DELETE /agents/{agent_id}/knowledge/datasets/{dataset_id}	-	deletes the dataset

Hybrid mode

With engine set to hybrid, Mem0 keeps the facts and memories, Cognee the knowledge and relations. A write goes to one engine only: a memory to Mem0, a knowledge ingestion to Cognee. A recall queries both, merges the results, deduplicates them by content and keeps every source. Session memory always stays in builtin, never in Mem0 nor in Cognee.