From facts to observations to mental models

Raw text is a bad memory format. Store transcripts and hope embeddings find the right passage later, and you inherit every ambiguity of the original conversation forever. Illumina structures memory into three layers, each one a compression of the layer below it.

Layer one: typed facts

Retain runs LLM extraction with forced tool use. The model must call an extract_facts tool; it cannot answer in prose. Every fact arrives as structured output with a type, a timestamp, its entities, and any causal relations it asserts. Structured extraction, not embed-and-pray.

Entity resolution runs at write time. Trigram matching catches surface variants ("Sarah Chen", "schen", "Sarah"), and co-occurrence plus temporal scoring decides whether two mentions are the same person or two people who share a name. Facts then get linked to each other by eight edge types: temporal, semantic, entity, causes, caused_by, enables, prevents, and supersedes. The causal edges are what let recall answer "why" questions by walking the graph instead of guessing from adjacency; supersedes is what keeps a decision's history intact when a later decision overrides it, so recall returns what the team decided most recently and can still show what it replaced.

Layer two: observations

Individual facts are noisy. One standup comment saying the billing service caused a checkout incident might be wrong. Four facts from different sources saying the same thing is a pattern.

A background consolidation pass groups corroborating facts into observations. Each observation carries a proof count and full source provenance, so it is auditable down to the original inputs:

{
  "statement": "Checkout latency incidents trace back to the billing service",
  "proof_count": 4,
  "sources": [
    { "fact_id": "fct_8a21", "origin": "slack:#incidents", "occurred_at": "2026-02-11" },
    { "fact_id": "fct_9c04", "origin": "github:acme/checkout#412", "occurred_at": "2026-03-02" }
  ]
}

Corroboration also feeds retrieval. Recall scores observations higher when more independent sources back them, so a well-evidenced pattern outranks a one-off remark on the same topic.

Layer three: mental models

Facts and observations are still granular. A mental model is the synthesized document above them: "how our deploy pipeline works", "what the enterprise segment keeps asking for". Mental models are living documents with version history, and after each consolidation pass they refresh through delta operations. Only the sections touched by new observations change; nothing gets regenerated wholesale. You can diff version 14 against version 13 and see what the organization learned that week.

Reflect reads all three

Reflect is the reasoning operation, and it works across every layer: mental models for the shape of things, observations for the evidence, raw facts for the specifics. Two controls steer it per namespace. Dispositions set temperament on a 1-to-5 scale across skepticism, literalism, and empathy, so a compliance namespace can demand strong evidence while a brainstorming namespace stays loose. Directives are hard rules with no scale: "never speculate about unreleased pricing" binds regardless of disposition.

Every reflect answer cites what it was based on. The facts, observations, and mental-model versions behind a conclusion come back with it, so you can check the reasoning instead of trusting it.

Three layers, one guarantee: nothing in the stack is more than one hop from the evidence that produced it.