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> {
43 m.iter()
44 .filter(|(k, _)| !k.starts_with(crate::memory::MNEMO_META_NS) || is_caller_key(k))
45 .map(|(k, v)| (k.clone(), v.clone()))
46 .collect()
47 };
48 strip(&incoming.metadata) == strip(&live.metadata)
49 }
50
51 pub fn default_agent(&mut self) -> Result<Option<String>> {
56 Ok(self
57 .about_in(crate::memory::VisibilitySet::ALL)?
58 .into_iter()
59 .find(is_manifest)
60 .and_then(|m| {
61 m.metadata
62 .get(MNEMO_META_DEFAULT_AGENT)
63 .and_then(Value::as_str)
64 .map(str::to_string)
65 }))
66 }
67
68 pub fn set_default_agent(&mut self, agent: Option<&str>) -> Result<WriteOutcome> {
74 if self.read_only {
75 return Err(MnemoError::ReadOnly);
76 }
77 if let Some(a) = agent {
78 if !crate::memory::valid_agent_id(a) {
79 return Err(MnemoError::Invalid(format!(
80 "{a:?} isn't an agent id: 1 to 64 of letters, digits, '.', '_' and '-'"
81 )));
82 }
83 }
84 let Some(mut m) = self
85 .about_in(crate::memory::VisibilitySet::ALL)?
86 .into_iter()
87 .find(is_manifest)
88 else {
89 return Err(MnemoError::Invalid(
90 "this brain has no manifest to record a default agent on".into(),
91 ));
92 };
93 let want = agent.map(|a| Value::String(a.to_string()));
94 if m.metadata.get(MNEMO_META_DEFAULT_AGENT) == want.as_ref() {
95 return Ok(WriteOutcome::Unchanged);
96 }
97 match want {
98 Some(v) => m.metadata.insert(MNEMO_META_DEFAULT_AGENT.into(), v),
99 None => m.metadata.remove(MNEMO_META_DEFAULT_AGENT),
100 };
101 m.metadata.insert(
102 crate::memory::MNEMO_META_UPDATED_AT.into(),
103 Value::Number(memory::now_secs().into()),
104 );
105 self.put(m)?;
106 Ok(WriteOutcome::Updated)
107 }
108
109 pub fn remember_keyed(
126 &mut self,
127 mut memory: Memory,
128 key: &str,
129 ) -> Result<(Ulid, WriteOutcome)> {
130 if self.read_only {
131 return Err(MnemoError::ReadOnly);
132 }
133 if key.is_empty() {
134 return Err(MnemoError::Invalid(
135 "remember_keyed: 'key' must not be empty".into(),
136 ));
137 }
138 check_caller_reserved(&memory.metadata)?;
143 self.ensure_key_caches()?;
144 let slot = Self::key_slot_for(&memory, key);
145 let existing = self.key_index.as_ref().and_then(|k| k.get(&slot).copied());
146
147 memory
149 .metadata
150 .insert(MNEMO_META_KEY.into(), Value::String(key.to_string()));
151
152 if let Some(prev_id_u) = existing {
156 let prev_idx = self
157 .index
158 .get(prev_id_u, &self.catalog)
159 .ok_or_else(|| MnemoError::Invalid("key_index drift".into()))?;
160 let prev_entry = self.catalog[prev_idx].clone();
161 let prev_mem = self.read_memory(&prev_entry)?;
162 inherit_levels(&mut memory, &prev_mem);
163 let rounded = prev_entry.v9.is_some() && !self.float_vectors();
164 if Self::is_identical_keyed_write(&memory, &prev_mem, rounded) {
165 return Ok((Ulid(prev_id_u), WriteOutcome::Unchanged));
166 }
167
168 let now = memory::now_secs();
171 memory.id = Ulid::nil(); memory.metadata.insert(
173 MNEMO_META_SUPERSEDES.into(),
174 Value::String(Ulid(prev_id_u).to_string()),
175 );
176 let new_id = self.put(memory)?;
177 let mut prev_mut = prev_mem;
179 prev_mut.metadata.insert(
180 MNEMO_META_SUPERSEDED_BY.into(),
181 Value::String(new_id.to_string()),
182 );
183 prev_mut
184 .metadata
185 .insert(MNEMO_META_INVALID_AT.into(), Value::Number(now.into()));
186 self.put(prev_mut)?;
188 if let Some(k) = self.key_index.as_mut() {
190 k.insert(slot, new_id.0);
191 }
192 if let Some(s) = self.superseded.as_mut() {
193 s.insert(prev_id_u);
194 }
195 return Ok((new_id, WriteOutcome::Superseded));
196 }
197
198 memory.id = Ulid::nil();
200 let new_id = self.put(memory)?;
201 if let Some(k) = self.key_index.as_mut() {
202 k.insert(slot, new_id.0);
203 }
204 Ok((new_id, WriteOutcome::Added))
205 }
206
207 pub fn remember_keyed_superseding(
232 &mut self,
233 mut memory: Memory,
234 key: &str,
235 supersedes: &Ulid,
236 ) -> Result<(Ulid, WriteOutcome)> {
237 if self.read_only {
238 return Err(MnemoError::ReadOnly);
239 }
240 if key.is_empty() {
241 return Err(MnemoError::Invalid(
242 "remember_keyed_superseding: 'key' must not be empty".into(),
243 ));
244 }
245 check_caller_reserved(&memory.metadata)?;
248 self.ensure_key_caches()?;
249 let slot = Self::key_slot_for(&memory, key);
250 if self
251 .key_index
252 .as_ref()
253 .is_some_and(|k| k.contains_key(&slot))
254 {
255 return Err(MnemoError::Invalid(format!(
256 "supersedes: key {key:?} already has a live record; a named memory can only \
257 become a key's first version (use the plain keyed write)"
258 )));
259 }
260 let bad = |why: &str| MnemoError::Invalid(format!("supersedes {supersedes}: {why}"));
261 let old_idx = self
262 .index
263 .get(supersedes.0, &self.catalog)
264 .ok_or_else(|| bad("no such memory"))?;
265 let old_entry = self.catalog[old_idx].clone();
266 if old_entry.deleted {
267 return Err(bad("the memory is deleted"));
268 }
269 let mut old = self.read_memory(&old_entry)?;
270 if old.metadata.contains_key(MNEMO_META_SUPERSEDED_BY)
271 || self
272 .superseded
273 .as_ref()
274 .is_some_and(|s| s.contains(&supersedes.0))
275 {
276 return Err(bad("it is already superseded"));
277 }
278 if old.metadata.contains_key(MNEMO_META_KEY) {
279 return Err(bad(
280 "it already has a key; use the plain keyed write with that key",
281 ));
282 }
283 if old.metadata.contains_key(MNEMO_META_KIND) || is_manifest(&old) {
284 return Err(bad(
285 "it is an engine record (a thread, essence or the manifest)",
286 ));
287 }
288 if Self::key_slot_for(&old, key) != slot {
289 return Err(bad(
290 "it isn't in this key's scope (a Private write takes this agent's Private \
291 memory, a Shared write a Shared one)",
292 ));
293 }
294 memory
295 .metadata
296 .insert(MNEMO_META_KEY.into(), Value::String(key.to_string()));
297 old.metadata
298 .insert(MNEMO_META_KEY.into(), Value::String(key.to_string()));
299 inherit_levels(&mut memory, &old);
300 let rounded = old_entry.v9.is_some() && !self.float_vectors();
301 if Self::is_identical_keyed_write(&memory, &old, rounded) {
302 self.put(old)?;
304 if let Some(k) = self.key_index.as_mut() {
305 k.insert(slot, supersedes.0);
306 }
307 return Ok((*supersedes, WriteOutcome::Updated));
308 }
309 let now = memory::now_secs();
310 memory.id = Ulid::nil();
311 memory.metadata.insert(
312 MNEMO_META_SUPERSEDES.into(),
313 Value::String(supersedes.to_string()),
314 );
315 let new_id = self.put(memory)?;
316 old.metadata.insert(
317 MNEMO_META_SUPERSEDED_BY.into(),
318 Value::String(new_id.to_string()),
319 );
320 old.metadata
321 .insert(MNEMO_META_INVALID_AT.into(), Value::Number(now.into()));
322 self.put(old)?;
323 if let Some(k) = self.key_index.as_mut() {
324 k.insert(slot, new_id.0);
325 }
326 if let Some(s) = self.superseded.as_mut() {
327 s.insert(supersedes.0);
328 }
329 Ok((new_id, WriteOutcome::Superseded))
330 }
331
332 pub fn remember_keyed_text_superseding(
335 &mut self,
336 content: &str,
337 memory_type: MemoryType,
338 key: &str,
339 supersedes: &Ulid,
340 ) -> Result<(Ulid, WriteOutcome)> {
341 if self.read_only {
342 return Err(MnemoError::ReadOnly);
343 }
344 let embedder = self.embedder.as_ref().ok_or_else(|| {
345 MnemoError::Invalid(
346 "no embedder registered on this handle; call set_embedder first".into(),
347 )
348 })?;
349 let mut vectors = embedder.embed(&[content])?;
350 let vector = vectors.pop().ok_or_else(|| {
351 MnemoError::Invalid("embedder returned no vector for the input text".into())
352 })?;
353 if vector.len() != self.dimensions {
354 return Err(MnemoError::DimensionMismatch {
355 expected: self.dimensions,
356 got: vector.len(),
357 });
358 }
359 let memory = Memory::new(content.to_string(), memory_type, vector);
360 self.remember_keyed_superseding(memory, key, supersedes)
361 }
362
363 pub fn remember_keyed_text(
366 &mut self,
367 content: &str,
368 memory_type: MemoryType,
369 key: &str,
370 ) -> Result<(Ulid, WriteOutcome)> {
371 if self.read_only {
372 return Err(MnemoError::ReadOnly);
373 }
374 let embedder = self.embedder.as_ref().ok_or_else(|| {
375 MnemoError::Invalid(
376 "no embedder registered on this handle; call set_embedder first".into(),
377 )
378 })?;
379 let mut vectors = embedder.embed(&[content])?;
380 let vector = vectors.pop().ok_or_else(|| {
381 MnemoError::Invalid("embedder returned no vector for the input text".into())
382 })?;
383 if vector.len() != self.dimensions {
384 return Err(MnemoError::DimensionMismatch {
385 expected: self.dimensions,
386 got: vector.len(),
387 });
388 }
389 let memory = Memory::new(content.to_string(), memory_type, vector);
390 self.remember_keyed(memory, key)
391 }
392
393 pub fn update(&mut self, id: &Ulid, patch: MemoryPatch) -> Result<WriteOutcome> {
409 if let Some(m) = patch.metadata.as_ref() {
410 check_caller_reserved(m)?;
411 }
412 if let Some(m) = patch.caller_keys.as_ref() {
413 for (k, v) in m {
414 if !is_caller_key(k) {
415 return Err(super::crud::reserved_key_error(k));
416 }
417 if !v.is_null() {
418 crate::memory::check_caller_key(k, v).map_err(MnemoError::Invalid)?;
419 }
420 }
421 }
422 self.update_unchecked(id, patch)
423 }
424
425 pub(super) fn update_unchecked(
428 &mut self,
429 id: &Ulid,
430 patch: MemoryPatch,
431 ) -> Result<WriteOutcome> {
432 if self.read_only {
433 return Err(MnemoError::ReadOnly);
434 }
435 if patch.content.is_some() && patch.vector.is_none() {
436 return Err(MnemoError::Invalid(
437 "update: a content change needs a matching vector (or call update_text \
438 to re-embed through the registered embedder)"
439 .into(),
440 ));
441 }
442 let idx = self
443 .index
444 .get(id.0, &self.catalog)
445 .ok_or_else(|| MnemoError::NotFound(id.to_string()))?;
446 if self.catalog[idx].deleted {
447 return Err(MnemoError::NotFound(id.to_string()));
448 }
449 let entry = self.catalog[idx].clone();
450 let existing = self.read_memory(&entry)?;
451
452 let mut cand = existing.clone();
454 if let Some(c) = &patch.content {
455 cand.content = c.clone();
456 }
457 if let Some(v) = &patch.vector {
458 if v.len() != self.dimensions {
459 return Err(MnemoError::DimensionMismatch {
460 expected: self.dimensions,
461 got: v.len(),
462 });
463 }
464 cand.vector = v.clone();
465 }
466 if let Some(i) = patch.importance {
467 cand.importance = i.clamp(0.0, 1.0);
468 }
469 if let Some(mt) = patch.memory_type {
470 cand.memory_type = mt;
471 }
472 if let Some(new_meta) = patch.metadata {
473 let reserved: Vec<(String, Value)> = existing
477 .metadata
478 .iter()
479 .filter(|(k, _)| k.starts_with(crate::memory::MNEMO_META_NS))
480 .filter(|(k, _)| !(is_caller_key(k) && new_meta.contains_key(k.as_str())))
481 .map(|(k, v)| (k.clone(), v.clone()))
482 .collect();
483 cand.metadata = new_meta;
484 for (k, v) in reserved {
485 cand.metadata.insert(k, v);
486 }
487 }
488 if let Some(keys) = patch.caller_keys {
489 for (k, v) in keys {
490 if v.is_null() {
491 cand.metadata.remove(&k);
492 } else {
493 cand.metadata.insert(k, v);
494 }
495 }
496 }
497 if let Some(ttl) = patch.ttl_secs {
498 cand.ttl_secs = ttl;
499 }
500
501 if cand.content == existing.content
503 && cand.vector == existing.vector
504 && (cand.importance - existing.importance).abs() <= f32::EPSILON
505 && cand.memory_type == existing.memory_type
506 && cand.metadata == existing.metadata
507 && cand.ttl_secs == existing.ttl_secs
508 {
509 return Ok(WriteOutcome::Unchanged);
510 }
511
512 let now = memory::now_secs();
514 cand.metadata
515 .insert(MNEMO_META_UPDATED_AT.into(), Value::Number(now.into()));
516 cand.id = existing.id;
517 cand.created_at = existing.created_at;
518 self.put(cand)?;
520 Ok(WriteOutcome::Updated)
522 }
523
524 pub fn update_text(
527 &mut self,
528 id: &Ulid,
529 new_text: &str,
530 mut patch: MemoryPatch,
531 ) -> Result<WriteOutcome> {
532 if self.read_only {
533 return Err(MnemoError::ReadOnly);
534 }
535 let embedder = self.embedder.as_ref().ok_or_else(|| {
536 MnemoError::Invalid(
537 "no embedder registered on this handle; call set_embedder first".into(),
538 )
539 })?;
540 let mut vectors = embedder.embed(&[new_text])?;
541 let vector = vectors.pop().ok_or_else(|| {
542 MnemoError::Invalid("embedder returned no vector for the input text".into())
543 })?;
544 if vector.len() != self.dimensions {
545 return Err(MnemoError::DimensionMismatch {
546 expected: self.dimensions,
547 got: vector.len(),
548 });
549 }
550 patch.content = Some(new_text.to_string());
551 patch.vector = Some(vector);
552 self.update(id, patch)
553 }
554
555 pub fn history(&mut self, key: &str, agent_id: Option<&str>) -> Result<Vec<Memory>> {
577 let scope = match agent_id {
578 Some(a) => KeyScope::Private(a.to_string()),
579 None => KeyScope::private_default(),
580 };
581 self.history_in(key, scope)
582 }
583
584 pub fn history_in(&mut self, key: &str, scope: KeyScope) -> Result<Vec<Memory>> {
591 self.ensure_key_caches()?;
592 let slot = crate::store::KeySlot {
593 scope_owner: match scope {
594 KeyScope::Private(a) => Some(a),
595 KeyScope::Shared => None,
596 },
597 key: key.to_string(),
598 };
599 let live_id = self.key_index.as_ref().and_then(|k| k.get(&slot).copied());
600 let mut out = Vec::new();
601 let mut cursor = live_id;
602 while let Some(id_u) = cursor {
603 let idx = self.index.get(id_u, &self.catalog).ok_or_else(|| {
604 MnemoError::Invalid("history: superseded chain references missing id".into())
605 })?;
606 let entry = self.catalog[idx].clone();
607 if entry.deleted {
608 break;
609 }
610 let m = self.read_memory(&entry)?;
611 let next = m
612 .metadata
613 .get(MNEMO_META_SUPERSEDES)
614 .and_then(|v| v.as_str())
615 .and_then(|s| Ulid::from_string(s).ok())
616 .map(|u| u.0);
617 out.push(m);
618 cursor = next;
619 }
620 Ok(out)
621 }
622
623 }
625
626fn inherit_levels(new: &mut Memory, prev: &Memory) {
630 for k in [
631 crate::memory::MNEMO_META_VISIBILITY,
632 crate::memory::MNEMO_META_REVIEW_BY,
633 ] {
634 if !new.metadata.contains_key(k) {
635 if let Some(v) = prev.metadata.get(k) {
636 new.metadata.insert(k.into(), v.clone());
637 }
638 }
639 }
640}
641
642impl Mnemo {
643 pub fn superseded_level_change(&mut self, id: &Ulid) -> Result<Option<(String, String)>> {
647 let new = self.get(id)?;
648 let Some(old) = new
649 .metadata
650 .get(MNEMO_META_SUPERSEDES)
651 .and_then(Value::as_str)
652 .and_then(|s| Ulid::from_string(s).ok())
653 else {
654 return Ok(None);
655 };
656 let old = self.get(&old)?;
657 let (a, b) = (
658 crate::memory::visibility_of(&old).to_string(),
659 crate::memory::visibility_of(&new).to_string(),
660 );
661 Ok((a != b).then_some((a, b)))
662 }
663}