Temporal/entity layer — facts age and contradict

[servathadi]

Context

Pure vector similarity cannot distinguish "user loves coffee" from "user hates coffee" if embeddings are similar. Zep beats Mem0 by 15+ points on memory benchmarks specifically because it models time and entity relationships — things that cosine distance is blind to.

Motivation

Without temporal tracking, outdated facts remain equally weighted as current ones. Without entity refs, contradictions in memory are invisible. Both are required for reliable long-term agent memory.

Implementation

Schema additions to mirror_engrams

ALTER TABLE mirror_engrams ADD COLUMN entity_refs text[];          -- named entities in the text
ALTER TABLE mirror_engrams ADD COLUMN valid_from timestamptz;      -- when fact became true
ALTER TABLE mirror_engrams ADD COLUMN valid_until timestamptz;     -- when fact was superseded
ALTER TABLE mirror_engrams ADD COLUMN supersedes uuid REFERENCES mirror_engrams(id);

New endpoint

POST /engrams/{id}/supersede — marks an older engram as deprecated by a newer one:

• Sets valid_until = now() on the old engram
• Sets supersedes = old_id on the new engram

Search behavior

• Filter out superseded engrams by default (where valid_until IS NOT NULL)
• Add include_superseded=true query param to override
• Index entity_refs with GIN for fast entity-based lookup

Notes

• Entity extraction can be done at write time via simple NER or regex patterns initially
• valid_from defaults to created_at if not provided
• Inspired by Zep Memory v2 graph architecture and Honcho temporal signals