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
/**
* Hybrid logical clock (design D3): pure arithmetic, no I/O.
*
* A stamp is `{ physical, counter }`, written `"<physical_ms>.<counter>"`.
* Records fold in (hlc, device, id) order, and two rules keep that order
* causal across machines whose wall clocks disagree:
*
* - Send: when the wall clock is ahead of the local clock's physical part,
* the stamp is the wall clock with counter 0; otherwise the physical
* part stays and the counter increments. Every stamp a device issues is
* therefore strictly greater than the one before, even when the wall
* clock steps backwards.
* - Receive: observing a remote stamp raises the local clock to at least
* that stamp. The next send then orders after it, so a record written
* in reply to a remote record folds after it even when the replying
* machine's wall clock is behind. A remote stamp more than
* {@link HLC_MAX_DRIFT_MS} ahead of the wall clock (a broken clock, a
* damaged line) is not adopted, so one bad record cannot push this
* device's clock into the far future for good.
*
* Persistence of the local clock per device lives in `clock-store.ts`.
*/
/** One hybrid logical clock stamp. */
export interface Hlc {
/** Milliseconds since the Unix epoch. */
readonly physical: number;
/** Tie-breaker within one physical millisecond. */
readonly counter: number;
}
/** Remote stamps further ahead of the wall clock than this are not adopted (one day). */
export const HLC_MAX_DRIFT_MS = 24 * 60 * 60 * 1000;
/** The clock before anything was sent or observed. */
export const HLC_ZERO: Hlc = Object.freeze({ physical: 0, counter: 0 });
/** Non-negative integers without leading zeros: `0`, `7`, `1762400000123`. */
const HLC_RE = /^(0|[1-9]\d{0,15})\.(0|[1-9]\d{0,9})$/;
/** The text form written into the envelope's `hlc` field. */
export function formatHlc(clock: Hlc): string {
return `${clock.physical}.${clock.counter}`;
}
/** Parse the text form; `null` for anything that is not exactly one stamp. */
export function parseHlc(text: string): Hlc | null {
const match = HLC_RE.exec(text);
if (match === null) return null;
const physical = Number(match[1]);
const counter = Number(match[2]);
if (!Number.isSafeInteger(physical) || !Number.isSafeInteger(counter)) return null;
return { physical, counter };
}
/** Negative, zero or positive as `a` orders before, with or after `b`. */
export function compareHlc(a: Hlc, b: Hlc): number {
if (a.physical !== b.physical) return a.physical < b.physical ? -1 : 1;
if (a.counter !== b.counter) return a.counter < b.counter ? -1 : 1;
return 0;
}
/** The larger of two stamps. */
export function maxHlc(a: Hlc, b: Hlc): Hlc {
return compareHlc(a, b) >= 0 ? a : b;
}
/**
* Send rule: the stamp for a new local record, given the local clock and
* the wall clock in milliseconds. The result is also the new local clock.
*/
export function sendHlc(local: Hlc, wallMs: number): Hlc {
const wall = Math.max(0, Math.floor(wallMs));
if (wall > local.physical) return { physical: wall, counter: 0 };
return { physical: local.physical, counter: local.counter + 1 };
}
/**
* Receive rule: the local clock after observing `remote`. It never moves
* backwards and never falls below the remote stamp, so the next
* {@link sendHlc} orders after everything observed so far. The wall clock
* only matters when it is ahead of both. A remote stamp more than
* {@link HLC_MAX_DRIFT_MS} ahead of the wall clock is ignored.
*/
export function receiveHlc(local: Hlc, remote: Hlc, wallMs: number): Hlc {
const wall = Math.max(0, Math.floor(wallMs));
const adoptable = remote.physical - wall <= HLC_MAX_DRIFT_MS;
const known = adoptable ? maxHlc(local, remote) : local;
if (wall > known.physical) return { physical: wall, counter: 0 };
return known;
}