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
/**
* Read-only diff between two materialised `Brain/` trees.
*
* Used by both `o2b brain snapshot diff <a> [<b>]` and
* `o2b brain rollback --dry-run <id>` — they share the same tree-
* comparison primitive; the renderer (markdown / json) is split out
* into `snapshot-diff-render.ts` so the differ stays purely
* computational.
*
* The walker classifies every file under each root into one of six
* artifact kinds (preference, retired, signal, log, config, other).
* Preferences and retired files get a typed field-level diff for the
* canonical set of derived/identity fields; everything else compares
* by byte equality so the renderer can flag "log file body changed"
* without listing every byte. The log bucket covers every shape a log
* file takes — see {@link isBrainLogDay}.
*
* Inputs are expected to be Brain/ root directories (not vault
* roots). Callers feed `extractSnapshotToTemp(...).brainRoot` for
* snapshots and `<vault>/Brain` for the live tree.
*/
import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
import { join, relative } from "node:path";
import { parseLogFileName } from "./log-jsonl.ts";
import { BRAIN_LOG_DIR, BRAIN_SNAPSHOTS_DIR } from "./path-constants.ts";
import { parsePreference, parseRetired } from "./preference.ts";
import type { BrainPreference, BrainRetired } from "./types.ts";
// ----- Public types --------------------------------------------------------
export type BrainTreeEntryKind = "preference" | "retired" | "signal" | "log" | "config" | "other";
export interface BrainTreeEntry {
/** Vault-relative path under `Brain/<…>`. */
readonly path: string;
readonly kind: BrainTreeEntryKind;
/** Artifact id when applicable (`pref-foo`, `ret-bar`, `sig-…`). */
readonly id: string | null;
/**
* Human-readable title sourced from `principle` for preference and
* retired entries — the markdown renderer uses it to build titled
* wikilinks (§27). Empty string for other kinds and for entries
* that failed to parse.
*/
readonly principle: string;
}
export interface BrainFieldChange {
readonly field: string;
readonly before: string | number | boolean | null;
readonly after: string | number | boolean | null;
}
export interface BrainTreeChange {
readonly entry: BrainTreeEntry;
/** Empty when only the body bytes differ. */
readonly fields: ReadonlyArray<BrainFieldChange>;
readonly bodyChanged: boolean;
}
export interface BrainTreeDiff {
readonly added: ReadonlyArray<BrainTreeEntry>;
readonly removed: ReadonlyArray<BrainTreeEntry>;
readonly modified: ReadonlyArray<BrainTreeChange>;
}
const TRACKED_PREF_FIELDS: ReadonlyArray<keyof BrainPreference> = Object.freeze([
"status",
"applied_count",
"violated_count",
"confidence",
"confidence_value",
"pinned",
"last_evidence_at",
"confirmed_at",
]);
const TRACKED_RETIRED_FIELDS: ReadonlyArray<keyof BrainRetired> = Object.freeze([
"retired_reason",
"applied_count",
"violated_count",
"confidence",
"confidence_value",
"pinned",
"last_evidence_at",
"superseded_by",
]);
// ----- Public API ----------------------------------------------------------
/**
* Compute the artifact-level diff between two `Brain/` trees.
*
* Both roots must exist; missing files inside either root are
* treated as "not present", not as errors. The function never
* mutates either tree. Returned arrays are frozen for caller safety.
*/
export function diffBrainTrees(rootA: string, rootB: string): BrainTreeDiff {
const a = walkBrain(rootA);
const b = walkBrain(rootB);
const aByPath = new Map<string, ScannedFile>();
const bByPath = new Map<string, ScannedFile>();
for (const f of a) aByPath.set(f.entry.path, f);
for (const f of b) bByPath.set(f.entry.path, f);
const added: BrainTreeEntry[] = [];
const removed: BrainTreeEntry[] = [];
const modified: BrainTreeChange[] = [];
for (const f of b) {
if (!aByPath.has(f.entry.path)) {
added.push(f.entry);
}
}
for (const f of a) {
if (!bByPath.has(f.entry.path)) {
removed.push(f.entry);
}
}
for (const f of a) {
const right = bByPath.get(f.entry.path);
if (!right) continue;
const change = diffFile(f, right);
if (change !== null) modified.push(change);
}
// Deterministic ordering: kind ascending, then path ascending. Two
// runs on identical inputs must produce identical output bytes so
// operators can grep a stable diff.
const sortFn = (
x: { readonly path: string; readonly kind: BrainTreeEntryKind },
y: { readonly path: string; readonly kind: BrainTreeEntryKind },
): number => {
if (x.kind !== y.kind) return x.kind.localeCompare(y.kind);
return x.path.localeCompare(y.path);
};
added.sort((x, y) => sortFn(x, y));
removed.sort((x, y) => sortFn(x, y));
modified.sort((x, y) => sortFn(x.entry, y.entry));
return Object.freeze({
added: Object.freeze(added),
removed: Object.freeze(removed),
modified: Object.freeze(modified),
});
}
/**
* True for one day of the Brain log: `log/<date>.md`, `log/<date>.jsonl`,
* or the per-device shards `log/<date>.<device-id>.{md,jsonl}`.
*
* The classifier predated per-device sharding and matched only the
* unsharded markdown, so on any vault with a `device_id` configured — the
* normal case, and the only case where a rollback diff is interesting,
* because sharding exists for multi-device replication — every log file
* fell through to `other`. The machine-primary `.jsonl` surface, which is
* what `readLogDay` actually reads, was misclassified on every vault.
*
* The shape comes from {@link parseLogFileName} in `log-jsonl.ts`, the
* module whose contract is that the shard layout lives in exactly one
* place. This module previously carried a pattern of its own, and that
* copy IS the defect above: a duplicated shape does not stay in step with
* the builders, and a third copy written to repair the second would be a
* third chance to fall behind them.
*
* The depth check keeps the bucket honest in the other direction. The log
* directory also holds ledgers (`capture-decisions.jsonl`,
* `recurrence-support.jsonl`) and subdirectories (`dream-runs/`,
* `pref-audit/`) that are not days of the log, so the class is "a log day
* directly under `log/`" rather than "anything below `log/`".
*/
function isBrainLogDay(rel: string): boolean {
const segments = rel.split("/");
if (segments.length !== 2 || segments[0] !== BRAIN_LOG_DIR) return false;
return parseLogFileName(segments[1]!) !== null;
}
// ----- Walker + classifier -------------------------------------------------
interface ScannedFile {
readonly entry: BrainTreeEntry;
readonly absolutePath: string;
readonly pref?: BrainPreference;
readonly retired?: BrainRetired;
readonly bytes?: string;
}
function walkBrain(root: string): ReadonlyArray<ScannedFile> {
if (!existsSync(root)) return [];
const out: ScannedFile[] = [];
const stack: string[] = [root];
while (stack.length > 0) {
const dir = stack.pop()!;
let entries: ReadonlyArray<string>;
try {
entries = readdirSync(dir);
} catch {
continue;
}
for (const name of entries) {
const abs = join(dir, name);
let st;
try {
// `lstatSync` (NOT `statSync`) so we never follow a symlink.
// A malicious snapshot tarball that contained a symlink
// under `Brain/` pointing at `/etc/passwd` would otherwise
// have the walker read the target file as if it were a
// Brain artifact and surface its bytes inside the diff.
// Skipping symlinks is the cheapest, most honest defense.
st = lstatSync(abs);
} catch {
continue;
}
if (st.isSymbolicLink()) continue;
const rel = relative(root, abs).replaceAll("\\", "/");
// `.snapshots/` is the snapshot family itself — comparing
// archives across snapshots is not meaningful (each snapshot
// owns its own archive set). Skip the tree entirely.
if (rel === BRAIN_SNAPSHOTS_DIR || rel.startsWith(`${BRAIN_SNAPSHOTS_DIR}/`)) continue;
// Defense-in-depth: an entry whose relative path escapes the
// walker root (`..` segment) cannot legitimately be inside
// a Brain snapshot — drop it rather than classify under a
// bogus path. `relative()` returning `..` is the canonical
// marker for "out of root".
if (rel.startsWith("..")) continue;
if (st.isDirectory()) {
stack.push(abs);
continue;
}
if (!st.isFile()) continue;
out.push(scanFile(root, abs, rel));
}
}
return out;
}
function scanFile(_root: string, abs: string, rel: string): ScannedFile {
const baseName = rel.split("/").pop() ?? rel;
if (rel.startsWith("preferences/") && baseName.startsWith("pref-")) {
try {
const pref = parsePreference(abs);
return {
entry: {
path: `Brain/${rel}`,
kind: "preference",
id: pref.id,
principle: pref.principle,
},
absolutePath: abs,
pref,
bytes: readFileSafe(abs),
};
} catch {
return {
entry: {
path: `Brain/${rel}`,
kind: "preference",
id: baseName.replace(/\.md$/, ""),
principle: "",
},
absolutePath: abs,
bytes: readFileSafe(abs),
};
}
}
if (rel.startsWith("retired/") && baseName.startsWith("ret-")) {
try {
const retired = parseRetired(abs);
return {
entry: {
path: `Brain/${rel}`,
kind: "retired",
id: retired.id,
principle: retired.principle,
},
absolutePath: abs,
retired,
bytes: readFileSafe(abs),
};
} catch {
return {
entry: {
path: `Brain/${rel}`,
kind: "retired",
id: baseName.replace(/\.md$/, ""),
principle: "",
},
absolutePath: abs,
bytes: readFileSafe(abs),
};
}
}
if ((rel.startsWith("inbox/") || rel.startsWith("processed/")) && baseName.startsWith("sig-")) {
return {
entry: {
path: `Brain/${rel}`,
kind: "signal",
id: baseName.replace(/\.md$/, ""),
principle: "",
},
absolutePath: abs,
bytes: readFileSafe(abs),
};
}
if (isBrainLogDay(rel)) {
return {
entry: {
path: `Brain/${rel}`,
kind: "log",
id: null,
principle: "",
},
absolutePath: abs,
bytes: readFileSafe(abs),
};
}
if (rel === "_brain.yaml" || rel === "_BRAIN.md" || rel === "active.md") {
return {
entry: {
path: `Brain/${rel}`,
kind: "config",
id: null,
principle: "",
},
absolutePath: abs,
bytes: readFileSafe(abs),
};
}
return {
entry: {
path: `Brain/${rel}`,
kind: "other",
id: null,
principle: "",
},
absolutePath: abs,
bytes: readFileSafe(abs),
};
}
function readFileSafe(path: string): string {
try {
return readFileSync(path, "utf8");
} catch {
return "";
}
}
// ----- Per-file diff -------------------------------------------------------
function diffFile(a: ScannedFile, b: ScannedFile): BrainTreeChange | null {
// Bytes-equal is the cheapest path. Both sides identical → no
// change row in the diff.
if (a.bytes !== undefined && b.bytes !== undefined && a.bytes === b.bytes) {
return null;
}
if (a.entry.kind === "preference" && a.pref && b.pref) {
return diffPreference(a, b);
}
if (a.entry.kind === "retired" && a.retired && b.retired) {
return diffRetired(a, b);
}
// Signals, logs, config, other — body-only diff.
return {
entry: b.entry.principle.length > 0 ? b.entry : a.entry,
fields: [],
bodyChanged: true,
};
}
function diffPreference(a: ScannedFile, b: ScannedFile): BrainTreeChange {
const fields: BrainFieldChange[] = [];
if (a.pref && b.pref) {
for (const field of TRACKED_PREF_FIELDS) {
const before = normaliseValue(a.pref[field]);
const after = normaliseValue(b.pref[field]);
if (before !== after) {
fields.push({ field, before, after });
}
}
}
// Strip frontmatter region from the byte comparison so a pure
// body change is still visible without claiming "fields changed".
// The cheap heuristic: when the rendered field set is empty but
// bytes differ, mark `bodyChanged: true`.
const bodyChanged = fields.length === 0 && a.bytes !== b.bytes;
return { entry: b.entry, fields, bodyChanged };
}
function diffRetired(a: ScannedFile, b: ScannedFile): BrainTreeChange {
const fields: BrainFieldChange[] = [];
if (a.retired && b.retired) {
for (const field of TRACKED_RETIRED_FIELDS) {
const before = normaliseValue(a.retired[field]);
const after = normaliseValue(b.retired[field]);
if (before !== after) {
fields.push({ field, before, after });
}
}
}
const bodyChanged = fields.length === 0 && a.bytes !== b.bytes;
return { entry: b.entry, fields, bodyChanged };
}
function normaliseValue(v: unknown): string | number | boolean | null {
if (v === undefined) return null;
if (v === null) return null;
if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
return v;
}
// Arrays / objects are not currently in TRACKED_*_FIELDS; collapse
// anything unexpected to a JSON string so the diff stays
// human-readable rather than emitting `[object Object]`.
return JSON.stringify(v);
}