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}