1. 1//! Durable memory notes (docs/design/26-learning.md): one plain-markdown
2. 2//! file per workspace under `<home>/memory/<hash>/MEMORY.md`, plus a global
3. 3//! user-profile tier at `<home>/memory/user/USER.md`
4. 4//! (docs/design/29-personal-os.md P1). The model appends through the
5. 5//! `remember` tool; humans edit or prune the file directly — the parser
6. 6//! tolerates hand-edits rather than fighting them. Forget/amend rewrite the
7. 7//! markdown file in place; sessions stay append-only.
8. 8
9. 9use std::path::{Path, PathBuf};
10. 10use std::time::{Duration, Instant, SystemTime};
11. 11
12. 12use chrono::{DateTime, Utc};
13. 13
14. 14/// FNV-1a 64-bit, matching vak-session's cwd hashing so every per-workspace
15. 15/// store keys off the same identity.
16. 16pub fn hash_cwd(cwd: &Path) -> String {
17. 17 fnv1a(cwd.to_string_lossy().as_bytes())
18. 18}
19. 19
20. 20fn fnv1a(data: &[u8]) -> String {
21. 21 let mut h: u64 = 0xcbf2_9ce4_8422_2325;
22. 22 for b in data {
23. 23 h ^= u64::from(*b);
24. 24 h = h.wrapping_mul(0x0000_0100_0000_01b3);
25. 25 }
26. 26 format!("{h:016x}")
27. 27}
28. 28
29. 29/// Stable note id: FNV-1a 64 of the full header line (without any trailing
30. 30/// newline/carriage-return). Deterministic across processes and toolchains,
31. 31/// so list/forget/amend agree without extra state; hand-editing a header
32. 32/// deliberately changes its id.
33. 33fn note_id(header_line: &str) -> String {
34. 34 fnv1a(header_line.as_bytes())
35. 35}
36. 36
37. 37#[derive(Debug, Clone, PartialEq)]
38. 38pub struct NoteBlock {
39. 39 pub id: String,
40. 40 pub ts: DateTime<Utc>,
41. 41 pub kind: String,
42. 42 pub tag: String,
43. 43 pub session_id: String,
44. 44 pub text: String,
45. 45}
46. 46
47. 47#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
48. 48pub struct CleanupReport {
49. 49 pub removed_locks: usize,
50. 50 pub removed_temps: usize,
51. 51 pub removed_empty_dirs: usize,
52. 52}
53. 53
54. 54/// Remove only abandoned write artifacts and empty workspace directories.
55. 55/// Durable note files are never age-pruned: retention is an explicit
56. 56/// forget/amend decision so an old fact cannot disappear silently.
57. 57pub fn cleanup_artifacts(home: &Path, older_than: Duration) -> CleanupReport {
58. 58 let root = home.join("memory");
59. 59 let Ok(entries) = std::fs::read_dir(&root) else {
60. 60 return CleanupReport::default();
61. 61 };
62. 62 let cutoff = SystemTime::now().checked_sub(older_than);
63. 63 let mut report = CleanupReport::default();
64. 64 for entry in entries.flatten() {
65. 65 let path = entry.path();
66. 66 if !path.is_dir() || path.file_name().is_some_and(|n| n == "user") {
67. 67 continue;
68. 68 }
69. 69 let Ok(files) = std::fs::read_dir(&path) else {
70. 70 continue;
71. 71 };
72. 72 for file in files.flatten() {
73. 73 let file_path = file.path();
74. 74 let name = file_path
75. 75 .file_name()
76. 76 .and_then(|n| n.to_str())
77. 77 .unwrap_or_default();
78. 78 let artifact = name.ends_with(".lock") || name.contains(".tmp.");
79. 79 let old = cutoff
80. 80 .zip(
81. 81 std::fs::metadata(&file_path)
82. 82 .and_then(|m| m.modified())
83. 83 .ok(),
84. 84 )
85. 85 .is_some_and(|(cutoff, modified)| modified <= cutoff);
86. 86 if artifact && old && std::fs::remove_file(&file_path).is_ok() {
87. 87 if name.ends_with(".lock") {
88. 88 report.removed_locks += 1;
89. 89 } else {
90. 90 report.removed_temps += 1;
91. 91 }
92. 92 }
93. 93 }
94. 94 if std::fs::read_dir(&path)
95. 95 .map(|mut d| d.next().is_none())
96. 96 .unwrap_or(false)
97. 97 && std::fs::remove_dir(&path).is_ok()
98. 98 {
99. 99 report.removed_empty_dirs += 1;
100. 100 }
101. 101 }
102. 102 report
103. 103}
104. 104
105. 105fn memory_path(home: &Path, cwd: &Path) -> PathBuf {
106. 106 home.join("memory").join(hash_cwd(cwd)).join("MEMORY.md")
107. 107}
108. 108
109. 109/// Global profile-tier store, keyed to the user rather than a workspace.
110. 110pub fn profile_path(home: &Path) -> PathBuf {
111. 111 home.join("memory").join("user").join("USER.md")
112. 112}
113. 113
114. 114pub fn append_note(
115. 115 home: &Path,
116. 116 cwd: &Path,
117. 117 kind: &str,
118. 118 tag: &str,
119. 119 session_id: &str,
120. 120 text: &str,
121. 121) -> Result<NoteBlock, String> {
122. 122 append_block(&memory_path(home, cwd), kind, tag, session_id, text)
123. 123}
124. 124
125. 125/// Append to the global USER.md profile tier (same grammar, same validation,
126. 126/// lazy directory creation) — memories that follow the user across projects.
127. 127pub fn append_profile_note(
128. 128 home: &Path,
129. 129 kind: &str,
130. 130 tag: &str,
131. 131 text: &str,
132. 132 session: &str,
133. 133) -> Result<NoteBlock, String> {
134. 134 append_block(&profile_path(home), kind, tag, session, text)
135. 135}
136. 136
137. 137fn append_block(
138. 138 path: &Path,
139. 139 kind: &str,
140. 140 tag: &str,
141. 141 session_id: &str,
142. 142 text: &str,
143. 143) -> Result<NoteBlock, String> {
144. 144 if !matches!(
145. 145 kind,
146. 146 "fact" | "decision" | "preference" | "reference" | "note" | "invariant" | "procedural"
147. 147 ) {
148. 148 return Err("unknown note kind; expected fact, decision, preference, reference, invariant, or procedural".into());
149. 149 }
150. 150 validate_field("kind", kind, 32)?;
151. 151 validate_field("tag", tag, 96)?;
152. 152 validate_field("session", session_id, 160)?;
153. 153 let text = text.trim();
154. 154 if text.is_empty() {
155. 155 return Err("note must not be empty".into());
156. 156 }
157. 157 if text.len() > 128 * 1024 {
158. 158 return Err("note exceeds the 128 KiB limit".into());
159. 159 }
160. 160 let ts = Utc::now();
161. 161 if let Some(parent) = path.parent() {
162. 162 std::fs::create_dir_all(parent).map_err(|e| format!("create memory dir: {e}"))?;
163. 163 }
164. 164 let _lock = StoreLock::acquire(path)?;
165. 165 let header = format!(
166. 166 "## {} [{kind}] tag={tag} session={session_id}",
167. 167 ts.to_rfc3339()
168. 168 );
169. 169 let block = format!("{header}\n{text}\n");
170. 170 use std::io::Write;
171. 171 let mut f = std::fs::OpenOptions::new()
172. 172 .create(true)
173. 173 .append(true)
174. 174 .open(path)
175. 175 .map_err(|e| format!("open {}: {e}", path.display()))?;
176. 176 f.write_all(format!("{block}\n").as_bytes())
177. 177 .map_err(|e| format!("append {}: {e}", path.display()))?;
178. 178 f.sync_data()
179. 179 .map_err(|e| format!("flush {}: {e}", path.display()))?;
180. 180 Ok(NoteBlock {
181. 181 id: note_id(&header),
182. 182 ts,
183. 183 kind: kind.to_string(),
184. 184 tag: tag.to_string(),
185. 185 session_id: session_id.to_string(),
186. 186 text: text.to_string(),
187. 187 })
188. 188}
189. 189
190. 190fn validate_field(name: &str, value: &str, max: usize) -> Result<(), String> {
191. 191 if value.len() > max
192. 192 || value
193. 193 .chars()
194. 194 .any(|c| c.is_control() || c == '\n' || c == '\r')
195. 195 {
196. 196 return Err(format!("{name} contains invalid characters or is too long"));
197. 197 }
198. 198 Ok(())
199. 199}
200. 200
201. 201struct StoreLock {
202. 202 path: PathBuf,
203. 203}
204. 204
205. 205impl StoreLock {
206. 206 fn acquire(store: &Path) -> Result<Self, String> {
207. 207 let path = store.with_extension("lock");
208. 208 let deadline = Instant::now() + Duration::from_secs(10);
209. 209 loop {
210. 210 match std::fs::OpenOptions::new()
211. 211 .write(true)
212. 212 .create_new(true)
213. 213 .open(&path)
214. 214 {
215. 215 Ok(mut file) => {
216. 216 use std::io::Write;
217. 217 let _ = writeln!(file, "pid={}", std::process::id());
218. 218 return Ok(Self { path });
219. 219 }
220. 220 Err(e)
221. 221 if e.kind() == std::io::ErrorKind::AlreadyExists
222. 222 && Instant::now() < deadline =>
223. 223 {
224. 224 if std::fs::metadata(&path)
225. 225 .and_then(|m| m.modified())
226. 226 .ok()
227. 227 .and_then(|t| t.elapsed().ok())
228. 228 .is_some_and(|age| age > Duration::from_secs(60))
229. 229 {
230. 230 let _ = std::fs::remove_file(&path);
231. 231 continue;
232. 232 }
233. 233 std::thread::sleep(Duration::from_millis(10));
234. 234 }
235. 235 Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
236. 236 return Err(format!("timed out waiting for {}", path.display()));
237. 237 }
238. 238 Err(e) => return Err(format!("lock {}: {e}", path.display())),
239. 239 }
240. 240 }
241. 241 }
242. 242}
243. 243
244. 244impl Drop for StoreLock {
245. 245 fn drop(&mut self) {
246. 246 let _ = std::fs::remove_file(&self.path);
247. 247 }
248. 248}
249. 249
250. 250/// Parse MEMORY.md blocks. Tolerant by design: lines before the first
251. 251/// heading and malformed headings attach to whatever precedes them, so a
252. 252/// hand-edit never silently loses content.
253. 253///
254. 254/// Reads exactly `home`'s memory. An Agent's memory is private
255. 255/// (invariant 37); an empty home is empty, never a reason to read another
256. 256/// Agent's notes.
257. 257pub fn list_notes(home: &Path, cwd: &Path) -> Vec<NoteBlock> {
258. 258 blocks_at(&memory_path(home, cwd))
259. 259}
260. 260
261. 261/// Parse the global profile tier of exactly `home`.
262. 262pub fn list_profile_notes(home: &Path) -> Vec<NoteBlock> {
263. 263 blocks_at(&profile_path(home))
264. 264}
265. 265
266. 266fn blocks_at(path: &Path) -> Vec<NoteBlock> {
267. 267 let Ok(raw) = std::fs::read_to_string(path) else {
268. 268 return Vec::new();
269. 269 };
270. 270 parse_blocks(&raw)
271. 271}
272. 272
273. 273pub fn parse_blocks(raw: &str) -> Vec<NoteBlock> {
274. 274 struct Open {
275. 275 header_line: String,
276. 276 ts: DateTime<Utc>,
277. 277 kind: String,
278. 278 tag: String,
279. 279 session_id: String,
280. 280 }
281. 281
282. 282 fn flush(open: &mut Option<Open>, body: &mut String, out: &mut Vec<NoteBlock>) {
283. 283 if let Some(o) = open.take() {
284. 284 let text = body.trim().to_string();
285. 285 if !text.is_empty() {
286. 286 out.push(NoteBlock {
287. 287 id: note_id(&o.header_line),
288. 288 ts: o.ts,
289. 289 kind: o.kind,
290. 290 tag: o.tag,
291. 291 session_id: o.session_id,
292. 292 text,
293. 293 });
294. 294 }
295. 295 }
296. 296 body.clear();
297. 297 }
298. 298
299. 299 let mut out: Vec<NoteBlock> = Vec::new();
300. 300 let mut open: Option<Open> = None;
301. 301 let mut body = String::new();
302. 302
303. 303 for line in raw.lines() {
304. 304 if let Some(rest) = line.strip_prefix("## ") {
305. 305 match parse_header(rest) {
306. 306 Some((ts, kind, tag, sid)) => {
307. 307 flush(&mut open, &mut body, &mut out);
308. 308 open = Some(Open {
309. 309 header_line: line.to_string(),
310. 310 ts,
311. 311 kind,
312. 312 tag,
313. 313 session_id: sid,
314. 314 });
315. 315 }
316. 316 None => {
317. 317 // Not our grammar: treat as continuation text of the
318. 318 // previous block (or drop leading junk).
319. 319 if open.is_some() {
320. 320 body.push_str(line);
321. 321 body.push('\n');
322. 322 }
323. 323 }
324. 324 }
325. 325 } else if open.is_some() {
326. 326 body.push_str(line);
327. 327 body.push('\n');
328. 328 }
329. 329 }
330. 330 flush(&mut open, &mut body, &mut out);
331. 331 out
332. 332}
333. 333
334. 334/// Byte span of each parsed note in `raw`, mirroring parse_blocks exactly:
335. 335/// a block runs from its valid `## ` header through the newline of its last
336. 336/// non-blank body line; malformed headings count as body text; headers with
337. 337/// empty bodies yield no span (they yield no note either).
338. 338struct Span {
339. 339 id: String,
340. 340 start: usize,
341. 341 end: usize,
342. 342}
343. 343
344. 344fn note_spans(raw: &str) -> Vec<Span> {
345. 345 let pieces: Vec<&str> = raw.split('\n').collect();
346. 346 let mut starts = Vec::with_capacity(pieces.len());
347. 347 let mut off = 0usize;
348. 348 for p in &pieces {
349. 349 starts.push(off);
350. 350 off += p.len() + 1;
351. 351 }
352. 352
353. 353 fn close(
354. 354 open: &mut Option<(String, usize)>,
355. 355 last_content: &mut Option<usize>,
356. 356 starts: &[usize],
357. 357 pieces: &[&str],
358. 358 raw_len: usize,
359. 359 out: &mut Vec<Span>,
360. 360 ) {
361. 361 if let Some((id, h)) = open.take()
362. 362 && let Some(l) = last_content.take()
363. 363 {
364. 364 let end = (starts[l] + pieces[l].len() + 1).min(raw_len);
365. 365 out.push(Span {
366. 366 id,
367. 367 start: starts[h],
368. 368 end,
369. 369 });
370. 370 }
371. 371 }
372. 372
373. 373 let mut out: Vec<Span> = Vec::new();
374. 374 let mut open: Option<(String, usize)> = None;
375. 375 let mut last_content: Option<usize> = None;
376. 376 for (i, piece) in pieces.iter().enumerate() {
377. 377 let line = piece.strip_suffix('\r').unwrap_or(piece);
378. 378 if let Some(rest) = line.strip_prefix("## ")
379. 379 && parse_header(rest).is_some()
380. 380 {
381. 381 close(
382. 382 &mut open,
383. 383 &mut last_content,
384. 384 &starts,
385. 385 &pieces,
386. 386 raw.len(),
387. 387 &mut out,
388. 388 );
389. 389 open = Some((note_id(line), i));
390. 390 } else if open.is_some() && !line.trim().is_empty() {
391. 391 last_content = Some(i);
392. 392 }
393. 393 }
394. 394 close(
395. 395 &mut open,
396. 396 &mut last_content,
397. 397 &starts,
398. 398 &pieces,
399. 399 raw.len(),
400. 400 &mut out,
401. 401 );
402. 402 out
403. 403}
404. 404
405. 405fn load_raw(path: &Path) -> Result<String, String> {
406. 406 std::fs::read_to_string(path).map_err(|e| format!("read {}: {e}", path.display()))
407. 407}
408. 408
409. 409fn persist_locked(path: &Path, contents: String) -> Result<(), String> {
410. 410 let tmp = path.with_extension(format!("tmp.{}", std::process::id()));
411. 411 let result = (|| {
412. 412 let mut f =
413. 413 std::fs::File::create(&tmp).map_err(|e| format!("rewrite {}: {e}", path.display()))?;
414. 414 use std::io::Write;
415. 415 f.write_all(contents.as_bytes())
416. 416 .map_err(|e| format!("rewrite {}: {e}", path.display()))?;
417. 417 f.sync_all()
418. 418 .map_err(|e| format!("rewrite {}: {e}", path.display()))?;
419. 419 std::fs::rename(&tmp, path).map_err(|e| format!("replace {}: {e}", path.display()))
420. 420 })();
421. 421 if result.is_err() {
422. 422 let _ = std::fs::remove_file(&tmp);
423. 423 }
424. 424 result
425. 425}
426. 426
427. 427/// Rewrite-not-tombstone forget: removes exactly one block (the first whose
428. 428/// id matches) and returns the number of bytes deleted. Everything outside
429. 429/// the removed span — preambles, blank separators, hand-edited prose — is
430. 430/// preserved byte-for-byte.
431. 431pub fn forget_note(path: &Path, note_id: &str) -> Result<usize, String> {
432. 432 let _lock = StoreLock::acquire(path)?;
433. 433 let raw = load_raw(path)?;
434. 434 for span in note_spans(&raw) {
435. 435 if span.id != note_id {
436. 436 continue;
437. 437 }
438. 438 let mut out = String::with_capacity(raw.len() - (span.end - span.start));
439. 439 out.push_str(&raw[..span.start]);
440. 440 out.push_str(&raw[span.end..]);
441. 441 persist_locked(path, out)?;
442. 442 return Ok(span.end - span.start);
443. 443 }
444. 444 Err(format!("no note '{note_id}' in {}", path.display()))
445. 445}
446. 446
447. 447/// Replace one block's body while keeping its provenance header line
448. 448/// verbatim — including any unknown/garbled tokens a hand-edit introduced.
449. 449pub fn amend_note(path: &Path, note_id: &str, new_text: &str) -> Result<(), String> {
450. 450 let text = new_text.trim();
451. 451 if text.is_empty() {
452. 452 return Err("note must not be empty".into());
453. 453 }
454. 454 if text.len() > 128 * 1024 {
455. 455 return Err("note exceeds the 128 KiB limit".into());
456. 456 }
457. 457 let _lock = StoreLock::acquire(path)?;
458. 458 let raw = load_raw(path)?;
459. 459 for span in note_spans(&raw) {
460. 460 if span.id != note_id {
461. 461 continue;
462. 462 }
463. 463 let old = &raw[span.start..span.end];
464. 464 let header_end = old.find('\n').unwrap_or(old.len());
465. 465 let rebuilt = format!("{}\n{text}\n", &old[..header_end]);
466. 466 let mut out = String::with_capacity(raw.len() - old.len() + rebuilt.len());
467. 467 out.push_str(&raw[..span.start]);
468. 468 out.push_str(&rebuilt);
469. 469 out.push_str(&raw[span.end..]);
470. 470 return persist_locked(path, out);
471. 471 }
472. 472 Err(format!("no note '{note_id}' in {}", path.display()))
473. 473}
474. 474
475. 475/// `2026-08-23T12:00:00+00:00 [decision] tag=x session=abc` → parts.
476. 476fn parse_header(rest: &str) -> Option<(DateTime<Utc>, String, String, String)> {
477. 477 let mut parts = rest.splitn(2, char::is_whitespace);
478. 478 let ts_raw = parts.next()?.trim();
479. 479 let ok_ts = DateTime::parse_from_rfc3339(ts_raw).ok()?;
480. 480 let tail = parts.next().unwrap_or("").trim();
481. 481
482. 482 let mut kind = "note".to_string();
483. 483 let mut remainder = tail;
484. 484 if let Some(after) = tail.strip_prefix('[')
485. 485 && let Some((inner, r)) = after.split_once(']')
486. 486 {
487. 487 kind = inner.trim().to_string();
488. 488 remainder = r.trim();
489. 489 }
490. 490
491. 491 let mut tag = String::new();
492. 492 let mut session = String::new();
493. 493 let mut leftover = String::new();
494. 494 for token in remainder.split_whitespace() {
495. 495 if let Some(v) = token.strip_prefix("tag=") {
496. 496 tag = v.to_string();
497. 497 } else if let Some(v) = token.strip_prefix("session=") {
498. 498 session = v.to_string();
499. 499 } else if !token.is_empty() {
500. 500 leftover.push_str(token);
501. 501 leftover.push(' ');
502. 502 }
503. 503 }
504. 504 // Unknown trailing tokens are preserved as a pseudo-tag so nothing a
505. 505 // human typed disappears.
506. 506 if tag.is_empty() && !leftover.trim().is_empty() {
507. 507 tag = leftover.trim().to_string();
508. 508 }
509. 509 Some((ok_ts.with_timezone(&Utc), kind, tag, session))
510. 510}
511. 511
512. 512#[cfg(test)]
513. 513mod tests {
514. 514 #![allow(clippy::unwrap_used, clippy::expect_used)]
515. 515 use super::*;
516. 516
517. 517 #[test]
518. 518 fn append_then_parse_roundtrips() {
519. 519 let dir = tempfile::tempdir().unwrap();
520. 520 let home = dir.path();
521. 521 let cwd = dir.path().join("ws");
522. 522 std::fs::create_dir_all(&cwd).unwrap();
523. 523
524. 524 let b = append_note(
525. 525 home,
526. 526 &cwd,
527. 527 "decision",
528. 528 "deploy",
529. 529 "sess-1",
530. 530 "pause before rollbacks",
531. 531 )
532. 532 .unwrap();
533. 533 let notes = list_notes(home, &cwd);
534. 534 assert_eq!(notes.len(), 1);
535. 535 assert_eq!(notes[0], b);
536. 536 assert_eq!(notes[0].kind, "decision");
537. 537 assert_eq!(notes[0].tag, "deploy");
538. 538 }
539. 539
540. 540 #[test]
541. 541 fn parser_tolerates_hand_edits_and_junk() {
542. 542 let raw = "leading junk line\n\n## not a real header just text\nmore prose\n\n## 2026-08-23T10:00:00+00:00 [fact] session=abc\nthe deploy script lives in scripts/deploy.sh\ncustom user line\n";
543. 543 let blocks = parse_blocks(raw);
544. 544 // The malformed heading becomes part of the leading-junk block? No:
545. 545 // it precedes any valid header, so only the valid block survives.
546. 546 assert_eq!(blocks.len(), 1);
547. 547 assert_eq!(blocks[0].kind, "fact");
548. 548 assert_eq!(blocks[0].session_id, "abc");
549. 549 assert!(blocks[0].text.contains("deploy.sh"));
550. 550 assert!(blocks[0].text.contains("custom user line"));
551. 551 }
552. 552
553. 553 #[test]
554. 554 fn empty_note_rejected() {
555. 555 let dir = tempfile::tempdir().unwrap();
556. 556 let err = append_note(dir.path(), dir.path(), "fact", "", "s", " ");
557. 557 assert!(err.is_err());
558. 558 }
559. 559
560. 560 #[test]
561. 561 fn header_metadata_rejects_control_characters() {
562. 562 let dir = tempfile::tempdir().unwrap();
563. 563 assert!(append_note(dir.path(), dir.path(), "fact", "bad\ntag", "s", "x").is_err());
564. 564 assert!(append_note(dir.path(), dir.path(), "fact", "ok", "s\n2", "x").is_err());
565. 565 }
566. 566
567. 567 #[test]
568. 568 fn malformed_heading_remains_in_preceding_note() {
569. 569 let raw = "## 2026-08-23T10:00:00+00:00 [fact] session=s\nfirst\n## not metadata\nmore\n";
570. 570 let notes = parse_blocks(raw);
571. 571 assert_eq!(notes.len(), 1);
572. 572 assert!(notes[0].text.contains("## not metadata"));
573. 573 assert!(notes[0].text.contains("more"));
574. 574 }
575. 575
576. 576 #[test]
577. 577 fn concurrent_appends_keep_every_block_intact() {
578. 578 let dir = tempfile::tempdir().unwrap();
579. 579 let home = dir.path().to_path_buf();
580. 580 let cwd = dir.path().join("ws");
581. 581 std::fs::create_dir_all(&cwd).unwrap();
582. 582 let mut joins = Vec::new();
583. 583 for i in 0..16 {
584. 584 let home = home.clone();
585. 585 let cwd = cwd.clone();
586. 586 joins.push(std::thread::spawn(move || {
587. 587 append_note(
588. 588 &home,
589. 589 &cwd,
590. 590 "fact",
591. 591 "parallel",
592. 592 &format!("s{i}"),
593. 593 &format!("note-{i}"),
594. 594 )
595. 595 .unwrap();
596. 596 }));
597. 597 }
598. 598 for join in joins {
599. 599 join.join().unwrap();
600. 600 }
601. 601 assert_eq!(list_notes(&home, &cwd).len(), 16);
602. 602 }
603. 603
604. 604 #[test]
605. 605 fn forget_removes_exactly_one_block_preserving_rest_byte_for_byte() {
606. 606 let dir = tempfile::tempdir().unwrap();
607. 607 let home = dir.path();
608. 608 let cwd = dir.path().join("ws");
609. 609
610. 610 let a = append_note(home, &cwd, "fact", "x", "s1", "alpha note").unwrap();
611. 611 let b = append_note(home, &cwd, "decision", "y", "s2", "beta note").unwrap();
612. 612
613. 613 let block_a = format!(
614. 614 "## {} [fact] tag=x session=s1\nalpha note\n",
615. 615 a.ts.to_rfc3339()
616. 616 );
617. 617 let block_b = format!(
618. 618 "## {} [decision] tag=y session=s2\nbeta note\n",
619. 619 b.ts.to_rfc3339()
620. 620 );
621. 621 let path = home.join("memory").join(hash_cwd(&cwd)).join("MEMORY.md");
622. 622 assert_eq!(
623. 623 std::fs::read_to_string(&path).unwrap(),
624. 624 format!("{block_a}\n{block_b}\n")
625. 625 );
626. 626
627. 627 let removed = forget_note(&path, &a.id).unwrap();
628. 628 assert_eq!(removed, block_a.len());
629. 629 assert_eq!(
630. 630 std::fs::read_to_string(&path).unwrap(),
631. 631 format!("\n{block_b}\n")
632. 632 );
633. 633
634. 634 let notes = list_notes(home, &cwd);
635. 635 assert_eq!(notes.len(), 1);
636. 636 assert_eq!(notes[0].id, b.id);
637. 637
638. 638 assert!(forget_note(&path, &a.id).is_err());
639. 639 assert_eq!(
640. 640 std::fs::read_to_string(&path).unwrap(),
641. 641 format!("\n{block_b}\n")
642. 642 );
643. 643 }
644. 644
645. 645 #[test]
646. 646 fn amend_swaps_body_and_preserves_provenance_header() {
647. 647 let dir = tempfile::tempdir().unwrap();
648. 648 let home = dir.path();
649. 649 let cwd = dir.path().join("ws");
650. 650
651. 651 let n = append_note(home, &cwd, "fact", "", "s3", "original body").unwrap();
652. 652 let header = format!("## {} [fact] tag= session=s3", n.ts.to_rfc3339());
653. 653 let path = home.join("memory").join(hash_cwd(&cwd)).join("MEMORY.md");
654. 654
655. 655 amend_note(&path, &n.id, "revised body with more detail").unwrap();
656. 656
657. 657 assert_eq!(
658. 658 std::fs::read_to_string(&path).unwrap(),
659. 659 format!("{header}\nrevised body with more detail\n\n")
660. 660 );
661. 661 let notes = list_notes(home, &cwd);
662. 662 assert_eq!(notes.len(), 1);
663. 663 assert_eq!(notes[0].id, n.id);
664. 664 assert_eq!(notes[0].ts, n.ts);
665. 665 assert_eq!(notes[0].kind, n.kind);
666. 666 assert_eq!(notes[0].tag, n.tag);
667. 667 assert_eq!(notes[0].session_id, n.session_id);
668. 668 assert_eq!(notes[0].text, "revised body with more detail");
669. 669
670. 670 assert!(amend_note(&path, &n.id, " ").is_err());
671. 671 assert!(amend_note(&path, "deadbeef", "x").is_err());
672. 672 }
673. 673
674. 674 #[test]
675. 675 fn amend_preserves_hand_edited_header_tokens() {
676. 676 let dir = tempfile::tempdir().unwrap();
677. 677 let path = dir.path().join("USER.md");
678. 678 let raw = "## 2026-08-23T10:00:00+00:00 [fact] tag=custom=foo session=abc mystery-token\ncold body\n";
679. 679 std::fs::write(&path, raw).unwrap();
680. 680 let id = parse_blocks(raw)[0].id.clone();
681. 681
682. 682 amend_note(&path, &id, "warm body").unwrap();
683. 683 let after = std::fs::read_to_string(&path).unwrap();
684. 684 assert!(after.starts_with(
685. 685 "## 2026-08-23T10:00:00+00:00 [fact] tag=custom=foo session=abc mystery-token\n"
686. 686 ));
687. 687 assert!(after.ends_with("warm body\n"));
688. 688 }
689. 689
690. 690 #[test]
691. 691 fn forget_leaves_hand_edited_garbage_between_blocks_intact() {
692. 692 let dir = tempfile::tempdir().unwrap();
693. 693 let home = dir.path();
694. 694 let cwd = dir.path().join("ws");
695. 695 std::fs::create_dir_all(&cwd).unwrap();
696. 696 let path = home.join("memory").join(hash_cwd(&cwd)).join("MEMORY.md");
697. 697 std::fs::create_dir_all(path.parent().unwrap()).unwrap();
698. 698 let raw = "prelude scribble\n\n## 2026-08-23T10:00:00+00:00 [fact] tag=a session=s1\nfirst note\nHUMAN GARBAGE ## fake header here\nmore scribble\n\n## 2026-08-23T11:00:00+00:00 [decision] tag=b session=s2\nsecond note";
699. 699 std::fs::write(&path, raw).unwrap();
700. 700
701. 701 let notes = list_notes(home, &cwd);
702. 702 assert_eq!(notes.len(), 2);
703. 703 assert!(notes[0].text.contains("HUMAN GARBAGE"));
704. 704
705. 705 let removed = forget_note(&path, &notes[1].id).unwrap();
706. 706 let after = std::fs::read_to_string(&path).unwrap();
707. 707 assert_eq!(removed, raw.len() - after.len());
708. 708 assert_eq!(after, &raw[..raw.len() - removed]);
709. 709 assert!(after.contains("HUMAN GARBAGE"));
710. 710
711. 711 let removed2 = forget_note(&path, &notes[0].id).unwrap();
712. 712 assert_eq!(
713. 713 std::fs::read_to_string(&path).unwrap(),
714. 714 "prelude scribble\n\n\n"
715. 715 );
716. 716 assert!(list_notes(home, &cwd).is_empty());
717. 717 assert_eq!(
718. 718 removed + removed2 + "prelude scribble\n\n\n".len(),
719. 719 raw.len()
720. 720 );
721. 721 }
722. 722
723. 723 #[test]
724. 724 fn profile_tier_roundtrips() {
725. 725 let dir = tempfile::tempdir().unwrap();
726. 726 let home = dir.path();
727. 727
728. 728 assert_eq!(
729. 729 profile_path(home),
730. 730 home.join("memory").join("user").join("USER.md")
731. 731 );
732. 732 assert!(list_profile_notes(home).is_empty());
733. 733
734. 734 let p = append_profile_note(
735. 735 home,
736. 736 "preference",
737. 737 "editor",
738. 738 "prefers vim bindings",
739. 739 "sess-u",
740. 740 )
741. 741 .unwrap();
742. 742 let q =
743. 743 append_profile_note(home, "fact", "timezone", "works in UTC+5:30", "sess-u").unwrap();
744. 744
745. 745 let notes = list_profile_notes(home);
746. 746 assert_eq!(notes.len(), 2);
747. 747 assert_eq!(notes[0], p);
748. 748 assert_eq!(notes[1], q);
749. 749 assert_eq!(notes[0].tag, "editor");
750. 750
751. 751 let again = list_profile_notes(home);
752. 752 assert_eq!(again[0].id, p.id);
753. 753 assert_eq!(again[1].id, q.id);
754. 754
755. 755 let cwd = dir.path().join("ws");
756. 756 std::fs::create_dir_all(&cwd).unwrap();
757. 757 assert!(list_notes(home, &cwd).is_empty());
758. 758
759. 759 assert!(append_profile_note(home, "fact", "", " ", "sess-u").is_err());
760. 760 }
761. 761
762. 762 #[test]
763. 763 fn load_matrix_scales_real_store_from_low_to_high() {
764. 764 let dir = tempfile::tempdir().unwrap();
765. 765 let home = dir.path();
766. 766 let cwd = home.join("load-workspace");
767. 767 std::fs::create_dir_all(&cwd).unwrap();
768. 768 let mut expected = 0;
769. 769 for (label, count) in [("low", 10usize), ("medium", 500), ("high", 4_096)] {
770. 770 for i in 0..count {
771. 771 append_note(
772. 772 home,
773. 773 &cwd,
774. 774 "fact",
775. 775 label,
776. 776 "load-test",
777. 777 &format!("{label} load item {i}: durable memory remains searchable"),
778. 778 )
779. 779 .unwrap();
780. 780 }
781. 781 expected += count;
782. 782 let notes = list_notes(home, &cwd);
783. 783 assert_eq!(notes.len(), expected, "{label} load phase");
784. 784 assert!(notes.iter().all(|n| n.session_id == "load-test"));
785. 785 }
786. 786 let raw = std::fs::read_to_string(memory_path(home, &cwd)).unwrap();
787. 787 assert!(raw.len() > 500_000, "high-load store unexpectedly small");
788. 788 }
789. 789
790. 790 #[test]
791. 791 fn old_notes_are_retained_until_explicitly_forgotten() {
792. 792 let dir = tempfile::tempdir().unwrap();
793. 793 let home = dir.path();
794. 794 let cwd = home.join("retention-workspace");
795. 795 let path = memory_path(home, &cwd);
796. 796 std::fs::create_dir_all(path.parent().unwrap()).unwrap();
797. 797 let raw = "## 2020-01-01T00:00:00+00:00 [fact] tag=old session=historical\nlong-lived knowledge\n";
798. 798 std::fs::write(&path, raw).unwrap();
799. 799 let notes = list_notes(home, &cwd);
800. 800 assert_eq!(notes.len(), 1);
801. 801 assert_eq!(notes[0].text, "long-lived knowledge");
802. 802 forget_note(&path, &notes[0].id).unwrap();
803. 803 assert!(list_notes(home, &cwd).is_empty());
804. 804 }
805. 805
806. 806 #[test]
807. 807 fn cleanup_removes_only_abandoned_artifacts() {
808. 808 let dir = tempfile::tempdir().unwrap();
809. 809 let home = dir.path();
810. 810 let cwd = home.join("cleanup-workspace");
811. 811 let path = memory_path(home, &cwd);
812. 812 append_note(home, &cwd, "fact", "keep", "s", "keep this note").unwrap();
813. 813 let lock = path.with_extension("lock");
814. 814 let tmp = path.with_file_name("MEMORY.tmp.crashed");
815. 815 std::fs::write(&lock, "pid=dead\n").unwrap();
816. 816 std::fs::write(&tmp, "partial\n").unwrap();
817. 817
818. 818 let report = cleanup_artifacts(home, Duration::ZERO);
819. 819 assert_eq!(report.removed_locks, 1);
820. 820 assert_eq!(report.removed_temps, 1);
821. 821 assert!(path.is_file());
822. 822 assert_eq!(list_notes(home, &cwd).len(), 1);
823. 823 assert!(!lock.exists());
824. 824 assert!(!tmp.exists());
825. 825 }
826. 826}
827. 827