1use super::*;
4
5impl Mnemo {
6 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 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 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 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 memory
80 .metadata
81 .insert(MNEMO_META_KEY.into(), Value::String(key.to_string()));
82
83 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 let now = memory::now_secs();
100 memory.id = Ulid::nil(); 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 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 self.put(prev_mut)?;
117 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 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 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 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 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 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 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 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 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 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 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 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 self.put(cand)?;
432 Ok(WriteOutcome::Updated)
434 }
435
436 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 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 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 }