1use super::*;
4
5pub(super) fn status_of(m: &Memory) -> Option<&str> {
12 m.metadata.get(MNEMO_META_STATUS).and_then(|v| v.as_str())
13}
14
15fn render_essence_item(section: EssenceSection, m: &Memory, now: i64) -> String {
19 if section == EssenceSection::Timeline {
20 let date = format_unix_date(m.created_at);
21 format!("- [{date}] {}\n", m.content)
22 } else {
23 let status = status_of(m).unwrap_or(essence_status::OPEN);
24 let stale = crate::memory::stale_since(m, now)
26 .map(|t| format!(" [stale since {}]", format_unix_date(t)))
27 .unwrap_or_default();
28 format!("- [{status}] {}{stale}\n", m.content)
29 }
30}
31
32pub(crate) fn format_unix_date(secs: i64) -> String {
35 let days_total = secs.div_euclid(86_400);
36 let (y, m, d) = civil_from_days(days_total);
37 format!("{y:04}-{m:02}-{d:02}")
38}
39
40fn civil_from_days(z: i64) -> (i64, u32, u32) {
44 let z = z + 719_468;
45 let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
46 let doe = (z - era * 146_097) as u64;
47 let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
48 let y = yoe as i64 + era * 400;
49 let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
50 let mp = (5 * doy + 2) / 153;
51 let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
52 let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
53 let y = if m <= 2 { y + 1 } else { y };
54 (y, m, d)
55}
56
57impl Mnemo {
58 pub fn essence_add(
67 &mut self,
68 scope: EssenceScope,
69 section: EssenceSection,
70 text: &str,
71 refs: Option<Vec<String>>,
72 ) -> Result<Ulid> {
73 if self.read_only {
74 return Err(MnemoError::ReadOnly);
75 }
76 Self::check_essence_add(section, text)?;
77 self.essence_add_with(scope, section, text, refs, None)
78 }
79
80 pub fn essence_add_with_vector(
85 &mut self,
86 scope: EssenceScope,
87 section: EssenceSection,
88 text: &str,
89 refs: Option<Vec<String>>,
90 vector: Vec<f32>,
91 ) -> Result<Ulid> {
92 if self.read_only {
93 return Err(MnemoError::ReadOnly);
94 }
95 Self::check_essence_add(section, text)?;
96 self.essence_add_with(scope, section, text, refs, Some(vector))
97 }
98
99 pub(super) fn check_essence_add(section: EssenceSection, text: &str) -> Result<()> {
101 if section == EssenceSection::Timeline {
102 return Err(MnemoError::Invalid(
103 "essence_add: use essence_append_timeline for the timeline section".into(),
104 ));
105 }
106 if text.is_empty() {
107 return Err(MnemoError::Invalid(
108 "essence_add: text must not be empty".into(),
109 ));
110 }
111 if text.len() > section.item_max_bytes() {
112 return Err(MnemoError::Invalid(format!(
113 "essence_add: '{}' items must be <= {} bytes; got {}",
114 section.as_str(),
115 section.item_max_bytes(),
116 text.len()
117 )));
118 }
119 Ok(())
120 }
121
122 pub(super) fn essence_add_with(
124 &mut self,
125 scope: EssenceScope,
126 section: EssenceSection,
127 text: &str,
128 refs: Option<Vec<String>>,
129 vector: Option<Vec<f32>>,
130 ) -> Result<Ulid> {
131 let now = memory::now_secs();
132 let mem = self.build_essence_record(scope, section, text, refs, Some(now), vector)?;
133 self.put(mem)
134 }
135
136 pub fn essence_append_timeline(
141 &mut self,
142 scope: EssenceScope,
143 text: &str,
144 refs: Option<Vec<String>>,
145 ) -> Result<Ulid> {
146 if self.read_only {
147 return Err(MnemoError::ReadOnly);
148 }
149 Self::check_essence_append(text)?;
150 self.essence_append_with(scope, text, refs, None)
151 }
152
153 pub fn essence_append_timeline_with_vector(
156 &mut self,
157 scope: EssenceScope,
158 text: &str,
159 refs: Option<Vec<String>>,
160 vector: Vec<f32>,
161 ) -> Result<Ulid> {
162 if self.read_only {
163 return Err(MnemoError::ReadOnly);
164 }
165 Self::check_essence_append(text)?;
166 self.essence_append_with(scope, text, refs, Some(vector))
167 }
168
169 pub(super) fn check_essence_append(text: &str) -> Result<()> {
172 if text.is_empty() {
173 return Err(MnemoError::Invalid(
174 "essence_append_timeline: text must not be empty".into(),
175 ));
176 }
177 if text.len() > EssenceSection::Timeline.item_max_bytes() {
178 return Err(MnemoError::Invalid(format!(
179 "essence_append_timeline: entries must be <= {} bytes; got {}",
180 EssenceSection::Timeline.item_max_bytes(),
181 text.len()
182 )));
183 }
184 Ok(())
185 }
186
187 pub(super) fn essence_append_with(
190 &mut self,
191 scope: EssenceScope,
192 text: &str,
193 refs: Option<Vec<String>>,
194 vector: Option<Vec<f32>>,
195 ) -> Result<Ulid> {
196 let mem =
197 self.build_essence_record(scope, EssenceSection::Timeline, text, refs, None, vector)?;
198 self.put(mem)
199 }
200
201 pub fn essence_update(
206 &mut self,
207 id: &Ulid,
208 text: &str,
209 refs: Option<Vec<String>>,
210 ) -> Result<WriteOutcome> {
211 if self.read_only {
212 return Err(MnemoError::ReadOnly);
213 }
214 let existing = self.load_essence_record(id)?;
215 let section = self.section_of(&existing)?;
216 if section == EssenceSection::Timeline {
217 return Err(MnemoError::Invalid(
218 "essence_update: timeline entries are append-only; append a new one instead".into(),
219 ));
220 }
221 if text.is_empty() {
222 return Err(MnemoError::Invalid(
223 "essence_update: text must not be empty".into(),
224 ));
225 }
226 if text.len() > section.item_max_bytes() {
227 return Err(MnemoError::Invalid(format!(
228 "essence_update: '{}' items must be <= {} bytes; got {}",
229 section.as_str(),
230 section.item_max_bytes(),
231 text.len()
232 )));
233 }
234 let mut patch = MemoryPatch {
235 content: Some(text.to_string()),
236 ..Default::default()
237 };
238 patch.vector = Some(existing.vector.clone());
243 if let Some(r) = refs {
244 let mut meta = Map::new();
245 meta.insert(
249 MNEMO_META_REFS.into(),
250 Value::Array(r.into_iter().map(Value::String).collect()),
251 );
252 patch.metadata = Some(meta);
253 }
254 self.update_unchecked(id, patch)
255 }
256
257 pub fn essence_resolve(&mut self, id: &Ulid) -> Result<WriteOutcome> {
262 self.essence_transition_status(id, essence_status::RESOLVED)
263 }
264
265 pub fn essence_remove(&mut self, id: &Ulid) -> Result<()> {
269 if self.read_only {
270 return Err(MnemoError::ReadOnly);
271 }
272 self.delete(id)
273 }
274
275 pub fn essence(&mut self, scope: EssenceScope, max_bytes: usize) -> Result<String> {
287 let max_bytes = if max_bytes == 0 {
288 ESSENCE_DEFAULT_RENDER_BYTES
289 } else {
290 max_bytes
291 };
292 let entries = self.essence_entries()?;
295 let now = memory::now_secs();
296 let mut by_section: std::collections::BTreeMap<&'static str, Vec<Memory>> =
297 std::collections::BTreeMap::new();
298 for section in EssenceSection::render_order() {
299 by_section.insert(section.as_str(), Vec::new());
300 }
301 for e in &entries {
302 let m = self.read_memory(e)?;
303 if m.metadata.get(MNEMO_META_KIND).and_then(|v| v.as_str())
304 != Some(MNEMO_META_KIND_ESSENCE)
305 {
306 continue;
307 }
308 let rec_thread = m.metadata.get(MNEMO_META_THREAD).and_then(|v| v.as_str());
312 let matches_scope = match (&scope, rec_thread) {
313 (EssenceScope::Project, None) => true,
314 (EssenceScope::Thread(_), None) => true, (EssenceScope::Thread(t), Some(rt)) => rt == t,
316 (EssenceScope::Project, Some(_)) => false,
317 };
318 if !matches_scope {
319 continue;
320 }
321 if !crate::memory::VisibilitySet::DEFAULT.shows(&m) {
323 continue;
324 }
325 let section_str = m
326 .metadata
327 .get(MNEMO_META_SECTION)
328 .and_then(|v| v.as_str())
329 .unwrap_or("timeline");
330 by_section
331 .entry(
332 EssenceSection::parse(section_str)
333 .map(|s| s.as_str())
334 .unwrap_or("timeline"),
335 )
336 .or_default()
337 .push(m);
338 }
339
340 for (name, items) in by_section.iter_mut() {
345 let newest_first = matches!(*name, "decisions" | "timeline");
346 items.sort_by(|a, b| {
347 let a_resolved = status_of(a) == Some(essence_status::RESOLVED);
348 let b_resolved = status_of(b) == Some(essence_status::RESOLVED);
349 match (a_resolved, b_resolved) {
350 (false, true) => std::cmp::Ordering::Less,
351 (true, false) => std::cmp::Ordering::Greater,
352 _ => {
353 if newest_first {
354 b.created_at.cmp(&a.created_at)
355 } else {
356 a.created_at.cmp(&b.created_at)
357 }
358 }
359 }
360 });
361 }
362
363 let header_reserve = 256usize; let body_budget = max_bytes.saturating_sub(header_reserve);
369 let per_section_budget = |section: EssenceSection| -> usize {
370 match section {
371 EssenceSection::Intent => body_budget / 8,
372 EssenceSection::Conventions => body_budget / 6,
373 EssenceSection::Decisions => body_budget / 4,
374 EssenceSection::State => body_budget / 8,
375 EssenceSection::Open => body_budget / 8,
376 EssenceSection::Next => body_budget / 12,
377 EssenceSection::Lessons => body_budget / 12,
378 EssenceSection::Timeline => body_budget / 4,
379 }
380 };
381
382 let mut out = String::with_capacity(max_bytes);
383 let scope_label = match &scope {
384 EssenceScope::Thread(t) => format!("thread `{t}`"),
385 EssenceScope::Project => "project".to_string(),
386 };
387 out.push_str(&format!("# essence — {scope_label}\n\n"));
388
389 if let EssenceScope::Thread(new_id) = &scope {
394 if let Some(prev_id) = self.predecessor_thread(new_id)? {
395 let continuation = self
396 .render_continuation_prelude(&prev_id, max_bytes.saturating_sub(out.len()))?;
397 if !continuation.is_empty() && out.len() + continuation.len() <= max_bytes {
398 out.push_str(&continuation);
399 }
400 }
401 }
402
403 for section in EssenceSection::render_order() {
404 let items = match by_section.get(section.as_str()) {
405 Some(v) if !v.is_empty() => v,
406 _ => continue,
407 };
408 let budget = per_section_budget(*section);
409 let section_header = format!("## {}\n", section.as_str());
410 if out.len() + section_header.len() > max_bytes {
411 break;
412 }
413 out.push_str(§ion_header);
414 let mut used = 0usize;
415 let mut rendered = 0usize;
416 for item in items {
417 let line = render_essence_item(*section, item, now);
418 if used + line.len() > budget {
419 break;
420 }
421 if out.len() + line.len() > max_bytes {
422 break;
423 }
424 out.push_str(&line);
425 used += line.len();
426 rendered += 1;
427 }
428 if *section == EssenceSection::Timeline && rendered < items.len() {
430 let fold = format!("- +{} earlier milestones\n", items.len() - rendered);
431 if out.len() + fold.len() <= max_bytes {
432 out.push_str(&fold);
433 }
434 }
435 if out.len() < max_bytes {
436 out.push('\n');
437 }
438 }
439
440 let pointer = match &scope {
442 EssenceScope::Thread(t) => format!(
443 "> full history: `mnemo thread export <file> --thread {t}` or `recall --thread {t}`\n"
444 ),
445 EssenceScope::Project => String::from(
446 "> full history: `mnemo thread export <file> --thread <id>` or `recall --thread <id>`\n",
447 ),
448 };
449 if out.len() + pointer.len() <= max_bytes {
450 out.push_str(&pointer);
451 }
452 Ok(out)
453 }
454
455 pub(super) fn build_essence_record(
464 &self,
465 scope: EssenceScope,
466 section: EssenceSection,
467 text: &str,
468 refs: Option<Vec<String>>,
469 status_at: Option<i64>,
470 vector: Option<Vec<f32>>,
471 ) -> Result<Memory> {
472 let v = match (vector, self.embedder.as_ref()) {
473 (Some(v), _) => v,
474 (None, Some(e)) => e.embed(&[text])?.pop().ok_or_else(|| {
475 MnemoError::Invalid("essence: embedder returned no vector".into())
476 })?,
477 (None, None) => self.sentinel_vector(),
478 };
479 let mut m = Memory::new(text.to_string(), MemoryType::Semantic, v).with_importance(0.5);
480 m.metadata.insert(
481 MNEMO_META_KIND.into(),
482 Value::String(MNEMO_META_KIND_ESSENCE.into()),
483 );
484 m.metadata.insert(
485 MNEMO_META_SECTION.into(),
486 Value::String(section.as_str().into()),
487 );
488 if let EssenceScope::Thread(t) = &scope {
489 m.metadata
490 .insert(MNEMO_META_THREAD.into(), Value::String(t.clone()));
491 }
492 if let Some(r) = refs {
493 m.metadata.insert(
494 MNEMO_META_REFS.into(),
495 Value::Array(r.into_iter().map(Value::String).collect()),
496 );
497 }
498 if let Some(at) = status_at {
499 m.metadata.insert(
500 MNEMO_META_STATUS.into(),
501 Value::String(essence_status::OPEN.into()),
502 );
503 m.metadata.insert(
504 MNEMO_META_STATUS_HISTORY.into(),
505 Value::Array(vec![serde_json::json!({
506 "status": essence_status::OPEN,
507 "at": at,
508 })]),
509 );
510 }
511 Ok(m)
512 }
513
514 pub(super) fn sentinel_vector(&self) -> Vec<f32> {
517 let dims = self.dimensions.max(1);
518 vec![1.0 / (dims as f32).sqrt(); dims]
519 }
520
521 pub(super) fn load_essence_record(&mut self, id: &Ulid) -> Result<Memory> {
522 let m = self.get(id)?;
523 if m.metadata.get(MNEMO_META_KIND).and_then(|v| v.as_str()) != Some(MNEMO_META_KIND_ESSENCE)
524 {
525 return Err(MnemoError::Invalid(format!(
526 "essence: record {id} is not an essence record (missing `_mnemo.kind = essence`)"
527 )));
528 }
529 Ok(m)
530 }
531
532 pub(super) fn section_of(&self, m: &Memory) -> Result<EssenceSection> {
533 let s = m
534 .metadata
535 .get(MNEMO_META_SECTION)
536 .and_then(|v| v.as_str())
537 .ok_or_else(|| {
538 MnemoError::Invalid("essence: record missing `_mnemo.section`".into())
539 })?;
540 EssenceSection::parse(s)
541 .ok_or_else(|| MnemoError::Invalid(format!("essence: unknown section '{s}' on record")))
542 }
543
544 pub(super) fn essence_transition_status(
545 &mut self,
546 id: &Ulid,
547 to: &str,
548 ) -> Result<WriteOutcome> {
549 if self.read_only {
550 return Err(MnemoError::ReadOnly);
551 }
552 let existing = self.load_essence_record(id)?;
553 let section = self.section_of(&existing)?;
554 if !section.has_status_lifecycle() {
555 return Err(MnemoError::Invalid(format!(
556 "essence_transition: '{}' section has no status lifecycle",
557 section.as_str()
558 )));
559 }
560 let from = existing
561 .metadata
562 .get(MNEMO_META_STATUS)
563 .and_then(|v| v.as_str())
564 .unwrap_or(essence_status::OPEN);
565 if from == to {
566 return Ok(WriteOutcome::Unchanged);
567 }
568 let allowed = ESSENCE_TRANSITIONS
569 .iter()
570 .any(|(f, t)| *f == from && *t == to);
571 if !allowed {
572 return Err(MnemoError::Invalid(format!(
573 "essence_transition: '{from}' → '{to}' is not a valid transition for essence"
574 )));
575 }
576 let mut new = existing.clone();
580 new.metadata
581 .insert(MNEMO_META_STATUS.into(), Value::String(to.to_string()));
582 let now = memory::now_secs();
583 let history_entry = serde_json::json!({ "status": to, "at": now });
584 let history = new
585 .metadata
586 .entry(MNEMO_META_STATUS_HISTORY.to_string())
587 .or_insert_with(|| Value::Array(Vec::new()));
588 if let Value::Array(arr) = history {
589 arr.push(history_entry);
590 }
591 new.metadata
592 .insert(MNEMO_META_UPDATED_AT.into(), Value::Number(now.into()));
593 new.id = existing.id;
594 new.created_at = existing.created_at;
595 self.put(new)?;
596 Ok(WriteOutcome::Updated)
597 }
598
599 }