Struct Fact 

pub struct Fact {

    pub id: FactId,
    pub text: String,
    pub scope: Scope,
    pub tier: MemoryTier,
    pub category: Option<String>,
    pub source: Option<String>,
    pub confidence: Option<f32>,
    pub valid_from: DateTime<Utc>,
    pub invalid_at: Option<DateTime<Utc>>,
    pub created_at: DateTime<Utc>,
    pub embedding: Vec<f32>,
    pub entity_refs: Vec<EntityId>,
    pub supersedes: Option<FactId>,
    pub superseded_by: Option<FactId>,
    pub access_count: u64,
    pub last_accessed: Option<DateTime<Utc>>,
    pub metadata: Map<String, Value>,
}

An atomic unit of agent memory.

A Fact is the fundamental record stored by Engram. It carries free-text content alongside rich provenance metadata, temporal validity bounds, an optional embedding vector for semantic search, and a supersession chain for versioned knowledge updates.

Fields

id: FactId

text: String

Human-readable text content of this fact.

scope: Scope

Memory scope this fact belongs to.

tier: MemoryTier

Retention tier.

category: Option<String>

Optional free-form category tag (e.g. "preference", "task_result").

source: Option<String>

Identifier of the source that produced this fact (agent id, tool name, …).

confidence: Option<f32>

Confidence score in [0.0, 1.0]. None means “unrated”.

valid_from: DateTime<Utc>

When this fact became valid. Defaults to creation time.

invalid_at: Option<DateTime<Utc>>

When this fact stops being valid. None means “still valid”.

created_at: DateTime<Utc>

embedding: Vec<f32>

Dense embedding vector (e.g. 1536-dim for text-embedding-3-small).

entity_refs: Vec<EntityId>

UUIDs of entities this fact references.

supersedes: Option<FactId>

ID of the fact this one supersedes (if this is an update).

superseded_by: Option<FactId>

ID of the fact that superseded this one (set when this fact is outdated).

access_count: u64

How many times this fact has been retrieved.

last_accessed: Option<DateTime<Utc>>

When this fact was last retrieved.

metadata: Map<String, Value>

Arbitrary extra metadata.

Implementations

impl Fact

pub fn new(text: impl Into<String>, scope: Scope) -> Self

Create a new fact with required fields; all optional fields default to None/empty.

pub fn is_valid(&self) -> bool

Returns true if this fact is currently valid (not yet expired).

pub fn is_valid_at(&self, at: DateTime<Utc>) -> bool

Returns true if this fact was valid at the given point in time.

pub fn with_tier(self, tier: MemoryTier) -> Self

pub fn with_category(self, category: impl Into<String>) -> Self

pub fn with_confidence(self, confidence: f32) -> Self

pub fn with_source(self, source: impl Into<String>) -> Self

Trait Implementations

impl Clone for Fact

fn clone(&self) -> Fact

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Fact

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Fact

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Fact

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.