weavatrix-memory 0.3.2

Event-sourced bitemporal evidence memory and budgeted context retrieval for coding agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

use super::{Confidence, Evidence};
use crate::{
    error::{MemoryError, Result},
    id::{AgentId, EntityId, FactId, SessionId},
    time::Timestamp,
};
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MemoryFact {
    pub id: FactId,
    pub source: EntityId,
    pub relation: String,
    pub target: EntityId,
    pub valid_from: Timestamp,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub valid_until: Option<Timestamp>,
    pub observed_at: Timestamp,
    pub recorded_at: Timestamp,
    pub agent_id: AgentId,
    pub session_id: SessionId,
    pub confidence: Confidence,
    pub evidence: Vec<Evidence>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub supersedes: Option<FactId>,
}

impl MemoryFact {
    /// Creates an evidence-carrying temporal relation.
    ///
    /// # Errors
    ///
    /// Rejects invalid relation text or missing evidence.
    #[allow(clippy::too_many_arguments)]
    pub fn new(
        id: FactId,
        source: EntityId,
        relation: impl Into<String>,
        target: EntityId,
        valid_from: Timestamp,
        recorded_at: Timestamp,
        agent_id: AgentId,
        session_id: SessionId,
        evidence: Evidence,
    ) -> Result<Self> {
        let fact = Self {
            id,
            source,
            relation: relation.into(),
            target,
            valid_from,
            valid_until: None,
            observed_at: recorded_at,
            recorded_at,
            agent_id,
            session_id,
            confidence: Confidence::CERTAIN,
            evidence: vec![evidence],
            supersedes: None,
        };
        fact.validate()?;
        Ok(fact)
    }

    /// Sets the exclusive end of the fact's valid interval.
    ///
    /// # Errors
    ///
    /// Rejects an end that is not later than `valid_from`.
    pub fn valid_until(mut self, value: Timestamp) -> Result<Self> {
        self.valid_until = Some(value);
        self.validate()?;
        Ok(self)
    }

    #[must_use]
    pub const fn observed_at(mut self, value: Timestamp) -> Self {
        self.observed_at = value;
        self
    }

    #[must_use]
    pub const fn with_confidence(mut self, value: Confidence) -> Self {
        self.confidence = value;
        self
    }

    /// Links this fact to the historical fact it replaces.
    ///
    /// # Errors
    ///
    /// Rejects self-supersession.
    pub fn supersedes(mut self, fact: FactId) -> Result<Self> {
        if fact == self.id {
            return Err(MemoryError::InvalidValue {
                field: "fact.supersedes",
                reason: "a fact cannot supersede itself",
            });
        }
        self.supersedes = Some(fact);
        Ok(self)
    }

    #[must_use]
    pub fn with_evidence(mut self, evidence: Evidence) -> Self {
        self.evidence.push(evidence);
        self
    }

    pub(crate) fn validate(&self) -> Result<()> {
        super::validate_text("fact.relation", &self.relation)?;
        if self.observed_at > self.recorded_at {
            return Err(MemoryError::InvalidValue {
                field: "fact.observed_at",
                reason: "must not be later than recorded_at",
            });
        }
        if self
            .valid_until
            .is_some_and(|until| until <= self.valid_from)
        {
            return Err(MemoryError::InvalidValue {
                field: "fact.valid_until",
                reason: "must be later than valid_from",
            });
        }
        if self.evidence.is_empty() {
            return Err(MemoryError::InvalidValue {
                field: "fact.evidence",
                reason: "at least one evidence item is required",
            });
        }
        self.evidence.iter().try_for_each(Evidence::validate)
    }
}