Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* Time helpers for the Brain layer. A true leaf: it imports nothing from
* this repository, which is what lets every layer above depend on it
* without closing a cycle (`tests/core/architecture/import-cycles.test.ts`).
*
* ## Formatting half
*
* These emit canonical UTC strings expected by the on-disk formats
* (frontmatter, log headings, run ids):
*
* - `isoSecond` → `YYYY-MM-DDTHH:MM:SSZ` (no sub-second precision).
* The log heading shape is `HH:MM:SS` only, so anything finer is
* silently dropped by `appendLogEvent`; truncating here keeps the
* return value consistent with what actually lands on disk.
* - `isoDate` → `YYYY-MM-DD` (UTC calendar day).
*
* Both default to `new Date()` so callers can do `isoSecond()` without
* threading the clock when they don't need determinism.
*
* ## Measurement half (evidence-at-the-boundary, unit B3)
*
* "How old is this file by wall clock, from its mtime" existed as five
* independent copies, spelling one day three different ways
* (`86_400_000`, `24 * 3600 * 1000`, `24 * 60 * 60 * 1000`) and - worse -
* disagreeing about the stat failure. `profile-doc` treated it as stale,
* `idea-discovery` returned age zero so an unreadable note read as brand
* new, `stale-watch` let the raw `ENOENT` abort the whole scan. Three
* policies for one event, none of them chosen at the site that had to
* live with it.
*
* {@link fileAgeMs} therefore returns `null` and every caller must say
* what it means. The rejected alternative was a discriminated result
* (`{ ok: true, ageMs } | { ok: false, reason }`), which carries a named
* reason but costs a shape and a guard at six call sites for a
* distinction none of them acts on: absent and unreadable both mean
* "this measurement did not happen", and the callers that want to name
* the path already have it in hand. `null` is the smallest thing
* `noUncheckedIndexedAccess`-grade strictness will not let a caller
* ignore, and that unignorability is the whole point - a value that
* cannot be silently averaged into an age. What is deliberately NOT
* offered is a default-carrying overload: `fileAgeMs(path, now, 0)`
* would rebuild the exact defect this unit removes.
*
* Neither function clamps a negative age. A file stamped in the future
* is a real condition (clock skew, a copied mtime) and the callers that
* want it floored - `weekly-brief`'s recency label - floor it themselves
* where the floor is part of that surface's meaning, not of the
* measurement.
*/
import { statSync } from "node:fs";
/**
* Milliseconds in one day. The single spelling for every day-scale
* conversion in the Brain layer; see the module docblock for the three
* it replaced.
*/
export const MS_PER_DAY = 86_400_000;
/**
* A duration in milliseconds as completed whole days, truncating the
* partial day.
*
* Pure unit conversion, deliberately separate from {@link fileAgeMs}:
* one of these can fail to measure and the other cannot, and folding
* them into a single `fileAgeDays` would force the sub-day callers
* (`profile-doc` gates on seconds) back onto their own arithmetic. It
* takes a DURATION rather than a pair of instants because that is what
* {@link fileAgeMs} hands back and what four of the five re-pointed
* sites already had; a two-instant signature would have made each of
* them spell the subtraction again, which is half of what was
* duplicated. Negative for a negative duration; see the module docblock.
*/
export function msToWholeDays(durationMs: number): number {
return Math.floor(durationMs / MS_PER_DAY);
}
/**
* Wall-clock age of the file at `path` in milliseconds, measured from
* its mtime against the caller-supplied `nowMs`.
*
* `null` means the age could not be measured at all - the path is
* absent, or it exists behind a directory that denies traversal. It is
* NOT an age, and no caller may treat it as one; see the module
* docblock for why this is a `null` rather than a discriminated result
* and why there is no default-carrying overload.
*
* `nowMs` is required rather than defaulted so a caller that already
* holds a pinned clock cannot accidentally measure against a second,
* later one mid-scan.
*
* A negative age within the clock's own millisecond is age zero: `nowMs`
* is a whole millisecond (`Date.now()`) while the filesystem stamps a
* sub-millisecond mtime, so a file written in that millisecond would
* otherwise read as stamped in the future - a precision artefact, not
* clock skew. Every other age keeps its fraction, so an mtime a whole
* millisecond or more ahead still reads negative.
*/
export function fileAgeMs(path: string, nowMs: number): number | null {
try {
const mtimeMs = statSync(path).mtimeMs;
const ageMs = nowMs - mtimeMs;
return ageMs < 0 && Math.floor(mtimeMs) === Math.floor(nowMs) ? 0 : ageMs;
} catch {
return null;
}
}
/** ISO-8601 UTC at whole-second precision (`YYYY-MM-DDTHH:MM:SSZ`). */
export function isoSecond(d: Date = new Date()): string {
// `Date#toISOString` always emits `YYYY-MM-DDTHH:MM:SS.sssZ`; strip
// the milliseconds segment in-place to land on the canonical shape.
return d.toISOString().replace(/\.\d{3}Z$/, "Z");
}
/** ISO-8601 UTC calendar day (`YYYY-MM-DD`). */
export function isoDate(d: Date = new Date()): string {
return d.toISOString().slice(0, 10);
}
/**
* Compact UTC run-id stamp (`YYYY-MM-DD-HHMMSS`). Whole-second
* precision, no separators inside the time-of-day segment, so the
* result is a filesystem-safe run-id stem under
* {@link validateRunId} (`[A-Za-z0-9][A-Za-z0-9._-]*`). Shared by the
* `dream` run-id formatter and the destructive-snapshot gate so both
* mint ids the same way.
*/
export function compactRunStamp(d: Date = new Date()): string {
const yyyy = d.getUTCFullYear().toString().padStart(4, "0");
const mm = (d.getUTCMonth() + 1).toString().padStart(2, "0");
const dd = d.getUTCDate().toString().padStart(2, "0");
const hh = d.getUTCHours().toString().padStart(2, "0");
const mi = d.getUTCMinutes().toString().padStart(2, "0");
const ss = d.getUTCSeconds().toString().padStart(2, "0");
return `${yyyy}-${mm}-${dd}-${hh}${mi}${ss}`;
}
/**
* Render the gap between an ISO-8601 timestamp and `now` as a short,
* human-readable relative-age label — "just now", "3m ago", "2h ago",
* "5d ago", "2w ago", "3mo ago", "1y ago". Used by session-start
* surfaces (the morning brief's typed recent-activity timeline) so an
* operator can scan recency at a glance without parsing absolute times.
*
* Deterministic given the two timestamps. A future `isoTimestamp` clamps
* to "just now" so a clock skew cannot produce a nonsensical "-3m ago".
* Returns the empty string for an unparseable input so call sites can
* omit the label without a try/catch at every one of them.
*
* Accepts both whole-second ISO (`2026-05-01T00:00:00Z`) and calendar-day
* (`2026-05-01`) shapes; `Date.parse` handles both.
*/
export function relativeAge(isoTimestamp: string, now: Date = new Date()): string {
const ts = Date.parse(isoTimestamp);
if (Number.isNaN(ts)) return "";
let diffMs = now.getTime() - ts;
if (diffMs < 0) diffMs = 0;
const sec = Math.floor(diffMs / 1000);
if (sec < 60) return "just now";
const min = Math.floor(sec / 60);
if (min < 60) return `${min}m ago`;
const hr = Math.floor(min / 60);
if (hr < 24) return `${hr}h ago`;
const day = Math.floor(hr / 24);
if (day < 7) return `${day}d ago`;
const wk = Math.floor(day / 7);
if (wk < 5) return `${wk}w ago`;
const mo = Math.floor(day / 30);
if (day < 365) return `${mo}mo ago`;
const yr = Math.floor(day / 365);
return `${yr}y ago`;
}