mentedb 0.12.1

A purpose-built database engine for AI agent memory
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

//! Hot flushes checkpoint the WAL only; index and graph snapshots are
//! rewritten every flush_snapshot_interval flushes (and always on close).
//! Open reconciles stale snapshots against storage in both directions, so a
//! crash between snapshot writes never loses recall and never resurrects
//! forgotten memories into the index.

use mentedb::CognitiveConfig;
use mentedb::MenteDb;
use mentedb::prelude::*;

fn vec_for(axis: usize) -> Vec<f32> {
    let mut v = vec![0.1_f32; 8];
    v[axis] = 1.0;
    v
}

fn store(db: &MenteDb, content: &str, axis: usize) -> MemoryId {
    let node = MemoryNode::new(
        AgentId::nil(),
        MemoryType::Semantic,
        content.to_string(),
        vec_for(axis),
    );
    let id = node.id;
    db.store(node).unwrap();
    id
}

fn now_us() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .unwrap()
        .as_micros() as u64
}

fn recall_ids(db: &MenteDb, axis: usize) -> Vec<MemoryId> {
    db.recall_hybrid_at(&vec_for(axis), None, 10, now_us(), None, None)
        .unwrap()
        .into_iter()
        .map(|(id, _)| id)
        .collect()
}

#[test]
fn recall_survives_crash_between_snapshots() {
    let dir = tempfile::tempdir().unwrap();
    let id;
    {
        let db = MenteDb::open_with_config(dir.path(), CognitiveConfig::default()).unwrap();
        // Establish snapshots once so they exist, then go stale.
        db.flush_full().unwrap();
        id = store(&db, "stored after the last snapshot", 0);
        // Hot flush: WAL checkpoint only, snapshots untouched.
        db.flush().unwrap();
        db.simulate_crash();
    }
    let db = MenteDb::open_with_config(dir.path(), CognitiveConfig::default()).unwrap();
    assert!(
        recall_ids(&db, 0).contains(&id),
        "open must reindex memories the stale snapshot missed"
    );
}

#[test]
fn forgotten_memory_stays_gone_despite_newer_snapshot() {
    let dir = tempfile::tempdir().unwrap();
    let id;
    {
        let db = MenteDb::open_with_config(dir.path(), CognitiveConfig::default()).unwrap();
        id = store(&db, "will be forgotten", 1);
        // Snapshot contains the memory.
        db.flush_full().unwrap();
        // Forget afterwards, hot flush only: the snapshot still has it.
        db.forget(id).unwrap();
        db.flush().unwrap();
        db.simulate_crash();
    }
    let db = MenteDb::open_with_config(dir.path(), CognitiveConfig::default()).unwrap();
    assert!(
        !recall_ids(&db, 1).contains(&id),
        "open must retire vectors whose pages are gone"
    );
    assert!(
        db.get_memory(id).is_err(),
        "the memory itself stays deleted"
    );
}

#[test]
fn snapshots_write_on_the_configured_interval() {
    let dir = tempfile::tempdir().unwrap();
    let config = CognitiveConfig {
        flush_snapshot_interval: 3,
        ..CognitiveConfig::default()
    };
    let db = MenteDb::open_with_config(dir.path(), config).unwrap();
    store(&db, "first", 2);
    db.flush_full().unwrap();

    let hnsw = dir.path().join("indexes").join("hnsw.bin");
    let before = std::fs::metadata(&hnsw).unwrap().modified().unwrap();

    store(&db, "second", 3);
    db.flush().unwrap();
    db.flush().unwrap();
    let mid = std::fs::metadata(&hnsw).unwrap().modified().unwrap();
    assert_eq!(before, mid, "snapshots must not rewrite on hot flushes");

    db.flush().unwrap();
    let after = std::fs::metadata(&hnsw).unwrap().modified().unwrap();
    assert!(after > before, "the Nth flush must rewrite snapshots");
}

#[test]
fn quick_close_survives_reopen_with_full_recall() {
    let dir = tempfile::tempdir().unwrap();
    let id;
    {
        let db = MenteDb::open_with_config(dir.path(), CognitiveConfig::default()).unwrap();
        db.flush_full().unwrap();
        id = store(&db, "written just before quick close", 5);
        db.close_quick().unwrap();
    }
    let db = MenteDb::open_with_config(dir.path(), CognitiveConfig::default()).unwrap();
    assert!(
        recall_ids(&db, 5).contains(&id),
        "quick close must lose nothing; open reconciles the stale snapshot"
    );
    assert!(db.get_memory(id).is_ok());
}