> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flumes.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory Model Explained

> The schema we guarantee, how supersession works, and how retrieval blends signals.

## What exactly is a “memory”?

A memory is a typed, versioned statement linked to an entity.

* `type`: `fact | event | document | note | profile | chunk`
* `entity_id` (optional): the focal entity this memory belongs to

Fact fields:

* `subject`, `predicate`, `object_text | object_num | object_entity`, `object_type`, `unit`, `valid_from`, `valid_to`, `confidence`, `keys[]`

Event fields:

* `actor`, `verb`, `target`, `timestamp`

Common fields:

* `namespace`, `tags[]`, `metadata`, `status` (`active | superseded | disputed`), `sensitivity` (`auto | pii`), `provenance`, `created_at`, `updated_at`
* `memory_id`: unique id (UUID/ULID)

## Indexing & retrieval

Text and structured fields are embedded and indexed with Postgres + pgvector (HNSW) and full‑text search. Retrieval blends:

* semantic similarity, keyword/BM25, recency, predicate/entity priors, confidence, and optional graph proximity.

`/v0/context/assemble` packs the highest‑value items under a token budget, emits a summary, and can extract+ingest new facts from the current turn.

## Supersession

Use `keys[]` (for example, `["{subject}|{predicate}"]`) to ensure only one active fact per key. New writes supersede prior ones:

* previous rows are marked `status: superseded`
* `valid_to` is set to now

Querying “current truth” means filtering by `status=active` and your `namespace`/`entity_id`.