The Five Memory Layers
How CortexDB models memory across Events, Episodes, Facts, Beliefs, and Understanding — and why single-layer systems fail.
The five memory layers organize memory into strictly addressable tiers — Events, Episodes, Facts, Beliefs, Understanding — isolating raw observations from probabilistic derivations. CortexDB queries all five simultaneously during recall to return a unified StratifiedPack, over a lossless, event-sourced foundation.
Why memory layers matter
Memory systems typically rely on a single flat layer of LLM-rewritten summaries. Single-layer designs collapse raw observations ("the user clicked cancel") and probabilistic conclusions ("the user dislikes the UI") into the same vector space — which destroys confidence as a first-class metric.
CortexDB preserves the "why" behind every piece of information by separating lossless capture (Events) from structured assertions (Facts), probabilistic claims (Beliefs), and conceptual synthesis (Understanding). Agents can traverse from a high-level belief down to the exact immutable events that generated it.
The derivation graph
CortexDB treats memory as a derivation graph starting from raw, immutable Events. Bounded spans of
interaction group into Episodes. Extraction pipelines identify triple-shaped, bi-temporal Facts.
Facts can conflict, so consolidation produces Beliefs (probabilistic claims that carry a supports
chain back to the underlying evidence). Understanding synthesizes higher-level summaries, lagging
real-time by minutes to hours.
What each layer holds
| Layer | Shape | Derived from | Confidence | Typical retrieval use |
|---|---|---|---|---|
| Events | Immutable append-only records (id, content, scope, context.observed_at, context.recorded_at) | Ingest (write path) | 1.0 (raw) | Verbatim quotes; audit trail; replay |
| Episodes | Bounded sequences of related events (id, events, summary) | Events (async) | 1.0 (structural) | Session / conversation context |
| Facts | Triple-shaped bi-temporal claims (subject, predicate, object, validity window) | Episodes + extraction (async) | 0.0–1.0 per extraction | Structured Q&A; timelines |
| Beliefs | Probabilistic claims with a supports chain to Facts | Facts (async consolidation) | 0.0–1.0 per consolidation | "What do you currently think about X?" |
| Understanding | Higher-order synthesized summaries, versioned | Facts + Beliefs (async, lagging) | implicit | Long-horizon overviews; briefings |
Only Events are not derived. Every derived record carries a supports chain back through the layers
to the immutable events that produced it — that chain is what makes evidence traceable and forgetting honest.
Derived layers require enrichment
Facts, Beliefs, and Understanding are produced by an LLM extraction/synthesis pipeline. On a content-only self-hosted instance with no enrichment configured, these layers stay empty — Events and vector search still work. See Self-hosting defaults.
What five layers enable
- Evidence traceability — every Belief points to Facts, every Fact to Episodes and Events; agents can audit why they believe something by following the chain.
- Safe schema evolution — CortexDB can rebuild Facts, Beliefs, and Understanding from raw Events if extraction models improve later.
- Deep temporal reasoning — reconstruct historical state across deep history (see Bi-temporal).
Retrieval across layers
Recall reads across the layers and fuses the results. The full retrieval architecture is hybrid — BM25 + HNSW vectors + graph traversal + cross-encoder reranking — but not every channel is on by default:
Default vs full capability
A default self-hosted instance runs BM25 + vector + RRF fusion only (visible with diagnostics=full).
Graph traversal needs a knowledge graph (CORTEX_ENTITY_GRAPH=1 + enrichment); cross-encoder
rerank needs a reranker (a Cohere rerank-v3.5 key or a local model; see Recall Tuning). On managed cloud the fuller stack is configured for you. See
Hybrid Retrieval and Self-hosting defaults.
FAQ
What are the five memory layers? Events (raw immutable observations), Episodes (bounded sequences), Facts (triple-shaped assertions), Beliefs (probabilistic claims), and Understanding (synthesized summaries).
How are Beliefs different from Facts? Facts are triple-shaped bi-temporal assertions extracted from
events. Beliefs consolidate correlated Facts and carry a supports chain to the underlying Facts.
Does the five-layer model slow down writes? No — there is no LLM on the write path. A write appends an
Event and returns immediately (202); Facts, Beliefs, and Understanding are derived asynchronously.
What is a StratifiedPack? The unified output returned by recall — relevant context across all five
layers merged into one structured response. See POST /v1/recall.
See also
- Event Sourcing — why CortexDB stores raw events, not summaries.
- Bi-temporal Model — validity windows and supersession.