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    ///
14    /// `rounded` says the live vector was read from a v9 file's fp16 column
15    /// (FMT-9b), so it's compared with the incoming vector after the same
16    /// rounding: a real embedder's value never survives it exactly, and
17    /// before v0.16 every such re-write added a version.
18    pub(super) fn is_identical_keyed_write(
19        incoming: &Memory,
20        live: &Memory,
21        rounded: bool,
22    ) -> bool {
23        if incoming.content != live.content {
24            return false;
25        }
26        if incoming.memory_type != live.memory_type {
27            return false;
28        }
29        if (incoming.importance - live.importance).abs() > f32::EPSILON {
30            return false;
31        }
32        let same_vector = if rounded {
33            crate::veccol::dequantize(&crate::veccol::quantize(&incoming.vector).0) == live.vector
34        } else {
35            incoming.vector == live.vector
36        };
37        if !same_vector {
38            return false;
39        }
40        // Strip `_mnemo.*` from both sides before comparing user metadata.
41        let strip = |m: &Map<String, Value>| -> Map<String, Value> {
42            m.iter()
43                .filter(|(k, _)| !k.starts_with(crate::memory::MNEMO_META_NS))
44                .map(|(k, v)| (k.clone(), v.clone()))
45                .collect()
46        };
47        strip(&incoming.metadata) == strip(&live.metadata)
48    }
49
50    /// Store a memory under a keyed upsert slot. Returns the live record's
51    /// id and a [`WriteOutcome`] saying whether this write created a new
52    /// slot (`Added`), replaced a prior record (`Superseded`), or matched
53    /// the existing live record byte-for-byte (`Unchanged`, no file write).
54    ///
55    /// The slot is identified by `(scope_owner, key)`:
56    /// * `Scope::Private` memories share a slot per `(agent_id, key)`.
57    /// * `Scope::Shared` memories share one slot per `key` across the file.
58    ///
59    /// On supersession the prior record is **not** deleted — it remains
60    /// retrievable through [`Mnemo::history`] — but it is excluded from
61    /// default [`Mnemo::recall`] and [`Mnemo::about`]. A caller that wants
62    /// the full lineage of a key walks `history(key)`.
63    ///
64    /// This is the atomic 12.1 "supersede-or-noop" write path. Plain
65    /// [`Mnemo::remember`] without a key is unchanged.
66    pub fn remember_keyed(
67        &mut self,
68        mut memory: Memory,
69        key: &str,
70    ) -> Result<(Ulid, WriteOutcome)> {
71        if self.read_only {
72            return Err(MnemoError::ReadOnly);
73        }
74        if key.is_empty() {
75            return Err(MnemoError::Invalid(
76                "remember_keyed: 'key' must not be empty".into(),
77            ));
78        }
79        // RB-001.24: a keyed write is always a new record, so no caller
80        // `_mnemo.*` key is accepted (the engine sets `_mnemo.key` below).
81        if let Some(k) = memory
82            .metadata
83            .keys()
84            .find(|k| k.starts_with(crate::memory::MNEMO_META_NS))
85        {
86            return Err(super::crud::reserved_key_error(k));
87        }
88        self.ensure_key_caches()?;
89        let slot = Self::key_slot_for(&memory, key);
90        let existing = self.key_index.as_ref().and_then(|k| k.get(&slot).copied());
91
92        // The canonical `_mnemo.key`, so the record is self-identifying.
93        memory
94            .metadata
95            .insert(MNEMO_META_KEY.into(), Value::String(key.to_string()));
96
97        // NOOP check: if a live record exists for this slot and its
98        // user-visible fields match, return the existing id without a
99        // write.
100        if let Some(prev_id_u) = existing {
101            let prev_idx = self
102                .index
103                .get(prev_id_u, &self.catalog)
104                .ok_or_else(|| MnemoError::Invalid("key_index drift".into()))?;
105            let prev_entry = self.catalog[prev_idx].clone();
106            let prev_mem = self.read_memory(&prev_entry)?;
107            let rounded = prev_entry.v9.is_some() && !self.float_vectors();
108            if Self::is_identical_keyed_write(&memory, &prev_mem, rounded) {
109                return Ok((Ulid(prev_id_u), WriteOutcome::Unchanged));
110            }
111
112            // SUPERSESSION: insert the new record, then rewrite the old
113            // with `_mnemo.superseded_by` + `_mnemo.invalid_at`.
114            let now = memory::now_secs();
115            memory.id = Ulid::nil(); // force a fresh ULID in `put`
116            memory.metadata.insert(
117                MNEMO_META_SUPERSEDES.into(),
118                Value::String(Ulid(prev_id_u).to_string()),
119            );
120            let new_id = self.put(memory)?;
121            // Mark the prior record.
122            let mut prev_mut = prev_mem;
123            prev_mut.metadata.insert(
124                MNEMO_META_SUPERSEDED_BY.into(),
125                Value::String(new_id.to_string()),
126            );
127            prev_mut
128                .metadata
129                .insert(MNEMO_META_INVALID_AT.into(), Value::Number(now.into()));
130            // keep prev_mut.id so `put` overwrites in place.
131            self.put(prev_mut)?;
132            // Update caches incrementally.
133            if let Some(k) = self.key_index.as_mut() {
134                k.insert(slot, new_id.0);
135            }
136            if let Some(s) = self.superseded.as_mut() {
137                s.insert(prev_id_u);
138            }
139            return Ok((new_id, WriteOutcome::Superseded));
140        }
141
142        // ADDED: no prior record for this slot.
143        memory.id = Ulid::nil();
144        let new_id = self.put(memory)?;
145        if let Some(k) = self.key_index.as_mut() {
146            k.insert(slot, new_id.0);
147        }
148        Ok((new_id, WriteOutcome::Added))
149    }
150
151    /// 12.3 step 5b (v0.15): a keyed write that **adopts a named, unkeyed
152    /// memory as the key's first version, then supersedes it**. Use it to
153    /// put a fact that was written without a key under one, so the old
154    /// version stops showing in recall without being deleted.
155    ///
156    /// The old record (`supersedes`) takes the key (`_mnemo.key`) and is
157    /// marked `_mnemo.superseded_by` and `_mnemo.invalid_at`; the new record
158    /// gets `_mnemo.supersedes = <old id>`. [`Mnemo::history`] then lists the
159    /// old record as the oldest version, and recall and `about` leave it out,
160    /// as for any superseded record. No format change: these are the keyed
161    /// path's own `_mnemo.*` keys, which older builds carry through.
162    ///
163    /// **When the new content matches the old record's** user-visible fields
164    /// (the identical-write rule of [`Mnemo::remember_keyed`]), no new record
165    /// is written: the old one takes the key and becomes the slot's live
166    /// record, and the outcome is [`WriteOutcome::Updated`] with its id.
167    ///
168    /// Refused with [`MnemoError::Invalid`] when the old id doesn't exist or
169    /// is deleted; is already superseded; already has a key (use the plain
170    /// keyed write); is an engine record (any `_mnemo.kind`, or the
171    /// manifest); isn't in the key's slot scope (the same agent's Private
172    /// memory for a Private write, a Shared one for a Shared write); or when
173    /// the slot already has a live record. [`MnemoError::ReadOnly`] on a
174    /// read-only handle.
175    pub fn remember_keyed_superseding(
176        &mut self,
177        mut memory: Memory,
178        key: &str,
179        supersedes: &Ulid,
180    ) -> Result<(Ulid, WriteOutcome)> {
181        if self.read_only {
182            return Err(MnemoError::ReadOnly);
183        }
184        if key.is_empty() {
185            return Err(MnemoError::Invalid(
186                "remember_keyed_superseding: 'key' must not be empty".into(),
187            ));
188        }
189        if let Some(k) = memory
190            .metadata
191            .keys()
192            .find(|k| k.starts_with(crate::memory::MNEMO_META_NS))
193        {
194            return Err(super::crud::reserved_key_error(k));
195        }
196        self.ensure_key_caches()?;
197        let slot = Self::key_slot_for(&memory, key);
198        if self
199            .key_index
200            .as_ref()
201            .is_some_and(|k| k.contains_key(&slot))
202        {
203            return Err(MnemoError::Invalid(format!(
204                "supersedes: key {key:?} already has a live record; a named memory can only \
205                 become a key's first version (use the plain keyed write)"
206            )));
207        }
208        let bad = |why: &str| MnemoError::Invalid(format!("supersedes {supersedes}: {why}"));
209        let old_idx = self
210            .index
211            .get(supersedes.0, &self.catalog)
212            .ok_or_else(|| bad("no such memory"))?;
213        let old_entry = self.catalog[old_idx].clone();
214        if old_entry.deleted {
215            return Err(bad("the memory is deleted"));
216        }
217        let mut old = self.read_memory(&old_entry)?;
218        if old.metadata.contains_key(MNEMO_META_SUPERSEDED_BY)
219            || self
220                .superseded
221                .as_ref()
222                .is_some_and(|s| s.contains(&supersedes.0))
223        {
224            return Err(bad("it is already superseded"));
225        }
226        if old.metadata.contains_key(MNEMO_META_KEY) {
227            return Err(bad(
228                "it already has a key; use the plain keyed write with that key",
229            ));
230        }
231        if old.metadata.contains_key(MNEMO_META_KIND) || is_manifest(&old) {
232            return Err(bad(
233                "it is an engine record (a thread, essence or the manifest)",
234            ));
235        }
236        if Self::key_slot_for(&old, key) != slot {
237            return Err(bad(
238                "it isn't in this key's scope (a Private write takes this agent's Private \
239                 memory, a Shared write a Shared one)",
240            ));
241        }
242        memory
243            .metadata
244            .insert(MNEMO_META_KEY.into(), Value::String(key.to_string()));
245        old.metadata
246            .insert(MNEMO_META_KEY.into(), Value::String(key.to_string()));
247        let rounded = old_entry.v9.is_some() && !self.float_vectors();
248        if Self::is_identical_keyed_write(&memory, &old, rounded) {
249            // Adopt the old record as the slot's live record.
250            self.put(old)?;
251            if let Some(k) = self.key_index.as_mut() {
252                k.insert(slot, supersedes.0);
253            }
254            return Ok((*supersedes, WriteOutcome::Updated));
255        }
256        let now = memory::now_secs();
257        memory.id = Ulid::nil();
258        memory.metadata.insert(
259            MNEMO_META_SUPERSEDES.into(),
260            Value::String(supersedes.to_string()),
261        );
262        let new_id = self.put(memory)?;
263        old.metadata.insert(
264            MNEMO_META_SUPERSEDED_BY.into(),
265            Value::String(new_id.to_string()),
266        );
267        old.metadata
268            .insert(MNEMO_META_INVALID_AT.into(), Value::Number(now.into()));
269        self.put(old)?;
270        if let Some(k) = self.key_index.as_mut() {
271            k.insert(slot, new_id.0);
272        }
273        if let Some(s) = self.superseded.as_mut() {
274            s.insert(supersedes.0);
275        }
276        Ok((new_id, WriteOutcome::Superseded))
277    }
278
279    /// [`Mnemo::remember_keyed_superseding`] with `content` embedded by the
280    /// registered embedder (the document side).
281    pub fn remember_keyed_text_superseding(
282        &mut self,
283        content: &str,
284        memory_type: MemoryType,
285        key: &str,
286        supersedes: &Ulid,
287    ) -> Result<(Ulid, WriteOutcome)> {
288        if self.read_only {
289            return Err(MnemoError::ReadOnly);
290        }
291        let embedder = self.embedder.as_ref().ok_or_else(|| {
292            MnemoError::Invalid(
293                "no embedder registered on this handle; call set_embedder first".into(),
294            )
295        })?;
296        let mut vectors = embedder.embed(&[content])?;
297        let vector = vectors.pop().ok_or_else(|| {
298            MnemoError::Invalid("embedder returned no vector for the input text".into())
299        })?;
300        if vector.len() != self.dimensions {
301            return Err(MnemoError::DimensionMismatch {
302                expected: self.dimensions,
303                got: vector.len(),
304            });
305        }
306        let memory = Memory::new(content.to_string(), memory_type, vector);
307        self.remember_keyed_superseding(memory, key, supersedes)
308    }
309
310    /// Text-side keyed write: embed `content` through the registered
311    /// embedder, then [`Mnemo::remember_keyed`]. Same returns.
312    pub fn remember_keyed_text(
313        &mut self,
314        content: &str,
315        memory_type: MemoryType,
316        key: &str,
317    ) -> Result<(Ulid, WriteOutcome)> {
318        if self.read_only {
319            return Err(MnemoError::ReadOnly);
320        }
321        let embedder = self.embedder.as_ref().ok_or_else(|| {
322            MnemoError::Invalid(
323                "no embedder registered on this handle; call set_embedder first".into(),
324            )
325        })?;
326        let mut vectors = embedder.embed(&[content])?;
327        let vector = vectors.pop().ok_or_else(|| {
328            MnemoError::Invalid("embedder returned no vector for the input text".into())
329        })?;
330        if vector.len() != self.dimensions {
331            return Err(MnemoError::DimensionMismatch {
332                expected: self.dimensions,
333                got: vector.len(),
334            });
335        }
336        let memory = Memory::new(content.to_string(), memory_type, vector);
337        self.remember_keyed(memory, key)
338    }
339
340    /// Update an existing memory in place, preserving its ULID,
341    /// `created_at` and access stats. Returns [`WriteOutcome::Updated`]
342    /// on a real change, [`WriteOutcome::Unchanged`] when every field in
343    /// the patch already matches the live record.
344    ///
345    /// Reserved `_mnemo.*` metadata keys on the existing record are
346    /// preserved across a `metadata` replacement; a `metadata` of
347    /// `Some(map)` replaces every **user-visible** key with `map`'s
348    /// entries. A `content` change requires a matching `vector`
349    /// (use [`Mnemo::update_text`] to re-embed) — a bare `content` patch
350    /// is rejected to stop text and embedding drifting apart silently.
351    ///
352    /// A `metadata` map with a key starting with `_mnemo.` is refused with
353    /// [`MnemoError::Invalid`]: those keys are the engine's, and the
354    /// record's own are kept as described above.
355    pub fn update(&mut self, id: &Ulid, patch: MemoryPatch) -> Result<WriteOutcome> {
356        if let Some(k) = patch.metadata.as_ref().and_then(|m| {
357            m.keys()
358                .find(|k| k.starts_with(crate::memory::MNEMO_META_NS))
359        }) {
360            return Err(super::crud::reserved_key_error(k));
361        }
362        self.update_unchecked(id, patch)
363    }
364
365    /// [`Mnemo::update`] without the reserved-key check, for the engine's own
366    /// updates (essence items carry `_mnemo.refs`).
367    pub(super) fn update_unchecked(
368        &mut self,
369        id: &Ulid,
370        patch: MemoryPatch,
371    ) -> Result<WriteOutcome> {
372        if self.read_only {
373            return Err(MnemoError::ReadOnly);
374        }
375        if patch.content.is_some() && patch.vector.is_none() {
376            return Err(MnemoError::Invalid(
377                "update: a content change needs a matching vector (or call update_text \
378                 to re-embed through the registered embedder)"
379                    .into(),
380            ));
381        }
382        let idx = self
383            .index
384            .get(id.0, &self.catalog)
385            .ok_or_else(|| MnemoError::NotFound(id.to_string()))?;
386        if self.catalog[idx].deleted {
387            return Err(MnemoError::NotFound(id.to_string()));
388        }
389        let entry = self.catalog[idx].clone();
390        let existing = self.read_memory(&entry)?;
391
392        // Apply patch into a candidate, detect no-op after the fact.
393        let mut cand = existing.clone();
394        if let Some(c) = &patch.content {
395            cand.content = c.clone();
396        }
397        if let Some(v) = &patch.vector {
398            if v.len() != self.dimensions {
399                return Err(MnemoError::DimensionMismatch {
400                    expected: self.dimensions,
401                    got: v.len(),
402                });
403            }
404            cand.vector = v.clone();
405        }
406        if let Some(i) = patch.importance {
407            cand.importance = i.clamp(0.0, 1.0);
408        }
409        if let Some(mt) = patch.memory_type {
410            cand.memory_type = mt;
411        }
412        if let Some(new_meta) = patch.metadata {
413            // Keep reserved `_mnemo.*` keys from the existing record.
414            let reserved: Vec<(String, Value)> = existing
415                .metadata
416                .iter()
417                .filter(|(k, _)| k.starts_with(crate::memory::MNEMO_META_NS))
418                .map(|(k, v)| (k.clone(), v.clone()))
419                .collect();
420            cand.metadata = new_meta;
421            for (k, v) in reserved {
422                cand.metadata.insert(k, v);
423            }
424        }
425        if let Some(ttl) = patch.ttl_secs {
426            cand.ttl_secs = ttl;
427        }
428
429        // No-op detection: compare all user-visible fields.
430        if cand.content == existing.content
431            && cand.vector == existing.vector
432            && (cand.importance - existing.importance).abs() <= f32::EPSILON
433            && cand.memory_type == existing.memory_type
434            && cand.metadata == existing.metadata
435            && cand.ttl_secs == existing.ttl_secs
436        {
437            return Ok(WriteOutcome::Unchanged);
438        }
439
440        // Stamp `_mnemo.updated_at` and preserve id + created_at.
441        let now = memory::now_secs();
442        cand.metadata
443            .insert(MNEMO_META_UPDATED_AT.into(), Value::Number(now.into()));
444        cand.id = existing.id;
445        cand.created_at = existing.created_at;
446        // put() preserves accessed_at/access_count via the index lookup.
447        self.put(cand)?;
448        // `put` kept the key slot and the other handle caches current.
449        Ok(WriteOutcome::Updated)
450    }
451
452    /// In-place update that re-embeds `new_text` through the registered
453    /// embedder. Shorthand for `update(id, patch.with_content_and_vector)`.
454    pub fn update_text(
455        &mut self,
456        id: &Ulid,
457        new_text: &str,
458        mut patch: MemoryPatch,
459    ) -> Result<WriteOutcome> {
460        if self.read_only {
461            return Err(MnemoError::ReadOnly);
462        }
463        let embedder = self.embedder.as_ref().ok_or_else(|| {
464            MnemoError::Invalid(
465                "no embedder registered on this handle; call set_embedder first".into(),
466            )
467        })?;
468        let mut vectors = embedder.embed(&[new_text])?;
469        let vector = vectors.pop().ok_or_else(|| {
470            MnemoError::Invalid("embedder returned no vector for the input text".into())
471        })?;
472        if vector.len() != self.dimensions {
473            return Err(MnemoError::DimensionMismatch {
474                expected: self.dimensions,
475                got: vector.len(),
476            });
477        }
478        patch.content = Some(new_text.to_string());
479        patch.vector = Some(vector);
480        self.update(id, patch)
481    }
482
483    /// Walk the full chain for a keyed slot: every record this key has
484    /// ever held, newest first. Entry 0 is the **live** record (unless
485    /// the slot is empty, in which case the vector is empty); subsequent
486    /// entries are the superseded history in reverse-supersession order.
487    ///
488    /// **Slot resolution (v0.8.1 bugfix, lane A).** The lookup slot
489    /// matches a keyed `remember` with the same arguments, so the
490    /// obvious `history(key, None)` walks the private slot of the
491    /// default agent — the same slot
492    /// `remember_keyed(Memory::new(...), key)` writes to when the
493    /// caller omits an explicit `agent_id` / `scope`. Pre-v0.8.1
494    /// `agent_id = None` incorrectly looked up the shared slot and
495    /// returned an empty chain for the common case; the old behavior
496    /// is still reachable via `history_in(key, KeyScope::Shared)`.
497    ///
498    /// * `agent_id = Some(a)` → private slot for that agent.
499    /// * `agent_id = None` → private slot for the default agent (same
500    ///   as [`KeyScope::private_default`]).
501    ///
502    /// Use [`Mnemo::history_in`] with [`KeyScope::Shared`] for the
503    /// shared slot.
504    pub fn history(&mut self, key: &str, agent_id: Option<&str>) -> Result<Vec<Memory>> {
505        let scope = match agent_id {
506            Some(a) => KeyScope::Private(a.to_string()),
507            None => KeyScope::private_default(),
508        };
509        self.history_in(key, scope)
510    }
511
512    /// Walk the full chain for a keyed slot identified by an explicit
513    /// [`KeyScope`]. Returns the same shape as [`Mnemo::history`] —
514    /// live record first, then the superseded chain newest-first.
515    ///
516    /// Use this when you need the **shared** slot (`KeyScope::Shared`),
517    /// which `history(key, None)` no longer reaches as of v0.8.1.
518    pub fn history_in(&mut self, key: &str, scope: KeyScope) -> Result<Vec<Memory>> {
519        self.ensure_key_caches()?;
520        let slot = crate::store::KeySlot {
521            scope_owner: match scope {
522                KeyScope::Private(a) => Some(a),
523                KeyScope::Shared => None,
524            },
525            key: key.to_string(),
526        };
527        let live_id = self.key_index.as_ref().and_then(|k| k.get(&slot).copied());
528        let mut out = Vec::new();
529        let mut cursor = live_id;
530        while let Some(id_u) = cursor {
531            let idx = self.index.get(id_u, &self.catalog).ok_or_else(|| {
532                MnemoError::Invalid("history: superseded chain references missing id".into())
533            })?;
534            let entry = self.catalog[idx].clone();
535            if entry.deleted {
536                break;
537            }
538            let m = self.read_memory(&entry)?;
539            let next = m
540                .metadata
541                .get(MNEMO_META_SUPERSEDES)
542                .and_then(|v| v.as_str())
543                .and_then(|s| Ulid::from_string(s).ok())
544                .map(|u| u.0);
545            out.push(m);
546            cursor = next;
547        }
548        Ok(out)
549    }
550
551    // --- Phase 12.7a: thread archive --------------------------------
552}