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).
Governing what the derived layers learn
What enrichment learns into the derived layers is governed by data you control (see Governed Memory):
- A derivation policy decides, per scope subtree, which events are read, which stages run
(
facts,entities,beliefs,episodes,understanding), which topics and sensitive values are never kept, and what waits for review. Every candidate is judged before it reaches a layer, and denied content is never stored. - Every derived fact records how it was made: the policy rule that admitted it, the policy's hash,
the models and the prompt version (
include=derivation). - Corrections reject, replace, pin or confirm a claim, and the layers built on it follow: a rejected claim's facts are deleted with the beliefs and concepts built from them, and nothing learns it again.
- Layers built across scopes honour every input scope's restrictions, and never blend a sealed compartment with its siblings.
Events stay outside all of this: a policy governs what is learned from an event, never the event itself. The event is still stored, indexed and searchable.
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.