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 digest roster and comparison (design D6, task 1.7). Pure: the
* caller reads the records, this module decides what doctor reports.
*
* - Roster: the devices with records in the partition during the last
* 30 days, minus devices retired by a `device-retire` human record. A
* retired device that writes again after its retire record (a reused
* id, a machine brought back) is on the roster again.
* - Silent: a roster device that has published no digest in the partition
* for 7 days. A device first seen less than 7 days ago gets that much
* grace before it is reported.
* - Divergent: two devices whose latest digests over the SAME cut carry a
* different hash for a fold. Digests over different cuts are never
* compared, so an offline device, an idle device or a machine without
* a partition can neither stall the check nor raise a false alarm; it
* is at most reported as silent.
*
* Only digests from the last 7 days are compared, so a divergence that a
* fixed release no longer produces stops being reported once its digests
* age out.
*/
import {
DAY_MS,
DIGEST_COMPARE_WINDOW_DAYS,
DIGEST_ROSTER_WINDOW_DAYS,
DIGEST_SILENCE_DAYS,
STATE_DIGEST_FOLDS,
STATE_DIGEST_REQUIRED_FOLDS,
STATE_DIGEST_KIND,
type StateDigestFold,
type StorePartition,
} from "./constants.ts";
import { latestRetirements, wroteAfter } from "./device-retirement.ts";
import { compareRecords, type StoreRecord } from "./envelope.ts";
import { prepareRecords } from "./fold.ts";
import { parseHlc } from "./hlc.ts";
import type { DigestBody } from "./state-digest.ts";
const SHA256_RE = /^[0-9a-f]{64}$/;
const physical = (record: StoreRecord): number => parseHlc(record.hlc)!.physical;
/** A digest record whose body has the digest shape, or `null`. */
export function parseDigest(record: StoreRecord): DigestBody | null {
if (record.kind !== STATE_DIGEST_KIND) return null;
const body = record.body as Partial<Record<keyof DigestBody, unknown>>;
if (typeof body.partition !== "string" || !Array.isArray(body.cut)) return null;
if (typeof body.cut_hash !== "string" || !SHA256_RE.test(body.cut_hash)) return null;
const folds = body.folds as Record<string, unknown> | undefined;
if (typeof folds !== "object" || folds === null) return null;
for (const fold of STATE_DIGEST_REQUIRED_FOLDS) {
if (typeof folds[fold] !== "string" || !SHA256_RE.test(folds[fold] as string)) return null;
}
// A fold added later (`topics`) is optional; when present it must be a hash.
for (const fold of STATE_DIGEST_FOLDS) {
if (
folds[fold] !== undefined &&
!(typeof folds[fold] === "string" && SHA256_RE.test(folds[fold]))
) {
return null;
}
}
return record.body as unknown as DigestBody;
}
export interface RosterDevice {
readonly device: string;
/** Physical time of its first and last record in the window. */
readonly firstSeenMs: number;
readonly lastSeenMs: number;
}
export interface Roster {
readonly devices: ReadonlyArray<RosterDevice>;
/** Devices with records in the window that a human retired. */
readonly retired: ReadonlyArray<string>;
}
/**
* The roster of a partition at `nowMs`. `retireRecords` are the
* `device-retire` records to apply (they live in the `shared` partition's
* `settings` stream, so the private partition's roster uses them too);
* only those with `authority: "human"` count.
*/
export function computeRoster(
partitionRecords: Iterable<StoreRecord>,
retireRecords: Iterable<StoreRecord>,
nowMs: number,
): Roster {
const since = nowMs - DIGEST_ROSTER_WINDOW_DAYS * DAY_MS;
const seen = new Map<string, { first: number; last: StoreRecord }>();
const prepared = prepareRecords(partitionRecords);
const all = [...prepared.records, ...prepared.pending].toSorted(compareRecords);
for (const record of all) {
const ms = physical(record);
if (ms < since) continue;
const entry = seen.get(record.device);
if (entry === undefined) seen.set(record.device, { first: ms, last: record });
else entry.last = record; // fold order: later records come later
}
// The one retirement rule (`device-retirement.ts`): retired unless it
// wrote again after its latest human retirement.
const retiredAt = latestRetirements(prepareRecords(retireRecords).records);
const devices: RosterDevice[] = [];
const retired: string[] = [];
for (const device of [...seen.keys()].toSorted()) {
const { first, last } = seen.get(device)!;
const retire = retiredAt.get(device);
if (retire !== undefined && !wroteAfter(last, retire)) {
retired.push(device);
continue;
}
devices.push({ device, firstSeenMs: first, lastSeenMs: physical(last) });
}
return { devices, retired };
}
export interface DivergentDevice {
readonly device: string;
readonly hash: string;
/** Id of the digest record. */
readonly digest: string;
}
export type DigestFinding =
| {
readonly kind: "divergent";
readonly partition: StorePartition;
readonly fold: StateDigestFold;
readonly cutHash: string;
readonly devices: ReadonlyArray<DivergentDevice>;
}
| {
readonly kind: "silent";
readonly partition: StorePartition;
readonly device: string;
/** Physical time of its last digest in the partition, `null` when it never published one. */
readonly lastDigestMs: number | null;
readonly lastRecordMs: number;
};
export interface DigestComparison {
readonly partition: StorePartition;
readonly roster: Roster;
/** Cuts that at least two devices published digests for, with those devices. */
readonly comparedCuts: ReadonlyArray<{
readonly cutHash: string;
readonly devices: ReadonlyArray<string>;
}>;
readonly findings: ReadonlyArray<DigestFinding>;
}
export interface CompareDigestsInput {
readonly partition: StorePartition;
/** Every record read from the partition, digests included. */
readonly records: ReadonlyArray<StoreRecord>;
/** `device-retire` records (see {@link computeRoster}). */
readonly retireRecords: ReadonlyArray<StoreRecord>;
readonly nowMs: number;
}
/** Compare a partition's digests and report divergence and silence. */
export function compareDigests(input: CompareDigestsInput): DigestComparison {
const { partition, nowMs } = input;
const roster = computeRoster(input.records, input.retireRecords, nowMs);
const digests = prepareRecords(input.records)
.records.map((record) => ({ record, body: parseDigest(record) }))
.filter((d): d is { record: StoreRecord; body: DigestBody } => d.body?.partition === partition);
const lastDigest = new Map<string, number>();
for (const { record } of digests) lastDigest.set(record.device, physical(record));
// Latest digest per (cut, device) inside the comparison window.
const since = nowMs - DIGEST_COMPARE_WINDOW_DAYS * DAY_MS;
const byCut = new Map<string, Map<string, { record: StoreRecord; body: DigestBody }>>();
for (const digest of digests) {
if (physical(digest.record) < since) continue;
const devices = byCut.get(digest.body.cut_hash) ?? new Map();
devices.set(digest.record.device, digest); // fold order: the latest wins
byCut.set(digest.body.cut_hash, devices);
}
const findings: DigestFinding[] = [];
const comparedCuts: Array<{ cutHash: string; devices: string[] }> = [];
for (const cutHash of [...byCut.keys()].toSorted()) {
const devices = byCut.get(cutHash)!;
if (devices.size < 2) continue;
const names = [...devices.keys()].toSorted();
comparedCuts.push({ cutHash, devices: names });
for (const fold of STATE_DIGEST_FOLDS) {
// Only the digests that carry the fold (an older release's has no `topics`).
const carrying = names.filter(
(device) => devices.get(device)!.body.folds[fold] !== undefined,
);
const hashes = new Set(carrying.map((device) => devices.get(device)!.body.folds[fold]));
if (carrying.length < 2 || hashes.size < 2) continue;
findings.push({
kind: "divergent",
partition,
fold,
cutHash,
devices: carrying.map((device) => {
const { record, body } = devices.get(device)!;
return { device, hash: body.folds[fold]!, digest: record.id };
}),
});
}
}
const silentSince = nowMs - DIGEST_SILENCE_DAYS * DAY_MS;
for (const member of roster.devices) {
const last = lastDigest.get(member.device) ?? null;
if (last !== null && last >= silentSince) continue;
if (member.firstSeenMs >= silentSince) continue; // still in its grace period
findings.push({
kind: "silent",
partition,
device: member.device,
lastDigestMs: last,
lastRecordMs: member.lastSeenMs,
});
}
return { partition, roster, comparedCuts, findings };
}