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. Documents, episodes, memories and memory
blocks store it under
header in the data item’s external_metadata. Facts
imported in preserve or hybrid mode store it as flat properties on the
graph edge (nested values as JSON strings). There the edge’s confidence stays
the numeric score, with confidence_outcome, confidence_verified_at and
confidence_verified_by beside it. A later export reads these edge values
back, so a fact’s origin, validity, evidence and confidence survive a round
trip. Other records’ headers don’t come back on export: the export reads the
graph, not external_metadata. Entity records’ headers are not stored, and in
re-derive mode facts are folded into digest documents without their headers.
On export, Cognee fills in the header from what its graph knows. For
example, evidence lists the chunks a record was extracted from (role
derived), ai_involvement is full for extracted entities and facts and
none for source chunks, and accountable is the user who ran the pipeline,
when the graph records one.
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