Memory Model
MemMesh stores knowledge as typed, timestamped memories linked to entities in a graph. This page explains the units the engine works with.
Memories
A memory is the atomic unit of knowledge. Each memory has:
- Content — the distilled statement (e.g. “EU region requires data residency in eu-west-1”).
- Kind — what kind of knowledge it is (see below).
- Scope — who it belongs to (see Scopes).
- Status — where it sits in the lifecycle (see below).
- Importance — a 0–10 weight (default 5) that feeds hybrid ranking alongside semantic similarity and recency.
- Provenance — when and how it was learned, so a recall can be explained.
- Validity window —
validFrom/validTo, so a memory can be superseded and time-travel queries can ask “what did we know as of date X”.
Memory kinds
The kind field is a free-form string; the engine and packs use a growing set.
Common kinds:
| Kind | What it captures |
|---|---|
fact | A stated fact about a subject or the world. |
preference | A stated preference (e.g. “always use pnpm”). |
rule | An always-true constraint or policy. |
decision | A recorded choice (also written by the outcome loop). |
insight | A higher-order generalization synthesized from multiple memories by reflection. |
behavior_pattern | A mined behavioral regularity (the lattice output). |
estimate | A derived score (e.g. a PhenoAge bio-age estimate), persisted to build a trajectory. |
outcome | The realized result of a decision (the outcome loop). |
Because patterns, insights, estimates, and outcomes are all stored as memories, they are retrievable by the same search and covered by the same GDPR subject cascade.
Status lifecycle
Every memory carries a status that moves through a small state machine:
pending ──▶ confirmed ──▶ superseded
└──────▶ rejected (a newer memory replaced it)- pending — extracted but not yet confirmed; may sit in the review queue.
- confirmed — active, trusted knowledge (the default for explicit saves).
- superseded — replaced by a newer memory; kept for history, not returned by default recall.
- rejected — reviewed and dismissed.
Superseded memories are retained rather than destroyed, which is what lets a recall answer not just what but why and since when, and lets time-travel queries reconstruct a past belief state.
Entities (subjects)
An entity is a canonical node in the memory graph — a person, project, or account that memories attach to. An entity is considered active while its validity window is open. The count of active subjects is the unit that plans and caps are sized around.
Relationships
Entities connect to each other through typed, weighted, bi-temporal edges, forming the knowledge graph that the lattice and prediction layer build on.
Provenance and supersession
When a fact changes, MemMesh supersedes the old memory rather than deleting
it — preserving an auditable history. Every derived artifact (pattern,
prediction, insight) carries sourceMemoryIds back to the raw memories that
produced it, which is what powers the right-to-explanation surface.