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