Skip to main content
Facts can change. User facts retain validity and supersession metadata so a new value can replace an old one without presenting both as current. This is distinct from deleting a fact the application no longer wants to retain.

How It Works

A fact can have validFrom, invalidatedAt, and invalidationReason metadata. Retrieval methods distinguish active facts from retained history. There is no memory.userFacts.includeSuperseded configuration option in v4.

Code Example: Full Lifecycle

Run this example locally with @agentium/core@4.0.0; it makes no model calls:
Expect the active set to contain Works at Globex. Inspect the full records for the superseded Acme fact. The explicit supersedes relationship makes this example deterministic; automatic extraction uses a model and can require review.

Contradiction Detection

Extraction can propose updated facts from a conversation. Scope it to a verified user and inspect important changes before relying on them. A contradictory sentence alone is not proof of a real-world change.

What the Agent Sees

The normal user-fact context includes active facts. An application that displays history should call the appropriate store methods and label past records explicitly. Do not reintroduce historical claims into a prompt as if they were current.

Viewing Temporal History

getFacts(userId) includes retained records; getActiveFacts(userId) filters invalidated ones. Use those methods behind host authorization. Retained history is still stored data and belongs in the application’s retention/deletion design.

Works Across Store Types

Entity and graph stores have their own temporal APIs; their arguments are not interchangeable with user-fact options. See entity memory and graph memory. A graph traversal’s includeInvalid option is not a unified userFacts configuration field.