Skip to main content

second_brain_core/
digest.rs

1use std::collections::{BTreeMap, HashMap, HashSet};
2
3use chrono::{DateTime, Duration, Utc};
4use serde::{Deserialize, Serialize};
5use uuid::Uuid;
6
7use crate::schema::{Conversation, Memory};
8use crate::sqlite_store::{AgentNote, NoteKind, SqliteStore};
9
10pub const DEFAULT_WINDOW: &str = "24h";
11
12pub const MAX_ITEMS_PER_SECTION: usize = 5;
13
14const MAX_WINDOW_MINUTES: i64 = 3652 * 24 * 60;
15
16const NO_PROJECT: &str = "(no project)";
17
18const TIME_FORMAT: &str = "%Y-%m-%d %H:%M";
19
20#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
21pub struct Window {
22    pub since: DateTime<Utc>,
23    pub until: DateTime<Utc>,
24}
25
26impl Window {
27    /// The span `text` names (`90m`, `24h`, `7d`) ending at `until`.
28    pub fn parse(text: &str, until: DateTime<Utc>) -> Result<Window, String> {
29        let text = text.trim();
30        let invalid = || {
31            format!(
32                "invalid window '{text}': give a whole number of minutes, hours or days \
33                 up to ten years, like 90m, 24h or 7d"
34            )
35        };
36        let mut chars = text.chars();
37        let minutes_per_unit = match chars.next_back() {
38            Some('m') => 1,
39            Some('h') => 60,
40            Some('d') => 24 * 60,
41            _ => return Err(invalid()),
42        };
43        let count = chars.as_str();
44        if count.is_empty() || !count.bytes().all(|b| b.is_ascii_digit()) {
45            return Err(invalid());
46        }
47        let minutes = count
48            .parse::<i64>()
49            .ok()
50            .and_then(|count| count.checked_mul(minutes_per_unit))
51            .filter(|minutes| (1..=MAX_WINDOW_MINUTES).contains(minutes))
52            .ok_or_else(invalid)?;
53        Ok(Window {
54            since: until - Duration::minutes(minutes),
55            until,
56        })
57    }
58
59    fn describe(&self) -> String {
60        format!(
61            "{} to {} UTC",
62            self.since.format(TIME_FORMAT),
63            self.until.format(TIME_FORMAT)
64        )
65    }
66}
67
68#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
69#[non_exhaustive]
70pub struct DigestItem {
71    pub text: String,
72    #[serde(default, skip_serializing_if = "String::is_empty")]
73    pub reason: String,
74    /// How many notes said it; duplicates are merged into one item.
75    pub count: usize,
76}
77
78#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
79#[non_exhaustive]
80pub struct DigestSection {
81    pub items: Vec<DigestItem>,
82    /// Items past `MAX_ITEMS_PER_SECTION`, left out.
83    pub omitted: usize,
84}
85
86#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
87#[non_exhaustive]
88pub struct ProjectDigest {
89    pub project: Option<String>,
90    pub noted_sessions: usize,
91    pub unnoted_sessions: usize,
92    pub decided: DigestSection,
93    pub abandoned: DigestSection,
94    pub blocked_on_user: DigestSection,
95}
96
97/// What agents recorded in their notes over a window, per project, and how
98/// many sessions in it have none.
99#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
100#[non_exhaustive]
101pub struct Digest {
102    pub window: Window,
103    pub project: Option<String>,
104    pub projects: Vec<ProjectDigest>,
105}
106
107impl Digest {
108    pub fn read(
109        store: &SqliteStore,
110        window: Window,
111        project: Option<&str>,
112    ) -> anyhow::Result<Digest> {
113        let notes = store.notes_created_between(window.since, window.until, project)?;
114        let noted: HashSet<Uuid> = store
115            .noted_session_ids()?
116            .iter()
117            .map(|session| Conversation::claude_code_id(session))
118            .collect();
119        let unnoted: Vec<Option<String>> = store
120            .claude_code_sessions_between(window.since, window.until, project)?
121            .into_iter()
122            .filter(|session| !noted.contains(&session.conversation_id))
123            .map(|session| session.project_path)
124            .collect();
125        Ok(Digest::assemble(
126            window,
127            project.map(str::to_string),
128            &notes,
129            &unnoted,
130        ))
131    }
132
133    /// `notes` newest first; `unnoted` holds the project of each session in
134    /// the window that has no note.
135    pub fn assemble(
136        window: Window,
137        project: Option<String>,
138        notes: &[(Memory, AgentNote)],
139        unnoted: &[Option<String>],
140    ) -> Digest {
141        let mut projects: BTreeMap<(bool, String), ProjectBuilder> = BTreeMap::new();
142        for (index, (memory, note)) in notes.iter().enumerate() {
143            let builder = projects
144                .entry(project_key(&memory.project_path))
145                .or_default();
146            builder.sessions.insert(&memory.source_id);
147            match note.kind {
148                NoteKind::SessionEnd | NoteKind::Decision => {
149                    builder.decided.add(&note.decision, &note.reason, index)
150                }
151                NoteKind::DeadEnd => builder.abandoned.add(&note.decision, &note.reason, index),
152                NoteKind::Fact => {}
153            }
154            for dead_end in &note.dead_ends {
155                builder.abandoned.add(dead_end, "", index);
156            }
157            for blocked in &note.blocked_on_user {
158                builder.blocked_on_user.add(blocked, "", index);
159            }
160        }
161        for project in unnoted {
162            projects.entry(project_key(project)).or_default().unnoted += 1;
163        }
164        let projects = projects
165            .into_iter()
166            .filter_map(|((unnamed, name), builder)| builder.finish((!unnamed).then_some(name)))
167            .collect();
168        Digest {
169            window,
170            project,
171            projects,
172        }
173    }
174
175    pub fn render(&self) -> String {
176        let span = self.window.describe();
177        let scope = self
178            .project
179            .as_ref()
180            .map(|project| format!(" for {project}"))
181            .unwrap_or_default();
182        if self.projects.is_empty() {
183            return format!("Nothing recorded{scope} from {span}.");
184        }
185        let mut out = format!("Agent digest{scope}, {span}");
186        for project in &self.projects {
187            out.push_str("\n\n");
188            project.render_into(&mut out);
189        }
190        out
191    }
192}
193
194impl ProjectDigest {
195    fn render_into(&self, out: &mut String) {
196        let mut counts = Vec::new();
197        if self.noted_sessions > 0 {
198            counts.push(sessions(self.noted_sessions, "with notes"));
199        }
200        if self.unnoted_sessions > 0 {
201            counts.push(sessions(self.unnoted_sessions, "without a note"));
202        }
203        out.push_str(self.project.as_deref().unwrap_or(NO_PROJECT));
204        out.push_str(": ");
205        out.push_str(&counts.join(", "));
206        for (title, section) in [
207            ("Decided", &self.decided),
208            ("Tried and abandoned", &self.abandoned),
209            ("Blocked on you", &self.blocked_on_user),
210        ] {
211            if section.items.is_empty() {
212                continue;
213            }
214            out.push_str(&format!("\n  {title}:"));
215            for item in &section.items {
216                out.push_str(&format!("\n  - {}", item.text));
217                if item.count > 1 {
218                    out.push_str(&format!(" ({} notes)", item.count));
219                }
220                if !item.reason.is_empty() {
221                    out.push_str(&format!("\n    why: {}", item.reason));
222                }
223            }
224            if section.omitted > 0 {
225                out.push_str(&format!("\n  and {} more", section.omitted));
226            }
227        }
228    }
229}
230
231fn sessions(count: usize, what: &str) -> String {
232    let noun = if count == 1 { "session" } else { "sessions" };
233    format!("{count} {noun} {what}")
234}
235
236/// Named projects sort by name and come before notes filed under none.
237fn project_key(project: &Option<String>) -> (bool, String) {
238    (project.is_none(), project.clone().unwrap_or_default())
239}
240
241/// Case, spacing and closing punctuation don't make two items different.
242fn merge_key(text: &str) -> String {
243    text.split_whitespace()
244        .collect::<Vec<_>>()
245        .join(" ")
246        .trim_end_matches(['.', '!', '?', ',', ';', ':'])
247        .trim_end()
248        .to_lowercase()
249}
250
251#[derive(Default)]
252struct SectionBuilder {
253    items: Vec<DigestItem>,
254    by_key: HashMap<String, (usize, usize)>,
255}
256
257impl SectionBuilder {
258    /// Counts each note once however often it repeats an item; the first
259    /// wording seen is kept, and the first reason given.
260    fn add(&mut self, text: &str, reason: &str, note: usize) {
261        let key = merge_key(text);
262        if key.is_empty() {
263            return;
264        }
265        match self.by_key.get_mut(&key) {
266            Some((at, last_note)) => {
267                let item = &mut self.items[*at];
268                if *last_note != note {
269                    item.count += 1;
270                    *last_note = note;
271                }
272                if item.reason.is_empty() {
273                    item.reason = reason.to_string();
274                }
275            }
276            None => {
277                self.by_key.insert(key, (self.items.len(), note));
278                self.items.push(DigestItem {
279                    text: text.to_string(),
280                    reason: reason.to_string(),
281                    count: 1,
282                });
283            }
284        }
285    }
286
287    fn finish(mut self) -> DigestSection {
288        let omitted = self.items.len().saturating_sub(MAX_ITEMS_PER_SECTION);
289        self.items.truncate(MAX_ITEMS_PER_SECTION);
290        DigestSection {
291            items: self.items,
292            omitted,
293        }
294    }
295}
296
297#[derive(Default)]
298struct ProjectBuilder<'a> {
299    sessions: HashSet<&'a str>,
300    unnoted: usize,
301    decided: SectionBuilder,
302    abandoned: SectionBuilder,
303    blocked_on_user: SectionBuilder,
304}
305
306impl ProjectBuilder<'_> {
307    /// None when the project has nothing to show: only fact notes and no
308    /// session without a note.
309    fn finish(self, project: Option<String>) -> Option<ProjectDigest> {
310        let digest = ProjectDigest {
311            project,
312            noted_sessions: self.sessions.len(),
313            unnoted_sessions: self.unnoted,
314            decided: self.decided.finish(),
315            abandoned: self.abandoned.finish(),
316            blocked_on_user: self.blocked_on_user.finish(),
317        };
318        let shows_something = digest.unnoted_sessions > 0
319            || !digest.decided.items.is_empty()
320            || !digest.abandoned.items.is_empty()
321            || !digest.blocked_on_user.items.is_empty();
322        shows_something.then_some(digest)
323    }
324}
325
326#[cfg(test)]
327mod tests {
328    use chrono::TimeZone;
329
330    use super::*;
331    use crate::schema::{AGENT_NOTE_SOURCE, Conversation, MemoryType};
332    use crate::store::Store;
333
334    fn now() -> DateTime<Utc> {
335        Utc.with_ymd_and_hms(2026, 11, 2, 8, 0, 0).unwrap()
336    }
337
338    fn hours_ago(hours: i64) -> DateTime<Utc> {
339        now() - Duration::hours(hours)
340    }
341
342    fn day() -> Window {
343        Window::parse("24h", now()).unwrap()
344    }
345
346    fn note(
347        store: &SqliteStore,
348        session: &str,
349        project: &str,
350        hours: i64,
351        note: AgentNote,
352    ) -> Memory {
353        let mut memory = Memory::new(
354            note.render(),
355            note.kind.memory_type(),
356            AGENT_NOTE_SOURCE.to_string(),
357            session.to_string(),
358        )
359        .with_project_path((!project.is_empty()).then(|| project.to_string()));
360        memory.created_at = hours_ago(hours);
361        store.store_memory(&memory).unwrap();
362        memory
363    }
364
365    fn transcript_line(store: &SqliteStore, path: &str, session: &str, project: &str, hours: i64) {
366        let mut memory = Memory::new(
367            format!("{path} {hours}"),
368            MemoryType::Episodic,
369            "claude-code".to_string(),
370            path.to_string(),
371        )
372        .with_project_path(Some(project.to_string()));
373        memory.conversation_id = Some(Conversation::claude_code_id(session));
374        memory.session_at = Some(hours_ago(hours));
375        store.store_memory(&memory).unwrap();
376    }
377
378    fn strings(items: &[&str]) -> Vec<String> {
379        items.iter().map(|item| item.to_string()).collect()
380    }
381
382    fn three_projects() -> SqliteStore {
383        let store = SqliteStore::in_memory("m".to_string()).unwrap();
384
385        let mut cache = AgentNote::new(NoteKind::SessionEnd, "keep the build cache per worktree");
386        cache.reason = "a shared cache mixed crates between branches".to_string();
387        cache.dead_ends = strings(&["one shared target dir"]);
388        cache.open_items = strings(&["rerun the flaky test"]);
389        cache.blocked_on_user = strings(&["approve the signing key"]);
390        note(&store, "s1", "-srv-app", 20, cache);
391        transcript_line(&store, "/p/-srv-app/s1.jsonl", "s1", "-srv-app", 21);
392        note(
393            &store,
394            "s2",
395            "-srv-app",
396            18,
397            AgentNote::new(NoteKind::Decision, "Keep the build  cache per worktree."),
398        );
399        let mut raced = AgentNote::new(NoteKind::DeadEnd, "One shared target dir");
400        raced.reason = "two builds raced on it".to_string();
401        note(&store, "s2", "-srv-app", 17, raced);
402        transcript_line(&store, "/p/-srv-app/s9.jsonl", "s9", "-srv-app", 3);
403        note(
404            &store,
405            "s0",
406            "-srv-app",
407            30,
408            AgentNote::new(NoteKind::Decision, "an older decision"),
409        );
410        transcript_line(&store, "/p/-srv-app/s0.jsonl", "s0", "-srv-app", 2);
411        let retired = note(
412            &store,
413            "s8",
414            "-srv-app",
415            5,
416            AgentNote::new(NoteKind::Decision, "a retired decision"),
417        );
418        store.retire_memory(retired.id, "test").unwrap();
419
420        let mut router = AgentNote::new(NoteKind::SessionEnd, "split the router table by concern");
421        router.blocked_on_user = strings(&[
422            "pick a port",
423            "name the crate",
424            "confirm the license",
425            "review the API shape",
426            "choose a release date",
427            "approve the CI secret",
428            "sign off the docs",
429        ]);
430        note(&store, "s3", "-srv-web", 9, router);
431        note(
432            &store,
433            "s4",
434            "-srv-web",
435            8,
436            AgentNote::new(NoteKind::Fact, "the port is 7300"),
437        );
438
439        transcript_line(&store, "/p/-srv-tools/s5.jsonl", "s5", "-srv-tools", 6);
440        transcript_line(&store, "/p/-srv-tools/s6.jsonl", "s6", "-srv-tools", 4);
441        transcript_line(
442            &store,
443            "/p/-srv-tools/s6/subagents/agent-a.jsonl",
444            "s6/a",
445            "-srv-tools",
446            4,
447        );
448        transcript_line(&store, "/p/-srv-tools/s7.jsonl", "s7", "-srv-tools", 30);
449        let mut toolchain = AgentNote::new(NoteKind::SessionEnd, "pin the toolchain");
450        toolchain.blocked_on_user = strings(&["Ship on Friday?", "ship on  friday"]);
451        note(&store, "s5", "-srv-tools", 5, toolchain);
452
453        note(
454            &store,
455            "s10",
456            "",
457            7,
458            AgentNote::new(NoteKind::Decision, "retire the old sync timer"),
459        );
460        store
461    }
462
463    #[test]
464    fn notes_from_three_projects_give_the_expected_text() {
465        let store = three_projects();
466        let digest = Digest::read(&store, day(), None).unwrap();
467        assert_eq!(
468            digest.render(),
469            "Agent digest, 2026-11-01 08:00 to 2026-11-02 08:00 UTC\n\
470             \n\
471             -srv-app: 2 sessions with notes, 1 session without a note\n\
472             \x20 Decided:\n\
473             \x20 - Keep the build cache per worktree. (2 notes)\n\
474             \x20   why: a shared cache mixed crates between branches\n\
475             \x20 Tried and abandoned:\n\
476             \x20 - One shared target dir (2 notes)\n\
477             \x20   why: two builds raced on it\n\
478             \x20 Blocked on you:\n\
479             \x20 - approve the signing key\n\
480             \n\
481             -srv-tools: 1 session with notes, 1 session without a note\n\
482             \x20 Decided:\n\
483             \x20 - pin the toolchain\n\
484             \x20 Blocked on you:\n\
485             \x20 - Ship on Friday?\n\
486             \n\
487             -srv-web: 2 sessions with notes\n\
488             \x20 Decided:\n\
489             \x20 - split the router table by concern\n\
490             \x20 Blocked on you:\n\
491             \x20 - pick a port\n\
492             \x20 - name the crate\n\
493             \x20 - confirm the license\n\
494             \x20 - review the API shape\n\
495             \x20 - choose a release date\n\
496             \x20 and 2 more\n\
497             \n\
498             (no project): 1 session with notes\n\
499             \x20 Decided:\n\
500             \x20 - retire the old sync timer"
501        );
502    }
503
504    #[test]
505    fn a_project_filter_keeps_one_project() {
506        let store = three_projects();
507        let digest = Digest::read(&store, day(), Some("-srv-tools")).unwrap();
508        assert_eq!(
509            digest.render(),
510            "Agent digest for -srv-tools, 2026-11-01 08:00 to 2026-11-02 08:00 UTC\n\
511             \n\
512             -srv-tools: 1 session with notes, 1 session without a note\n\
513             \x20 Decided:\n\
514             \x20 - pin the toolchain\n\
515             \x20 Blocked on you:\n\
516             \x20 - Ship on Friday?"
517        );
518    }
519
520    #[test]
521    fn an_empty_window_prints_one_line() {
522        let store = three_projects();
523        let window = Window::parse("90m", now() - Duration::days(30)).unwrap();
524        assert_eq!(
525            Digest::read(&store, window, None).unwrap().render(),
526            "Nothing recorded from 2026-10-03 06:30 to 2026-10-03 08:00 UTC."
527        );
528        let empty = SqliteStore::in_memory("m".to_string()).unwrap();
529        assert_eq!(
530            Digest::read(&empty, day(), Some("-srv-app"))
531                .unwrap()
532                .render(),
533            "Nothing recorded for -srv-app from 2026-11-01 08:00 to 2026-11-02 08:00 UTC."
534        );
535    }
536
537    #[test]
538    fn a_digest_survives_json() {
539        let digest = Digest::read(&three_projects(), day(), None).unwrap();
540        let json = serde_json::to_string(&digest).unwrap();
541        assert_eq!(serde_json::from_str::<Digest>(&json).unwrap(), digest);
542    }
543
544    #[test]
545    fn a_window_is_minutes_hours_or_days() {
546        for (text, span) in [
547            ("90m", Duration::minutes(90)),
548            ("24h", Duration::hours(24)),
549            (" 7d ", Duration::days(7)),
550        ] {
551            assert_eq!(
552                Window::parse(text, now()),
553                Ok(Window {
554                    since: now() - span,
555                    until: now(),
556                }),
557                "{text}"
558            );
559        }
560        for text in ["", "24", "h", "0h", "-1h", "1.5h", "24x", "99999999999d"] {
561            assert!(Window::parse(text, now()).is_err(), "{text:?}");
562        }
563    }
564}