use std::collections::HashSet;
use anyhow::Result;
use chrono::{DateTime, Utc};
use rusqlite::params;
use serde::{Deserialize, Serialize};
use super::{MEMORY_COLS, SqliteStore, row_to_memory};
use crate::schema::{AGENT_NOTE_SOURCE, Memory, MemoryType};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[non_exhaustive]
pub enum NoteKind {
#[default]
#[serde(rename = "session-end")]
SessionEnd,
#[serde(rename = "decision")]
Decision,
#[serde(rename = "dead_end")]
DeadEnd,
#[serde(rename = "fact")]
Fact,
}
impl NoteKind {
pub const ALL: &'static [NoteKind] = &[
NoteKind::SessionEnd,
NoteKind::Decision,
NoteKind::DeadEnd,
NoteKind::Fact,
];
pub fn as_str(self) -> &'static str {
match self {
NoteKind::SessionEnd => "session-end",
NoteKind::Decision => "decision",
NoteKind::DeadEnd => "dead_end",
NoteKind::Fact => "fact",
}
}
pub fn parse(name: &str) -> Option<Self> {
Self::ALL.iter().copied().find(|kind| kind.as_str() == name)
}
pub fn memory_type(self) -> MemoryType {
match self {
NoteKind::SessionEnd | NoteKind::Decision => MemoryType::Decision,
NoteKind::DeadEnd => MemoryType::Debugging,
NoteKind::Fact => MemoryType::Semantic,
}
}
fn label(self) -> &'static str {
match self {
NoteKind::SessionEnd => "Session-end note: ",
NoteKind::Decision => "Decision: ",
NoteKind::DeadEnd => "Dead end: ",
NoteKind::Fact => "Fact: ",
}
}
}
#[derive(Debug, Clone, PartialEq, Eq, Default, Serialize, Deserialize)]
#[non_exhaustive]
pub struct AgentNote {
#[serde(default)]
pub kind: NoteKind,
pub decision: String,
#[serde(default)]
pub reason: String,
#[serde(default)]
pub dead_ends: Vec<String>,
#[serde(default)]
pub open_items: Vec<String>,
#[serde(default)]
pub blocked_on_user: Vec<String>,
}
const REASON: &str = "Reason: ";
const ITEM: &str = "- ";
const DEAD_ENDS: &str = "Dead ends:";
const OPEN_ITEMS: &str = "Open items:";
const BLOCKED_ON_USER: &str = "Blocked on user:";
fn one_line(text: &str) -> String {
text.split_whitespace().collect::<Vec<_>>().join(" ")
}
fn lines(items: &[String]) -> Vec<String> {
items
.iter()
.map(|item| one_line(item))
.filter(|item| !item.is_empty())
.collect()
}
impl AgentNote {
pub fn new(kind: NoteKind, decision: impl Into<String>) -> AgentNote {
AgentNote {
kind,
decision: decision.into(),
..AgentNote::default()
}
}
pub fn normalized(&self) -> AgentNote {
AgentNote {
kind: self.kind,
decision: one_line(&self.decision),
reason: one_line(&self.reason),
dead_ends: lines(&self.dead_ends),
open_items: lines(&self.open_items),
blocked_on_user: lines(&self.blocked_on_user),
}
}
pub fn render(&self) -> String {
let note = self.normalized();
let mut out = format!("{}{}", note.kind.label(), note.decision);
if !note.reason.is_empty() {
out.push('\n');
out.push_str(REASON);
out.push_str(¬e.reason);
}
for (header, items) in [
(DEAD_ENDS, ¬e.dead_ends),
(OPEN_ITEMS, ¬e.open_items),
(BLOCKED_ON_USER, ¬e.blocked_on_user),
] {
if items.is_empty() {
continue;
}
out.push('\n');
out.push_str(header);
for item in items {
out.push('\n');
out.push_str(ITEM);
out.push_str(item);
}
}
out
}
pub fn parse(content: &str) -> Option<AgentNote> {
let mut rows = content.split('\n');
let first = rows.next()?;
let (kind, decision) = NoteKind::ALL
.iter()
.copied()
.find_map(|kind| Some((kind, first.strip_prefix(kind.label())?)))?;
let mut note = AgentNote {
kind,
decision: decision.to_string(),
..AgentNote::default()
};
let mut section: Option<&mut Vec<String>> = None;
let mut seen_section = false;
for row in rows {
if let Some(item) = row.strip_prefix(ITEM) {
section.as_mut()?.push(item.to_string());
continue;
}
if let Some(reason) = row.strip_prefix(REASON) {
if seen_section || !note.reason.is_empty() {
return None;
}
note.reason = reason.to_string();
continue;
}
seen_section = true;
section = Some(match row {
DEAD_ENDS => &mut note.dead_ends,
OPEN_ITEMS => &mut note.open_items,
BLOCKED_ON_USER => &mut note.blocked_on_user,
_ => return None,
});
}
Some(note)
}
}
const LIVE_NOTE: &str = "source = ?1 AND tier = 'hot' AND superseded_by IS NULL";
fn parsed(
rows: impl Iterator<Item = rusqlite::Result<Memory>>,
kind: Option<NoteKind>,
limit: usize,
) -> Result<Vec<(Memory, AgentNote)>> {
let mut notes = Vec::new();
for memory in rows {
if notes.len() >= limit {
break;
}
let memory = memory?;
let Some(note) = AgentNote::parse(&memory.content) else {
continue;
};
if kind.is_none_or(|kind| kind == note.kind) {
notes.push((memory, note));
}
}
Ok(notes)
}
impl SqliteStore {
pub fn notes_for_session(
&self,
session_id: &str,
kind: Option<NoteKind>,
) -> Result<Vec<(Memory, AgentNote)>> {
self.live_notes("source_id", session_id, "created_at, id", kind, usize::MAX)
}
pub fn latest_notes_for_project(
&self,
project: &str,
kind: Option<NoteKind>,
limit: usize,
) -> Result<Vec<(Memory, AgentNote)>> {
self.live_notes("project_path", project, "created_at DESC, id", kind, limit)
}
fn live_notes(
&self,
column: &str,
value: &str,
order: &str,
kind: Option<NoteKind>,
limit: usize,
) -> Result<Vec<(Memory, AgentNote)>> {
let conn = self.reader();
let mut stmt = conn.prepare(&format!(
"SELECT {MEMORY_COLS} FROM memories \
WHERE {LIVE_NOTE} AND {column} = ?2 ORDER BY {order}"
))?;
let rows = stmt.query_map(params![AGENT_NOTE_SOURCE, value], |r| {
row_to_memory(r, false)
})?;
parsed(rows, kind, limit)
}
pub fn notes_created_between(
&self,
since: DateTime<Utc>,
until: DateTime<Utc>,
project_path: Option<&str>,
) -> Result<Vec<(Memory, AgentNote)>> {
let conn = self.reader();
let mut stmt = conn.prepare(&format!(
"SELECT {MEMORY_COLS} FROM memories \
WHERE {LIVE_NOTE} AND created_at >= ?2 AND created_at < ?3 \
AND (?4 IS NULL OR project_path = ?4) \
ORDER BY created_at DESC, id"
))?;
let rows = stmt.query_map(
params![
AGENT_NOTE_SOURCE,
since.to_rfc3339(),
until.to_rfc3339(),
project_path
],
|r| row_to_memory(r, false),
)?;
parsed(rows, None, usize::MAX)
}
pub fn noted_session_ids(&self) -> Result<HashSet<String>> {
let conn = self.reader();
let mut stmt = conn.prepare(&format!(
"SELECT DISTINCT source_id FROM memories WHERE {LIVE_NOTE}"
))?;
let rows = stmt.query_map(params![AGENT_NOTE_SOURCE], |r| r.get::<_, String>(0))?;
Ok(rows.collect::<rusqlite::Result<HashSet<_>>>()?)
}
}
#[cfg(test)]
mod tests {
use chrono::{Duration, TimeZone};
use uuid::Uuid;
use super::*;
use crate::store::Store;
fn full() -> AgentNote {
AgentNote {
kind: NoteKind::SessionEnd,
decision: "keep the cache per worktree".to_string(),
reason: "a shared one\nmixed crates".to_string(),
dead_ends: vec!["one shared dir".to_string(), " ".to_string()],
open_items: vec!["- starts with a dash".to_string()],
blocked_on_user: vec!["Reason: looks like a header".to_string()],
}
}
#[test]
fn a_rendered_note_reads_back_as_its_normalized_form() {
let note = full();
let text = note.render();
assert_eq!(
text,
"Session-end note: keep the cache per worktree\n\
Reason: a shared one mixed crates\n\
Dead ends:\n- one shared dir\n\
Open items:\n- - starts with a dash\n\
Blocked on user:\n- Reason: looks like a header"
);
assert_eq!(AgentNote::parse(&text), Some(note.normalized()));
assert_eq!(AgentNote::parse(&text).unwrap().render(), text);
}
#[test]
fn every_kind_round_trips_with_only_a_decision() {
for &kind in NoteKind::ALL {
let note = AgentNote {
kind,
decision: "x".to_string(),
..AgentNote::default()
};
assert_eq!(AgentNote::parse(¬e.render()), Some(note), "{kind:?}");
assert_eq!(NoteKind::parse(kind.as_str()), Some(kind));
assert_eq!(
serde_json::to_value(kind).unwrap(),
serde_json::json!(kind.as_str())
);
}
}
#[test]
fn text_in_another_shape_is_not_a_note() {
for text in [
"",
"plain remembered text",
"Session-end note: a\nsomething else",
"Session-end note: a\n- item before any section",
"Session-end note: a\nDead ends:\n- x\nReason: late",
"Session-end note: a\nReason: one\nReason: two",
] {
assert_eq!(AgentNote::parse(text), None, "{text:?}");
}
}
fn stored(store: &SqliteStore, session: &str, note: &AgentNote) -> Memory {
let memory = Memory::new(
note.render(),
note.kind.memory_type(),
AGENT_NOTE_SOURCE.to_string(),
session.to_string(),
);
store.store_memory(&memory).unwrap();
memory
}
#[test]
fn notes_for_a_session_are_its_live_agent_notes_filtered_by_kind() {
let store = SqliteStore::in_memory("m".to_string()).unwrap();
let end = stored(&store, "s1", &full());
let fact = AgentNote {
kind: NoteKind::Fact,
decision: "the port is 7300".to_string(),
..AgentNote::default()
};
let fact_row = stored(&store, "s1", &fact);
stored(&store, "s2", &full());
let retired = stored(&store, "s1", &full());
store.retire_memory(retired.id, "test").unwrap();
let mut other_source = Memory::new(
full().render(),
MemoryType::Decision,
"mcp-direct".to_string(),
"s1".to_string(),
);
other_source.id = uuid::Uuid::new_v4();
store.store_memory(&other_source).unwrap();
let all: Vec<_> = store
.notes_for_session("s1", None)
.unwrap()
.into_iter()
.map(|(m, _)| m.id)
.collect();
let mut expected = vec![(end.created_at, end.id), (fact_row.created_at, fact_row.id)];
expected.sort_by_key(|(at, id)| (*at, id.to_string()));
let expected: Vec<_> = expected.into_iter().map(|(_, id)| id).collect();
assert_eq!(all, expected);
let ends = store
.notes_for_session("s1", Some(NoteKind::SessionEnd))
.unwrap();
assert_eq!(ends.len(), 1);
assert_eq!(ends[0].0.id, end.id);
assert_eq!(ends[0].1, full().normalized());
assert!(store.notes_for_session("nope", None).unwrap().is_empty());
}
fn at(hour: i64) -> DateTime<Utc> {
Utc.with_ymd_and_hms(2026, 11, 1, 0, 0, 0).unwrap() + Duration::hours(hour)
}
fn filed(store: &SqliteStore, session: &str, project: Option<&str>, hour: i64) -> Memory {
let mut memory = Memory::new(
AgentNote::new(NoteKind::Decision, format!("{session} at {hour}")).render(),
MemoryType::Decision,
AGENT_NOTE_SOURCE.to_string(),
session.to_string(),
)
.with_project_path(project.map(str::to_string));
memory.created_at = at(hour);
store.store_memory(&memory).unwrap();
memory
}
#[test]
fn notes_created_in_a_window_come_newest_first_and_live_only() {
let store = SqliteStore::in_memory("m".to_string()).unwrap();
let early = filed(&store, "s1", Some("-a"), 4);
let late = filed(&store, "s2", None, 9);
let other = filed(&store, "s3", Some("-b"), 6);
filed(&store, "s4", Some("-a"), 3);
filed(&store, "s5", Some("-a"), 12);
let retired = filed(&store, "s6", Some("-a"), 5);
store.retire_memory(retired.id, "test").unwrap();
let mut plain = Memory::new(
"Decision: looks like a note".to_string(),
MemoryType::Decision,
"mcp-direct".to_string(),
"s7".to_string(),
);
plain.created_at = at(5);
store.store_memory(&plain).unwrap();
let ids = |project| -> Vec<Uuid> {
store
.notes_created_between(at(4), at(12), project)
.unwrap()
.into_iter()
.map(|(m, _)| m.id)
.collect()
};
assert_eq!(ids(None), vec![late.id, other.id, early.id]);
assert_eq!(ids(Some("-a")), vec![early.id]);
}
#[test]
fn noted_session_ids_are_the_sessions_of_live_notes() {
let store = SqliteStore::in_memory("m".to_string()).unwrap();
filed(&store, "s1", None, 1);
filed(&store, "s1", Some("-a"), 2);
filed(&store, "s2", Some("-a"), 3);
let retired = filed(&store, "s3", None, 4);
store.retire_memory(retired.id, "test").unwrap();
let expected: HashSet<String> = ["s1", "s2"].iter().map(|s| s.to_string()).collect();
assert_eq!(store.noted_session_ids().unwrap(), expected);
}
fn project_note(project: &str, minute: u32, note: &AgentNote) -> Memory {
let mut memory = Memory::new(
note.render(),
note.kind.memory_type(),
AGENT_NOTE_SOURCE.to_string(),
format!("s{minute}"),
)
.with_project_path(Some(project.to_string()));
memory.created_at =
chrono::DateTime::parse_from_rfc3339(&format!("2026-11-01T10:{minute:02}:00Z"))
.unwrap()
.with_timezone(&chrono::Utc);
memory
}
fn ids(notes: Vec<(Memory, AgentNote)>) -> Vec<uuid::Uuid> {
notes.into_iter().map(|(m, _)| m.id).collect()
}
#[test]
fn latest_notes_for_a_project_are_its_live_notes_newest_first() {
let store = SqliteStore::in_memory("m".to_string()).unwrap();
let end = |decision: &str| AgentNote::new(NoteKind::SessionEnd, decision);
let first = project_note("p1", 1, &end("first"));
let second = project_note("p1", 2, &end("second"));
let third = project_note("p1", 3, &end("third"));
let fact = project_note("p1", 4, &AgentNote::new(NoteKind::Fact, "the port is 7300"));
let retired = project_note("p1", 5, &end("retired"));
let elsewhere = project_note("p2", 6, &end("other project"));
let mut unparsed = project_note("p1", 7, &end("unparsed"));
unparsed.content = "plain remembered text".to_string();
let mut other_source = project_note("p1", 8, &end("other source"));
other_source.source = "mcp-direct".to_string();
for memory in [
&third,
&first,
&fact,
&second,
&retired,
&elsewhere,
&unparsed,
&other_source,
] {
store.store_memory(memory).unwrap();
}
store.retire_memory(retired.id, "test").unwrap();
assert_eq!(
ids(store.latest_notes_for_project("p1", None, 10).unwrap()),
vec![fact.id, third.id, second.id, first.id]
);
assert_eq!(
ids(store.latest_notes_for_project("p1", None, 2).unwrap()),
vec![fact.id, third.id]
);
let ends = store
.latest_notes_for_project("p1", Some(NoteKind::SessionEnd), 2)
.unwrap();
assert_eq!(ends[0].1, end("third"));
assert_eq!(ids(ends), vec![third.id, second.id]);
assert!(
store
.latest_notes_for_project("p1", Some(NoteKind::DeadEnd), 10)
.unwrap()
.is_empty()
);
assert!(
store
.latest_notes_for_project("nope", None, 10)
.unwrap()
.is_empty()
);
}
}