1  /**
 2   * Days elapsed since mtime.  Floor-rounded — 0 for today, 1 for
 3   * yesterday, 2+ for older.  Negative inputs (future mtime, clock skew)
 4   * clamp to 0.
 5   */
 6  export function memoryAgeDays(mtimeMs: number): number {
 7    return Math.max(0, Math.floor((Date.now() - mtimeMs) / 86_400_000))
 8  }
 9  
10  /**
11   * Human-readable age string.  Models are poor at date arithmetic —
12   * a raw ISO timestamp doesn't trigger staleness reasoning the way
13   * "47 days ago" does.
14   */
15  export function memoryAge(mtimeMs: number): string {
16    const d = memoryAgeDays(mtimeMs)
17    if (d === 0) return 'today'
18    if (d === 1) return 'yesterday'
19    return `${d} days ago`
20  }
21  
22  /**
23   * Plain-text staleness caveat for memories >1 day old.  Returns ''
24   * for fresh (today/yesterday) memories — warning there is noise.
25   *
26   * Use this when the consumer already provides its own wrapping
27   * (e.g. messages.ts relevant_memories → wrapMessagesInSystemReminder).
28   *
29   * Motivated by user reports of stale code-state memories (file:line
30   * citations to code that has since changed) being asserted as fact —
31   * the citation makes the stale claim sound more authoritative, not less.
32   */
33  export function memoryFreshnessText(mtimeMs: number): string {
34    const d = memoryAgeDays(mtimeMs)
35    if (d <= 1) return ''
36    return (
37      `This memory is ${d} days old. ` +
38      `Memories are point-in-time observations, not live state — ` +
39      `claims about code behavior or file:line citations may be outdated. ` +
40      `Verify against current code before asserting as fact.`
41    )
42  }
43  
44  /**
45   * Per-memory staleness note wrapped in <system-reminder> tags.
46   * Returns '' for memories ≤ 1 day old.  Use this for callers that
47   * don't add their own system-reminder wrapper (e.g. FileReadTool output).
48   */
49  export function memoryFreshnessNote(mtimeMs: number): string {
50    const text = memoryFreshnessText(mtimeMs)
51    if (!text) return ''
52    return `<system-reminder>${text}</system-reminder>\n`
53  }