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
/**
* The one parser for the `since` / `until` window bounds the write-ledger
* readers accept (`listNoteWrites`, `listWriteDestinations`).
*
* Two readers grew the same three constants and the same completion rule,
* and neither copy validated: a bound that was neither spelling -
* `yesterday`, `03/01/2026` - fell through the regex untouched, compared
* lexicographically against canonical timestamps, matched no log day, and
* the query answered a clean, wrong empty. One parser that THROWS a named
* error turns that silent empty into a usage error the surface can blame
* on the flag the caller mistyped.
*
* Accepted spellings, which the schema text on both surfaces promises:
*
* - a bare `YYYY-MM-DD`, completed to the day's start or end by the
* caller's suffix - an `--until 2026-03-04` means "through the end of
* the fourth", not "up to midnight starting it";
* - an ISO-8601 UTC timestamp in the shape the log writer emits
* (`YYYY-MM-DDTHH:MM:SSZ`, optional sub-second precision). The strict
* canonical shape keeps a bound in the same vocabulary the log and
* the revert-plan digests carry - an offset spelling or a missing
* seconds field is refused rather than normalized - but the window
* comparison itself orders by instant ({@link timestampInWindow}):
* the log writer stamps whole seconds while the JSONL reader admits
* sub-second foreign lines, and a plain string compare would order
* `…56.789Z` before `…56Z`, admitting an entry `--until` should
* exclude and dropping one `--since` should include.
*/
import { neutralizeSingleLine } from "../untrusted-source.ts";
/** A bare `YYYY-MM-DD`, which both bounds accept as shorthand for a day. */ export const ISO_DATE_ONLY_RE =
/^\d{4}-\d{2}-\d{2}$/;
/** How a bare date is completed at the window's lower end. */
export const DAY_START_SUFFIX = "T00:00:00Z";
/**
* How a bare date is completed at the window's upper end: through the
* day. The suffix reaches past the whole last second because the JSONL
* reader admits sub-second foreign lines - ending at `…59Z` would drop
* an entry inside the bound day's final fraction, and "through the end
* of the fourth" has to mean all of it.
*/
export const DAY_END_SUFFIX = "T23:59:59.999Z";
/** Characters of an ISO-8601 timestamp that spell its date. */
export const DATE_LENGTH = 10;
/** Which end of the window a bound names, so an error can blame the flag. */
export type WindowBoundEdge = "since" | "until";
/**
* A window bound in neither accepted spelling. The message names the flag
* (`--since` / `--until`) and the rejected value, because "empty" is what
* a misread bound looks like and the caller deserves the difference. The
* raw value stays on {@link value} for programmatic callers; the message
* carries only the fenced form.
*/
export class LogWindowBoundError extends Error {
readonly edge: WindowBoundEdge;
readonly value: string;
constructor(edge: WindowBoundEdge, value: string) {
super(
`--${edge} must be YYYY-MM-DD or an ISO-8601 UTC timestamp, got '${fenceBoundValue(value)}'`,
);
this.name = "LogWindowBoundError";
this.edge = edge;
this.value = value;
}
}
/**
* The longest stretch of a rejected bound the error message carries.
* The message reaches the model through INVALID_PARAMS - the same
* model-facing channel the log parse warnings fence at their source - so
* the value is neutralized to one line, then capped, the same rule
* `log-jsonl.ts` applies to its own warnings.
*/
const MAX_BOUND_VALUE_CHARS = 120;
/** Fence one rejected bound for interpolation into the error message. */
function fenceBoundValue(value: string): string {
const neutralized = neutralizeSingleLine(value);
return neutralized.length > MAX_BOUND_VALUE_CHARS
? `${neutralized.slice(0, MAX_BOUND_VALUE_CHARS)}…`
: neutralized;
}
/** Canonical ISO-8601 UTC timestamp shape, the log writer's own. */
const ISO_UTC_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
/**
* Complete and validate one window bound, ready for the readers' window
* comparisons against canonical log timestamps.
*
* A bare date is completed with `suffix` and calendar-checked by parsing
* (`2026-13-01` has the right shape and no such day); a full timestamp is
* passed through only when it is already canonical. Everything else throws
* {@link LogWindowBoundError} naming the `edge` - since or until - that
* carried it.
*/
export function parseWindowBound(
value: string,
edge: WindowBoundEdge,
suffix: typeof DAY_START_SUFFIX | typeof DAY_END_SUFFIX,
): string {
if (ISO_DATE_ONLY_RE.test(value)) {
const completed = `${value}${suffix}`;
if (Number.isFinite(Date.parse(completed))) return completed;
} else if (ISO_UTC_TS_RE.test(value) && Number.isFinite(Date.parse(value))) {
return value;
}
throw new LogWindowBoundError(edge, value);
}
/**
* Whether one log entry timestamp falls inside the parsed window.
*
* Both sides are compared as instants (epoch milliseconds), not strings:
* a bound at whole seconds and an entry carrying sub-second precision
* order opposite ways under a plain string compare (`…56.789Z` sorts
* before `…56Z`), and an until that admits an entry it should exclude -
* or a since that drops one it should include - is exactly the kind of
* wrong this module exists to make loud. A null bound leaves that end
* unbounded.
*
* A timestamp that parses to nothing is outside every bounded window:
* the JSONL reader admits a value by shape, so a right-shaped but
* impossible instant (month 13, hour 99) reaches here as NaN, every NaN
* comparison is false, and an unguarded predicate would fail open -
* answering "inside" for any window and riding the bad entry into every
* bounded read, revert plans included. Only a fully unbounded window,
* which filters nothing, still shows it.
*/
export function timestampInWindow(
timestamp: string,
since: string | null,
until: string | null,
): boolean {
const at = Date.parse(timestamp);
if (!Number.isFinite(at)) return since === null && until === null;
if (since !== null && at < Date.parse(since)) return false;
if (until !== null && at > Date.parse(until)) return false;
return true;
}