COGX: Agent Memory Exchange Format

COGX is Cognee’s portable format for agent memory: import memories from Mem0, LangMem, Letta, Zep or Graphiti, and export, back up or move Cognee memory

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:

Mem0    ─┐                                                             ┌─► back up to disk
Letta   ─┤                                                             ├─► move to another Cognee instance
Zep     ─┼─►  COGX records  ─►  Cognee graph  ─►  COGX records  ─┤
Graphiti ┘    (import hub)                        (export hub)          └─► translate onward

• 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:

Record	What it represents	Typical source
Document	Raw source content — a file, an archival passage, or standalone text.	Letta archival memory, uploaded files
Episode	A conversation: ordered turns, each with a role and timestamp.	Letta message history, Zep episodes
Entity	An extracted entity, with an optional type, aliases, and description.	Zep / Graphiti nodes
Fact	A triplet (subject → predicate → object), optionally with a validity window.	Zep / Graphiti edges
Memory	A single short derived fact (“atomic memory”).	Mem0 memories, LangMem memories
Memory block	A named, size-bounded core-memory block.	Letta core memory
Raw node	Any graph node stored verbatim when no typed mapping fits, so nothing is lost.	Cognee → Cognee exports

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.

Archive layout

An exported COGX archive is just a directory you can inspect:

my_cogx_archive/
├── manifest.json      # format version, source system, record counts
├── documents.jsonl    # one JSON record per line, one file per record kind
├── episodes.jsonl
├── entities.jsonl
├── facts.jsonl
├── memories.jsonl
├── memory_blocks.jsonl
├── nodes.jsonl        # raw graph nodes that do not map to a typed record
└── ...

manifest.json records the COGX version the archive was written with (the current version is 0.1, 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.

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:

Mode	What it does	Cost
re-derive	Ingest the raw content and run Cognee’s own extraction. The source’s own graph is ignored.	LLM calls; richest result
preserve	Map the source’s already-extracted entities and facts straight into the graph. Raw content is stored but not re-processed.	Zero LLM calls
hybrid	Keep the source’s graph and re-cognify the raw content.	LLM calls; most complete

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