Skip to main content

mnemo_engine/store/
keyed.rs

1//! Phase 12.1: keyed upserts, edit in place (update), and supersession history.
2
3use super::*;
4
5impl Mnemo {
6    /// Stage-identical check for a 12.1 keyed no-op. The incoming write
7    /// is byte-equal to the live record iff every user-visible field
8    /// (content, type, importance, vector, user metadata) matches. The
9    /// `_mnemo.*` reserved keys on the live record are **ignored** for
10    /// this comparison — a repeat of an identical write re-issued by an
11    /// extractor must be a NOOP even if the live record already carries
12    /// supersession bookkeeping from a prior op.
13    pub(super) fn is_identical_keyed_write(incoming: &Memory, live: &Memory) -> bool {
14        if incoming.content != live.content {
15            return false;
16        }
17        if incoming.memory_type != live.memory_type {
18            return false;
19        }
20        if (incoming.importance - live.importance).abs() > f32::EPSILON {
21            return false;
22        }
23        if incoming.vector != live.vector {
24            return false;
25        }
26        // Strip `_mnemo.*` from both sides before comparing user metadata.
27        let strip = |m: &Map<String, Value>| -> Map<String, Value> {
28            m.iter()
29                .filter(|(k, _)| !k.starts_with(crate::memory::MNEMO_META_NS))
30                .map(|(k, v)| (k.clone(), v.clone()))
31                .collect()
32        };
33        strip(&incoming.metadata) == strip(&live.metadata)
34    }
35
36    /// Store a memory under a keyed upsert slot. Returns the live record's
37    /// id and a [`WriteOutcome`] saying whether this write created a new
38    /// slot (`Added`), replaced a prior record (`Superseded`), or matched
39    /// the existing live record byte-for-byte (`Unchanged`, no file write).
40    ///
41    /// The slot is identified by `(scope_owner, key)`:
42    /// * `Scope::Private` memories share a slot per `(agent_id, key)`.
43    /// * `Scope::Shared` memories share one slot per `key` across the file.
44    ///
45    /// On supersession the prior record is **not** deleted — it remains
46    /// retrievable through [`Mnemo::history`] — but it is excluded from
47    /// default [`Mnemo::recall`] and [`Mnemo::about`]. A caller that wants
48    /// the full lineage of a key walks `history(key)`.
49    ///
50    /// This is the atomic 12.1 "supersede-or-noop" write path. Plain
51    /// [`Mnemo::remember`] without a key is unchanged.
52    pub fn remember_keyed(
53        &mut self,
54        mut memory: Memory,
55        key: &str,
56    ) -> Result<(Ulid, WriteOutcome)> {
57        if self.read_only {
58            return Err(MnemoError::ReadOnly);
59        }
60        if key.is_empty() {
61            return Err(MnemoError::Invalid(
62                "remember_keyed: 'key' must not be empty".into(),
63            ));
64        }
65        self.ensure_key_caches()?;
66        let slot = Self::key_slot_for(&memory, key);
67        let existing = self.key_index.as_ref().and_then(|k| k.get(&slot).copied());
68
69        // Caller may already have set `_mnemo.key` on the memory; rewrite
70        // it to our canonical value regardless so the record is
71        // self-identifying.
72        memory
73            .metadata
74            .insert(MNEMO_META_KEY.into(), Value::String(key.to_string()));
75
76        // NOOP check: if a live record exists for this slot and its
77        // user-visible fields match, return the existing id without a
78        // write.
79        if let Some(prev_id_u) = existing {
80            let prev_idx = self
81                .index
82                .get(prev_id_u, &self.catalog)
83                .ok_or_else(|| MnemoError::Invalid("key_index drift".into()))?;
84            let prev_entry = self.catalog[prev_idx].clone();
85            let prev_mem = self.read_memory(&prev_entry)?;
86            if Self::is_identical_keyed_write(&memory, &prev_mem) {
87                return Ok((Ulid(prev_id_u), WriteOutcome::Unchanged));
88            }
89
90            // SUPERSESSION: insert the new record, then rewrite the old
91            // with `_mnemo.superseded_by` + `_mnemo.invalid_at`.
92            let now = memory::now_secs();
93            memory.id = Ulid::nil(); // force a fresh ULID in `put`
94            memory.metadata.insert(
95                MNEMO_META_SUPERSEDES.into(),
96                Value::String(Ulid(prev_id_u).to_string()),
97            );
98            let new_id = self.put(memory)?;
99            // Mark the prior record.
100            let mut prev_mut = prev_mem;
101            prev_mut.metadata.insert(
102                MNEMO_META_SUPERSEDED_BY.into(),
103                Value::String(new_id.to_string()),
104            );
105            prev_mut
106                .metadata
107                .insert(MNEMO_META_INVALID_AT.into(), Value::Number(now.into()));
108            // keep prev_mut.id so `put` overwrites in place.
109            self.put(prev_mut)?;
110            // Update caches incrementally.
111            if let Some(k) = self.key_index.as_mut() {
112                k.insert(slot, new_id.0);
113            }
114            if let Some(s) = self.superseded.as_mut() {
115                s.insert(prev_id_u);
116            }
117            return Ok((new_id, WriteOutcome::Superseded));
118        }
119
120        // ADDED: no prior record for this slot.
121        memory.id = Ulid::nil();
122        let new_id = self.put(memory)?;
123        if let Some(k) = self.key_index.as_mut() {
124            k.insert(slot, new_id.0);
125        }
126        Ok((new_id, WriteOutcome::Added))
127    }
128
129    /// Text-side keyed write: embed `content` through the registered
130    /// embedder, then [`Mnemo::remember_keyed`]. Same returns.
131    pub fn remember_keyed_text(
132        &mut self,
133        content: &str,
134        memory_type: MemoryType,
135        key: &str,
136    ) -> Result<(Ulid, WriteOutcome)> {
137        if self.read_only {
138            return Err(MnemoError::ReadOnly);
139        }
140        let embedder = self.embedder.as_ref().ok_or_else(|| {
141            MnemoError::Invalid(
142                "no embedder registered on this handle; call set_embedder first".into(),
143            )
144        })?;
145        let mut vectors = embedder.embed(&[content])?;
146        let vector = vectors.pop().ok_or_else(|| {
147            MnemoError::Invalid("embedder returned no vector for the input text".into())
148        })?;
149        if vector.len() != self.dimensions {
150            return Err(MnemoError::DimensionMismatch {
151                expected: self.dimensions,
152                got: vector.len(),
153            });
154        }
155        let memory = Memory::new(content.to_string(), memory_type, vector);
156        self.remember_keyed(memory, key)
157    }
158
159    /// Update an existing memory in place, preserving its ULID,
160    /// `created_at` and access stats. Returns [`WriteOutcome::Updated`]
161    /// on a real change, [`WriteOutcome::Unchanged`] when every field in
162    /// the patch already matches the live record.
163    ///
164    /// Reserved `_mnemo.*` metadata keys on the existing record are
165    /// preserved across a `metadata` replacement; a `metadata` of
166    /// `Some(map)` replaces every **user-visible** key with `map`'s
167    /// entries. A `content` change requires a matching `vector`
168    /// (use [`Mnemo::update_text`] to re-embed) — a bare `content` patch
169    /// is rejected to stop text and embedding drifting apart silently.
170    pub fn update(&mut self, id: &Ulid, patch: MemoryPatch) -> Result<WriteOutcome> {
171        if self.read_only {
172            return Err(MnemoError::ReadOnly);
173        }
174        if patch.content.is_some() && patch.vector.is_none() {
175            return Err(MnemoError::Invalid(
176                "update: a content change needs a matching vector (or call update_text \
177                 to re-embed through the registered embedder)"
178                    .into(),
179            ));
180        }
181        let idx = self
182            .index
183            .get(id.0, &self.catalog)
184            .ok_or_else(|| MnemoError::NotFound(id.to_string()))?;
185        if self.catalog[idx].deleted {
186            return Err(MnemoError::NotFound(id.to_string()));
187        }
188        let entry = self.catalog[idx].clone();
189        let existing = self.read_memory(&entry)?;
190
191        // Apply patch into a candidate, detect no-op after the fact.
192        let mut cand = existing.clone();
193        if let Some(c) = &patch.content {
194            cand.content = c.clone();
195        }
196        if let Some(v) = &patch.vector {
197            if v.len() != self.dimensions {
198                return Err(MnemoError::DimensionMismatch {
199                    expected: self.dimensions,
200                    got: v.len(),
201                });
202            }
203            cand.vector = v.clone();
204        }
205        if let Some(i) = patch.importance {
206            cand.importance = i.clamp(0.0, 1.0);
207        }
208        if let Some(mt) = patch.memory_type {
209            cand.memory_type = mt;
210        }
211        if let Some(new_meta) = patch.metadata {
212            // Keep reserved `_mnemo.*` keys from the existing record.
213            let reserved: Vec<(String, Value)> = existing
214                .metadata
215                .iter()
216                .filter(|(k, _)| k.starts_with(crate::memory::MNEMO_META_NS))
217                .map(|(k, v)| (k.clone(), v.clone()))
218                .collect();
219            cand.metadata = new_meta;
220            for (k, v) in reserved {
221                cand.metadata.insert(k, v);
222            }
223        }
224        if let Some(ttl) = patch.ttl_secs {
225            cand.ttl_secs = ttl;
226        }
227
228        // No-op detection: compare all user-visible fields.
229        if cand.content == existing.content
230            && cand.vector == existing.vector
231            && (cand.importance - existing.importance).abs() <= f32::EPSILON
232            && cand.memory_type == existing.memory_type
233            && cand.metadata == existing.metadata
234            && cand.ttl_secs == existing.ttl_secs
235        {
236            return Ok(WriteOutcome::Unchanged);
237        }
238
239        // Stamp `_mnemo.updated_at` and preserve id + created_at.
240        let now = memory::now_secs();
241        cand.metadata
242            .insert(MNEMO_META_UPDATED_AT.into(), Value::Number(now.into()));
243        cand.id = existing.id;
244        cand.created_at = existing.created_at;
245        // put() preserves accessed_at/access_count via the index lookup.
246        self.put(cand)?;
247        // `put` kept the key slot and the other handle caches current.
248        Ok(WriteOutcome::Updated)
249    }
250
251    /// In-place update that re-embeds `new_text` through the registered
252    /// embedder. Shorthand for `update(id, patch.with_content_and_vector)`.
253    pub fn update_text(
254        &mut self,
255        id: &Ulid,
256        new_text: &str,
257        mut patch: MemoryPatch,
258    ) -> Result<WriteOutcome> {
259        if self.read_only {
260            return Err(MnemoError::ReadOnly);
261        }
262        let embedder = self.embedder.as_ref().ok_or_else(|| {
263            MnemoError::Invalid(
264                "no embedder registered on this handle; call set_embedder first".into(),
265            )
266        })?;
267        let mut vectors = embedder.embed(&[new_text])?;
268        let vector = vectors.pop().ok_or_else(|| {
269            MnemoError::Invalid("embedder returned no vector for the input text".into())
270        })?;
271        if vector.len() != self.dimensions {
272            return Err(MnemoError::DimensionMismatch {
273                expected: self.dimensions,
274                got: vector.len(),
275            });
276        }
277        patch.content = Some(new_text.to_string());
278        patch.vector = Some(vector);
279        self.update(id, patch)
280    }
281
282    /// Walk the full chain for a keyed slot: every record this key has
283    /// ever held, newest first. Entry 0 is the **live** record (unless
284    /// the slot is empty, in which case the vector is empty); subsequent
285    /// entries are the superseded history in reverse-supersession order.
286    ///
287    /// **Slot resolution (v0.8.1 bugfix, lane A).** The lookup slot
288    /// matches a keyed `remember` with the same arguments, so the
289    /// obvious `history(key, None)` walks the private slot of the
290    /// default agent — the same slot
291    /// `remember_keyed(Memory::new(...), key)` writes to when the
292    /// caller omits an explicit `agent_id` / `scope`. Pre-v0.8.1
293    /// `agent_id = None` incorrectly looked up the shared slot and
294    /// returned an empty chain for the common case; the old behavior
295    /// is still reachable via `history_in(key, KeyScope::Shared)`.
296    ///
297    /// * `agent_id = Some(a)` → private slot for that agent.
298    /// * `agent_id = None` → private slot for the default agent (same
299    ///   as [`KeyScope::private_default`]).
300    ///
301    /// Use [`Mnemo::history_in`] with [`KeyScope::Shared`] for the
302    /// shared slot.
303    pub fn history(&mut self, key: &str, agent_id: Option<&str>) -> Result<Vec<Memory>> {
304        let scope = match agent_id {
305            Some(a) => KeyScope::Private(a.to_string()),
306            None => KeyScope::private_default(),
307        };
308        self.history_in(key, scope)
309    }
310
311    /// Walk the full chain for a keyed slot identified by an explicit
312    /// [`KeyScope`]. Returns the same shape as [`Mnemo::history`] —
313    /// live record first, then the superseded chain newest-first.
314    ///
315    /// Use this when you need the **shared** slot (`KeyScope::Shared`),
316    /// which `history(key, None)` no longer reaches as of v0.8.1.
317    pub fn history_in(&mut self, key: &str, scope: KeyScope) -> Result<Vec<Memory>> {
318        self.ensure_key_caches()?;
319        let slot = crate::store::KeySlot {
320            scope_owner: match scope {
321                KeyScope::Private(a) => Some(a),
322                KeyScope::Shared => None,
323            },
324            key: key.to_string(),
325        };
326        let live_id = self.key_index.as_ref().and_then(|k| k.get(&slot).copied());
327        let mut out = Vec::new();
328        let mut cursor = live_id;
329        while let Some(id_u) = cursor {
330            let idx = self.index.get(id_u, &self.catalog).ok_or_else(|| {
331                MnemoError::Invalid("history: superseded chain references missing id".into())
332            })?;
333            let entry = self.catalog[idx].clone();
334            if entry.deleted {
335                break;
336            }
337            let m = self.read_memory(&entry)?;
338            let next = m
339                .metadata
340                .get(MNEMO_META_SUPERSEDES)
341                .and_then(|v| v.as_str())
342                .and_then(|s| Ulid::from_string(s).ok())
343                .map(|u| u.0);
344            out.push(m);
345            cursor = next;
346        }
347        Ok(out)
348    }
349
350    // --- Phase 12.7a: thread archive --------------------------------
351}