1use super::*;
4
5impl Mnemo {
6 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 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 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 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 memory
94 .metadata
95 .insert(MNEMO_META_KEY.into(), Value::String(key.to_string()));
96
97 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 let now = memory::now_secs();
115 memory.id = Ulid::nil(); 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 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 self.put(prev_mut)?;
132 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 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 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 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 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 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 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 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 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 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 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 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 self.put(cand)?;
448 Ok(WriteOutcome::Updated)
450 }
451
452 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 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 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 }