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<()> {
270 if self.read_only {
271 return Err(MnemoError::ReadOnly);
272 }
273 self.load_essence_record(id)?;
274 self.delete(id)
275 }
276
277 pub fn essence(&mut self, scope: EssenceScope, max_bytes: usize) -> Result<String> {
289 let max_bytes = if max_bytes == 0 {
290 ESSENCE_DEFAULT_RENDER_BYTES
291 } else {
292 max_bytes
293 };
294 let entries = self.essence_entries()?;
297 let now = memory::now_secs();
298 let mut by_section: std::collections::BTreeMap<&'static str, Vec<Memory>> =
299 std::collections::BTreeMap::new();
300 for section in EssenceSection::render_order() {
301 by_section.insert(section.as_str(), Vec::new());
302 }
303 for e in &entries {
304 let m = self.read_memory(e)?;
305 if m.metadata.get(MNEMO_META_KIND).and_then(|v| v.as_str())
306 != Some(MNEMO_META_KIND_ESSENCE)
307 {
308 continue;
309 }
310 let rec_thread = m.metadata.get(MNEMO_META_THREAD).and_then(|v| v.as_str());
314 let matches_scope = match (&scope, rec_thread) {
315 (EssenceScope::Project, None) => true,
316 (EssenceScope::Thread(_), None) => true, (EssenceScope::Thread(t), Some(rt)) => rt == t,
318 (EssenceScope::Project, Some(_)) => false,
319 };
320 if !matches_scope {
321 continue;
322 }
323 if !crate::memory::VisibilitySet::DEFAULT.shows(&m) {
325 continue;
326 }
327 let section_str = m
328 .metadata
329 .get(MNEMO_META_SECTION)
330 .and_then(|v| v.as_str())
331 .unwrap_or("timeline");
332 by_section
333 .entry(
334 EssenceSection::parse(section_str)
335 .map(|s| s.as_str())
336 .unwrap_or("timeline"),
337 )
338 .or_default()
339 .push(m);
340 }
341
342 for (name, items) in by_section.iter_mut() {
347 let newest_first = matches!(*name, "decisions" | "timeline");
348 items.sort_by(|a, b| {
349 let a_resolved = status_of(a) == Some(essence_status::RESOLVED);
350 let b_resolved = status_of(b) == Some(essence_status::RESOLVED);
351 match (a_resolved, b_resolved) {
352 (false, true) => std::cmp::Ordering::Less,
353 (true, false) => std::cmp::Ordering::Greater,
354 _ => {
355 if newest_first {
356 b.created_at.cmp(&a.created_at)
357 } else {
358 a.created_at.cmp(&b.created_at)
359 }
360 }
361 }
362 });
363 }
364
365 let header_reserve = 256usize; let body_budget = max_bytes.saturating_sub(header_reserve);
371 let per_section_budget = |section: EssenceSection| -> usize {
372 match section {
373 EssenceSection::Intent => body_budget / 8,
374 EssenceSection::Conventions => body_budget / 6,
375 EssenceSection::Decisions => body_budget / 4,
376 EssenceSection::State => body_budget / 8,
377 EssenceSection::Open => body_budget / 8,
378 EssenceSection::Next => body_budget / 12,
379 EssenceSection::Lessons => body_budget / 12,
380 EssenceSection::Timeline => body_budget / 4,
381 }
382 };
383
384 let mut out = String::with_capacity(max_bytes);
385 let scope_label = match &scope {
386 EssenceScope::Thread(t) => format!("thread `{t}`"),
387 EssenceScope::Project => "project".to_string(),
388 };
389 out.push_str(&format!("# essence — {scope_label}\n\n"));
390
391 if let EssenceScope::Thread(new_id) = &scope {
396 if let Some(prev_id) = self.predecessor_thread(new_id)? {
397 let continuation = self
398 .render_continuation_prelude(&prev_id, max_bytes.saturating_sub(out.len()))?;
399 if !continuation.is_empty() && out.len() + continuation.len() <= max_bytes {
400 out.push_str(&continuation);
401 }
402 }
403 }
404
405 for section in EssenceSection::render_order() {
406 let items = match by_section.get(section.as_str()) {
407 Some(v) if !v.is_empty() => v,
408 _ => continue,
409 };
410 let budget = per_section_budget(*section);
411 let section_header = format!("## {}\n", section.as_str());
412 if out.len() + section_header.len() > max_bytes {
413 break;
414 }
415 out.push_str(§ion_header);
416 let mut used = 0usize;
417 let mut rendered = 0usize;
418 for item in items {
419 let line = render_essence_item(*section, item, now);
420 if used + line.len() > budget {
421 break;
422 }
423 if out.len() + line.len() > max_bytes {
424 break;
425 }
426 out.push_str(&line);
427 used += line.len();
428 rendered += 1;
429 }
430 if *section == EssenceSection::Timeline && rendered < items.len() {
432 let fold = format!("- +{} earlier milestones\n", items.len() - rendered);
433 if out.len() + fold.len() <= max_bytes {
434 out.push_str(&fold);
435 }
436 }
437 if out.len() < max_bytes {
438 out.push('\n');
439 }
440 }
441
442 let pointer = match &scope {
444 EssenceScope::Thread(t) => format!(
445 "> full history: `mnemo thread export <file> --thread {t}` or `recall --thread {t}`\n"
446 ),
447 EssenceScope::Project => String::from(
448 "> full history: `mnemo thread export <file> --thread <id>` or `recall --thread <id>`\n",
449 ),
450 };
451 if out.len() + pointer.len() <= max_bytes {
452 out.push_str(&pointer);
453 }
454 Ok(out)
455 }
456
457 pub(super) fn build_essence_record(
466 &self,
467 scope: EssenceScope,
468 section: EssenceSection,
469 text: &str,
470 refs: Option<Vec<String>>,
471 status_at: Option<i64>,
472 vector: Option<Vec<f32>>,
473 ) -> Result<Memory> {
474 let v = match (vector, self.embedder.as_ref()) {
475 (Some(v), _) => v,
476 (None, Some(e)) => e.embed(&[text])?.pop().ok_or_else(|| {
477 MnemoError::Invalid("essence: embedder returned no vector".into())
478 })?,
479 (None, None) => self.sentinel_vector(),
480 };
481 let mut m = Memory::new(text.to_string(), MemoryType::Semantic, v).with_importance(0.5);
482 m.metadata.insert(
483 MNEMO_META_KIND.into(),
484 Value::String(MNEMO_META_KIND_ESSENCE.into()),
485 );
486 m.metadata.insert(
487 MNEMO_META_SECTION.into(),
488 Value::String(section.as_str().into()),
489 );
490 if let EssenceScope::Thread(t) = &scope {
491 m.metadata
492 .insert(MNEMO_META_THREAD.into(), Value::String(t.clone()));
493 }
494 if let Some(r) = refs {
495 m.metadata.insert(
496 MNEMO_META_REFS.into(),
497 Value::Array(r.into_iter().map(Value::String).collect()),
498 );
499 }
500 if let Some(at) = status_at {
501 m.metadata.insert(
502 MNEMO_META_STATUS.into(),
503 Value::String(essence_status::OPEN.into()),
504 );
505 m.metadata.insert(
506 MNEMO_META_STATUS_HISTORY.into(),
507 Value::Array(vec![serde_json::json!({
508 "status": essence_status::OPEN,
509 "at": at,
510 })]),
511 );
512 }
513 Ok(m)
514 }
515
516 pub(super) fn sentinel_vector(&self) -> Vec<f32> {
519 let dims = self.dimensions.max(1);
520 vec![1.0 / (dims as f32).sqrt(); dims]
521 }
522
523 pub(super) fn load_essence_record(&mut self, id: &Ulid) -> Result<Memory> {
524 let m = self.get(id)?;
525 if m.metadata.get(MNEMO_META_KIND).and_then(|v| v.as_str()) != Some(MNEMO_META_KIND_ESSENCE)
526 {
527 return Err(MnemoError::Invalid(format!(
528 "essence: record {id} is not an essence record (missing `_mnemo.kind = essence`)"
529 )));
530 }
531 Ok(m)
532 }
533
534 pub(super) fn section_of(&self, m: &Memory) -> Result<EssenceSection> {
535 let s = m
536 .metadata
537 .get(MNEMO_META_SECTION)
538 .and_then(|v| v.as_str())
539 .ok_or_else(|| {
540 MnemoError::Invalid("essence: record missing `_mnemo.section`".into())
541 })?;
542 EssenceSection::parse(s)
543 .ok_or_else(|| MnemoError::Invalid(format!("essence: unknown section '{s}' on record")))
544 }
545
546 pub(super) fn essence_transition_status(
547 &mut self,
548 id: &Ulid,
549 to: &str,
550 ) -> Result<WriteOutcome> {
551 if self.read_only {
552 return Err(MnemoError::ReadOnly);
553 }
554 let existing = self.load_essence_record(id)?;
555 let section = self.section_of(&existing)?;
556 if !section.has_status_lifecycle() {
557 return Err(MnemoError::Invalid(format!(
558 "essence_transition: '{}' section has no status lifecycle",
559 section.as_str()
560 )));
561 }
562 let from = existing
563 .metadata
564 .get(MNEMO_META_STATUS)
565 .and_then(|v| v.as_str())
566 .unwrap_or(essence_status::OPEN);
567 if from == to {
568 return Ok(WriteOutcome::Unchanged);
569 }
570 let allowed = ESSENCE_TRANSITIONS
571 .iter()
572 .any(|(f, t)| *f == from && *t == to);
573 if !allowed {
574 return Err(MnemoError::Invalid(format!(
575 "essence_transition: '{from}' → '{to}' is not a valid transition for essence"
576 )));
577 }
578 let mut new = existing.clone();
582 new.metadata
583 .insert(MNEMO_META_STATUS.into(), Value::String(to.to_string()));
584 let now = memory::now_secs();
585 let history_entry = serde_json::json!({ "status": to, "at": now });
586 let history = new
587 .metadata
588 .entry(MNEMO_META_STATUS_HISTORY.to_string())
589 .or_insert_with(|| Value::Array(Vec::new()));
590 if let Value::Array(arr) = history {
591 arr.push(history_entry);
592 }
593 new.metadata
594 .insert(MNEMO_META_UPDATED_AT.into(), Value::Number(now.into()));
595 new.id = existing.id;
596 new.created_at = existing.created_at;
597 self.put(new)?;
598 Ok(WriteOutcome::Updated)
599 }
600
601 }