mindcore 0.2.0

Pluggable, feature-gated memory engine for AI agent applications
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

use crate::traits::{ConsolidationAction, ConsolidationStrategy, MemoryMeta, ScoredResult};

/// Near-duplicate detection via vector similarity threshold.
///
/// When a new memory is stored, if an existing memory has similarity
/// above the threshold, the action depends on the score:
/// - similarity > 0.95: Noop (near-exact duplicate)
/// - similarity > 0.85: Update the existing memory
/// - otherwise: Add as new
///
/// Requires vector search to be enabled (the engine must pass
/// vector-similarity results as the `existing` parameter).
pub struct SimilarityDedup {
    /// Threshold above which two memories are considered duplicates.
    noop_threshold: f32,
    /// Threshold above which an existing memory should be updated.
    update_threshold: f32,
}

impl SimilarityDedup {
    /// Create with a single threshold (used for both noop and update).
    pub fn new(threshold: f32) -> Self {
        Self {
            noop_threshold: threshold.max(0.90),
            update_threshold: threshold.max(0.80) - 0.10,
        }
    }

    /// Create with explicit noop and update thresholds.
    pub fn with_thresholds(noop: f32, update: f32) -> Self {
        Self {
            noop_threshold: noop,
            update_threshold: update,
        }
    }
}

impl Default for SimilarityDedup {
    fn default() -> Self {
        Self::new(0.95)
    }
}

impl ConsolidationStrategy for SimilarityDedup {
    fn consolidate(
        &self,
        _new: &MemoryMeta,
        existing: &[ScoredResult],
    ) -> Vec<ConsolidationAction> {
        if existing.is_empty() {
            return vec![ConsolidationAction::Add];
        }

        let top = &existing[0];

        if top.score >= self.noop_threshold {
            vec![ConsolidationAction::Noop]
        } else if top.score >= self.update_threshold {
            vec![ConsolidationAction::Update {
                target_id: top.memory_id,
            }]
        } else {
            vec![ConsolidationAction::Add]
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::traits::MemoryType;
    use chrono::Utc;

    fn meta() -> MemoryMeta {
        MemoryMeta {
            id: None,
            searchable_text: "test".into(),
            memory_type: MemoryType::Semantic,
            importance: 5,
            category: None,
            created_at: Utc::now(),
            metadata: Default::default(),
        }
    }

    fn scored(id: i64, score: f32) -> ScoredResult {
        ScoredResult {
            memory_id: id,
            score,
            raw_score: score,
            score_multiplier: 1.0,
        }
    }

    #[test]
    fn no_existing_adds() {
        let dedup = SimilarityDedup::default();
        let actions = dedup.consolidate(&meta(), &[]);
        assert_eq!(actions, vec![ConsolidationAction::Add]);
    }

    #[test]
    fn high_similarity_noops() {
        let dedup = SimilarityDedup::default();
        let existing = vec![scored(42, 0.98)];
        let actions = dedup.consolidate(&meta(), &existing);
        assert_eq!(actions, vec![ConsolidationAction::Noop]);
    }

    #[test]
    fn medium_similarity_updates() {
        let dedup = SimilarityDedup::with_thresholds(0.95, 0.85);
        let existing = vec![scored(42, 0.90)];
        let actions = dedup.consolidate(&meta(), &existing);
        assert_eq!(
            actions,
            vec![ConsolidationAction::Update { target_id: 42 }]
        );
    }

    #[test]
    fn low_similarity_adds() {
        let dedup = SimilarityDedup::with_thresholds(0.95, 0.85);
        let existing = vec![scored(42, 0.50)];
        let actions = dedup.consolidate(&meta(), &existing);
        assert_eq!(actions, vec![ConsolidationAction::Add]);
    }
}