Events, Episodes, Facts, Beliefs, Understanding — what each layer is for and how they derive from each other.

The Five Memory Layers

CortexDB does not have one memory pool. It has five addressable layers, each with its own atomic unit, mutability rules, and time semantics. Clients can read each layer independently or pull them together as a stratified pack via POST /v1/recall.

| Layer | Purpose | Atomic unit | Mutability | Time semantics | |---|---|---|---|---| | Events | Lossless capture of experience | WAL entry | Immutable | observed_at + recorded_at | | Episodes | Bounded spans of related events | Causal chain with start / end | Sealed once consolidated | started_at / ended_at; bi-temporal at boundaries | | Facts | Triple-shaped assertions | (subject, predicate, object, validity) | Supersedable | Full bi-temporal: (valid_from, valid_to, recorded_from, recorded_to) | | Beliefs | Probabilistic claims with confidence + supports | Claim + interval + supports graph | Continuously revisable | Bi-temporal + last_revised_at | | Understanding | Synthesized conceptual model | Concept node + edges | Versioned | version + valid_from; revisions chained |

Why five and not three

  • Mem0 has facts only — they cannot distinguish "what I observed" (Events) from "what I concluded" (Beliefs), so they cannot answer why do you think that?
  • Zep has facts + episodes — they collapse Belief into Fact, losing confidence as a first-class field.
  • We separate lossless capture (Events), bounded recall (Episodes), structured assertion (Facts), probabilistic conclusion (Beliefs), and conceptual synthesis (Understanding). This is the minimum set that lets us answer every recall mode the platform promises.

Derivation graph

                                       (synthesize)
Events  ──(window)──▶  Episodes  ──(extract)──▶  Facts  ──(rank+revise)──▶  Beliefs
   │                                                │                          │
   └──────────────────(group + abstract)────────────┴──────────────────────────┴──▶  Understanding

Every derived record carries a supports: [event_id, ...] field. Walking this chain backwards is the why trail — surfaced explicitly by GET /v1/beliefs/why.

Reading layers

Each layer has a dedicated endpoint:

Or pull all five at once with POST /v1/recall, which returns them as a stratified pack with a token budget, citations, and provenance.