Skip to main content

What COGX is

COGX (the Cognee eXchange format) is the common shape that memory data takes when it moves into or out of Cognee. It is the single format that every importer translates into and every exporter writes out of — so adding a new memory tool, backing up a dataset, or moving data between Cognee instances all use the same machinery. You rarely touch COGX directly. It’s the layer underneath cognee.remember() (for import) and cognee.export() (for export). This page explains what it is so the migration tools make sense.

Why a common format

Every memory tool stores data differently: Mem0 has short memory strings, Letta has agent memory blocks and message history, Zep and Graphiti have entity graphs with time-stamped facts. Without a shared format, importing from N tools and exporting to M tools would need N × M one-off converters. COGX collapses that into N + M. Each tool only has to translate to or from COGX once:
  • On import, a source adapter reads one tool’s export and emits COGX records. A single loader ingests those records — identical no matter where they came from. Sources ship for Mem0, LangMem, Letta, Zep, and Graphiti, and you can write your own for any other tool.
  • On export, Cognee dumps a dataset’s graph into a COGX archive that you can store, restore, or hand to another system.

What’s in COGX

COGX represents memory as a stream of typed records. Each record describes one kind of thing a memory system can hold: Typed records also carry a scope (user_id, agent_id, session_id, run_id) and timestamps, so ownership and time information survive the move. Raw nodes preserve their original graph properties verbatim.

Record header

Since COGX 0.2, every typed record (everything except raw nodes) can carry an optional header based on the Open Memory Protocol (OMP). It describes where a record came from, who wrote it, and how far it can be trusted. Every field is optional. A missing field means “not stated”, so 0.1 archives and existing sources keep working unchanged. On import, the header is kept as one omp_header JSON value on the element the record becomes. Documents, episodes, memories and memory blocks store it in the data item’s external_metadata, which comes back on export once the item is cognified (so not after a preserve import). Entities imported in preserve or hybrid mode store it on the Entity node’s omp_header field, and facts on the graph edge, where the edge’s numeric confidence score stays beside it. In re-derive mode facts and entities are folded into digest documents without their headers. On export, the header a memory was imported with comes back and wins. Entities and facts read their own omp_header, and a chunk takes the header of the document it is part of. Cognee only fills in the fields that header leaves empty, from what its graph records:
  • evidence: for a fact, the chunks its edge evidence records: role inferred for an extracted edge and observed for a structural one, with that evidence’s confidence. For an entity, the chunks that contain it (role derived).
  • ai_involvement: for a fact, full when all its evidence was extracted, none when all of it is structural, mixed for both, and not stated when no evidence is recorded. Entities are full when the cognify pipeline extracted them; chunks are none.
  • accountable: the user stamped on the node, or the owning human when that user is an agent.
  • confidence: a fact that conflict review judged carries its verdict, which replaces any imported confidence: conflicting → contradicted, superseded → corrected, current → confirmed (verified by automatic), and accepted by a user → confirmed (verified by human). The edge’s score is kept.
The manifest’s coverage states the same for each field.
Facts imported by earlier COGX 0.2 builds stored their header as flat edge properties. Export no longer reads those, apart from version, tags, semantic kind, validity, invalidated_by and the numeric confidence score, so those facts’ imported origin, contributors, accountable, evidence and confidence outcome, verification time and verifier are not exported.

Archive layout

An exported COGX archive is just a directory you can inspect:
manifest.json records the COGX version the archive was written with (the current version is 0.2, exposed as cognee.migration.COGX_VERSION). A reader refuses to load an archive written by a newer major version than it understands, so an out-of-date Cognee won’t silently misread a future archive. Archives written as 0.1 still load. The manifest’s coverage map says, for each header field, what the exporter was able to fill in and how. A field the exporter can’t state is left out of the records (list fields such as evidence are written empty), so a missing or empty field means “not populated”, not “false”. When an archive has to travel as a single file — pushing a dataset to Cognee Cloud, or uploading to the remember API endpoint — the directory is packed as a .cogx.tar.gz tarball. On disk you’ll normally work with the plain directory.

Import modes

When records enter Cognee, a mode controls how much processing they get. This is the main knob you’ll actually set: Each source picks a sensible default (Mem0, LangMem, and Letta default to re-derive, Zep/Graphiti to hybrid, COGX archives to preserve), and you can override it.
A Cognee-origin cogx archive writes each document chunk twice — as a Document record and as a Raw node carrying the chunk’s original properties. A preserve restore rehydrates the raw node, so facts that reference the chunk keep their graph topology instead of dangling, and the chunk’s content survives the round-trip. As a result, CHUNK and hybrid search work against the dataset after a Cognee → Cognee import.

Where to go next

Migrate Memory Systems

Import from Mem0, LangMem, Letta, Zep, or Graphiti — with runnable examples

remember()

The operation that ingests COGX records into the graph