1use crate::memory::{MemoryBackend, MemoryError, MemoryService, worker_gate};
22use crate::memory_records::{MAX_SITUATION_BYTES, RecordIndex, Typed, content_cap};
23use kernel::Signal;
24use kernel::store::FileDocumentStore;
25use serde_json::{Map, Value, json};
26use std::collections::BTreeMap;
27use std::path::{Path, PathBuf};
28use std::sync::Arc;
29use yaml_rust2::{Yaml, YamlLoader};
30
31#[derive(Debug, Clone, Copy, PartialEq, Eq)]
32pub enum Harness {
33 ClaudeCode,
34 Codex,
35}
36
37impl Harness {
38 pub fn parse(name: &str) -> Option<Harness> {
40 match name {
41 "claude-code" | "claude" => Some(Harness::ClaudeCode),
42 "codex" => Some(Harness::Codex),
43 _ => None,
44 }
45 }
46
47 pub fn label(self) -> &'static str {
48 match self {
49 Harness::ClaudeCode => "Claude Code",
50 Harness::Codex => "Codex",
51 }
52 }
53}
54
55#[derive(Debug, Clone, PartialEq, Eq)]
57pub struct Note {
58 pub key: String,
59 pub kind: &'static str,
60 pub situation: String,
61 pub content: String,
62 pub file: PathBuf,
64}
65
66#[derive(Debug, Clone, PartialEq, Eq)]
68pub struct Source {
69 pub harness: Harness,
70 pub directory: PathBuf,
71 pub project: Option<PathBuf>,
73}
74
75pub fn notes_root(harness: Harness, home: &Path, var: &dyn Fn(&str) -> Option<String>) -> PathBuf {
77 let configured = |name: &str| var(name).filter(|value| !value.trim().is_empty()).map(PathBuf::from);
78 match harness {
79 Harness::ClaudeCode => configured("CLAUDE_CONFIG_DIR")
80 .unwrap_or_else(|| home.join(".claude"))
81 .join("projects"),
82 Harness::Codex => configured("CODEX_HOME")
83 .unwrap_or_else(|| home.join(".codex"))
84 .join("memories"),
85 }
86}
87
88pub fn discover(harness: Harness, root: &Path) -> Vec<Source> {
90 match harness {
91 Harness::ClaudeCode => {
92 let mut projects: Vec<PathBuf> = std::fs::read_dir(root)
93 .into_iter()
94 .flatten()
95 .flatten()
96 .map(|entry| entry.path())
97 .filter(|project| project.join("memory").is_dir())
98 .collect();
99 projects.sort();
100 projects
101 .into_iter()
102 .map(|project| Source {
103 harness,
104 directory: project.join("memory"),
105 project: project_path(&project),
106 })
107 .collect()
108 }
109 Harness::Codex => {
110 if root.join("memory_summary.md").is_file() || root.join("MEMORY.md").is_file() {
111 vec![Source {
112 harness,
113 directory: root.to_path_buf(),
114 project: None,
115 }]
116 } else {
117 Vec::new()
118 }
119 }
120 }
121}
122
123pub fn project_path(project_dir: &Path) -> Option<PathBuf> {
126 let name = project_dir.file_name()?.to_string_lossy().into_owned();
127 let segments: Vec<&str> = name.trim_start_matches('-').split('-').collect();
128 let mut matches = Vec::new();
129 resolve_segments(Path::new("/"), &segments, &mut matches);
130 (matches.len() == 1).then(|| matches.remove(0))
131}
132
133fn resolve_segments(base: &Path, segments: &[&str], matches: &mut Vec<PathBuf>) {
134 if matches.len() > 1 {
135 return;
136 }
137 if segments.is_empty() {
138 matches.push(base.to_path_buf());
139 return;
140 }
141 for take in 1..=segments.len() {
142 let candidate = base.join(segments[..take].join("-"));
143 if candidate.is_dir() {
144 resolve_segments(&candidate, &segments[take..], matches);
145 }
146 }
147}
148
149impl Source {
150 pub fn read(&self) -> Result<Vec<Note>, String> {
151 match self.harness {
152 Harness::ClaudeCode => claude_code_notes(&self.directory),
153 Harness::Codex => codex_notes(&self.directory),
154 }
155 }
156}
157
158fn collect_markdown(directory: &Path, out: &mut Vec<PathBuf>) -> Result<(), String> {
159 let entries = std::fs::read_dir(directory).map_err(|e| format!("{}: {e}", directory.display()))?;
160 for entry in entries {
161 let entry = entry.map_err(|e| e.to_string())?;
162 let path = entry.path();
163 let name = entry.file_name().to_string_lossy().into_owned();
164 let file_type = entry.file_type().map_err(|e| e.to_string())?;
165 if name.starts_with('.') || file_type.is_symlink() {
166 continue;
167 }
168 if file_type.is_dir() {
169 if name != "old" {
170 collect_markdown(&path, out)?;
171 }
172 } else if file_type.is_file() && name.ends_with(".md") && name != "MEMORY.md" {
173 out.push(path);
174 }
175 }
176 Ok(())
177}
178
179fn split_frontmatter(text: &str) -> (Option<&str>, &str) {
181 let Some(rest) = text.strip_prefix("---\n").or_else(|| text.strip_prefix("---\r\n")) else {
182 return (None, text);
183 };
184 let mut cursor = 0;
185 for line in rest.split_inclusive('\n') {
186 if line.trim_end() == "---" {
187 return (Some(&rest[..cursor]), &rest[cursor + line.len()..]);
188 }
189 cursor += line.len();
190 }
191 (None, text)
192}
193
194fn yaml_text<'a>(yaml: &'a Yaml, key: &str) -> Option<&'a str> {
195 yaml[key].as_str().map(str::trim).filter(|text| !text.is_empty())
196}
197
198pub fn claude_code_notes(directory: &Path) -> Result<Vec<Note>, String> {
200 let mut files = Vec::new();
201 collect_markdown(directory, &mut files)?;
202 files.sort();
203 let mut notes = Vec::new();
204 for path in files {
205 let text = std::fs::read_to_string(&path).map_err(|e| format!("{}: {e}", path.display()))?;
206 let (front, body) = split_frontmatter(&text);
207 let front = front
208 .and_then(|yaml| YamlLoader::load_from_str(yaml).ok())
209 .and_then(|mut docs| (!docs.is_empty()).then(|| docs.remove(0)))
210 .unwrap_or(Yaml::Null);
211 let body = body.trim();
212 if body.is_empty() {
213 continue;
214 }
215 let stem = path
216 .file_stem()
217 .map(|stem| stem.to_string_lossy().into_owned())
218 .unwrap_or_default();
219 let name = yaml_text(&front, "name").map(str::to_string).unwrap_or(stem);
220 let kind = match yaml_text(&front["metadata"], "type").or_else(|| yaml_text(&front, "type")) {
221 Some("feedback") => "preference",
222 Some("user" | "project") => "fact",
223 _ => "reference",
224 };
225 notes.push(Note {
226 key: slug_key(&name),
227 kind,
228 situation: yaml_text(&front, "description").unwrap_or_default().to_string(),
229 content: body.to_string(),
230 file: path,
231 });
232 }
233 Ok(notes)
234}
235
236struct Section {
237 heading: String,
238 lines: Vec<String>,
239}
240
241impl Section {
242 fn bullets(&self) -> Vec<String> {
244 let mut bullets: Vec<String> = Vec::new();
245 for line in &self.lines {
246 let trimmed = line.trim_start_matches([' ', '\t']);
247 if let Some(item) = trimmed.strip_prefix("- ") {
248 bullets.push(item.trim().to_string());
249 } else if (line.starts_with(' ') || line.starts_with('\t'))
250 && let Some(last) = bullets.last_mut()
251 {
252 last.push(' ');
253 last.push_str(line.trim());
254 }
255 }
256 bullets
257 }
258
259 fn paragraphs(&self) -> Vec<String> {
260 self.lines
261 .iter()
262 .map(|line| line.trim())
263 .filter(|line| !line.is_empty() && !line.starts_with("- "))
264 .map(str::to_string)
265 .collect()
266 }
267}
268
269fn sections(text: &str) -> Vec<Section> {
271 let mut sections: Vec<Section> = Vec::new();
272 for line in text.lines() {
273 if let Some(heading) = line.strip_prefix("## ") {
274 sections.push(Section {
275 heading: heading.trim().to_string(),
276 lines: Vec::new(),
277 });
278 } else if line.starts_with('#') {
279 sections.push(Section {
280 heading: String::new(),
281 lines: Vec::new(),
282 });
283 } else if let Some(section) = sections.last_mut() {
284 section.lines.push(line.to_string());
285 }
286 }
287 sections.retain(|section| !section.heading.is_empty());
288 sections
289}
290
291fn note(key: &str, kind: &'static str, situation: &str, content: &str, file: &Path) -> Note {
292 Note {
293 key: slug_key(key),
294 kind,
295 situation: situation.to_string(),
296 content: content.to_string(),
297 file: file.to_path_buf(),
298 }
299}
300
301fn summary_notes(text: &str, file: &Path) -> Vec<Note> {
302 let mut notes = Vec::new();
303 for section in sections(text) {
304 match section.heading.as_str() {
305 "User Profile" => {
306 let profile = section.paragraphs().join(" ");
307 if !profile.is_empty() {
308 notes.push(note(
309 "codex-user-profile",
310 "fact",
311 "who the user is, as Codex summarized it",
312 &profile,
313 file,
314 ));
315 }
316 }
317 "User preferences" => {
318 for bullet in section.bullets() {
319 notes.push(note(
320 &format!("codex-pref-{}", slug_key(&bullet)),
321 "preference",
322 "how the user wants work done, as Codex summarized it",
323 &bullet,
324 file,
325 ));
326 }
327 }
328 "General Tips" => {
329 for bullet in section.bullets() {
330 notes.push(note(
331 &format!("codex-tip-{}", slug_key(&bullet)),
332 "procedure",
333 "working practice Codex learned across tasks",
334 &bullet,
335 file,
336 ));
337 }
338 }
339 _ => {}
340 }
341 }
342 notes
343}
344
345fn task_heading(heading: &str) -> Option<(String, String)> {
347 let rest = heading.strip_prefix("Task ")?;
348 let (number, title) = rest.split_once(": ")?;
349 (!number.is_empty() && number.bytes().all(|b| b.is_ascii_digit()) && !title.trim().is_empty())
350 .then(|| (number.to_string(), title.trim().to_string()))
351}
352
353fn trailing_task_tag(content: &str) -> Option<(String, usize)> {
355 let trimmed = content.trim_end();
356 let inner = trimmed.strip_suffix(']')?;
357 let open = inner.rfind("[Task ")?;
358 let number = &inner[open + "[Task ".len()..];
359 if number.is_empty() || !number.bytes().all(|b| b.is_ascii_digit()) {
360 return None;
361 }
362 let start = content[..open].trim_end().len();
363 Some((number.to_string(), start))
364}
365
366fn memory_notes(text: &str, file: &Path) -> Vec<Note> {
367 let mut tasks: BTreeMap<String, String> = BTreeMap::new();
368 let mut notes = Vec::new();
369 for section in sections(text) {
370 if let Some((number, title)) = task_heading(§ion.heading) {
371 tasks.insert(number, title);
372 continue;
373 }
374 let (kind, prefix) = match section.heading.as_str() {
375 "User preferences" => ("preference", "codex-pref"),
376 "Reusable knowledge" => ("fact", "codex-fact"),
377 "Failures and how to do differently" => ("pitfall", "codex-pitfall"),
378 _ => continue,
379 };
380 for bullet in section.bullets() {
381 let mut situation = String::from("from the user's Codex task memory");
382 let mut content = bullet.clone();
383 while let Some((number, start)) = trailing_task_tag(&content) {
384 if let Some(title) = tasks.get(&number) {
385 situation = format!("Codex task: {title}");
386 }
387 content.truncate(start);
388 }
389 if content.trim().is_empty() {
390 continue;
391 }
392 notes.push(note(
393 &format!("{prefix}-{}", slug_key(&content)),
394 kind,
395 &situation,
396 content.trim(),
397 file,
398 ));
399 }
400 }
401 notes
402}
403
404pub fn codex_notes(directory: &Path) -> Result<Vec<Note>, String> {
406 let mut notes = Vec::new();
407 let mut read_any = false;
408 for (name, parse) in [
409 ("memory_summary.md", summary_notes as fn(&str, &Path) -> Vec<Note>),
410 ("MEMORY.md", memory_notes),
411 ] {
412 let path = directory.join(name);
413 match std::fs::read_to_string(&path) {
414 Ok(text) => {
415 read_any = true;
416 notes.extend(parse(&text, &path));
417 }
418 Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
419 Err(error) => return Err(format!("{}: {error}", path.display())),
420 }
421 }
422 if !read_any {
423 return Err(format!("no Codex memory files found in {}", directory.display()));
424 }
425 Ok(notes)
426}
427
428pub fn slug_key(text: &str) -> String {
430 let mut key = String::new();
431 let mut last_dash = true;
432 for character in text.chars().flat_map(char::to_lowercase) {
433 if character.is_ascii_alphanumeric() {
434 key.push(character);
435 last_dash = false;
436 } else if !last_dash {
437 key.push('-');
438 last_dash = true;
439 }
440 if key.len() >= 60 {
441 break;
442 }
443 }
444 let key = key.trim_matches('-').to_string();
445 if key.is_empty() { "note".to_string() } else { key }
446}
447
448fn clean(text: &str) -> String {
450 text.replace("\r\n", "\n")
451 .chars()
452 .filter(|ch| !ch.is_control() || *ch == '\n' || *ch == '\t')
453 .collect::<String>()
454 .trim()
455 .to_string()
456}
457
458fn truncate_bytes(text: &str, max: usize) -> &str {
459 let mut end = 0;
460 for (offset, ch) in text.char_indices() {
461 if offset + ch.len_utf8() > max {
462 break;
463 }
464 end = offset + ch.len_utf8();
465 }
466 &text[..end]
467}
468
469pub fn home_relative(path: &Path, home: &Path) -> String {
471 match path.strip_prefix(home) {
472 Ok(rest) if rest.as_os_str().is_empty() => "~".into(),
473 Ok(rest) => format!("~/{}", rest.display()),
474 Err(_) => path.display().to_string(),
475 }
476}
477
478fn note_key(harness: Harness, note: &Note, occurrence: usize) -> String {
481 let file = note.file.display().to_string();
482 let mut identity = match harness {
483 Harness::ClaudeCode => file,
484 Harness::Codex => format!("{file}\0{}", clean(¬e.content)),
485 };
486 if occurrence > 1 {
487 identity.push_str(&format!("\0{occurrence}"));
488 }
489 let suffix = &jsrt::hash::sha256_hex(identity.as_bytes())[..12];
490 let base = note.key.trim_end_matches('-');
491 let end = base.len().min(64 - 1 - suffix.len());
492 format!("{}-{suffix}", base[..end].trim_end_matches('-'))
493}
494
495#[derive(Debug, Clone, PartialEq, Eq)]
497pub enum Action {
498 Add,
500 Replace(String),
502 Unchanged(String),
504 Refuse(String),
506}
507
508#[derive(Debug, Clone, PartialEq, Eq)]
510pub struct Planned {
511 pub typed: Typed,
512 pub content: String,
513 pub scope: &'static str,
514 pub project: Option<PathBuf>,
516 pub file_sha: String,
518 pub action: Action,
519}
520
521pub type ScopeTags<'a> = &'a dyn Fn(Option<&Path>) -> Map<String, Value>;
524
525pub fn plan(sources: &[Source], home: &Path, index: &RecordIndex, tags: ScopeTags<'_>) -> Result<Vec<Planned>, String> {
527 let mut planned = Vec::new();
528 for source in sources {
529 let notes = source.read()?;
530 let scope = if source.project.is_some() { "project" } else { "global" };
531 let filters = tags(source.project.as_deref());
532 let mut seen: BTreeMap<String, usize> = BTreeMap::new();
533 for note in notes {
534 let count = seen.entry(note_key(source.harness, ¬e, 1)).or_default();
535 *count += 1;
536 let key = note_key(source.harness, ¬e, *count);
537 let situation = clean(¬e.situation).replace(['\n', '\t'], " ");
538 let situation = match truncate_bytes(&situation, MAX_SITUATION_BYTES).trim() {
539 "" => "from the user's imported notes".to_string(),
540 text => text.to_string(),
541 };
542 let content = clean(¬e.content);
543 let typed = Typed {
544 kind: note.kind.to_string(),
545 key: Some(key.clone()),
546 situation,
547 path_globs: Vec::new(),
548 source: Some(format!(
549 "{} {}",
550 source.harness.label(),
551 home_relative(¬e.file, home)
552 )),
553 };
554 let file_sha = std::fs::read(¬e.file)
555 .map(|bytes| jsrt::hash::sha256_hex(&bytes))
556 .map_err(|e| format!("{}: {e}", note.file.display()))?;
557 let action = if content.len() > content_cap(note.kind) {
558 Action::Refuse(format!(
559 "over the {}-byte cap of a {} record",
560 content_cap(note.kind),
561 note.kind
562 ))
563 } else if host::secrets::contains_sensitive_memory(&content)
564 || host::secrets::contains_sensitive_memory(&typed.screened())
565 {
566 Action::Refuse("holds a secret or personal identifier".into())
567 } else {
568 match index.by_key(&key, scope, &filters)? {
569 Some(entry)
570 if entry.text_hash == jsrt::hash::sha256_hex(content.as_bytes()) && entry.typed == typed =>
571 {
572 Action::Unchanged(entry.id)
573 }
574 Some(entry) => Action::Replace(entry.id),
575 None => Action::Add,
576 }
577 };
578 planned.push(Planned {
579 typed,
580 content,
581 scope,
582 project: source.project.clone(),
583 file_sha,
584 action,
585 });
586 }
587 }
588 Ok(planned)
589}
590
591pub fn propose_payload(planned: &Planned) -> Map<String, Value> {
593 let typed = &planned.typed;
594 let source = typed.source.clone().unwrap_or_default();
595 let mut payload = json!({
596 "text": planned.content,
597 "evidence": [{"ref": source, "sha256": planned.file_sha}],
598 "scope": planned.scope,
599 "evidenceClass": "user_statement",
600 "type": typed.kind,
601 "situation": typed.situation,
602 "source": source,
603 });
604 if let Some(key) = &typed.key {
605 payload["key"] = key.clone().into();
606 }
607 payload.as_object().cloned().unwrap_or_default()
608}
609
610pub fn import_one(service: &MemoryService, planned: &Planned) -> Result<Value, MemoryError> {
612 service.propose(&propose_payload(planned), &Signal::new())
613}
614
615pub type BackendFor<'a> = &'a dyn Fn(Option<&Path>) -> Result<Arc<dyn MemoryBackend>, String>;
617
618#[derive(Debug, Clone, PartialEq, Eq)]
620pub enum Imported {
621 Stored(String),
623 Replaced(String),
625 Unchanged,
626 Refused(String),
628 NotStored(String),
630 Failed(String),
631}
632
633pub fn import_all(
636 planned: &[Planned],
637 journal: &Path,
638 index: Arc<RecordIndex>,
639 backend_for: BackendFor<'_>,
640 each: &mut dyn FnMut(&Planned, Imported) -> Result<(), String>,
641) -> Result<(), String> {
642 let mut service: Option<(Option<PathBuf>, MemoryService)> = None;
643 for item in planned {
644 let outcome = match &item.action {
645 Action::Unchanged(_) => Imported::Unchanged,
646 Action::Refuse(reason) => Imported::Refused(reason.clone()),
647 Action::Add | Action::Replace(_) => {
648 if service.as_ref().is_none_or(|(project, _)| *project != item.project) {
649 let memory = MemoryService::new(
650 Arc::new(FileDocumentStore::new(journal)),
651 backend_for(item.project.as_deref())?,
652 worker_gate(),
653 )
654 .map_err(|e| e.to_string())?
655 .with_records(index.clone());
656 service = Some((item.project.clone(), memory));
657 }
658 let Some((_, memory)) = &service else {
659 continue;
660 };
661 match import_one(memory, item) {
662 Ok(op) if op["state"] == "sensitive" || op["state"] == "skipped" => {
663 Imported::Refused("holds a secret or personal identifier".into())
664 }
665 Ok(op) if op["phase"] == "backend" => {
666 let id = op["memoryId"].as_str().unwrap_or_default().to_string();
667 match item.action {
668 Action::Replace(_) => Imported::Replaced(id),
669 _ => Imported::Stored(id),
670 }
671 }
672 Ok(op) => Imported::NotStored(op["state"].as_str().unwrap_or("?").to_string()),
673 Err(error) => Imported::Failed(error.to_string()),
674 }
675 }
676 };
677 each(item, outcome)?;
678 }
679 Ok(())
680}