ai-memory 0.7.0

AI-agnostic persistent memory system — MCP server, HTTP API, and CLI for any AI platform
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

// Copyright 2026 AlphaOne LLC
// SPDX-License-Identifier: Apache-2.0

//! v0.7.0 #972 D1.5 (#986) — shared parity-test helpers for the
//! schemars-derived `McpTool` impls vs. the legacy hand-coded
//! `tool_definitions()` catalog.
//!
//! Each `d1_5_986_tests` mod under `src/mcp/tools/<tool>.rs` calls
//! [`legacy_props`], [`derived_props_for`], [`assert_property_set_parity`],
//! and [`assert_descriptions_match`] so the 4-helper boilerplate isn't
//! duplicated 30+ times across the family migration. The helpers
//! preserve the byte-for-byte invariant that D1.3 (#984) and D1.4
//! (#985) pin via the same shape (load_family.rs::d1_3_984_tests).
//!
//! Cfg-test only — these helpers are not compiled into the production
//! binary.

use serde_json::Value;

/// Resolve the legacy hand-coded `inputSchema.properties` map for one
/// tool out of [`crate::mcp::registry::tool_definitions`]. The legacy
/// catalog is the source-of-truth the D1.x split is migrating away
/// from (deleted in D1.6 (#987)); during the D1.1-D1.5 window both
/// surfaces coexist and the per-tool parity tests pin the new
/// schemars-derived schema against this map byte-for-byte.
pub(crate) fn legacy_props(tool_name: &str) -> serde_json::Map<String, Value> {
    let defs = crate::mcp::registry::tool_definitions();
    let tools = defs
        .get("tools")
        .and_then(Value::as_array)
        .expect("tool_definitions emits `tools` array");
    let entry = tools
        .iter()
        .find(|t| t.get("name").and_then(Value::as_str) == Some(tool_name))
        .unwrap_or_else(|| panic!("{tool_name} must be in legacy catalog"));
    entry
        .pointer("/inputSchema/properties")
        .and_then(Value::as_object)
        .unwrap_or_else(|| panic!("{tool_name}.inputSchema.properties must be object"))
        .clone()
}

/// Resolve the schemars-derived `properties` map for a `JsonSchema`
/// request type regardless of whether schemars emits the properties
/// directly under the root or under a `$ref`-resolved
/// `definitions/<Type>/properties` path. schemars 0.8 emits the
/// direct form; future versions may relocate. The fallback path lets
/// the parity helpers survive the relocation.
pub(crate) fn derived_props_for<T: schemars::JsonSchema>() -> serde_json::Map<String, Value> {
    let schema = schemars::schema_for!(T);
    let v = serde_json::to_value(schema).expect("schema -> value");
    // Empty / unit-like request structs (tools whose legacy schema is
    // `"properties": {}`) produce no `properties` key at all — schemars
    // omits the map when there are no fields. Treat that as an empty
    // properties map so the parity helpers can compare against the
    // legacy empty object.
    if let Some(props) = v.get("properties").and_then(Value::as_object) {
        return props.clone();
    }
    if let Some(props) = v
        .pointer(&format!(
            "/definitions/{}/properties",
            std::any::type_name::<T>().rsplit("::").next().unwrap_or("")
        ))
        .and_then(Value::as_object)
    {
        return props.clone();
    }
    serde_json::Map::new()
}

/// Pin property-set parity between the legacy hand-coded
/// `inputSchema.properties` map and the schemars-derived one. Every
/// legacy property must be present in the derived schema and vice
/// versa; a symmetric diff between the two key sets surfaces missing
/// or extra fields verbatim.
pub(crate) fn assert_property_set_parity(
    tool_name: &str,
    derived: &serde_json::Map<String, Value>,
) {
    let legacy = legacy_props(tool_name);
    let legacy_keys: std::collections::BTreeSet<&str> = legacy.keys().map(String::as_str).collect();
    let derived_keys: std::collections::BTreeSet<&str> =
        derived.keys().map(String::as_str).collect();
    assert_eq!(
        legacy_keys,
        derived_keys,
        "{tool_name}: property set drift; diff = {:?}",
        legacy_keys
            .symmetric_difference(&derived_keys)
            .collect::<Vec<_>>()
    );
}

/// Pin per-property `description` strings byte-for-byte against the
/// legacy hand-coded catalog. Legacy may omit `description` on rare
/// properties (e.g. open-ended `metadata`); the helper only asserts
/// equality when the legacy entry carries a non-null string. The
/// schemars-derived description comes from the per-field
/// `///`-doc-comment on the `<Tool>Request` struct.
pub(crate) fn assert_descriptions_match(tool_name: &str, derived: &serde_json::Map<String, Value>) {
    let legacy = legacy_props(tool_name);
    for (name, legacy_prop) in &legacy {
        if let Some(want) = legacy_prop.get("description").and_then(Value::as_str) {
            let got = derived
                .get(name)
                .and_then(|p| p.get("description"))
                .and_then(Value::as_str);
            assert_eq!(
                got,
                Some(want),
                "{tool_name}.{name}: description must match legacy byte-for-byte"
            );
        }
    }
}

#[cfg(test)]
mod self_tests {
    //! FUPC — direct happy-path exercise of the four shared parity
    //! helpers from a single call site. The per-tool `d1_5_986_tests`
    //! mods drive these in aggregate; this self-test pins the helper
    //! bodies (legacy lookup, schemars derive, both ref-resolution
    //! arms, set + description parity) so the module's own coverage is
    //! not solely a side effect of caller compilation.
    use super::{
        assert_descriptions_match, assert_property_set_parity, derived_props_for, legacy_props,
    };

    #[test]
    fn helpers_round_trip_on_memory_delete() {
        // `memory_delete` exists in the legacy catalog and has a stable
        // `DeleteRequest` schemars type → all four helpers run clean.
        let legacy = legacy_props("memory_delete");
        assert!(
            !legacy.is_empty(),
            "memory_delete must carry legacy properties"
        );
        let derived = derived_props_for::<crate::mcp::delete::DeleteRequest>();
        assert_property_set_parity("memory_delete", &derived);
        assert_descriptions_match("memory_delete", &derived);
    }

    #[test]
    fn derived_props_for_empty_request_is_empty_map() {
        // A unit-like request struct produces no `properties` key; the
        // helper's empty-map fallback arm must yield an empty map, not
        // panic.
        #[derive(schemars::JsonSchema)]
        #[allow(dead_code)]
        struct EmptyReq {}
        let derived = derived_props_for::<EmptyReq>();
        assert!(derived.is_empty());
    }
}