agm-core 1.1.0

Core library for parsing, validating, loading, and rendering AGM (Agent Graph Memory) files
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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

//! Memory sidecar model types for `.agm.mem` files.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

use super::memory::{MemoryScope, MemoryTtl};

/// Represents a parsed `.agm.mem` sidecar file.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MemFile {
    pub format_version: String,
    pub package: String,
    pub updated_at: String,
    pub entries: BTreeMap<String, MemFileEntry>,
}

/// A single memory entry.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MemFileEntry {
    pub topic: String,
    pub scope: MemoryScope,
    pub ttl: MemoryTtl,
    pub value: String,
    pub created_at: String,
    pub updated_at: String,
}

#[cfg(test)]
mod tests {
    use super::*;

    fn make_entry(ttl: MemoryTtl) -> MemFileEntry {
        MemFileEntry {
            topic: "infrastructure".to_owned(),
            scope: MemoryScope::Project,
            ttl,
            value: "some value".to_owned(),
            created_at: "2026-04-08T10:00:00Z".to_owned(),
            updated_at: "2026-04-08T10:00:00Z".to_owned(),
        }
    }

    // -----------------------------------------------------------------------
    // A: Serde roundtrip — minimal (no entries)
    // -----------------------------------------------------------------------

    #[test]
    fn test_mem_file_serde_roundtrip_minimal() {
        let mem = MemFile {
            format_version: "1.0".to_owned(),
            package: "test.pkg".to_owned(),
            updated_at: "2026-04-08T10:00:00Z".to_owned(),
            entries: BTreeMap::new(),
        };
        let json = serde_json::to_string(&mem).unwrap();
        let back: MemFile = serde_json::from_str(&json).unwrap();
        assert_eq!(mem, back);
    }

    // -----------------------------------------------------------------------
    // B: Serde roundtrip — permanent TTL
    // -----------------------------------------------------------------------

    #[test]
    fn test_mem_file_serde_roundtrip_permanent_ttl() {
        let mut entries = BTreeMap::new();
        entries.insert("key.one".to_owned(), make_entry(MemoryTtl::Permanent));
        let mem = MemFile {
            format_version: "1.0".to_owned(),
            package: "test.pkg".to_owned(),
            updated_at: "2026-04-08T10:00:00Z".to_owned(),
            entries,
        };
        let json = serde_json::to_string(&mem).unwrap();
        let back: MemFile = serde_json::from_str(&json).unwrap();
        assert_eq!(mem, back);
    }

    // -----------------------------------------------------------------------
    // C: Serde roundtrip — session TTL
    // -----------------------------------------------------------------------

    #[test]
    fn test_mem_file_serde_roundtrip_session_ttl() {
        let mut entries = BTreeMap::new();
        entries.insert("key.session".to_owned(), make_entry(MemoryTtl::Session));
        let mem = MemFile {
            format_version: "1.0".to_owned(),
            package: "test.pkg".to_owned(),
            updated_at: "2026-04-08T10:00:00Z".to_owned(),
            entries,
        };
        let json = serde_json::to_string(&mem).unwrap();
        let back: MemFile = serde_json::from_str(&json).unwrap();
        assert_eq!(mem, back);
    }

    // -----------------------------------------------------------------------
    // D: Serde roundtrip — duration TTL
    // -----------------------------------------------------------------------

    #[test]
    fn test_mem_file_serde_roundtrip_duration_ttl() {
        let mut entries = BTreeMap::new();
        entries.insert(
            "key.duration".to_owned(),
            make_entry(MemoryTtl::Duration("P30D".to_owned())),
        );
        let mem = MemFile {
            format_version: "1.0".to_owned(),
            package: "test.pkg".to_owned(),
            updated_at: "2026-04-08T10:00:00Z".to_owned(),
            entries,
        };
        let json = serde_json::to_string(&mem).unwrap();
        let back: MemFile = serde_json::from_str(&json).unwrap();
        assert_eq!(mem, back);
    }

    // -----------------------------------------------------------------------
    // E: All scopes in a single file
    // -----------------------------------------------------------------------

    #[test]
    fn test_mem_file_serde_roundtrip_all_scopes() {
        let mut entries = BTreeMap::new();
        for (key, scope) in [
            ("k.node", MemoryScope::Node),
            ("k.session", MemoryScope::Session),
            ("k.project", MemoryScope::Project),
            ("k.global", MemoryScope::Global),
        ] {
            entries.insert(
                key.to_owned(),
                MemFileEntry {
                    topic: "test".to_owned(),
                    scope,
                    ttl: MemoryTtl::Permanent,
                    value: "val".to_owned(),
                    created_at: "2026-04-08T10:00:00Z".to_owned(),
                    updated_at: "2026-04-08T10:00:00Z".to_owned(),
                },
            );
        }
        let mem = MemFile {
            format_version: "1.0".to_owned(),
            package: "test.pkg".to_owned(),
            updated_at: "2026-04-08T10:00:00Z".to_owned(),
            entries,
        };
        let json = serde_json::to_string(&mem).unwrap();
        let back: MemFile = serde_json::from_str(&json).unwrap();
        assert_eq!(mem, back);
    }
}