Skip to main content

​
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.