Module timeline 

Timeline — chronological memory log with time-window queries.

Every store appends a TimelineEntry alongside the main append.bin, giving the agent the ability to recall “what happened today/yesterday/ last session” without relying on similarity ranking.

Binary format: output/timeline.bin (magic TML1) Entry: 25 bytes header + text bytes [u8 magic 4 = “TML1”] [u64 ts_ms] [u8 layer_id] [u8 importance] [u8 depth] [u8 status (0=open, 1=resolved, 2=archived, 3=normal)] [u32 text_len] [bytes text_len]

Magic is written only once (file header). Subsequent entries are concatenated. Resolved/archived status flips are written as new entries so the log stays append-only.

Structs

TimelineEntry

One chronological memory entry.

Enums

TimeWindow

A time window descriptor used for filtering.

Constants

MAX_TEXT_LEN

STATUS_ARCHIVED

STATUS_NORMAL

Status byte in TimelineEntry.

STATUS_OPEN

STATUS_RESOLVED

Functions

append_entry

Append a TimelineEntry. Thread-safe-ish via O_APPEND on POSIX; on Windows the append mode also appends, but we serialize via FileLock at the caller.

filter

Filter entries by time window. For LastSession, finds the last gap

filter_at

Same as filter but with explicit now_ms for deterministic testing.

format_ts

Format an epoch_ms into “YYYY-MM-DD HH:MM” using a small pure-Rust calendar (UTC). Good enough for human display in tool output.

now_epoch_ms

Current epoch in milliseconds.

parse_iso8601_to_epoch_ms

Minimal ISO-8601 parser. Accepts: YYYY-MM-DD YYYY-MM-DDTHH:MM YYYY-MM-DDTHH:MM:SS YYYY-MM-DD HH:MM:SS Returns epoch_ms (UTC) or None.

read_all

Read all entries from the timeline log. Returns them in append order (oldest first) so the caller can sort/filter by window.