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 underneathcognee.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: roleinferredfor an extracted edge andobservedfor a structural one, with that evidence’s confidence. For an entity, the chunks that contain it (rolederived).ai_involvement: for a fact,fullwhen all its evidence was extracted,nonewhen all of it is structural,mixedfor both, and not stated when no evidence is recorded. Entities arefullwhen the cognify pipeline extracted them; chunks arenone.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 byautomatic), and accepted by a user →confirmed(verified byhuman). The edge’s score is kept.
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, amode 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